📬 Response y manejo de errores

Independientemente del canal (REST o Socket), xPOS Core devuelve un objeto JSON con dos partes: un núcleo común que aparece siempre y un subconjunto opcional que depende del país. La ficha de cada país indica qué campos aparecen y cómo interpretarlos.

Ejemplo de response completo

Este es el shape completo del response: incluye todos los campos posibles. Los valores aparecen como null cuando el país o la operación no los aplica.

{
"transactionId": null,
"message": null,
"custom_response": null,
"errorDescription": null,
"stage": null,
"number": null,
"docNumber": null,
"output": null,
"signedXml": null,
"input": null,
"barcodeText": null,
"barcodeBase64": null,
"countryIdentificationCode": null,
"statusCode": null,
"statusDescription": null,
"statusMessage": null,
"applicationResponse": null,
"timeGeneration": null,
"timeValidation": null,
"contingencyCode": null
}

Campos del núcleo (todos los países)

AtributoTipoDescripción

transactionIdstring (UUID)UUID de transacción xPOS.

messagestringOperation Successful u Operation Error.

custom_responsestring | nullContenido de custom_response_<pais>.xslt cuando aplica.

errorDescriptionstringError de transformación o validación (solo en error).

stagestringEtapa donde ocurre el error (solo en error).

numberstringNúmero o folio del documento tributario.

docNumberstringSerie y número del documento (formato definido por país, p. ej. SETP990044419).

outputstring (base64)Documento tributario firmado generado por xPOS (XML o JSON según país).

signedXmlstring (base64)DTE fiscal revisado por la entidad tributaria. Mismo contenido que output.

inputstring (base64)Documento de origen recibido del POS.

¿Y cuándo hay error?

Cuando message es Operation Error (o Operation Successful con observación en código 200), los campos stage y errorDescription indican exactamente qué pasó. Ver la sección Manejo de errores para el contrato de integración y el catálogo completo de códigos para la acción recomendada por etapa.

Campos opcionales por país

Código visual (QR / PDF417)

AtributoTipoDescripción

barcodeTextstringTexto del código de barras / QR.

barcodeBase64string (base64)Código de barras / QR en base64.

Chile usa PDF417 y solo devuelve barcodeBase64. El resto de los países usa QR y devuelve ambos campos.

Identificación tributaria

AtributoTipoDescripción

countryIdentificationCodestringIdentificador tributario del documento (CUDE/CUFE, código de generación, CDC, e-NCF, etc., según país).

Eco de la entidad tributaria

Estos campos aparecen cuando la autoridad tributaria responde de forma sincrónica al envío. Los países con respuesta asíncrona (Chile, Paraguay) no los devuelven en el response inicial — se consultan después vía /api/v1/status.

AtributoTipoDescripción

statusCodestringCódigo devuelto por la entidad tributaria.

statusDescriptionstringDescripción devuelta por la entidad.

statusMessagestringMensaje devuelto por la entidad.

applicationResponsestring (base64)Respuesta integral de la entidad (XML o JSON según país).

timeGenerationstringHora de generación del documento (HH:mm:ss±tz).

timeValidationstringHora de validación en la entidad (HH:mm:ss±tz).

Contingencia

AtributoTipoDescripción

contingencyCodestringCódigo de contingencia definido por la autoridad tributaria del país. Aplica a todos los países excepto Chile y Paraguay (modelo asíncrono — la nube Gosocket gestiona la contingencia).

Matriz de presencia por país

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 país incluye un mock de response con valores ilustrativos. Ver Comunicación por país.

🚦 Manejo de errores

xPOS-Core expresa cualquier resultado anómalo —error de validación, rechazo de la entidad tributaria, fallback de contingencia o reintento programado— a través de tres campos del núcleo del response: message, stage y errorDescription. El catálogo completo de etapas vive en Códigos de errores xPOS-Core; esta sección describe el contrato de integración que el POS debe respetar para reaccionar a cada caso.

Contrato del response

Cuando una operación no termina en éxito, xPOS puebla los tres campos así:

AtributoTipoDescripción

messagestringOperation Error (errores) u Operation Successful (código 200 con observación). Distingue un fallo del flujo normal con anotación operativa.

stagestringNombre simbólico de la etapa: TRANSFORM_JSON_STAGE, VALIDATE_XSD_STAGE, DIAN_RESPONSE_STAGE, etc. Llave para localizar la fila en el catálogo.

errorDescriptionstringMensaje humano-legible. Algunas etapas reenvían 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 al inicio de esta página.

Stage code vs. HTTP status

El stage code (200 / 400 / 404 / 503 / 510) que aparece en el catálogo 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 estándar del API.

Qué tiene que hacer el POS

Cada fila del catálogo trae una acción sugerida que el POS debería adoptar como contrato:

Acción	Decisión 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, validación temporal). Reenviar tal cual.
Recargar y reintentar	El estado local del xPOS no está sano (folios, certificados, plantillas). Llamar a PUT /api/v1/reobtain-config y reenviar.
Corregir	Revisar el caso sin reenviar automáticamente (la entidad tributaria ya respondió y deja la acción al operador).
Fin del proceso	No requiere acción del POS (documento duplicado, reintento automático programado en xPOS, o escalamiento manual a Gosocket).

Cuando el POS pierde el response

Si la red se cortó o el POS reinició 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 Reobtención de estados. Para diagnóstico más profundo (auditoría, escalamiento), los logs operativos en GET /api/v1/db-data/logs se filtran por uuid o metadata libre.