POST /v1/documents
Método principal del flujo ① — envía un PDF fiscal al pipeline de procesamiento de Docupath junto con sus metadatos. La IA del vertical Finn extrae los datos, los valida y exporta el resultado en Docupath AI Format (DIF), que luego se mapea al XML nativo de Gosocket.
Endpoint
https://api.docupathdev.app/v1/documentshttps://api.docupath.app/v1/documentsMétodo: POST · Autenticación: Authorization: Bearer {access_token} → ver POST /v1/oauth/token
Parámetros del body (multipart/form-data)
| Campo | Tipo | Req. | Descripción |
|---|---|---|---|
file | File | Requerido | Archivo del documento. Tipos: pdf, txt, doc, docx, png, jpg, jpeg. Máx: 50 MB / 150 páginas / 500 líneas. |
metadata | JSON (text) | Requerido | Objeto JSON con external_id y metadatos adicionales (ver estructura abajo) |
batch_id | String | Opcional | ID de lote generado por Gosocket para agrupar documentos relacionados. Docupath lo devuelve sin cambio como batchId en el Flujo ② |
El campo metadata debe enviarse como tipo text en el multipart/form-data, no como archivo. El JSON debe ser válido: true/false en minúscula, sin comas finales.
Estructura del campo metadata
{
"external_id": "0012-00003835",
"additional_metadata": {
"client_id": "ID_ORGANIZACION_EN_DOCUPATH",
"enrich_from_org": false
}
}
| Campo | Tipo | Descripción |
|---|---|---|
external_id | String (requerido) | ID único generado por Gosocket. Gosocket lo envía en el Flujo ① y Docupath lo devuelve sin cambio como externalId en el Flujo ② (UploadZipDocument). Clave de trazabilidad end-to-end. |
additional_metadata.client_id | String (requerido) | ID de la organización en Settings → Organizations de Docupath. ≠ al client_id de las credenciales OAuth. |
additional_metadata.enrich_from_org | Boolean (opcional) | Si true, Docupath enriquece el documento con datos de la organización configurada. |
Request / Response
POST {base_url}/v1/documents
Authorization: Bearer {access_token}
Content-Type: multipart/form-data
-- file: factura.pdf (campo tipo file)
-- metadata: (campo tipo text)
{
"external_id": "0012-00003835",
"additional_metadata": {
"client_id": "ID_ORGANIZACION_EN_DOCUPATH",
"enrich_from_org": false
}
}APIs de consulta disponibles
Docupath expone dos endpoints adicionales para consultar el estado e historial de documentos.
GET /v1/documents/search?external_id={id}— Gosocket sí lo integra: es el endpoint del Flujo ③ (consulta periódica / polling), usado para obtener el XML procesado (processed_info) y el PDF original (file_url) sin depender de que Docupath empuje el resultado vía el Flujo ②. Ver referencia completa.GET /v1/documents— lista documentos procesados en un rango de fechas (?start_timestamp=...&end_timestamp=...·?batch_id=...opcional). Gosocket no lo integra actualmente; queda registrado como referencia para monitoreo de lote.
Autenticación de ambos: Authorization: Bearer {access_token} (mismo token del POST).
Estados posibles del campo current_status:
| Estado | Descripción |
|---|---|
uploaded | Documento recibido, pendiente de procesamiento |
processing | La IA está extrayendo y validando los datos |
pending_review | Procesado — pendiente de revisión manual en el portal de Docupath. El XML y el PDF ya están disponibles en este estado, según pruebas contra DEV — ver Flujo ③ |
approved | Revisión manual completada |
rejected | Rechazado — no cumple las reglas de validación configuradas |
expired | El documento expiró sin ser procesado |
Formato de salida — Docupath AI Format (DIF)
Una vez aprobado un documento, Docupath lo exporta en Docupath AI Format (DIF), su formato interno unificado. A partir del DIF aplica el mapping al XML nativo de Gosocket (estructura <DTE><Documento><Encabezado>...), configurado en Settings → Destination Format & APIs del portal de Docupath.
El DIF es el formato interno de Docupath, no el XML que recibe Gosocket. Si aparecen inconsistencias de campos entre países o tipos de documento, contactar al equipo de Docupath con el external_id del documento afectado.