Documentos dentro. JSON trazable fuera.

Crear un trabajo

POST https://formatara.com/api/v1/documents
Authorization: Bearer ptk_••••
Content-Type: multipart/form-data

file=@contrato.pdf

→ 202 Accepted
{
  "document": {
    "id": "018f...",
    "status": "queued",
    "pageCount": 4
  }
}

PDF protegido con contraseña

Si la carga devuelve status: "password_required", envía la contraseña en el cuerpo de esta segunda petición. Solo se usa para preparar una copia de trabajo desbloqueada: no se almacena ni se incluye en la cola. El OCR no empieza hasta que la contraseña es correcta.

→ 202 Accepted
{
  "document": {
    "id": "018f...",
    "status": "password_required"
  }
}

POST https://formatara.com/api/v1/documents/{id}/password
Authorization: Bearer ptk_••••
Content-Type: application/json

{ "password": "••••••••" }

→ 202 Accepted
{ "document": { "id": "018f...", "status": "queued" } }

Consultar el resultado

GET https://formatara.com/api/v1/documents/{id}

{
  "document": {
    "status": "completed",
    "result": {
      "pages": [{
        "number": 1,
        "blocks": [{
          "type": "table",
          "bbox": [84, 322, 918, 704],
          "confidence": null,
          "table": { "rows": [["Concepto", "Total"]] }
        }]
      }]
    }
  }
}

Exportar y corregir

• POST /api/v1/documents/{id}/exports con {"mode":"editable"}. Conserva el export.id de la respuesta.
• Consulta GET /api/v1/documents/{id}/exports/{exportId} hasta recibir status: "completed" y downloadUrl. Si sigue en queued, repite el mismo POST: la operación es idempotente y no crea otra exportación.
• La exportación Word disponible es editable: reconstruye textos, campos, tablas y formularios según su posición en la página, también cuando los bordes de una tabla están incompletos. Las fotografías, los logotipos y los sellos reconocidos se conservan como imágenes.
• GET /api/v1/documents/{id}/export?format=json|markdown|csv
• PATCH /api/v1/documents/{id} con correcciones de texto o celdas.

Límites de entrada

• Se admiten documentos multipágina; cada página consume una unidad de saldo y el procesador mantiene un máximo técnico de 500 páginas y 200 MB por trabajo.
• PDF, PNG, JPG, WEBP y TIFF. Los PDF protegidos requieren el paso de contraseña anterior.
• El pageCount inicial puede ser una estimación; el recuento real se reconcilia al terminar.

Decisiones de diseño

• El OCR es asíncrono porque un documento puede tardar varios minutos. La exportación Word usa un recurso de trabajo idempotente para evitar duplicados.
• La cuota se reserva al aceptar el documento, se reconcilia con el recuento real y se devuelve ante fallo.
• La confianza permanece en null cuando no existe una puntuación suficientemente fiable.
• bbox puede ser null cuando no hay coordenadas válidas.
• Las exportaciones no vuelven a consumir créditos.
• Los tokens se muestran una sola vez; Formatara conserva únicamente SHA-256.