> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# Import por URL

> Importe produtos diretamente de páginas web usando a infraestrutura de web scraping do Bright Data — cole uma URL e o pipeline cuida do resto.

## Visão geral

O **Import por URL** permite criar produtos colando a URL de uma página de produto. A Alana usa a infraestrutura de scraping do Bright Data para extrair dados estruturados da página, mapeá-los para o schema da Alana e executar automaticamente o pipeline Bronze → Silver.

***

## Como funciona

```mermaid theme={null}
graph LR
    A["Colar URL"] --> B["Bright Data\nRaspa a página"]
    B --> C["Bronze\n(HTML bruto → schema)"]
    C --> D["Silver\n(normalizar campos)"]
    D --> E["Gold\n(pontuação opcional)"]
    E --> F["Produto aparece\nno catálogo"]
```

1. Você submete a URL de uma página de produto
2. O Bright Data busca a página (lidando com renderização JavaScript, CAPTCHAs e restrições geográficas)
3. O scraper extrai: título, descrição, imagens, preço, marca, especificações
4. Os dados extraídos são mapeados para o schema de produto da Alana (Bronze)
5. O Silver normaliza o resultado automaticamente
6. O produto aparece no seu catálogo

***

## Métodos de scraping

| Método         | Descrição                                                              | Melhor para                               |
| -------------- | ---------------------------------------------------------------------- | ----------------------------------------- |
| `web_scraper`  | Renderização completa de JavaScript, extração de dados estruturados    | Páginas de produto com conteúdo dinâmico  |
| `web_unlocker` | Contorna proteções anti-bot                                            | Varejistas com detecção agressiva de bots |
| `crawl`        | Segue links para extrair múltiplos produtos de uma página de categoria | Páginas de categoria ou coleção           |

***

## Importar uma única URL

### Via UI

1. Abra seu catálogo
2. Clique em **Adicionar Produtos** → **Importar por URL**
3. Cole a URL da página de produto
4. Selecione o método de scraping (padrão: `web_scraper`)
5. Clique em **Importar**
6. Um job é criado — o produto aparece no catálogo em 30–90 segundos

