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

# Markdown e bounding-box

> Obtenha o texto bruto extraído em markdown e as coordenadas dos campos no documento

Além dos campos estruturados, o Scanify pode retornar o texto OCR completo em **markdown** e as **coordenadas (bounding box)** onde cada campo foi localizado no documento. Úteis para revisão visual, auditoria e UIs de feedback.

## Markdown

### No fluxo síncrono

Passe `includeMarkdown: true` no corpo de `POST /extract/sync`. A resposta inclui o campo `markdown` ao lado de `fields`.

```json theme={"dark"}
{
  "request_id": "req_01HXXXXXXXXXXXXXX",
  "document_type": "BOLETO",
  "status": "success",
  "fields": { "...": "..." },
  "markdown": "# Boleto bancário\n\nBeneficiário: ACME S.A.\nValor: R$ 1.289,45\n...",
  "processed_at": "2026-05-28T14:32:07.812Z",
  "scanify": { "...": "..." }
}
```

### No fluxo assíncrono

Passe `includeMarkdownInWebhook: true` no corpo de `POST /extract`. No callback enviado para o seu `callbackUrl`, os seguintes campos são incluídos quando o markdown está disponível:

| Campo                   | Tipo                                 | Descrição                                        |
| ----------------------- | ------------------------------------ | ------------------------------------------------ |
| `markdown_status`       | `"pending" \| "success" \| "failed"` | Estado atual da geração de markdown.             |
| `markdown`              | `string`                             | Conteúdo em markdown. Presente quando `success`. |
| `markdown_generated_at` | `string` (ISO-8601)                  | Quando o markdown foi gerado.                    |
| `markdown_error`        | `string`                             | Mensagem de erro. Presente quando `failed`.      |

### Consulta direta

`GET /extract/{requestId}/markdown` retorna o status atual e, quando disponível, o conteúdo:

```json theme={"dark"}
{
  "request_id": "req_01HXXXXXXXXXXXXXX",
  "document_type": "BOLETO",
  "request_status": "success",
  "markdown_status": "success",
  "markdown_generated_at": "2026-05-28T14:32:09.451Z",
  "markdown_error": null,
  "markdown": "# Boleto bancário\n..."
}
```

Quando você envia `Accept: text/markdown` **e** `markdown_status === "success"`, o endpoint responde com o markdown bruto em `text/markdown; charset=utf-8`, sem o envelope JSON. Útil para clientes que querem o texto direto.

<Note>
  A geração de markdown pode levar mais tempo que a extração de campos. No
  fluxo síncrono, `includeMarkdown: true` aumenta o tempo total da requisição.
</Note>

## Bounding box

### Endpoint

`GET /extract/{requestId}/bounding-box?fieldPath=fields.<nome_do_campo>`

O parâmetro `fieldPath` é obrigatório e deve começar com `fields.` e apontar para um campo **leaf** (folha — string, número, booleano ou nulo). Exemplos:

* `fields.amount`
* `fields.due_date`
* `fields.transactions[0].date`

### Resposta

```json theme={"dark"}
{
  "request_id": "req_01HXXXXXXXXXXXXXX",
  "document_type": "BOLETO",
  "field_path": "fields.amount",
  "value": 1289.45,
  "resolution_status": "resolved",
  "reason": null,
  "segments": [
    {
      "page": 1,
      "text": "1.289,45",
      "bounding_box": {
        "left": 0.7124,
        "top": 0.3318,
        "width": 0.0852,
        "height": 0.0190
      },
      "polygon": [
        { "x": 0.7124, "y": 0.3318 },
        { "x": 0.7976, "y": 0.3318 },
        { "x": 0.7976, "y": 0.3508 },
        { "x": 0.7124, "y": 0.3508 }
      ]
    }
  ],
  "page_aggregates": [
    {
      "page": 1,
      "bounding_box": {
        "left": 0.7124,
        "top": 0.3318,
        "width": 0.0852,
        "height": 0.0190
      }
    }
  ]
}
```

Campos:

| Campo               | Tipo                                                         | Descrição                                                                                                             |
| ------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `value`             | leaf                                                         | Valor do campo no payload da extração.                                                                                |
| `resolution_status` | `"resolved" \| "ambiguous" \| "unresolved" \| "not_indexed"` | Estado da resolução geométrica (ver abaixo).                                                                          |
| `reason`            | `string \| null`                                             | Código explicando o status quando não é `resolved`.                                                                   |
| `segments`          | array                                                        | Um segmento por span de texto-fonte do campo. Cada um tem `page`, `text`, `bounding_box` e, opcionalmente, `polygon`. |
| `page_aggregates`   | array                                                        | Um item por página afetada, com o `bounding_box` mínimo que cobre todos os segmentos daquela página.                  |

### `resolution_status`

| Status        | Quando ocorre                                                                                                       | `reason` típico                                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resolved`    | Todos os spans do campo foram encontrados no texto OCR e geometrizados.                                             | `null`                                                                                                                                                           |
| `ambiguous`   | O span ocorre mais de uma vez na linha referida; não há como decidir qual posição é a correta.                      | `span_match_ambiguous`                                                                                                                                           |
| `unresolved`  | A requisição possui bounding boxes indexadas, mas o campo específico não pôde ser resolvido.                        | `bounding_box_not_found_for_field`, `missing_field_source`, `invalid_line_ref`, `line_words_not_indexed`, `span_match_not_found`, `segment_geometry_unavailable` |
| `not_indexed` | A requisição ainda não tem bounding boxes indexadas (extrações antigas, ou em fluxos onde a indexação não ocorreu). | `bounding_boxes_not_indexed_for_request`                                                                                                                         |

### Sistema de coordenadas

Coordenadas normalizadas em fração da página (0–1). Origem `(0,0)` no canto superior esquerdo. `polygon` está no mesmo espaço.

Para sobrepor em uma imagem renderizada, multiplique pelas dimensões em pixels da página renderizada (`x_px = left * page_width_px`, etc.).

<CardGroup cols={2}>
  <Card title="GET /extract/{requestId}" icon="server" href="/api-reference/endpoint/get-result">
    Endpoint de consulta de resultado.
  </Card>

  <Card title="Payload da resposta" icon="brackets-curly" href="/response-payload">
    Estrutura completa da resposta.
  </Card>

  <Card title="Confiabilidade" icon="shield-check" href="/reliability">
    Como interpretar o bloco `scanify`.
  </Card>
</CardGroup>