📬 Response and error handling

Regardless of the channel (REST or WebSocket), xPOS Core returns a JSON object with two parts: a common core that always appears and an optional subset that depends on the country. Each country's sheet indicates which fields appear and how to interpret them.

Do you need another response format?

This page describes the standard xPOS response, which is JSON and has a fixed structure. If your system needs to receive the response with a different structure — your own XML, a different JSON — that is solved with the custom response, which is a separate mechanism and does not alter anything described here.

Full response example

This is the full shape of the response: it includes all possible fields. Values appear as null when the country or the operation does not apply them.

{
"transactionId": null,
"message": null,
"custom_response": null,
"error_description": 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
}

Core fields (all countries)

AtributoTipoDescripción

transactionIdstring (UUID)xPOS transaction UUID.

messagestringOperation Successful or Operation Error.

custom_responsestring | nullContent of custom_response_<country>.xslt when applicable. It is one more field inside the standard response; not to be confused with the custom response, which replaces the whole response.

error_descriptionstringTransformation or validation error (only on error).

stagestringStage where the error occurs (only on error).

numberstringNumber or folio of the tax document.

docNumberstringSeries and number of the document (format defined per country, e.g. SETP990044419).

outputstring (base64)Signed tax document generated by xPOS (XML or JSON depending on country).

signedXmlstring (base64)Tax DTE reviewed by the tax authority. Same content as output.

inputstring (base64)Source document received from the POS.

And when is there an error?

When message is Operation Error (or Operation Successful with an observation in code 200), the stage and error_description fields indicate exactly what happened. See the Error handling section for the integration contract and the full code catalog for the recommended action per stage.

Optional fields by country

Visual code (QR / PDF417)

AtributoTipoDescripción

barcodeTextstringBarcode / QR text.

barcodeBase64string (base64)Barcode / QR in base64.

Chile uses PDF417 and only returns barcodeBase64. The rest of the countries use QR and return both fields.

Tax identification

AtributoTipoDescripción

countryIdentificationCodestringTax identifier of the document (CUDE/CUFE, generation code, CDC, e-NCF, etc., depending on country).

Tax authority echo

These fields appear when the tax authority responds synchronously to the submission. Countries with an asynchronous response (Chile, Paraguay) do not return them in the initial response — they are queried later via /api/v1/status.

AtributoTipoDescripción

statusCodestringCode returned by the tax authority.

statusDescriptionstringDescription returned by the entity.

statusMessagestringMessage returned by the entity.

applicationResponsestring (base64)Comprehensive response from the entity (XML or JSON depending on country).

timeGenerationstringDocument generation time (HH:mm:ss±tz).

timeValidationstringValidation time at the entity (HH:mm:ss±tz).

Contingency

AtributoTipoDescripción

contingencyCodestringContingency code defined by the country's tax authority. Applies to all countries except Chile and Paraguay (asynchronous model — the Gosocket cloud manages the contingency).

Presence matrix by country

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

¹ Chile returns barcodeBase64 in PDF417 format (not QR).

² In Peru barcodeText is not returned and barcodeBase64 arrives as the literal string "null" (it does not contain a code).

³ Peru emits statusCode and statusMessage (read from the SUNAT/OSE CDR), but not statusDescription. It also returns the Peru-specific field series — see the Peru sheet.

Each country sheet includes a response mock with illustrative values. See Communication by country.

🚦 Error handling

xPOS-Core expresses any anomalous result — validation error, tax authority rejection, contingency fallback or scheduled retry — through three core fields of the response: message, stage and error_description. The full catalog of stages lives in xPOS-Core error codes; this section describes the integration contract that the POS must respect to react to each case.

Response contract

When an operation does not end in success, xPOS populates the three fields like this:

AtributoTipoDescripción

messagestringOperation Error (errors) or Operation Successful (code 200 with observation). Distinguishes a failure from the normal flow with an operational annotation.

stagestringSymbolic name of the stage: TRANSFORM_JSON_STAGE, VALIDATE_XSD_STAGE, DIAN_RESPONSE_STAGE, etc. Key to locate the row in the catalog.

error_descriptionstringHuman-readable message. Some stages relay the message from the tax authority (DIAN, MH, SAT/Megaprint, DGII). The POS can show it to the operator or parse it when the stage has a stable format (e.g. duplicity).

Example of an error response: see the Response — Error tab at the top of this page.

Stage code vs. HTTP status

The stage code (200 / 400 / 404 / 503 / 510) that appears in the catalog is an internal operational label, not the HTTP status returned by the REST API. xPOS-Core delivers it inside the response body; the transport's HTTP status follows the standard API rules.

What the POS has to do

Each row of the catalog carries a suggested action that the POS should adopt as a contract:

Action	POS decision
Correct and retry	The input is responsible. Correct the data indicated by error_description and resend POST /api/v1/process-documents.
Retry	Transient error (network, token, temporary validation). Resend as is.
Reload and retry	The xPOS local state is not healthy (folios, certificates, templates). Call PUT /api/v1/reobtain-config and resend.
Correct	Review the case without resending automatically (the tax authority already responded and leaves the action to the operator).
End of process	No POS action required (duplicate document, automatic retry scheduled in xPOS, or manual escalation to Gosocket).

When the POS loses the response

If the network was cut or the POS restarted before processing the response, there is no need to resend the document: the GET /api/v1/status endpoint retrieves the original response from the transactionId or the docNumber — see Status re-retrieval. For deeper diagnosis (audit, escalation), the operational logs at GET /api/v1/db-data/logs are filtered by uuid or free metadata.