# Cuadros Delimitadores (bbox) — Ubicar Valores Extraídos

> bbox es un segundo paso opcional y facturado por separado que localiza exactamente dónde en la página se originó cada valor extraído — coordenadas directas del modelo sin verificación a nivel de píxel, por lo que la precisión debe tratarse como aproximada, no exacta.

bbox localiza *dónde en la página original* se originó un valor extraído — coordenadas que puede usar para resaltar o recortar esa región de la imagen.

bbox es un **segundo paso opcional y facturado por separado**, no algo que venga incluido con cada extracción. No se incluye automáticamente en una llamada normal a `process` ni en `results` a menos que lo solicite explícitamente — y, algo importante, también puede activarse automáticamente mediante una configuración a nivel de cuenta incluso si nunca llama usted mismo a los endpoints de bbox. Consulte "Facturación y configuración de cuenta" más abajo antes de asumir que su uso coincide solo con lo que solicitó explícitamente.

## Activar la anotación

Una vez que un documento haya terminado de extraerse (`status: "succeeded"`), active el paso bbox explícitamente:

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

Esto consume créditos y pone en cola un trabajo bbox (202 Accepted) — o, si un trabajo *bbox* para este documento ya está en ejecución por una llamada anterior a este mismo endpoint, devuelve 200 sin poner en cola ni cobrar de nuevo. Esta bandera `already_running` se refiere a un segundo trabajo bbox para el mismo documento, no a la extracción del documento — solo puede acceder a este endpoint en un documento que ya tenga `status: "succeeded"`, por lo que la extracción en sí nunca es lo que "ya está en ejecución" aquí:

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

Este endpoint acepta un encabezado `Idempotency-Key` — consulte [Idempotencia](/developers/guides/idempotency), ya que se trata de una acción de pago que consume créditos.

## Verificación del estado y los 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 nunca se ha activado un trabajo de bbox para este documento; es un estado muy común y esperado, no un error. Las coordenadas son valores flotantes `x1`/`y1`/`x2`/`y2` normalizados al rango 0–1 (esquinas superior izquierda e inferior derecha), independientes de las dimensiones reales en píxeles de la imagen original.

En lugar de consultar este endpoint, registre un webhook (consulte la [guía de Webhooks](/developers/guides/webhooks)) en el lote del documento; un trabajo de bbox que alcanza un estado terminal entrega un evento `document.bbox_completed` a esa misma URL de callback, junto con los eventos `batch.completed` que ya recibe. No hay un paso de registro separado específico para bbox; reutiliza el webhook existente del lote.

## Obtención de bbox en línea con los resultados

En lugar de los endpoints independientes anteriores, también puede solicitar al endpoint de resultados del lote que complete los datos de bbox ya calculados con `?include=bbox`:

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

Al hacerlo, cada valor de campo en `line_items` cambia de forma, de un escalar simple a `{"value": ..., "bbox": ...}`, con `bbox` establecido en `null` si no se ha calculado nada para ese campo:

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

`?include=bbox` solo lee datos que ya existen; nunca activa un nuevo trabajo de anotación facturable en su nombre. Si el bbox de un campo aún no se ha calculado, obtendrá `null` para ese campo, no un cargo implícito. Active la anotación explícitamente con `POST .../bbox` primero.

## Campos que son completamente una ubicación

Algunos campos no son un fragmento de texto con una ubicación incidental; el propósito completo del campo *es* la ubicación (por ejemplo, un campo que solicita "ubicar la foto de retrato" en un documento de identidad). Para estos, el valor se devuelve como un objeto más completo independientemente de si solicitó `?include=bbox`, ya que la ubicación *es* la respuesta, no metadatos opcionales sobre ella:

```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` apunta a `GET /documents/{document_id}/image?crop=...` — un recorte JPEG real y recuperable de esa región (rellenado ligeramente más ancho que las coordenadas brutas para que un recorte ajustado tenga menos probabilidades de recortar parte de lo que deseaba), no solo cuatro números que tendría que recortar de la imagen original usted mismo. También puede llamar a ese endpoint directamente con su propio `?crop=x1,y1,x2,y2` (misma convención normalizada 0–1) en cualquier documento, ya sea que provenga o no de un trabajo de bbox.

## Limitación conocida: las coordenadas son directas del modelo, no verificadas a nivel de píxel

Las coordenadas bbox provienen directamente del fundamento visual del modelo subyacente; no hay **ningún paso de verificación a nivel de píxel** que compruebe si un cuadro dado está dibujado de forma ajustada o holgada alrededor de su objetivo. En documentos simples y dispersos, esto suele ser lo suficientemente preciso como para usarlo directamente. En documentos complejos o densamente empaquetados — tablas con muchas columnas, formularios con campos muy espaciados — la precisión se degrada notablemente, y los cuadros pueden quedar demasiado ajustados, demasiado holgados u ocasionalmente hacer referencia al campo cercano incorrecto. **No trate la salida de bbox como una fuente de recorte exacta y perfecta a nivel de píxel** — si su flujo de trabajo depende de un recorte preciso (para OCR posterior, evidencia legal, etc.), verifique los resultados en lugar de confiar ciegamente en ellos, especialmente en diseños densos.

Los recortes de conveniencia de `image_url` (tanto para campos de ubicación pura como para sus propias llamadas `?crop=` contra un cuadro derivado de bbox) se generan con una pequeña cantidad de relleno alrededor de las coordenadas informadas, para reducir la posibilidad de que un cuadro demasiado ajustado recorte contenido real — esto es una medida de indulgencia, no una corrección de precisión. Las coordenadas `bbox` brutas devueltas en el propio JSON son siempre exactamente lo que informó el modelo, sin relleno.

## Facturación y configuración de la cuenta

El hecho de que se ejecute la anotación de bbox no depende al 100% de que usted mismo llame a los endpoints de bbox. Su cuenta tiene un ajuste — `auto_annotate_bbox`, configurado en la aplicación web, no a través de esta API — que, cuando está activado, activa automáticamente (y factura) un pase de bbox después de *cada* extracción completada, incluyendo las iniciadas a través de v1. Si su cuenta tiene este ajuste activado, se le puede facturar la anotación de bbox sin que usted llame nunca a `POST .../bbox`. Consulte [Configuración de la cuenta y comportamiento de la API](/developers/guides/account-settings) para obtener una visión completa de qué ajustes a nivel de cuenta la API permite o no anular por solicitud.

---

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