💻 REST integration examples

This page assumes you know the xPOS-Core communication protocol. Here you will find the same flow implemented in the most common languages, ready to adapt to your POS.

Reference code — do not copy as-is

These examples are reference material to understand the integration flow with xPOS Core: they are not official SDKs nor production-ready code. They illustrate the protocol contract (endpoints, parameters, error handling), but before using them in your project you must adapt them to your context: country and document type, actual document structure, retries, timeouts, logging, and your platform's exception handling. Always validate your implementation against the Sandbox environment (env=sbx) before moving to Production.

All examples implement the full recommended flow:

1. 1

   Healthcheck

   GET /health

   Verify the xPOS is healthy before issuing.

2. 2

   Pre-validation

   POST /process-documents · operation=test

   Validates the document without assigning a folio, signing, or sending it to the tax authority.

3. 3

   Real issuance

   POST /process-documents · operation=consolidate

   The same endpoint with operation=consolidate.

4. 4

   Error handling

   If message is Operation Error, stage and error_description indicate the cause; the action to take is in the error codes catalog.

5. 5

   State recovery

   GET /status

   If the POS lost the response, do not resend the document; recover the original response.

Example values

The examples use Chile (country=cl, typeDoc=39 electronic receipt) in Sandbox (env=sbx). Adjust country, typeDoc, and inputType according to your country's sheet. The document body is a placeholder: the actual document structure depends on the country and document type — check the corresponding sheet and the local Swagger (http://localhost:3200/api/v1/doc/).

The origin in the examples (<taxId>) is the issuer's tax identifier. If your installation has a single issuer you can omit the parameter; with two or more it is required.

Sample client per language

Terminal

Web

Backend

>_cURLTerminal (cURL)ejemplo.sh

# issuer taxId. Optional with 1 onboarding; required with 2 or more
ORIGIN="<taxId>"

# Healthcheck: 500 or status != "ok" → the xPOS is not ready to issue
curl "http://localhost:3200/api/v1/health"

# Validate the document structure without issuing (operation=test)
curl -X POST "http://localhost:3200/api/v1/process-documents?env=sbx&operation=test&typeDoc=39&country=cl&inputType=json&origin=$ORIGIN" \
  -H "Content-Type: application/json" \
  -d @document.json

# Issue for real (operation=consolidate)
curl -X POST "http://localhost:3200/api/v1/process-documents?env=sbx&operation=consolidate&typeDoc=39&country=cl&inputType=json&origin=$ORIGIN" \
  -H "Content-Type: application/json" \
  -d @document.json

# Recover the response of an already processed document (do not resend the document)
curl "http://localhost:3200/api/v1/status?transactionId=1ebf7ddc-94e2-4255-a741-de7e6cd0e439"

Protocol reminders

• Base URL: http://localhost:3200/api/v1 — xPOS Core is consumed via loopback; it is not published to the network and requires no authentication.
• The 5 query params of /process-documents are mandatory: env, operation, typeDoc, country, inputType. The sixth, origin, is conditional: optional with a single issuer installed, required with two or more (without it, HTTP 400). See Multiroot.
• inputType=txt is the body exception: it travels with Content-Type: text/plain and the body is the plain text as is, with no JSON and no base64. The examples on this page use inputType=json.
• The environment (sbx | prd) is set by onboarding: it cannot be switched on the fly via the query param.
• Base64 response fields: output, signedXml, input, applicationResponse, and barcodeBase64 (PDF417 in Chile, QR elsewhere).
• Asynchronous countries (Chile, Paraguay): the tax authority echo does not come in the initial response — see the country sheet to learn how to obtain the final fiscal status.