Saltar al contenido principal
POST
Python
Envía un documento y la lista de campos que quieres leer de él. Didit ejecuta su modelo de extracción predeterminado sobre el archivo, devuelve cada campo con su tipo (text, number o date como YYYY-MM-DD), detecta y decodifica los códigos QR y de barras compatibles, comprueba si el archivo ha sido manipulado y, de forma opcional, compara el nombre que figura en el documento con la persona o empresa que esperas. Úsalo para pruebas de fondos, nóminas, extractos bancarios, documentos fiscales, facturas o cualquier documento que no se ajuste a una plantilla fija. Esta es la versión servidor a servidor del paso alojado de Document AI. La solicitud es multipart/form-data: el archivo va en document y las definiciones de campos van en fields como una única cadena con un array codificado en JSON.

Define los campos que se van a extraer

fields es un array JSON de 1 a 30 elementos, enviado como una sola cadena. Cada elemento tiene una key (letras minúsculas, dígitos y guiones bajos, única dentro de la solicitud), un name legible para las personas, una instruction que indica al modelo qué buscar, un type (text, number o date) y dos indicadores: required y is_full_name.
En una solicitud multipart, el array completo es un único valor del formulario:
La respuesta devuelve los fields normalizados y extracted_data indexado por tus valores de key, con null para todo lo que el modelo no haya podido encontrar. name, instruction y type son opcionales en cada elemento (type es text de forma predeterminada); key es obligatorio. Si envías fields como claves de formulario con corchetes (fields[0][key]=...) o en cualquier formato que no sea un array JSON, se devuelve 400 antes de ejecutar ninguna extracción, por lo que no se factura nada.

Códigos QR y códigos de barras

Toda respuesta exitosa incluye document_ai.detected_codes. Cada elemento contiene: El array abarca todas las páginas procesadas de un PDF y está vacío cuando no se encuentra ningún código admitido. Didit nunca adivina un payload: los códigos QR dañados pueden devolverse con su ubicación y parsed_payload: null, y los fallos en la detección de códigos no hacen fallar la solicitud de Document AI.

Coincidencia de nombres

Marca como máximo un campo con is_full_name: true y envía el nombre de la persona o empresa a la que esperas que pertenezca el documento: Envía un grupo o el otro, no ambos. Cuando se extrae un nombre y hay un nombre esperado, la respuesta incluye name_match_score (de 0 a 100) y name_on_document. Una puntuación inferior a document_ai_name_match_score_threshold (80 de forma predeterminada) genera la advertencia DOCUMENT_AI_NAME_MISMATCH y aplica document_ai_name_mismatch_action. Si ningún campo está marcado con is_full_name, Didit recurre al primer campo de texto cuya clave parezca un nombre (name, holder, full_name, account_holder); marca el campo de forma explícita cuando quieras controlar qué valor se compara. Cuando no se encuentra ningún nombre en el documento, o no se envía ningún nombre esperado, la comprobación del nombre se omite y name_match_score es null.

Riesgos y acciones

Cada riesgo de la siguiente tabla corresponde a un parámetro de acción que puedes definir en cada solicitud: DECLINE, REVIEW o NO_ACTION. La acción más estricta que se active determina document_ai.status (Declined > In Review > Approved), y cada riesgo activado aparece en document_ai.warnings. Los valores predeterminados coinciden con los del paso del flujo alojado; consulta Reglas y advertencias de Document AI para saber cómo se detecta cada riesgo.

Archivos, guardado y facturación

  • Archivos aceptados: PDF (se admiten varias páginas), JPG, JPEG, PNG, TIFF, WebP o un ZIP que contenga el documento, de hasta 30 MB. Los PDF cifrados devuelven 400; sube un PDF descifrado o una foto en su lugar.
  • save_api_request (true de forma predeterminada): la solicitud, los campos extraídos y los códigos detectados aparecen en la Business Console, en Manual Checks, donde tu equipo puede revisarlos. Establécelo en false para no guardarlos.
  • vendor_data y metadata se devuelven sin cambios en la respuesta para que puedas vincular el resultado con tus propios registros.
  • Precio: $0.20 por documento, que se factura cuando el documento se procesa y se devuelve un estado. Se aplica el descuento de tu plan. Consulta Precios.
¿Necesitas que el usuario suba el documento por sí mismo, que se recopilen hasta 3 documentos en un mismo flujo, que se traduzca automáticamente la pantalla de carga o que se crucen los campos extraídos con los datos del documento de identidad o del cuestionario? Usa en su lugar el paso del flujo de Document AI alojado.

Autorizaciones

x-api-key
string
header
requerido

La clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys.

Cuerpo

multipart/form-data
document
file
requerido

El documento que se va a leer. Extensiones permitidas: tiff, jpg, jpeg, png, pdf, webp, zip. Tamaño máximo de carga: 30 MB (los archivos más grandes se rechazan con 400). Se admiten PDF de varias páginas (con una latencia mayor); los PDF cifrados se rechazan con 400. Las imágenes se comprimen automáticamente antes del procesamiento.

fields
string
requerido

