¿Cómo funciona la integración Docupath?

Gosocket utiliza Docupath como motor de Intelligent Document Processing (IDP): envía PDFs fiscales al pipeline del vertical Finn, Docupath los interpreta con IA sin plantillas, extrae los datos estructurados y los devuelve a Gosocket en formato XML nativo listo para el pipeline fiscal.

Arquitectura general

La integración consta de tres mecanismos: dos flujos que operan sobre APIs distintas con autenticación diferente (① y ②), y un tercero (③) que reutiliza la misma API y autenticación del Flujo ① para consultar el resultado por polling. El Flujo ③ es el proceso automático de la integración; el Flujo ② es simplemente una contingencia manual para cuando alguien aprueba el documento a mano en el portal de Docupath. Gosocket genera external_id y batch_id al enviar el PDF (Flujo ①); Docupath los almacena y los devuelve sin cambio como externalId + batchId en el ZIP de respuesta (Flujo ②) — o Gosocket los recupera directamente consultando el estado (Flujo ③), cerrando el ciclo de trazabilidad por cualquiera de las dos vías.

Los flujos

El Flujo ① siempre ocurre: Gosocket envía el documento. Para obtener el resultado hay dos caminos: el Flujo ② es una contingencia manual — depende de que alguien apruebe el documento en el portal de Docupath — y el Flujo ③ es el proceso automático, en el que Gosocket obtiene el resultado por su cuenta sin depender de esa aprobación.

No todos comparten autenticación ni endpoint

El flujo ① usa OAuth 2.0 contra la API de Docupath. El flujo ② usa Basic Auth contra la API de Gosocket. El flujo ③ reutiliza la API y el access_token del flujo ① — no es una integración nueva, es una forma distinta de consumir la misma API.

Flujo ① — Gosocket → Docupath

Gosocket actúa como cliente de la API de Docupath. Envía el PDF fiscal y sus metadatos; Docupath lo procesa con IA y entrega el resultado de vuelta vía el flujo ② (UploadZipDocument).

1. Autenticación

Gosocket obtiene un access_token vía OAuth 2.0 Client Credentials (POST /v1/oauth/token). El token expira en ~1 hora y puede renovarse con el refresh_token.

2. Envío del documento

POST /v1/documents — multipart/form-data con el PDF (file) y los metadatos (external_id + client_id de la organización). Gosocket genera el external_id para trazabilidad.

3. Procesamiento IA

Docupath extrae datos con el vertical Finn (finanzas): duplicados, varianza de precio, reglas de negocio. El estado pasa de uploaded → processing → approved / rejected.

4. Entrega

Docupath empaqueta el XML resultante + el PDF original y los entrega a Gosocket vía UploadZipDocument (flujo ②). Los documentos con errores se gestionan desde el portal privado de Docupath.

Paso 1 — AutenticaciónPOSTObtiene el access_token OAuth 2.0. Credenciales desde el portal de Docupath.Paso 2 — Enviar documentoPOSTPOST /v1/documents con el PDF, external_id y batch_id.Paso 3 — Procesamiento y entregaProcesoDocupath procesa con IA y entrega el resultado a Gosocket vía flujo ②.

Flujo ② — Docupath → Gosocket (contingencia manual)

Gosocket recibe el documento procesado a través del endpoint UploadZipDocument. Una vez que el motor IA completa el procesamiento y alguien lo aprueba manualmente en el portal de Docupath, Docupath empaqueta el resultado (XML + PDF original) en un .zip y lo entrega a Gosocket. Al depender de esa aprobación manual, este flujo es solo una contingencia, no el mecanismo automático de la integración — ese rol lo cumple el Flujo ③, descrito a continuación.

1. Autenticación

Basic Auth con credenciales asignadas por Gosocket a Docupath (par Username + Password, uno por ambiente). No hay flujo de obtención de token; las credenciales van en cada request.

2. Preparación del ZIP

El .zip debe contener exactamente un XML y un PDF con el mismo nombre base. El XML debe estar en formato nativo de Gosocket. El contenido se codifica en Base64 para enviarlo como string en el body JSON.

3. Envío a Gosocket

POST /api/v1/UploadZipDocument — body JSON con country, externalId, batchId, fileBase64 (ZIP en Base64), fileExt="zip" y fileName. Gosocket registra el documento y retorna el estado.

4. Correlación

Gosocket genera externalId y batchId en el Flujo ① y Docupath los devuelve sin cambio. Deben mantenerse iguales en reintentos para no romper la trazabilidad end-to-end.

Paso 1 — AutenticaciónBasic AuthCredenciales asignadas por Gosocket a Docupath, una por ambiente.Paso 2 — Preparar el ZIPProcesoEmpaquetar XML + PDF con mismo nombre base, codificar en Base64.Paso 3 — Enviar el documentoPOSTPOST /api/v1/UploadZipDocument con ZIP en Base64, externalId y batchId.

Flujo ③ — Consulta periódica (Polling) — proceso automático

Gosocket consulta el estado del documento directamente en la API de Docupath, en lugar de esperar a que el Flujo ② lo entregue. Es el proceso automático de la integración: no depende de que alguien apruebe el documento a mano en el portal de Docupath, a diferencia del Flujo ② (contingencia manual, arriba). Existe porque la transición a approved requiere esa revisión manual — el autoreview no se comporta de forma confiable (Help Center de Docupath) — y las pruebas mostraron que el XML y el PDF ya están disponibles desde el estado pending_review, antes de cualquier aprobación manual, lo que permite que el polling resuelva el documento sin intervención humana.

1. Autenticación

Reutiliza el access_token OAuth 2.0 obtenido en el Flujo ①. No requiere credenciales ni endpoint adicionales.

2. Polling

GET /v1/documents/search?external_id={id} cada 5 minutos, hasta 10 reintentos (~50 minutos) por documento.

3. Evaluación

Si current_status es pending_review o approved y processed_info trae el XML, se considera resuelto. Si es uploaded o processing, se reintenta. Si es rejected/expired, o se agotan los reintentos, se marca error en la tabla de monitoreo.

4. Obtención

processed_info entrega el XML procesado directamente en la respuesta. file_url entrega una URL firmada (con expiración) para descargar el PDF original.

Paso 1 — AutenticaciónOAuth 2.0Reutiliza el access_token del Flujo ①.Paso 2 — Consultar periódicamenteGETGET /v1/documents/search cada 5 minutos, máx. 10 reintentos.Paso 3 — Obtener XML y PDFProcesoExtraer processed_info y descargar file_url.

Ciclo de vida del documento

Por dónde seguir

Gosocket → DocupathFlujoProceso paso a paso: autenticación OAuth 2.0, envío del PDF y entrega del resultado.Docupath → GosocketFlujoContingencia manual: preparación del ZIP y entrega del documento procesado cuando alguien lo aprueba a mano en el portal.Consulta periódica (Polling)FlujoProceso automático: reutiliza el access_token, consulta cada 5 minutos y extrae el XML y el PDF sin intervención manual.APIsReferenciaReferencia técnica completa de los cuatro métodos: autenticación, parámetros, ejemplos y errores.