> ## 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.

# Captura de ecrã síncrona

> O endpoint `screenshot` executa uma sessão de navegador, executa JavaScript e devolve uma imagem codificada em base64 num único pedido síncrono.

## Primeiros passos

### URL base

```
https://screenshot.cleariflow.com/v1/screenshot
```

### Exemplo de pedido

```bash theme={"system"}
curl -X POST 'https://screenshot.cleariflow.com/v1/screenshot' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_UNIQUE_API_KEY",
    "url": "https://cleariflow.com",
    "capture_full_page": true,
    "export_format": "jpeg"
  }'
```

Um pedido bem-sucedido devolve a captura de ecrã em base64 e metadados:

<ResponseExample>
  ```json theme={"system"}
  {
    "ok": true,
    "image_base64": "/9j/4AAQSkZJRg...",
    "content_type": "image/jpeg",
    "meta": {
      "elapsed_ms": 4521
    }
  }
  ```
</ResponseExample>

Descodifique `image_base64` para obter os bytes JPEG ou PNG brutos.

### Opções de renderização

O objeto `render` controla como o navegador carrega a página antes da captura. Todos os campos são opcionais — se omitidos, aplicam-se os valores predefinidos do servidor.

```json theme={"system"}
"render": {
  "wait_until": "networkidle",
  "timeout_ms": 60000,
  "post_load_wait_ms": 2000,
  "ignore_https_errors": false,
  "full_page": true,
  "screenshot_format": "jpeg",
  "user_agent": "Mozilla/5.0 ...",
  "viewport": {
    "width": 1365,
    "height": 768
  }
}
```

| Campo                 | Tipo    | Predefinição       | Descrição                                                                                                                                                                        |
| --------------------- | ------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wait_until`          | String  | `domcontentloaded` | Quando considerar a navegação concluída. Use `domcontentloaded` para resultados mais rápidos; use `networkidle` quando a página carrega dados via XHR/fetch após o HTML inicial. |
| `timeout_ms`          | Integer | `60000`            | Tempo máximo em milissegundos para aguardar o carregamento da página.                                                                                                            |
| `post_load_wait_ms`   | Integer | `0`                | Atraso adicional em milissegundos após `wait_until` antes da captura. Útil para animações ou conteúdo lazy-loaded.                                                               |
| `ignore_https_errors` | Boolean | `false`            | Se `true`, ignora erros de certificado TLS da página alvo.                                                                                                                       |
| `full_page`           | Boolean | `true`             | Se `true`, captura toda a altura deslocável da página.                                                                                                                           |
| `screenshot_format`   | String  | `jpeg`             | Formato de saída: `jpeg` ou `png`.                                                                                                                                               |
| `user_agent`          | String  | —                  | String User-Agent personalizada para a sessão do navegador.                                                                                                                      |
| `viewport`            | Object  | `1365×768`         | Tamanho do viewport via `width` e `height` em píxeis.                                                                                                                            |

### Campos de conveniência

Estes campos de nível superior são aliases fundidos em `render` e `actions` para retrocompatibilidade e pedidos mais simples:

| Campo               | Mapeia para                | Descrição                                                      |
| ------------------- | -------------------------- | -------------------------------------------------------------- |
| `capture_full_page` | `render.full_page`         | Alternar captura de página completa.                           |
| `width` / `height`  | `render.viewport`          | Dimensões do viewport em píxeis.                               |
| `delay`             | `render.post_load_wait_ms` | Atraso em **segundos** antes da captura.                       |
| `export_format`     | `render.screenshot_format` | `jpeg` ou `png`.                                               |
| `user_agent`        | `render.user_agent`        | User-Agent personalizado.                                      |
| `css_injection`     | ação `inject_css`          | CSS injetado antes da captura quando não há ação `inject_css`. |

Exemplo com campos planos:

```bash theme={"system"}
curl -X POST 'https://screenshot.cleariflow.com/v1/screenshot' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_UNIQUE_API_KEY",
    "url": "https://cleariflow.com",
    "width": 1280,
    "height": 720,
    "delay": 2,
    "export_format": "png"
  }'
