GET /v1/document-types
Referencia de GET /v1/document-types: catálogo público de tipos de documento con campos, JSON Schema, validadores y checks aplicables, sin clave de API.
GET /v1/document-types devuelve el catálogo de tipos de documento que reconoce Constaia: el type que pasas en expect, sus campos, el JSON Schema de extracción, los validadores que se ejecutan y los checks que admite. Es la fuente de verdad del catálogo: cuando se añade un tipo, aparece aquí.
Es público: no necesita clave ni consume créditos. Se puede cachear (la respuesta lleva Cache-Control: public, max-age=300).
| Método y ruta | Qué hace |
|---|---|
GET /v1/document-types | Lista los tipos (todo el catálogo, 167 tipos, en una página por defecto), con filtros opcionales. |
GET /v1/document-types/{type} | Detalle de un tipo. 404 resource_missing si no existe. |
Para leer el catálogo en formato humano, mira la página de tipos de documento o el catálogo completo.
Parámetros
| Parámetro | Valores | Por defecto | Descripción |
|---|---|---|---|
language | es, en, pt, fr | es | Idioma de label, description y slug. labels, descriptions y slugs traen siempre los cuatro idiomas. |
country | ISO 3166-1 alfa-3 (ESP, USA, MEX…) | — | Tipos que se emiten en ese país. Incluye los universales (countries: ["*"], como passport o invoice) salvo con strict=true. |
strict | true, false | false | Con country, excluye los tipos universales. |
category | identity, residence, driving, certificate, health, education, employment, tax, finance, address, legal, vehicle, civil, sports, other | — | Tipos de esa categoría. |
q | texto (máx. 100) | — | Búsqueda sin tildes ni mayúsculas en el type, las etiquetas, las descripciones y las palabras clave de cada tipo. Todas las palabras deben aparecer. |
limit | 1–500 | 500 | Tipos por página. Por defecto cabe el catálogo completo. |
starting_after | type | — | Cursor: devuelve los tipos que van después de este. |
Los parámetros de GET /v1/document-types/{type} se reducen a language. Un valor no válido (por ejemplo, country=ES) devuelve 422 invalid_parameter.
# Tipos de EE. UU. sin los universales, en inglés
curl -s 'https://api.constaia.com/v1/document-types?country=USA&strict=true&language=en' \
| jq '{total, types: [.data[].type]}'
# Buscar por texto
curl -s 'https://api.constaia.com/v1/document-types?q=vida%20laboral' | jq -r '.data[].type'Respuesta
Listado
{
"object": "list",
"data": [ { "object": "document_type", "type": "es_dni", "…": "…" } ],
"has_more": false,
"total": 167,
"url": "/v1/document-types"
}total es el número de tipos que cumplen los filtros (no solo los de esta página). Para paginar, pasa en starting_after el type del último elemento mientras has_more sea true. Más en Paginación.
Detalle
Respuesta real de GET /v1/document-types/es_dni?language=en, con schema.properties recortado a tres campos:
curl -s 'https://api.constaia.com/v1/document-types/es_dni?language=en'{
"object": "document_type",
"type": "es_dni",
"label": "Spanish ID card (DNI)",
"labels": {
"es": "DNI (España)",
"en": "Spanish ID card (DNI)",
"pt": "Documento de identidade espanhol (DNI)",
"fr": "Carte d'identité espagnole (DNI)"
},
"description": "Spanish national identity card, front and back.",
"descriptions": { "es": "…", "en": "…", "pt": "…", "fr": "…" },
"category": "identity",
"countries": ["ESP"],
"slug": "spanish-id-card-dni",
"slugs": {
"es": "dni-espana",
"en": "spanish-id-card-dni",
"pt": "documento-de-identidade-espanhol-dni",
"fr": "carte-d-identite-espagnole-dni"
},
"fields": [
"document_number", "first_name", "last_name_1", "last_name_2", "sex", "nationality",
"birth_date", "expiry_date", "issue_date", "support_number", "address", "birth_place",
"parents", "mrz"
],
"schema": {
"type": "object",
"properties": {
"document_number": { "type": "string", "description": "Número de DNI (8 cifras + letra)" },
"sex": { "type": "string", "description": "Sexo (M/F)", "enum": ["M", "F", "X"] },
"birth_date": { "type": "string", "description": "Fecha de nacimiento", "format": "date" }
},
"additionalProperties": false
},
"validators": ["nif_check_digit", "mrz_checksums", "mrz_matches_visual", "not_expired", "holder", "age"],
"field_validators": [],
"checks": ["not_expired", "reference_date", "min_age_years", "max_age_years", "holder", "require_fields"],
"expiry_check_default": true,
"mrz": "TD1",
"signed_pdf": false,
"i9_lists": null
}| Campo | Descripción |
|---|---|
object | Siempre "document_type". |
type | Identificador que usas en expect y que recibes en document.type. |
label | Nombre en el idioma de language. |
labels | Nombre en es, en, pt y fr. |
description | Descripción breve en el idioma de language. descriptions la trae en los cuatro idiomas. |
slug, slugs | Identificador de la página del tipo en el catálogo, en el idioma de language y en los cuatro. |
category | Una de las 15 categorías del parámetro category. |
countries | Países ISO alfa-3 donde se emite. * significa cualquier país. |
fields | Nombres de los campos que devuelve extract: true, en orden. |
schema | JSON Schema de esos campos: tipo, formato (date), valores permitidos (enum) y descripción. Las description del esquema están en español. |
validators | Validaciones que Constaia aplica a este tipo (por ejemplo aamva_barcode, id_number, pdf_signature, i9_list). |
field_validators | Identificadores que se validan por campo: { field, scheme }, con scheme de @constaia/validators (us_dl, us_zip, br_cpf…). |
checks | Opciones de checks que tienen efecto en este tipo. Una opción fuera de esta lista no se evalúa. |
expiry_check_default | true si not_expired se comprueba por defecto (tipos con caducidad). |
mrz | Formato de MRZ que se lee localmente (TD1, TD2, TD3) o null. |
signed_pdf | true si el documento se descarga firmado de una sede electrónica: admite require_valid_signature. Ver Firmas digitales en PDF. |
i9_lists | Listas del formulario I-9 de EE. UU. (A, B, C) a las que pertenece, o null. Ver Documentos de EE. UU.. |
Usos habituales
Validar tu configuración al arrancar
Si tu aplicación guarda qué expect y checks usa cada formulario, compruébalo contra el catálogo al desplegar: detectarás un tipo mal escrito o un check que no aplica antes de que falle un análisis.
Construir formularios o pantallas de revisión
schema describe cada campo con tipo, formato y valores posibles. Puedes generar un formulario de revisión manual: un input type="date" para format: "date", un selector para enum, y usar description como ayuda.
Partir del esquema para un extract propio
Si solo necesitas algunos campos, copia las propiedades que te interesan del schema y pásalas en extract. fields devolverá solo los campos de tu esquema. Ver Extraer campos con tu propio esquema.
# Tipos de identidad de España (y los universales)
curl -s 'https://api.constaia.com/v1/document-types?country=ESP&category=identity&language=es' \
| jq -r '.data[] | "\(.type)\t\(.label)"'El catálogo crece. Tu código no debería fallar si recibe en document.type un tipo que no conoce: trátalo como "otro" y mándalo a revisión.
Siguientes pasos
POST /v1/batches
Referencia de POST /v1/batches: analiza hasta 100 documentos en una llamada asíncrona, con opciones comunes o por documento y export combinado.
Saldo y consumo
Referencia de GET /v1/balance y GET /v1/usage: créditos de packs, plan gratuito, reservas y consumo diario por tipo de documento, con ejemplos.