🩺 Resiliencia y operación

Todo lo que necesitas después de integrar la emisión: recuperar respuestas perdidas, monitorear la salud del servicio, recargar configuración y consultar el historial operativo.

🔁 Reobtención de estados

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

• Método: GET
• Endpoint: http://localhost:3200/api/v1/status

Query params

AtributoTipoDescripción

transactionIdstring — opcionalUUID de transacción devuelto en la emisión original.

docNumberstring — opcionalNúmero o folio del documento.

typeDocstring — opcionalTipo de documento.

Se necesita al menos un parámetro para identificar el documento. Algunos países requieren combinaciones específicas — ver ficha del país.

Respuesta

El Swagger declara los siguientes campos en la respuesta 200:

AtributoTipoDescripción

inputstringDocumento de origen.

custom_responsestringSalida de custom_response_<pais>.xslt cuando aplica.

messagestringResultado de la consulta.

pdf417stringPDF417 (solo Chile).

signedXmlstringXML firmado del documento.

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

🩺 Healthcheck

"¿Está vivo y sano?" Devuelve el estado operativo del xPOS Core para que cualquier monitor externo pueda verificarlo sin tocar la operación.

• Método: GET
• Endpoint: /api/v1/health

La respuesta 200 incluye:

• status, message (ok cuando todo está 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 crítico: xslt, xsd, schematron, templates, tmp.
• checks.certificates — lista de certificados con valid y expires.
• checks.connections — estado de conexión 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 última descarga de archivos auxiliares.

Intégralo a tu monitor

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

🔁 Reobtención de configuración

Fuerza al xPOS Core a re-descargar su configuración desde el portal administrativo. Útil cuando producto cambia parámetros del cliente y no quieres esperar al próximo refresh automático.

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

❌ Cancelaciones (solo Paraguay)

Solo aplica a Paraguay

Este endpoint solo se utiliza para integraciones de Paraguay. El resto de los países gestiona la cancelación por otros canales (ver ficha del país).

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

• Método: POST
• Endpoint: /api/v1/cancelation-event

AtributoTipoDescripción

uuidstring — requeridoUUID del xPOS.

envsbx | prd — opcionalAmbiente operativo.

countrystring — opcionalCódigo ISO del país (py).

Body application/json:

{
"countryDocumentId": "<id-tributario>",
"status": "<estado>",
"description": "<descripcion>"
}

🧾 Onboarding

Endpoints para consultar la información de onboarding del xPOS contra el portal de Gosocket.

Método	Endpoint	Para qué sirve
GET	/api/v1/onboarding	Trae la información del xPOS publicada en el portal. Query: uuid, env. Respuesta: { message, data }.
GET	/api/v1/onboarding/summary	Devuelve el último onboarding ejecutado. Útil para validar contra qué se inicializó el servicio.

📋 Registro de logs

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

Consulta por rango de fecha

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

• Método: GET
• Endpoint: /api/v1/db-data/logs

AtributoTipoDescripción

logTypestring — requeridoCategoría del log (ver lista debajo).

startDatestring — requeridoFecha de inicio del rango.

endDatestring — requeridoFecha de fin del rango.

Valores soportados para logType:

• Api-SendDocument — envíos a la entidad tributaria.
• Api-SendDocumentToSave — envíos 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 operación.

• Método: GET
• Endpoint: /api/v1/db-data/logs/search

AtributoTipoDescripción

uuidstring — opcionalUUID de la transacción.

paramsstring — opcionalFiltro libre por metadata (p. ej. {"XPosId":"…"}).

📊 Dashboard

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

Método	Endpoint	Para qué 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.