```

### Opções de recursos

O objeto `resources` controla que tipos de recursos o navegador carrega durante a captura. Bloquear recursos pesados acelera pedidos quando a fidelidade visual o permite.

```json theme={"system"}
"resources": {
  "block": ["images", "fonts", "media"]
}
```

| Valor    | Bloqueia                      |
| -------- | ----------------------------- |
| `images` | Imagens (`<img>`, fundos CSS) |
| `fonts`  | Fontes web                    |
| `media`  | Fluxos de vídeo e áudio       |

### Endpoint GET legacy

`GET /v1/` devolve bytes de imagem brutos (JPEG ou PNG) em vez de JSON. Passe os parâmetros como query strings:

```
https://screenshot.cleariflow.com/v1/?api_key=YOUR_UNIQUE_API_KEY&url=https://cleariflow.com&capture_full_page=true&export_format=jpeg
```

Parâmetros de consulta suportados: `url`, `api_key`, `session_id`, `fingerprint`, `capture_full_page`, `width`, `height`, `delay`, `css_injection`, `user_agent`, `export_format`.

### Parâmetros de pedido

<ParamField body="url" type="String" required>
  O URL alvo a capturar. Deve ser um URL HTTP ou HTTPS público. Pedidos a localhost e endereços IP privados são bloqueados pela proteção SSRF.
</ParamField>

<ParamField body="api_key" type="String" required>
  A sua chave API única.
</ParamField>

<ParamField body="session_id" type="String">
  Identificador de sessão opcional para reutilizar o estado do navegador (cookies, armazenamento local) entre múltiplos pedidos.
</ParamField>

<ParamField body="fingerprint" type="String">
  Preset de impressão digital do navegador. Valores suportados: `desktop_en_us`, `desktop_ru_ru`, `mobile_en_us`.
</ParamField>

<ParamField body="render" type="Object">
  Opções de renderização e captura para a sessão do navegador.
</ParamField>

<ParamField body="render.wait_until" type="String">
  Quando considerar a navegação concluída. Valores: `domcontentloaded`, `networkidle`. Predefinição: `domcontentloaded`.
</ParamField>

<ParamField body="render.timeout_ms" type="Integer">
  Tempo máximo em milissegundos para aguardar o carregamento da página. Predefinição: 60000.
</ParamField>

<ParamField body="render.post_load_wait_ms" type="Integer">
  Atraso adicional em milissegundos após o evento de carregamento da página antes da captura.
</ParamField>

<ParamField body="render.ignore_https_errors" type="Boolean">
  Se `true`, ignora erros de certificado TLS da página alvo.
</ParamField>

<ParamField body="render.full_page" type="Boolean">
  Se `true`, captura toda a página deslocável. Predefinição: `true`.
</ParamField>

<ParamField body="render.screenshot_format" type="String">
  Formato de saída: `jpeg` ou `png`. Predefinição: `jpeg`.
</ParamField>

<ParamField body="render.user_agent" type="String">
  User-Agent personalizado para a sessão do navegador.
</ParamField>

<ParamField body="render.viewport" type="Object">
  Tamanho do viewport com `width` e `height` em píxeis.
</ParamField>

<ParamField body="resources" type="Object">
  Controlos de carregamento de recursos.
</ParamField>

<ParamField body="resources.block" type="Array">
  Tipos de recursos a bloquear. Valores suportados: `images`, `fonts`, `media`.
</ParamField>

<ParamField body="actions" type="Array">
  Lista ordenada de ações do navegador antes da captura. Cada ação é um objeto com um campo `type`.
</ParamField>

<ParamField body="actions[].type" type="String" required>
  Tipo de ação. Valores suportados: `wait`, `wait_for`, `click`, `type`, `scroll`, `inject_css`.
</ParamField>

<ParamField body="actions[].selector" type="String">
  Seletor CSS para ações `wait_for`, `click` ou `type`.
</ParamField>

<ParamField body="actions[].text" type="String">
  Texto a digitar para a ação `type`.
</ParamField>

<ParamField body="actions[].css" type="String">
  String CSS para a ação `inject_css`.
</ParamField>

<ParamField body="actions[].to" type="String">
  Destino de scroll para a ação `scroll` (ex.: `bottom`).
</ParamField>

<ParamField body="actions[].wait_ms" type="Integer">
  Duração em milissegundos para a ação `wait`.
</ParamField>

<ParamField body="cookies" type="Array">
  Cookies a injetar antes da navegação. Cada objeto cookie requer `name` e `value`; campos opcionais: `domain`, `path`.
</ParamField>

<ParamField body="capture_full_page" type="Boolean">
  Alias de conveniência para `render.full_page`.
</ParamField>

<ParamField body="width" type="Integer">
  Alias de conveniência para `render.viewport.width`.
</ParamField>

<ParamField body="height" type="Integer">
  Alias de conveniência para `render.viewport.height`.
</ParamField>

<ParamField body="delay" type="Integer">
  Atraso em segundos antes da captura. Mapeado para `render.post_load_wait_ms`.
</ParamField>

<ParamField body="css_injection" type="String">
  CSS injetado via ação `inject_css` quando não está presente em `actions`.
</ParamField>

<ParamField body="export_format" type="String">
  Alias de conveniência para `render.screenshot_format`. Valores: `jpeg`, `png`.
</ParamField>

### Parâmetros de resposta

A resposta da API é devolvida num [formato JSON](https://www.json.org/json-en.html) universal e leve.

<ResponseField name="ok" type="Boolean">
  Se a captura de ecrã foi concluída com sucesso.
</ResponseField>

<ResponseField name="image_base64" type="String">
  Dados de imagem codificados em base64. Descodifique para obter bytes JPEG ou PNG brutos.
</ResponseField>

<ResponseField name="content_type" type="String">
  Tipo MIME da imagem (`image/jpeg` ou `image/png`).
</ResponseField>

<ResponseField name="meta" type="Object">
  Metadados sobre a captura, incluindo o tempo decorrido em milissegundos.
</ResponseField>

<ResponseField name="error" type="Object">
  Detalhes do erro quando `ok` é `false`.
</ResponseField>