Referencia de la API
Referencia interactiva y especificación OpenAPI 3.1 de la API de Constaia, convenciones de /v1, generación de clientes e importación en Postman.
La API de Constaia se describe con OpenAPI 3.1. La especificación se genera desde el código de la API, así que siempre coincide con lo que está en producción.
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, Insomnia o Bruno, o validar respuestas en tus tests.
Convenciones
| URL base | https://api.constaia.com/v1 |
| Autenticación | Authorization: Bearer ck_live_… o ck_test_…. Las claves publicables (pk_live_…/pk_test_…) solo sirven para subir documentos a una sesión desde el navegador. Ver Autenticación. |
| Formato | JSON con nombres en snake_case. Los ficheros se suben con multipart/form-data o como file_url/file_base64 en JSON. |
| Ids | Prefijo + ULID: an_ (análisis), bat_ (lote), we_ (endpoint de webhook), exp_ (exportación), key_ (clave de API), req_ (petición), msg_ (entrega de webhook), tpl_ (plantilla), vl_ (enlace de verificación), dos_ (expediente), sess_ (sesión). |
| Fechas | ISO 8601 en UTC. |
| Errores | { "error": { "type", "code", "message", "param", "request_id" } }. Ver Errores. |
| Idempotencia | Cabecera Idempotency-Key en los POST de análisis, clasificación, lotes y endpoints de webhook. Ver Idempotencia. |
| Paginación | Por cursor con limit y starting_after; respuesta con has_more. Ver Paginación. |
| Límites | Por plan: 2 peticiones por segundo por clave, 2 análisis simultáneos y 60 páginas/min en el gratuito; 10, 10 y 600 en el de pago; ampliables por cuenta. Cabeceras RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset y RateLimit-Policy; en un 429, Retry-After. Ver Límites. |
| Trazabilidad | Cabecera X-Request-Id en todas las respuestas. Inclúyela si nos escribes por un problema. |
| CORS | Abierto en /v1, pero las claves secretas nunca deben usarse desde un navegador (403 secret_key_in_browser). Desde el navegador, solo claves publicables con sesión. |
| Versionado | Versión en la ruta (/v1). Ver Versionado y el changelog. |
SDK oficiales
Antes de generar un cliente, mira si hay SDK para tu lenguaje: JavaScript/TypeScript, PHP y Python. Incluyen reintentos con Retry-After, Idempotency-Key automática, límite de concurrencia, paginación y verificación de webhooks, cosas que un cliente generado no trae.
Próximamente
SDK oficiales para Go, Java, Ruby y .NET. Mientras tanto, genera un cliente a partir de la especificación o llama a la API con tu cliente HTTP (ver las guías de Go, Spring Boot, Rails y .NET).
Generar un cliente
Con OpenAPI Generator (versión 7 o superior, que admite OpenAPI 3.1):
npx @openapitools/openapi-generator-cli generate \
-i https://api.constaia.com/openapi.json \
-g go \
-o ./constaia-go \
--additional-properties=packageName=constaiaTen en cuenta al usar un cliente generado:
- En
multipart/form-data, el campooptionses un string con JSON, no un objeto. Serialízalo tú. - Las respuestas
202devuelven el mismo objeto que200, constatusqueuedoprocessing. - No incluye verificación de webhooks: usa el algoritmo de Webhooks.
- Añade tú los reintentos ante
429y5xxrespetandoRetry-After, y envíaIdempotency-Keyen los POST. - Regenera el cliente cuando el changelog anuncie campos nuevos. Ignora en tu código los campos que no conozcas.
Importar en Postman, Insomnia o Bruno
- Importa la especificación desde la URL
https://api.constaia.com/openapi.json(o descárgala e importa el fichero). - Crea una variable de entorno con tu clave, por ejemplo
constaia_api_key = ck_test_..., y configura la autenticación de la colección como Bearer Token con esa variable. - En
POST /v1/analyze, elige cuerpoform-data: campofilede tipo fichero y campooptionsde texto con el JSON, por ejemplo{"expect":"es_dni"}. - Usa ficheros con los nombres del modo test (
dni_valid.jpg,dni_expired.jpg…) para ver cada tipo de respuesta sin coste.
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/verification-links | Lista enlaces de verificación (filtros status, reference, metadata) |
| post | /v1/verification-links | Crea un enlace de verificación (página alojada + expediente) |
| get | /v1/verification-links/{id} | Recupera un enlace de verificación |
| delete | /v1/verification-links/{id} | Cancela un enlace de verificación |
| 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 |
| post | /v1/face-verifications/sessions | Abrir una sesión de captura (retos aleatorios) |
| post | /v1/face-verifications | Comparar una selfie con la foto de un documento |
| get | /v1/face-verifications/{id} | Consultar una verificación facial |
OpenAPI 3.1 · /openapi.json · 1.2.0
Siguientes pasos
Tipos de documento
Catálogo de tipos de documento de Constaia por categorías, con sus campos y validadores; cómo usar expect con varios tipos y generic con tu propio esquema.
SDK de JavaScript y TypeScript
Referencia de @constaia/sdk para Node.js, Bun, Deno y runtimes edge. Instalación, opciones, métodos, errores, reintentos y verificación de webhooks.