### Via API

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://app.alana.shopping/api/workspace/WORKSPACE_ID/url-import" \
    -H "Authorization: Bearer SUA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://www.exemplo.com/produtos/tenis-running-pro",
      "catalogId": "CATALOG_ID",
      "method": "web_scraper"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/url-import`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        url: 'https://www.exemplo.com/produtos/tenis-running-pro',
        catalogId,
        method: 'web_scraper',
      }),
    }
  );
  const { jobId, status } = await response.json();
  console.log(`Job de import ${jobId} iniciado com status: ${status}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      f"https://app.alana.shopping/api/workspace/{workspace_id}/url-import",
      headers={"Authorization": f"Bearer {api_key}"},
      json={
          "url": "https://www.exemplo.com/produtos/tenis-running-pro",
          "catalogId": catalog_id,
          "method": "web_scraper",
      }
  )
  job = response.json()
  print(f"Job de import {job['jobId']} iniciado")
  ```
</CodeGroup>

### Resposta

```json theme={null}
{
  "jobId": "job_9x8k2m",
  "status": "processing",
  "url": "https://www.exemplo.com/produtos/tenis-running-pro",
  "estimatedSeconds": 45
}
```

***

## Importar múltiplas URLs (em lote)

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://app.alana.shopping/api/workspace/WORKSPACE_ID/url-import/bulk" \
    -H "Authorization: Bearer SUA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "urls": [
        "https://www.exemplo.com/produtos/item-1",
        "https://www.exemplo.com/produtos/item-2",
        "https://www.exemplo.com/produtos/item-3"
      ],
      "catalogId": "CATALOG_ID",
      "method": "web_scraper"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/url-import/bulk`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        urls: [
          'https://www.exemplo.com/produtos/item-1',
          'https://www.exemplo.com/produtos/item-2',
          'https://www.exemplo.com/produtos/item-3',
        ],
        catalogId,
        method: 'web_scraper',
      }),
    }
  );
  const { batchJobId, urlCount } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      f"https://app.alana.shopping/api/workspace/{workspace_id}/url-import/bulk",
      headers={"Authorization": f"Bearer {api_key}"},
      json={
          "urls": [
              "https://www.exemplo.com/produtos/item-1",
              "https://www.exemplo.com/produtos/item-2",
          ],
          "catalogId": catalog_id,
          "method": "web_scraper",
      }
  )
  batch = response.json()
  print(f"Job em lote {batch['batchJobId']} para {batch['urlCount']} URLs")
  ```
</CodeGroup>

***

## Rastrear uma página de categoria

Use o método `crawl` para importar todos os produtos de uma página de categoria ou coleção:

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://app.alana.shopping/api/workspace/WORKSPACE_ID/url-import" \
    -H "Authorization: Bearer SUA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://www.exemplo.com/categoria/tenis-running",
      "catalogId": "CATALOG_ID",
      "method": "crawl",
      "crawlOptions": {
        "maxProducts": 100,
        "followPagination": true
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/url-import`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        url: 'https://www.exemplo.com/categoria/tenis-running',
        catalogId,
        method: 'crawl',
        crawlOptions: { maxProducts: 100, followPagination: true },
      }),
    }
  );
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      f"https://app.alana.shopping/api/workspace/{workspace_id}/url-import",
      headers={"Authorization": f"Bearer {api_key}"},
      json={
          "url": "https://www.exemplo.com/categoria/tenis-running",
          "catalogId": catalog_id,
          "method": "crawl",
          "crawlOptions": {"maxProducts": 100, "followPagination": True},
      }
  )
  ```
</CodeGroup>

***

## Verificar status do job

<CodeGroup>
  ```bash curl theme={null}
  curl "https://app.alana.shopping/api/workspace/WORKSPACE_ID/url-import/JOB_ID" \
    -H "Authorization: Bearer SUA_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/url-import/${jobId}`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );
  const { status, productId, error } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      f"https://app.alana.shopping/api/workspace/{workspace_id}/url-import/{job_id}",
      headers={"Authorization": f"Bearer {api_key}"}
  )
  job = response.json()
  print(f"Status: {job['status']}, Product ID: {job.get('productId')}")
  ```
</CodeGroup>

### Valores de status do job

| Status       | Descrição                                            |
| ------------ | ---------------------------------------------------- |
| `processing` | O Bright Data está buscando e analisando a página    |
| `success`    | Produto criado no catálogo                           |
| `partial`    | Produto criado com alguns campos ausentes            |
| `failed`     | A página não pôde ser raspada (veja o campo `error`) |

***

## Limites de uso e custos

| Métrica                      | Limite                 |
| ---------------------------- | ---------------------- |
| Imports de URL única         | 100/hora por workspace |
| Imports em lote              | 500 URLs/requisição    |
| Máximo de produtos por crawl | 500/crawl              |
| Jobs simultâneos             | 10 por workspace       |

O custo por import é debitado do seu saldo de créditos Bright Data. Os custos variam por método:

| Método         | Custo aproximado                  |
| -------------- | --------------------------------- |
| `web_scraper`  | 0,001 créditos/página             |
| `web_unlocker` | 0,005 créditos/página             |
| `crawl`        | 0,001 créditos/produto encontrado |

Veja seu uso de créditos Bright Data em **Configurações** → **Integrações** → **Bright Data**.

***

## Boas práticas

<AccordionGroup>
  <Accordion title="Teste com uma única URL antes do import em lote">
    Sempre teste uma URL primeiro para confirmar que o scraper extrai corretamente os campos que você precisa. Varejistas diferentes têm estruturas de página diferentes.
  </Accordion>

  <Accordion title="Use web_unlocker para grandes varejistas">
    Sites como Amazon, Mercado Livre e grandes varejistas de moda têm detecção de bot. Use `web_unlocker` para evitar imports com falha.
  </Accordion>

  <Accordion title="Use crawl para imports no nível de categoria">
    Quando quiser todos os produtos de uma categoria, `crawl` é mais eficiente do que colar a URL de cada produto individualmente.
  </Accordion>

  <Accordion title="Verifique resultados parciais">
    Um status `partial` significa que o produto foi criado mas alguns campos não puderam ser extraídos. Revise esses produtos no Canvas e preencha os campos ausentes manualmente.
  </Accordion>
</AccordionGroup>