🩺 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 (UUID) — opcionalUUID de transacción devuelto en la emisión original. Debe ser un UUID válido; si no lo es, responde 400.

docNumberstring — opcionalNúmero o folio del documento. Se usa junto con typeDoc.

typeDocstring — opcionalTipo de documento. Se usa junto con docNumber.

formatmaster — opcionalDevuelve la respuesta maestra sin transformar, siempre como application/xml. Sirve para desarrollar plantillas de respuesta personalizada.

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

Precedencia entre identificadores

typeDoc + docNumber tienen precedencia: si se envían los dos, el transactionId se ignora.

El formato de la respuesta puede variar

Si el emisor tiene configurado el modo de salida Personalizada, este endpoint responde con el formato que defina su plantilla, no con el JSON estándar. Ver Respuesta personalizada.

Respuesta

El Swagger declara los siguientes campos en la respuesta 200:

AtributoTipoDescripción

inputstringDocumento de origen.

custom_responsestringSalida de custom_response_<país>.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 dashboard local 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	Documentos procesados.
GET	/api/v1/info/sii-responses	Respuestas recibidas desde la entidad tributaria (API-ET).
GET	/api/v1/info/errors	Documentos erróneos.
GET	/api/v1/info/contingencies	Contingencias registradas.

En instalaciones multiroot devuelven solo el emisor en vista

Desde la versión 2.6.0, cuando el equipo tiene varios emisores instalados estas vistas devuelven únicamente los datos del emisor seleccionado en el dashboard, no los del equipo completo. El filtro se aplica en el servidor.

Paginación, filtros y orden

Los cuatro endpoints aceptan el mismo juego de parámetros. Todos son opcionales: sin ninguno, devuelven la vista sin filtrar y con el orden histórico.

AtributoTipoDescripción

page / pageSizenumberPaginación en el servidor.

sortBydate | typeDoc | docNumber | folio | partnerFolio | stageCampo de orden, validado contra lista blanca. Un valor desconocido se ignora y se conserva el orden histórico. El orden se aplica sobre el conjunto completo, no sobre la página cargada.

sortDirasc | descDirección del orden.

typeDocstringFiltra por tipo de documento. Se normaliza a dos dígitos, como viaja en los documentos.

statusaceptado | aceptado_condicional | rechazado | en_procesoEstado ante la autoridad tributaria, calculado en el servidor. aceptado_condicional aplica solo a República Dominicana.

stagestringEtapa del error. Solo en /info/errors.

docNumberstringBusca por número de documento y también por identificador de transacción.

startDate / endDatedateRango de fechas.

Retrocompatible

Sin los parámetros nuevos, estos endpoints se comportan exactamente como antes de la versión 2.6.0.