Markdown e bounding-box

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.

{
  "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:

{
  "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.

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.

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

{
  "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.).

GET /extract/{requestId}

Endpoint de consulta de resultado.

Payload da resposta

Estrutura completa da resposta.

Confiabilidade

Como interpretar o bloco scanify.

Como funciona

Documentos e Dados

Markdown e bounding-box

Markdown

No fluxo síncrono

No fluxo assíncrono

Consulta direta

Bounding box

Endpoint

Resposta

`resolution_status`

Sistema de coordenadas

GET /extract/{requestId}

Payload da resposta

Confiabilidade

​Markdown

​No fluxo síncrono

​No fluxo assíncrono

​Consulta direta

​Bounding box

​Endpoint

​Resposta

​resolution_status

​Sistema de coordenadas

GET /extract/{requestId}

Payload da resposta

Confiabilidade

Markdown

No fluxo síncrono

No fluxo assíncrono

Consulta direta

Bounding box

Endpoint

Resposta

`resolution_status`

Sistema de coordenadas