🌐 Protocolo de comunicacion xPOS-Core

Contrato comun para todos los paises

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

Fuente

Esta pagina esta sincronizada contra el contrato publicado en el Swagger de xPOS Core (http://localhost:3200/api/v1/doc/), version 2.5.1 (OpenAPI 3.0).

📌 Modelo de operacion

xPOS Core es la pieza local que recibe los documentos desde el POS, los transforma al formato que pide la autoridad tributaria del pais y los envia (directamente o a traves de la nube Gosocket, segun el pais).

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

Ambiente	Para que sirve	Que ocurre al emitir
Sandbox (sbx)	Desarrollo, QA y capacitacion	Los documentos se procesan con datos ficticios y no llegan a la autoridad tributaria ni tienen efecto legal.
Produccion (prd)	Operacion real del cliente	Los documentos se emiten oficialmente: tienen efecto operativo, financiero y legal.

Como 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 Produccion (o viceversa) hay que rehacer el onboarding desde el portal.

🔌 Como conectarse

xPOS Core corre como un servicio local en el equipo del cliente. El POS y cualquier integracion 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/

🧭 Catalogo de endpoints

Todo lo que xPOS Core expone hoy, agrupado por proposito. Las secciones siguientes profundizan en cada grupo; esta es la vista de pajaro.

Document Processing — emision y consulta de documentos

Metodo	Path	Para que sirve
POST	/api/v1/process-documents	Endpoint principal: el POS lo invoca cada vez que necesita emitir un documento. xPOS lo arma, valida, firma (segun operation) y lo envia.
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 podes repetir la respuesta?" Recupera el resultado de un documento ya procesado, util cuando el POS perdio la conexion.

Onboarding — vinculacion con el portal Gosocket

Metodo	Path	Para que sirve
GET	/api/v1/onboarding	Trae al equipo local la configuracion del xPOS publicada en el portal de Gosocket (segun uuid + env).
GET	/api/v1/onboarding/summary	Muestra el ultimo onboarding ejecutado: util para verificar contra que se inicializo el servicio.

External Communication — eventos hacia fuera del POS

Metodo	Path	Para que sirve
POST	/api/v1/cancelation-event	Notifica al xPOS que un documento ya emitido fue cancelado (la cancelacion 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 configuracion desde el portal (util cuando producto cambia parametros).

Monitoring — ¿esta vivo y sano?

Metodo	Path	Para que sirve
GET	/api/v1/health	Healthcheck completo: estado del servicio, version, certificados, conexiones, folios, validaciones de onboarding. Pensado para monitoreo externo.

Log — historial operativo

Metodo	Path	Para que 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 transaccion o por metadata libre (params).

Dashboard — metricas que consume el portal/UI

Metodo	Path	Para que 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.

🔗 Integracion REST

El flujo principal — emitir un documento desde el POS — se invoca con POST /api/v1/process-documents.

Que parametros lleva en la URL

Todos van como query params (?env=…&operation=…&…) y los cinco son obligatorios.

Parametro	Valores	Para que sirve
env	sbx | prd	Ambiente operativo (debe coincidir con el del onboarding).
operation	test | consolidate	test valida sin emitir; consolidate emite y registra de verdad (ver flujo abajo).
typeDoc	string	Tipo de documento (factura, boleta, NC, NV, etc.). Cada pais usa su propia tabla — ver ficha del pais.
country	cl | co | cr | sv | gt | pa | py | do	Codigo ISO del pais que opera el xPOS.
inputType	json | xml | xdoc | txt	Formato del documento que envias en el body. Cada pais soporta un subconjunto — ver ficha del pais.

Que va en el body

El documento del POS, en el formato declarado en inputType:

• json: se envia tal cual, como JSON.
• xml / xdoc / txt: se envian codificados en base64 cuando el pais asi lo requiere.

Que hace xPOS Core con tu documento

xPOS aplica uno de tres patrones internos segun el pais. La diferencia esta en si el formato tributario final es XML o JSON, y en si hay bifurcacion por tipo de documento.

Patron A — XML con XSD (mayoria de paises)

Cuando llega un documento con operation=consolidate:

1. Recibe el input (json, xml, xdoc o txt).
2. Si el input no es XML, lo transforma a XML <root>.
3. Aplica input_to_dte_<pais>.xslt → XML Gosocket.
4. Aplica dte_to_fiscal_<pais>.xslt → DTE tributario.
5. Valida el resultado contra el XSD oficial.
6. Asigna folio (si el Gestor de Folios esta activo).
7. Firma el DTE.
8. Lo envia a la entidad tributaria.
9. Devuelve la respuesta al POS.
10. Publica el DTE en Gosocket (Inbox).

Patron B — JSON con JSON Schema

Igual que el Patron A, pero los pasos 4 y 5 generan JSON tributario y validan contra JSON Schema en lugar de XSD.

Patron C — XML dual

Igual que el Patron A, pero el paso 4 se bifurca segun el tipo de documento (DTE tributario vs. equivalente, cada uno con su XSLT).

Que cambia con operation = test

test ejecuta solo los pasos 1–5 (transformacion + validacion). No asigna folio, no firma, no envia a la entidad tributaria y no publica en Gosocket. Sirve para validar que el documento esta bien armado antes de emitirlo en serio.

🔄 Integracion por Socket

nota

El canal Socket no aparece en el Swagger (OpenAPI 3.0 no modela WebSockets). El contrato funcional descrito aqui es el acuerdo de implementacion para la integracion ws://localhost:3200.

Mismo flujo funcional que REST, con la diferencia de que los parametros viajan dentro del objeto de request (no en query params).

Como se envia

Se arma un objeto con el mismo contenido que el POST REST:

{"env":"sbx","operation":"consolidate","typeDoc":<N>,"country":"<XX>","inputType":"json","document":{...}}

Ese objeto se serializa a string y el string se envia en base64. El servidor procesa y responde tambien en base64; al decodificar, la estructura es equivalente al response REST.

📬 Response

Independientemente del canal (REST o Socket), xPOS Core devuelve un objeto JSON con dos partes: un nucleo comun que aparece siempre y un subconjunto opcional que depende del pais. La ficha de cada pais indica que campos aparecen y como interpretarlos.

Ejemplo de response completo

Este es el shape completo del response: incluye todos los campos posibles. Los valores aparecen como null cuando el pais o la operacion no los aplica. Ver el tab Response (shape completo) en la seccion Como se envia mas arriba.

Campos del nucleo (todos los paises)

Campo	Tipo	Descripcion
transactionId	string (UUID)	UUID de transaccion xPOS.
message	string	Operation Successful o Operation Error.
custom_response	string | null	Contenido de custom_response_<pais>.xslt cuando aplica.
errorDescription	string	Error de transformacion o validacion (solo en error).
stage	string	Etapa donde ocurre el error (solo en error).
number	string	Numero o folio del documento tributario.
docNumber	string	Serie y numero del documento (formato definido por pais, p. ej. SETP990044419).
output	string (base64)	Documento tributario firmado generado por xPOS (XML o JSON segun pais).
signedXml	string (base64)	DTE fiscal revisado por la entidad tributaria. Mismo contenido que output.
input	string (base64)	Documento de origen recibido del POS.

¿Y cuando hay error?

Cuando message es Operation Error (o Operation Successful con observacion en codigo 200), los campos stage y errorDescription indican exactamente que paso. Ver la seccion Manejo de errores para el contrato de integracion y el catalogo completo de codigos para la accion recomendada por etapa.

Codigo visual (QR / PDF417)

Campo	Tipo	Descripcion
barcodeText	string	Texto del codigo de barras / QR.
barcodeBase64	string (base64)	Codigo de barras / QR en base64.

Chile usa PDF417 y solo devuelve barcodeBase64. El resto de los paises usa QR y devuelve ambos campos.

Identificacion tributaria

Campo	Tipo	Descripcion
countryIdentificationCode	string	Identificador tributario del documento (CUDE/CUFE, codigo de generacion, CDC, e-NCF, etc., segun pais).

Eco de la entidad tributaria

Estos campos aparecen cuando la autoridad tributaria responde de forma sincronica al envio. Los paises con respuesta asincrona (Chile, Paraguay) no los devuelven en el response inicial — se consultan despues via /api/v1/status.

Campo	Tipo	Descripcion
statusCode	string	Codigo devuelto por la entidad tributaria.
statusDescription	string	Descripcion devuelta por la entidad.
statusMessage	string	Mensaje devuelto por la entidad.
applicationResponse	string (base64)	Respuesta integral de la entidad (XML o JSON segun pais).
timeGeneration	string	Hora de generacion del documento (HH:mm:ss±tz).
timeValidation	string	Hora de validacion en la entidad (HH:mm:ss±tz).

Contingencia

Campo	Tipo	Descripcion
contingencyCode	string	Codigo de contingencia definido por la autoridad tributaria del pais. Aplica a todos los paises excepto Chile y Paraguay (modelo asincrono — la nube Gosocket gestiona la contingencia).

Matriz de presencia por pais

Campo	CL	CO	CR	SV	GT	PA	PY	DO
barcodeText	–	✓	✓	✓	✓	✓	✓	✓
barcodeBase64	✓¹	✓	✓	✓	✓	✓	✓	✓
countryIdentificationCode	–	✓	✓	✓	✓	✓	✓	✓
statusCode / statusDescription / statusMessage	–	✓	✓	✓	✓	✓	–	✓
applicationResponse	–	✓	✓	✓	–	✓	–	✓
timeGeneration	–	✓	✓	✓	–	✓	–	✓
timeValidation	–	✓	✓	✓	–	✓	–	–
contingencyCode	–	✓	✓	✓	✓	✓	–	✓

¹ Chile devuelve barcodeBase64 en formato PDF417 (no QR).

Cada ficha de pais incluye un mock de response con valores ilustrativos. Ver Comunicacion por pais.

🚦 Manejo de errores

xPOS-Core expresa cualquier resultado anomalo —error de validacion, rechazo de la entidad tributaria, fallback de contingencia o reintento programado— a traves de tres campos del nucleo del response: message, stage y errorDescription. El catalogo completo de etapas vive en Codigos de errores xPOS-Core; esta seccion describe el contrato de integracion que el POS debe respetar para reaccionar a cada caso.

Contrato del response

Cuando una operacion no termina en exito, xPOS pobla los tres campos asi:

Campo	Valor	Como leerlo
message	Operation Error (errores) u Operation Successful (codigo 200 con observacion).	Distingue un fallo del flujo normal con anotacion operativa.
stage	Nombre simbolico de la etapa: TRANSFORM_JSON_STAGE, VALIDATE_XSD_STAGE, DIAN_RESPONSE_STAGE, etc.	Llave para localizar la fila en el catalogo.
errorDescription	Mensaje humano-legible. Algunas etapas reenvian el mensaje de la entidad tributaria (DIAN, MH, SAT/Megaprint, DGII).	El POS puede mostrarlo al operador o parsearlo cuando la etapa tiene formato estable (p. ej. duplicidad).

Ejemplo de response en error: ver el tab Response — Error en la seccion Como se envia mas arriba.

Stage code vs. HTTP status

El stage code (200 / 400 / 404 / 503 / 510) que aparece en el catalogo es una etiqueta operativa interna, no el status HTTP devuelto por la API REST. xPOS-Core lo entrega dentro del cuerpo del response; el status HTTP del transporte sigue las reglas estandar del API.

Que tiene que hacer el POS

Cada fila del catalogo trae una accion sugerida que el POS deberia adoptar como contrato:

Accion	Decision del POS
Corregir y reintentar	El input es el responsable. Corregir el dato indicado por errorDescription y reenviar POST /api/v1/process-documents.
Reintentar	Error transitorio (red, token, validacion temporal). Reenviar tal cual.
Recargar y reintentar	El estado local del xPOS no esta sano (folios, certificados, plantillas). Llamar a PUT /api/v1/reobtain-config y reenviar.
Corregir	Revisar el caso sin reenviar automaticamente (la entidad tributaria ya respondio y deja la accion al operador).
Fin del proceso	No requiere accion del POS (documento duplicado, reintento automatico programado en xPOS, o escalamiento manual a Gosocket).

Cuando el POS pierde el response

Si la red se corto o el POS reinicio antes de procesar el response, no hace falta reenviar el documento: el endpoint GET /api/v1/status recupera el response original a partir del transactionId o el docNumber (ver seccion Reobtencion de estados mas abajo). Para diagnostico mas profundo (auditoria, escalamiento), los logs operativos en GET /api/v1/db-data/logs se filtran por uuid o metadata libre.

♻️ Reobtencion de estados

¿El POS perdio la respuesta original (problema de red, reinicio, auditoria)? No es necesario reenviar el documento: con cualquiera de los identificadores siguientes se recupera la respuesta original.

• Metodo: GET
• Endpoint: http://localhost:3200/api/v1/status

Query params

Parametro	Tipo	Requerido	Descripcion
transactionId	string	No	UUID de transaccion devuelto en la emision original.
docNumber	string	No	Numero o folio del documento.
typeDoc	string	No	Tipo de documento.

Se necesita al menos un parametro para identificar el documento. Algunos paises requieren combinaciones especificas — ver ficha del pais.

Respuesta

El Swagger declara los siguientes campos en la respuesta 200:

Campo	Tipo	Descripcion
input	string	Documento de origen.
custom_response	string	Salida de custom_response_<pais>.xslt cuando aplica.
message	string	Resultado de la consulta.
pdf417	string	PDF417 (solo Chile).
signedXml	string	XML firmado del documento.

Respuesta 400: { date, message, stage, uuid, _id }.

🩺 Healthcheck

"¿Esta vivo y sano?" Devuelve el estado operativo del xPOS Core para que cualquier monitor externo pueda verificarlo sin tocar la operacion.

• Metodo: GET
• Endpoint: /api/v1/health

La respuesta 200 incluye:

• status, message (ok cuando todo esta sano).
• cwd, xposVersion, schemaVersion (Realm).
• checks.company — { taxId, name } de la empresa.
• checks.onboarding — { uuid, country, environment } del onboarding vigente.
• checks.files — flags por archivo critico: xslt, xsd, schematron, templates, tmp.
• checks.certificates — lista de certificados con valid y expires.
• checks.connections — estado de conexion con taxEntity, folioManager, mqtt.
• checks.folios — folios current y next por tipo, con series, from, to, currentFolio, lastUsed, xml, resolution.
• lastDownload — fecha y hora de la ultima descarga de archivos auxiliares.

Integralo a tu monitor

Una respuesta 500 o status distinto de ok indica que el xPOS no esta listo para emitir. Conviene alertar cuando aparezca un certificado proximo a vencer o cuando checks.connections.taxEntity sea false.

❌ Cancelaciones (solo Paraguay)

Solo aplica a Paraguay

Este endpoint solo se utiliza para integraciones de Paraguay. El resto de los paises gestiona la cancelacion por otros canales (ver ficha del pais).

Avisa a xPOS Core que un documento ya emitido fue cancelado en el POS. Sirve para que la cancelacion quede registrada en xPOS y, cuando aplique, se propague.

• Metodo: POST
• Endpoint: /api/v1/cancelation-event

Query param	Requerido	Descripcion
uuid	Si	UUID del xPOS.
env	No	sbx o prd.
country	No	Codigo ISO del pais (py).

Body application/json: ver el tab Request (body cancelacion) en la seccion Como se envia mas arriba.

♻️ Re-obtencion de configuracion

Fuerza al xPOS Core a re-descargar su configuracion desde el portal administrativo. Util cuando producto cambia parametros del cliente y no quieres esperar al proximo refresh automatico.

• Metodo: PUT
• Endpoint: /api/v1/reobtain-config
• No requiere query params ni body.

🧾 Onboarding

Endpoints para consultar la informacion de onboarding del xPOS contra el portal de Gosocket.

Metodo	Endpoint	Para que sirve
GET	/api/v1/onboarding	Trae la informacion del xPOS publicada en el portal. Query: uuid, env. Respuesta: { message, data }.
GET	/api/v1/onboarding/summary	Devuelve el ultimo onboarding ejecutado. Util para validar contra que se inicializo el servicio.

🗂️ Registro de logs

Los logs operativos se persisten en /databases/dbLogs.realm y se consultan por REST. Aplica a todos los paises soportados.

Consulta por rango de fecha

Lista todos los logs en una ventana de tiempo, filtrando por tipo.

• Metodo: GET
• Endpoint: /api/v1/db-data/logs

Parametro	Tipo	Requerido	Descripcion
logType	string	Si	Categoria del log (ver lista debajo).
startDate	string	Si	Fecha de inicio del rango.
endDate	string	Si	Fecha de fin del rango.

Valores soportados para logType:

• Api-SendDocument — envios a la entidad tributaria.
• Api-SendDocumentToSave — envios al Inbox de Gosocket.
• Api-SendContingenciesToPortal — errores de contingencia despachados al Inbox de Gosocket.

Consulta puntual por UUID o metadata

Ideal cuando ya tienes el transactionId o alguna propiedad que identifique la operacion.

• Metodo: GET
• Endpoint: /api/v1/db-data/logs/search

Parametro	Tipo	Requerido	Descripcion
uuid	string	No	UUID de la transaccion.
params	string	No	Filtro libre por metadata (p. ej. {"XPosId":"…"}).

📊 Dashboard

Endpoints internos pensados para alimentar el portal/UI de xPOS con contadores y resumenes operativos. Generalmente no los consume el POS.

Metodo	Endpoint	Para que sirve
GET	/api/v1/info/responses	Resumen de todas las respuestas registradas por xPOS.
GET	/api/v1/info/sii-responses	Respuestas recibidas desde la entidad tributaria (API-ET).
GET	/api/v1/info/errors	Resumen de los errores registrados.