Constaia

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.

Convenciones

URL basehttps://api.constaia.com/v1
AutenticaciónAuthorization: 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.
FormatoJSON con nombres en snake_case. Los ficheros se suben con multipart/form-data o como file_url/file_base64 en JSON.
IdsPrefijo + 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).
FechasISO 8601 en UTC.
Errores{ "error": { "type", "code", "message", "param", "request_id" } }. Ver Errores.
IdempotenciaCabecera Idempotency-Key en los POST de análisis, clasificación, lotes y endpoints de webhook. Ver Idempotencia.
PaginaciónPor cursor con limit y starting_after; respuesta con has_more. Ver Paginación.
LímitesPor 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.
TrazabilidadCabecera X-Request-Id en todas las respuestas. Inclúyela si nos escribes por un problema.
CORSAbierto 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.
VersionadoVersió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=constaia

Ten en cuenta al usar un cliente generado:

  • En multipart/form-data, el campo options es un string con JSON, no un objeto. Serialízalo tú.
  • Las respuestas 202 devuelven el mismo objeto que 200, con status queued o processing.
  • No incluye verificación de webhooks: usa el algoritmo de Webhooks.
  • Añade tú los reintentos ante 429 y 5xx respetando Retry-After, y envía Idempotency-Key en 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

  1. Importa la especificación desde la URL https://api.constaia.com/openapi.json (o descárgala e importa el fichero).
  2. 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.
  3. En POST /v1/analyze, elige cuerpo form-data: campo file de tipo fichero y campo options de texto con el JSON, por ejemplo {"expect":"es_dni"}.
  4. 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/analyzeAnaliza un documento y devuelve veredicto, campos y checks
post/v1/classifySolo clasifica el documento (0,2 créditos)
get/v1/analysesLista 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}/exportDescarga directa de una exportación
post/v1/batchesCrea un lote de hasta 100 documentos (siempre async)
get/v1/batches/{id}Estado de un lote
get/v1/document-typesCatálogo de tipos con campos y checks
get/v1/document-types/{type}Detalle de un tipo
get/v1/verification-linksLista enlaces de verificación (filtros status, reference, metadata)
post/v1/verification-linksCrea 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-endpointsLista endpoints
post/v1/webhook-endpointsAlta de un endpoint de webhook (devuelve el secret whsec_ una vez)
delete/v1/webhook-endpoints/{id}Borra un endpoint
get/v1/balanceCréditos disponibles, reservados y plan gratis
get/v1/usageUso agregado por día y tipo
post/v1/face-verifications/sessionsAbrir una sesión de captura (retos aleatorios)
post/v1/face-verificationsComparar 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

En esta página