🌐 Protocolo de comunicación xPOS-Core

Contrato común para todos los países

Las fichas por país (Chile, Colombia, …) solo documentan lo que cambia respecto a este protocolo.

Fuente

Esta sección está sincronizada contra el contrato publicado en el Swagger de xPOS Core (http://localhost:3200/api/v1/doc/), versión 2.5.1 (OpenAPI 3.0).

📌 Modelo de operación

xPOS Core es la pieza local que recibe los documentos desde el POS, los transforma al formato que pide la autoridad tributaria del país y los envía (directamente o a través de la nube Gosocket, según el país).

Trabaja siempre en un solo ambiente a la vez, definido durante el onboarding:

Ambiente	Para qué sirve	Qué ocurre al emitir
Sandbox (sbx)	Desarrollo, QA y capacitación	Los documentos se procesan con datos ficticios y no llegan a la autoridad tributaria ni tienen efecto legal.
Producción (prd)	Operación real del cliente	Los documentos se emiten oficialmente: tienen efecto operativo, financiero y legal.

Cómo cambiar de ambiente

El ambiente no se alterna en caliente desde el query param env: lo fija el onboarding. Para mover un xPOS de Sandbox a Producción (o viceversa) hay que rehacer el onboarding desde el portal.

🔌 Cómo conectarse

xPOS Core corre como un servicio local en el equipo del cliente. El POS y cualquier integración lo consumen por loopback: no se publica a la red.

Puerto TCP

3200

API REST

http://localhost:3200/api/v1

WebSocket

ws://localhost:3200

Swagger UI

http://localhost:3200/api/v1/doc/

🧭 ¿Qué necesitas hacer?

El protocolo está documentado por tarea. Empieza por la que te toca:

Emitir documentosIntegraciónEl flujo principal: enviar un documento desde el POS con POST /process-documents (REST) o por WebSocket, validar antes de emitir y entender qué hace xPOS con tu documento.Response y erroresReferenciaEl objeto de respuesta campo a campo, la matriz de presencia por país y el contrato de manejo de errores (stage + errorDescription).Resiliencia y operaciónOperaciónRecuperar un response perdido, healthcheck para monitoreo, recarga de configuración, logs, cancelaciones (Paraguay) y endpoints de dashboard.Ejemplos de integraciónCódigoEl flujo completo implementado en los lenguajes más comunes (cURL, Python, JavaScript, TypeScript, Java, C#/.NET, Go y PHP).Códigos de erroresReferenciaCatálogo completo de etapas de error con la acción sugerida para el POS en cada caso.

🗂️ Catálogo de endpoints

Todo lo que xPOS Core expone hoy, agrupado por propósito, con la página donde está documentado cada grupo.

Document Processing — emisión y consulta de documentos

Documentado en Emitir documentos y Resiliencia y operación.

Método	Path	Para qué sirve
POST	/api/v1/process-documents	Endpoint principal: el POS lo invoca cada vez que necesita emitir un documento. xPOS lo arma, valida, firma (según operation) y lo envía.
POST	/api/v1/process-documents/other	Variante para inputs legacy en text/plain (formato pipe-delimitado). Solo aplica a integraciones puntuales.
GET	/api/v1/status	"¿Me puedes repetir la respuesta?" Recupera el resultado de un documento ya procesado, útil cuando el POS perdió la conexión.

Onboarding — vinculación con el portal Gosocket

Documentado en Resiliencia y operación.

Método	Path	Para qué sirve
GET	/api/v1/onboarding	Trae al equipo local la configuración del xPOS publicada en el portal de Gosocket (según uuid + env).
GET	/api/v1/onboarding/summary	Muestra el último onboarding ejecutado: útil para verificar contra qué se inicializó el servicio.

External Communication — eventos hacia fuera del POS

Documentado en Resiliencia y operación.

Método	Path	Para qué sirve
POST	/api/v1/cancelation-event	Notifica al xPOS que un documento ya emitido fue cancelado (la cancelación la registra el POS). Solo se usa en Paraguay.
POST	/api/v1/logs	Empuja hacia Gosocket los logs locales acumulados por xPOS.
PUT	/api/v1/reobtain-config	Pide al xPOS que vuelva a descargar su configuración desde el portal (útil cuando producto cambia parámetros).

Monitoring — ¿está vivo y sano?

Documentado en Resiliencia y operación.

Método	Path	Para qué sirve
GET	/api/v1/health	Healthcheck completo: estado del servicio, versión, certificados, conexiones, folios, validaciones de onboarding. Pensado para monitoreo externo.

Log — historial operativo

Documentado en Resiliencia y operación.

Método	Path	Para qué sirve
GET	/api/v1/db-data/logs	Lista los logs operativos en un rango de fechas, filtrando por logType.
GET	/api/v1/db-data/logs/search	Busca un log puntual por uuid de transacción o por metadata libre (params).

Dashboard — métricas que consume el portal/UI

Documentado en Resiliencia y operación.

Método	Path	Para qué sirve
GET	/api/v1/info/responses	Resumen de todas las respuestas que xPOS ha registrado.
GET	/api/v1/info/sii-responses	Solo las respuestas recibidas desde la entidad tributaria (API-ET).
GET	/api/v1/info/errors	Resumen de los errores registrados.