Referencia de la API
Referencia interactiva y especificación OpenAPI 3.1 de la API de Constaia, con un resumen de todos los endpoints de /v1.
La API de Constaia se describe con OpenAPI 3.1. Hay dos formas de consultarla:
Referencia interactiva
Todos los endpoints, parámetros y respuestas. Puedes probar llamadas con tu clave ck_test_.
openapi.json
La especificación en JSON para generar clientes, importar en Postman o Insomnia o validar respuestas en tus tests.
Convenciones
| URL base | https://api.constaia.com/v1 |
| Autenticación | Authorization: Bearer ck_live_… o ck_test_…. Ver Autenticación. |
| Formato | JSON con nombres en snake_case. Los ficheros se suben con multipart/form-data. |
| Ids | Prefijo + ULID: an_ (análisis), bat_ (lote), we_ (endpoint de webhook), exp_ (exportación), req_ (petición). |
| Errores | { "error": { "type", "code", "message", "param", "request_id" } }. Ver Errores. |
| Idempotencia | Cabecera Idempotency-Key en cualquier POST. Ver Idempotencia. |
| Límites | 10 peticiones por segundo por clave, cabeceras RateLimit-*. Ver Límites. |
| Trazabilidad | Cabecera X-Request-Id en todas las respuestas. Inclúyela si nos escribes por un problema. |
Generar un cliente
Si trabajas en un lenguaje sin SDK oficial, puedes generar un cliente a partir de openapi.json con la herramienta que ya uses (por ejemplo, OpenAPI Generator). Mientras tanto, los SDK de JavaScript y PHP cubren toda la API y la guía de Python muestra cómo llamarla con httpx.
Resumen de endpoints
El resumen de abajo se genera a partir de un fichero OpenAPI de ejemplo incluido en esta web, para que puedas ver los endpoints de un vistazo. La fuente de verdad es siempre api.constaia.com/openapi.json.
| post | /v1/analyze | Analiza un documento y devuelve veredicto, campos y checks |
| post | /v1/classify | Solo clasifica el documento (0,2 créditos) |
| get | /v1/analyses | Lista análisis (paginada) |
| get | /v1/analyses/{id} | Recupera un análisis (si keep_results) |
| delete | /v1/analyses/{id} | Borra fichero y resultados |
| get | /v1/analyses/{id}/export | Descarga directa de una exportación |
| post | /v1/batches | Crea un lote de hasta 100 documentos (siempre async) |
| get | /v1/batches/{id} | Estado de un lote |
| get | /v1/document-types | Catálogo de tipos con campos y checks |
| get | /v1/document-types/{type} | Detalle de un tipo |
| get | /v1/webhook-endpoints | Lista endpoints |
| post | /v1/webhook-endpoints | Alta de un endpoint de webhook (devuelve el secret whsec_ una vez) |
| delete | /v1/webhook-endpoints/{id} | Borra un endpoint |
| get | /v1/balance | Créditos disponibles, reservados y plan gratis |
| get | /v1/usage | Uso agregado por día y tipo |
OpenAPI 3.1 · /openapi.json · 1.0.0
Catálogo de tipos de documento
Tipos de documento que reconoce Constaia, con sus campos, validadores y países. Cómo usar expect con varios tipos y generic con tu esquema.
SDK de JavaScript y TypeScript
@constaia/sdk: cliente oficial para Node.js 18+, Bun y Deno, sin dependencias. Análisis, lotes, webhooks, errores tipados y reintentos.