Una cadena con un array codificado en JSON con 1–30 definiciones de campos (máximo 16 KB). Cada elemento: key (obligatorio, ^[a-z0-9_]{1,64}$, único: la clave que se devuelve en extracted_data), name (≤100 caracteres, se muestra en los mensajes), instruction (≤500 caracteres, lo que el modelo debe leer), type (text por defecto | number | date), required (booleano, por defecto false), is_full_name (booleano, por defecto false, como máximo uno por solicitud). Los arrays de formulario con corchetes, el JSON no válido, las claves duplicadas o más de un is_full_name devuelven 400 antes de cualquier procesamiento o facturación.

Ejemplo:

"[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]"

expected_first_name
string

Nombre que se verifica contra el campo de nombre del documento (coincidencia aproximada, con soporte de transliteración). Úsalo junto con expected_last_name; no se puede combinar con expected_company_name.

Ejemplo:

"Sophia"

expected_last_name
string

Apellido que se verifica contra el campo de nombre del documento, combinado con expected_first_name para name_match_score.

Ejemplo:

"Martinez"

expected_company_name
string

Nombre de la empresa que se comparará con el campo de nombre del documento (para documentos de empresa). No se puede combinar con expected_first_name / expected_last_name (no tiene valor de ejemplo a propósito: el ejemplo de solicitud generado usa los campos de persona; sustitúyelos por este al verificar un documento de empresa).

expected_company_country
string

Código de país ISO 3166-1 alfa-2 opcional (dos letras ASCII, p. ej., FR) que ajusta la normalización del nombre de la empresa para expected_company_name. Solo se usa con expected_company_name.

document_ai_name_match_score_threshold
integer
predeterminado:80

name_match_score mínimo (0–100) para considerar que el nombre coincide. Una puntuación inferior añade DOCUMENT_AI_NAME_MISMATCH, que se rige por document_ai_name_mismatch_action.

Rango requerido: 0 <= x <= 100
Ejemplo:

80

document_ai_unreadable_document_action
enum<string>
predeterminado:REVIEW

Qué hacer cuando no se pudo leer ningún campo del documento (DOCUMENT_AI_UNREADABLE_DOCUMENT).

Opciones disponibles:
DECLINE,
REVIEW,
NO_ACTION
document_ai_missing_required_fields_action
enum<string>
predeterminado:REVIEW

Qué hacer cuando no se pudo leer al menos un campo required (DOCUMENT_AI_MISSING_REQUIRED_FIELDS; additional_data.missing_fields los enumera).

Opciones disponibles:
DECLINE,
REVIEW,
NO_ACTION
document_ai_document_tampering_action
enum<string>
predeterminado:DECLINE

Qué hacer cuando el análisis forense de PDF/EXIF sospecha una manipulación: modificación posterior a la firma digital, editor de PDF conocido, manipulación con texto superpuesto, reexportación sospechosa o anomalías en la imagen (DOCUMENT_AI_SUSPECTED_MANIPULATION).

Opciones disponibles:
DECLINE,
REVIEW,
NO_ACTION
document_ai_name_mismatch_action
enum<string>
predeterminado:NO_ACTION

Qué hacer cuando name_match_score está por debajo del umbral (DOCUMENT_AI_NAME_MISMATCH).

Opciones disponibles:
DECLINE,
REVIEW,
NO_ACTION
document_ai_unsupported_file_action
enum<string>
predeterminado:REVIEW

Qué hacer cuando el archivo subido está vacío o no se puede procesar (DOCUMENT_AI_UNSUPPORTED_FILE).

Opciones disponibles:
DECLINE,
REVIEW,
NO_ACTION
save_api_request
boolean
predeterminado:true

Cuando es true (valor predeterminado), guarda la llamada como una sesión de tipo API: visible en la Business Console, recuperable mediante GET /v3/session/{sessionId}/decision/ con el request_id devuelto, y con el documento subido, los valores extraídos, las definiciones de campos y la instantánea de la coincidencia de nombre almacenados. Cuando es false, no se almacena nada y request_id es un UUID temporal que solo sirve para correlacionar la respuesta; la llamada se factura igualmente.

Ejemplo:

true

vendor_data
string

Cadena opaca opcional (tu ID de usuario interno, correo electrónico, UUID…) que se guarda en la sesión persistida y se devuelve en la respuesta. Úsala para relacionar las llamadas a la API con tus propios registros y para filtrar sesiones más adelante.

Ejemplo:

"user-123"

metadata
object

Objeto JSON opcional que se almacena con la sesión (cuando save_api_request=true) y se devuelve en la respuesta. En solicitudes multipart, envíalo como un campo de cadena codificado en JSON (p. ej., metadata={"flow":"onboarding"}): se convierte en un objeto.

Ejemplo:

Respuesta

Documento procesado. document_ai.status es Approved, Declined o In Review; cada problema detectado se detalla en document_ai.warnings. Un documento con problemas también devuelve 200: revisa el cuerpo, no solo el código HTTP. Cuando save_api_request=true, request_id es el ID de la sesión guardada.

request_id
string<uuid>

ID de la sesión guardada cuando save_api_request=true (se puede usar con GET /v3/session/{sessionId}/decision/); en caso contrario, un UUID de correlación temporal.

document_ai
object
vendor_data
string | null

Devuelve el vendor_data que enviaste, o null.

metadata
object | null

Devuelve el objeto metadata que enviaste, o null.

created_at
string<date-time>

Fecha y hora en que se procesó la solicitud (UTC, ISO 8601).

Última modificación el 1 de noviembre de 2026