GET /v1/documents/search
Endpoint del flujo ③ — Gosocket consulta periódicamente (polling) el estado de un documento por su external_id hasta obtener el XML procesado y el PDF original, sin depender de que Docupath empuje el resultado vía UploadZipDocument (Flujo ②, que es solo una contingencia manual). Este endpoint es la base del proceso automático de la integración.
Endpoint
https://api.docupathdev.app/v1/documents/searchhttps://api.docupath.app/v1/documents/searchMétodo: GET · Autenticación: Authorization: Bearer {access_token} → ver POST /v1/oauth/token
¿Por qué Gosocket consume este endpoint?
El flujo ② (UploadZipDocument) depende de que Docupath empuje el resultado una vez el documento llega a estado approved. En la práctica esa transición requiere revisión manual en el portal de Docupath — la función de auto-aprobación ("autoreview") no se comporta de forma confiable, por lo que el push nunca ocurre o se demora indefinidamente. Para no depender de ese paso manual, Gosocket consulta este endpoint de forma periódica hasta obtener processed_info (XML procesado) y file_url (PDF original).
Parámetros
| Parámetro | Tipo | Req. | Descripción |
|---|---|---|---|
external_id (query) | String | Requerido | El mismo external_id que Gosocket generó y envió en POST /v1/documents |
Política de reintentos (polling)
Docupath no soporta webhooks ni reintentos automáticos — el propio proveedor documenta que la responsabilidad de reintentar es del sistema de integración. Gosocket implementa el polling con esta política:
| Parámetro | Valor |
|---|---|
| Intervalo entre consultas | 5 minutos |
| Máximo de reintentos | 10 |
| Ventana total de espera | ~50 minutos desde el envío del documento (Flujo ①) |
| Condición de éxito | current_status en pending_review o approved con processed_info presente en la respuesta |
| Condición de fin sin éxito | Reintentos agotados con current_status en uploaded / processing, o el documento pasa a rejected / expired |
Las pruebas contra el ambiente DEV muestran que processed_info y file_url ya están presentes en estado pending_review — antes de que alguien apruebe el documento manualmente en el portal de Docupath. Esto es lo que permite que el polling evite el cuello de botella del Flujo ②: Gosocket no necesita esperar a approved, solo a que exista processed_info en la respuesta.
Request / Response
GET {base_url}/v1/documents/search?external_id=0012-00003835
Authorization: Bearer {access_token}Campos de la respuesta
| Campo | Tipo | Descripción |
|---|---|---|
external_id | String | El mismo identificador enviado en el Flujo ① |
current_status | String (enum) | Ver Estados posibles |
processed_timestamp | DateTime | null | Fecha en que Docupath completó el procesamiento IA. En las pruebas contra DEV se observó siempre null, incluso en estado approved — pendiente confirmar con Docupath si se popula en otra configuración |
processed_info | String (XML) | XML procesado, en formato nativo de Gosocket — es el dato que satisface el criterio "obtener el XML procesado". Presente desde pending_review en adelante |
file_url | String (URL firmada) | URL al PDF original — satisface el criterio "obtener el PDF original". Es una URL firmada con expiración (parámetros Expires, Signature, Key-Pair-Id); debe descargarse de inmediato, no debe persistirse como referencia permanente |
Documentación previa de esta integración registraba el campo como document_url. Las respuestas capturadas en pruebas directas contra DEV devuelven file_url. Esta página usa el nombre confirmado por prueba directa; si una integración futura recibe document_url en su lugar, validar con el equipo de Docupath cuál es el nombre vigente en ese ambiente.
Estados posibles
| Estado | Descripción | processed_info / file_url disponibles |
|---|---|---|
uploaded | Documento recibido, pendiente de procesamiento | No |
processing | La IA está extrayendo y validando los datos | No |
pending_review | Procesado — pendiente de revisión manual en el portal de Docupath | Sí |
approved | Revisión manual completada | Sí |
rejected | Rechazado — no cumple las reglas de validación configuradas | No |
expired | El documento expiró sin ser procesado | No |
Catálogo de errores
| HTTP | Causa | Resolución |
|---|---|---|
| 401 | Token expirado o inválido | Solicitar nuevo access_token vía POST /v1/oauth/token |
No se ha confirmado el comportamiento cuando external_id no existe (404 vs. data vacío) ni el de /v1/documents/search en el ambiente PRD. Actualizar esta tabla cuando se confirme con pruebas.