# Caixas Delimitadoras (bbox) — Localize Valores Extraídos

> bbox é uma segunda passagem opcional e faturada separadamente que localiza exatamente onde na página cada valor extraído foi originado — coordenadas diretas do modelo, sem verificação em nível de pixel, portanto trate a precisão como aproximada, não exata.

bbox localiza *onde na página original* um valor extraído foi originado — coordenadas que você pode usar para destacar ou cortar aquela região da imagem.

bbox é uma **segunda passagem opcional e faturada separadamente**, não algo que vem gratuito com toda extração. Não é incluído automaticamente em uma chamada normal de `process` ou em `results` a menos que você solicite explicitamente — e, importante, também pode ser acionado automaticamente por uma configuração de conta mesmo que você nunca chame os endpoints bbox. Veja "Faturamento e configurações de conta" abaixo antes de assumir que seu uso corresponde apenas ao que você solicitou explicitamente.

## Acionando anotação

Assim que um documento terminar a extração (`status: "succeeded"`), acione a passagem bbox explicitamente:

```bash
curl -X POST https://imagetotable.ai/api/v1/documents/3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f/bbox \
  -H "Authorization: Bearer $API_KEY"
```

Isso gasta créditos e enfileira um job bbox (202 Accepted) — ou, se um job *bbox* para este documento já estiver em execução de uma chamada anterior a este mesmo endpoint, retorna 200 sem enfileirar ou cobrar novamente. Esta flag `already_running` é sobre um segundo job bbox para o mesmo documento, não sobre a extração do documento — você só pode acessar este endpoint em um documento que já está `status: "succeeded"`, portanto a extração em si nunca é o que está "já em execução" aqui:

```json
{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "group_batch_id": "bx_8a3c2e1f",
  "status": "processing",
  "already_running": false,
  "row_groups": 1
}
```

Este endpoint aceita um cabeçalho `Idempotency-Key` — veja [Idempotência](/developers/guides/idempotency), já que esta é uma ação paga que gasta créditos.

## Verificando status e resultados

```bash
curl https://imagetotable.ai/api/v1/documents/3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f/bbox \
  -H "Authorization: Bearer $API_KEY"
```

```json
{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "exists": true,
  "status": "succeeded",
  "group_batch_id": "bx_8a3c2e1f",
  "rows": {
    "0": {
      "invoice_number": { "x1": 0.121, "y1": 0.084, "x2": 0.312, "y2": 0.108, "unit": "normalized" },
      "total_amount": { "x1": 0.702, "y1": 0.611, "x2": 0.881, "y2": 0.639, "unit": "normalized" }
    }
  }
}
```

`exists: false` significa que nenhum job de bbox foi acionado para este documento — um estado muito comum e esperado, não um erro. As coordenadas são floats `x1`/`y1`/`x2`/`y2` normalizados no intervalo 0–1 (cantos superior esquerdo e inferior direito), independentes das dimensões reais em pixels da imagem original.

Em vez de consultar este endpoint repetidamente, registre um webhook (veja o [Guia de Webhooks](/developers/guides/webhooks)) no lote do documento — um job de bbox que atinge um status terminal entrega um evento `document.bbox_completed` para a mesma URL de callback, junto com quaisquer eventos `batch.completed` que ela já recebe. Não há uma etapa de registro separada para bbox especificamente; ele reutiliza o webhook existente do lote.

## Obtendo bbox inline com os resultados

Em vez dos endpoints independentes acima, você também pode solicitar que o endpoint de resultados do lote preencha dados de bbox já calculados com `?include=bbox`:

```bash
curl "https://imagetotable.ai/api/v1/batches/260716-4K9P/results?include=bbox" \
  -H "Authorization: Bearer $API_KEY"
```

Ao fazer isso, cada valor de campo em `line_items` muda de um escalar simples para `{"value": ..., "bbox": ...}`, com `bbox` definido como `null` se nada foi calculado para aquele campo:

```json
{ "invoice_number": { "value": "INV-1042", "bbox": { "x1": 0.121, "y1": 0.084, "x2": 0.312, "y2": 0.108, "unit": "normalized" } } }
```

`?include=bbox` apenas lê dados que já existem — nunca aciona um novo job de anotação faturável em seu nome. Se o bbox de um campo ainda não foi calculado, você recebe `null` para ele, sem cobrança implícita. Acione a anotação explicitamente com `POST .../bbox` primeiro.

## Campos que são inteiramente uma localização

Alguns campos não são um trecho de texto com uma localização incidental — o propósito inteiro do campo *é* a localização (por exemplo, um campo pedindo para "localizar a foto do retrato" em um documento de identidade). Para estes, o valor retorna como um objeto mais rico, independentemente de você ter solicitado `?include=bbox`, já que a localização *é* a resposta, não metadados opcionais sobre ela:

```json
{
  "portrait_location": {
    "type": "image_region",
    "bbox": { "x1": 0.05, "y1": 0.12, "x2": 0.28, "y2": 0.44, "unit": "normalized" },
    "image_url": "https://imagetotable.ai/api/v1/documents/3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f/image?crop=0.03%2C0.10%2C0.30%2C0.46"
  }
}
```

`image_url` aponta para `GET /documents/{document_id}/image?crop=...` — um JPEG cortado real e buscável daquela região (com um leve preenchimento além das coordenadas brutas para que um corte apertado tenha menos chance de cortar parte do que você queria), não apenas quatro números que você teria que recortar da imagem original. Você também pode chamar esse endpoint diretamente com seu próprio `?crop=x1,y1,x2,y2` (mesma convenção normalizada de 0–1) em qualquer documento, independentemente de ele ter vindo de um job bbox.

## Limitação conhecida: coordenadas são diretas do modelo, não verificadas por pixel

As coordenadas bbox vêm diretamente da fundamentação visual do modelo subjacente — não há **nenhuma etapa de verificação ao nível do pixel** que verifique se uma determinada caixa está desenhada de forma apertada ou solta em torno de seu alvo. Em documentos simples e esparsos, isso geralmente é próximo o suficiente para uso direto. Em documentos complexos ou densamente preenchidos — tabelas com muitas colunas, formulários com campos muito próximos — a precisão degrada consideravelmente, e as caixas podem acabar muito apertadas, muito soltas ou, ocasionalmente, referenciar o campo errado próximo. **Não trate a saída bbox como uma fonte de corte exata e perfeita ao nível do pixel** — se seu fluxo de trabalho depende de corte preciso (para OCR downstream, evidência legal, etc.), verifique os resultados em vez de confiar cegamente, especialmente em layouts densos.

Os cortes de conveniência `image_url` (tanto para campos de localização pura quanto para suas próprias chamadas `?crop=` contra uma caixa derivada de bbox) são gerados com uma pequena quantidade de preenchimento ao redor das coordenadas informadas, para reduzir a chance de um corte muito apertado cortar conteúdo real — esta é uma medida de tolerância, não uma correção de precisão. As coordenadas `bbox` brutas retornadas no próprio JSON são sempre exatamente o que o modelo informou, sem preenchimento.

## Faturamento e configurações da conta

A execução da anotação de bbox não é determinada 100% por você chamar ou não os endpoints de bbox. Sua conta possui uma configuração — `auto_annotate_bbox`, definida no aplicativo web, não por meio desta API — que, quando ativada, aciona automaticamente (e fatura) uma passagem de bbox após *toda* extração concluída, inclusive aquelas iniciadas via v1. Se sua conta tiver essa configuração ativada, você pode ser faturado pela anotação de bbox sem nunca chamar `POST .../bbox` diretamente. Consulte [Configurações da Conta e Comportamento da API](/developers/guides/account-settings) para obter o panorama completo de quais configurações no nível da conta a API permite ou não que você substitua por solicitação.

---

Source: https://imagetotable.ai/pt/developers/guides/bbox