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

# API de web scraping

> A API de web scraping Cleariflow oferece extração de páginas renderizadas com JavaScript através de uma interface JSON RESTful moderna, com proteção SSRF e opções de renderização flexíveis.

## Primeiros passos

<Card title="Scraping síncrono" icon="browser" href="scrape/scrape">
  O endpoint `scrape` executa uma sessão de navegador e devolve HTML renderizado num único pedido — ideal para integrações de baixa latência.
</Card>

<Card title="Tarefas assíncronas" icon="clock" href="scrape/jobs">
  Os endpoints `jobs` colocam scrapes na fila e permitem consultar o estado e os resultados — ideal para alto volume ou páginas lentas.
</Card>

### Arquitetura REST

A API de web scraping segue os princípios REST, com URLs previsíveis orientadas a recursos e códigos de estado HTTP padrão para integração fluida e tratamento de erros.

### Segurança HTTPS

Todas as comunicações da API são protegidas com TLS 1.2 ou superior para garantir a integridade e privacidade dos dados.

### Versões da API

A API de web scraping mantém compatibilidade retroativa através de versionamento e opera atualmente na Versão 1.

### Autenticação

A sua chave API é a credencial exclusiva para aceder à API de web scraping. Cada serviço Cleariflow requer uma chave única. Inclua a sua chave no corpo JSON como `api_key`.

### URL base

```
https://scrape.cleariflow.com
```

### Renderização de páginas

As páginas são renderizadas num navegador headless real. JavaScript é totalmente executado antes de devolver o conteúdo. A proteção SSRF integrada bloqueia pedidos a localhost e intervalos de IP privados.

## Códigos de resposta e erro

Quando os pedidos falham, a API devolve respostas de erro JSON estruturadas com códigos e descrições específicos para resolução eficaz de problemas.

| Código | Tipo                  | Detalhes                                                                                         |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------ |
| 200    | OK                    | Tudo funcionou como esperado.                                                                    |
| 202    | Accepted              | A tarefa assíncrona foi enfileirada com sucesso.                                                 |
| 400    | Bad request           | Pedido inválido — URL inválido, destino bloqueado ou payload mal formado.                        |
| 401    | Unauthorized          | O pedido não foi aceite. Normalmente devido a chave API em falta ou incorreta.                   |
| 422    | Quota reached         | O pedido foi abortado por créditos de API insuficientes. (Planos gratuitos)                      |
| 429    | Too many requests     | Limite de pedidos por segundo atingido. Nos planos gratuitos o limite é de 1 pedido por segundo. |
| 500    | Internal server error | O pedido não pôde ser concluído devido a um erro no servidor.                                    |