The Spanish version is the authoritative reference. View in Spanish
🌐 xPOS-Core communication protocol
This section is synchronized against the contract published in the xPOS Core Swagger (http://localhost:3200/api/v1/doc/), version 2.6.0 (OpenAPI 3.0).
📌 Operating model
xPOS Core is the local piece that receives documents from the POS, transforms them into the format required by the country's tax authority and sends them (directly or through the Gosocket cloud, depending on the country).
It always works in a single environment at a time, defined during onboarding:
| Environment | What it is for | What happens when issuing |
|---|---|---|
Sandbox (sbx) | Development, QA and training | Documents are processed with fictitious data and do not reach the tax authority nor have legal effect. |
Production (prd) | Real customer operation | Documents are officially issued: they have operational, financial and legal effect. |
The environment is not switched on the fly from the env query param: it is set by onboarding. To move an xPOS from Sandbox to Production (or vice versa) you have to redo the onboarding from the portal.
One or several issuers per device (multiroot)
From version 2.6.0 onwards, a single xPOS can have several issuers installed: several onboardings, each with its own digital certificate, its credentials against the authority and its folio ranges, fully separated from one another.
That changes exactly one thing in the contract with the POS: the origin parameter (the issuer's taxId) becomes required when two or more issuers are installed. With a single one it is optional and everything works as before. The details are in Issue documents.
🔌 How to connect
xPOS Core runs as a local service on the customer's machine. The POS and any integration consume it over loopback: it is not published to the network.
🧭 What do you need to do?
The protocol is documented by task. Start with the one that applies to you:
Issue documentsIntegrationThe main flow: sending a document from the POS with POST /process-documents (REST) or via WebSocket, choosing the right inputType, operating several issuers with origin and understanding what xPOS does with your document.Response and errorsReferenceThe response object field by field, the per-country presence matrix and the error-handling contract (stage + errorDescription).Custom responseIntegrationReceiving the xPOS response in the format your system requires (XML, JSON or other text), defined by an XSLT template delivered from the portal.Resilience and operationOperationRecovering a lost response, healthcheck for monitoring, configuration reload, logs, cancellations (Paraguay) and dashboard endpoints.Integration examplesCodeThe complete flow implemented in the most common languages (cURL, Python, JavaScript, TypeScript, Java, C#/.NET, Go and PHP).Error codesReferenceFull catalog of error stages with the suggested action for the POS in each case.🗂️ Endpoint catalog
Everything xPOS Core exposes today, grouped by purpose, with the page where each group is documented.
Document Processing — document issuance and query
Documented in Issue documents and Resilience and operation.
| Method | Path | What it is for |
|---|---|---|
POST | /api/v1/process-documents | Main endpoint and only issuance route: the POS invokes it every time it needs to issue a document. xPOS assembles it, validates it, signs it (according to operation) and sends it. The four input forms (json, xml, xdoc, txt) are chosen with the inputType query param. |
GET | /api/v1/status | "Can you repeat the response?" Retrieves the result of an already-processed document, useful when the POS lost the connection. It accepts format=master — see Custom response. |
Onboarding — linking with the Gosocket portal
Documented in Resilience and operation.
| Method | Path | What it is for |
|---|---|---|
GET | /api/v1/onboarding | Brings to the local machine the xPOS configuration published in the Gosocket portal (according to uuid + env). |
GET | /api/v1/onboarding/summary | Shows the last onboarding executed: useful to verify what the service was initialized against. |
External Communication — events outward from the POS
Documented in Resilience and operation.
| Method | Path | What it is for |
|---|---|---|
POST | /api/v1/cancelation-event | Notifies the xPOS that an already-issued document was canceled (the cancellation is recorded by the POS). Only used in Paraguay. |
POST | /api/v1/logs | Pushes to Gosocket the local logs accumulated by xPOS. |
PUT | /api/v1/reobtain-config | Asks the xPOS to re-download its configuration from the portal (useful when product changes parameters). |
Monitoring — is it alive and healthy?
Documented in Resilience and operation.
| Method | Path | What it is for |
|---|---|---|
GET | /api/v1/health | Complete healthcheck: service status, version, certificates, connections, folios, onboarding validations. Designed for external monitoring. |
GET | /api/v1/health/connectivity | External connectivity probe: checks that the device can reach the services it depends on. |
Log — operational history
Documented in Resilience and operation.
| Method | Path | What it is for |
|---|---|---|
GET | /api/v1/db-data/logs | Lists operational logs in a date range, filtering by logType. |
GET | /api/v1/db-data/logs/search | Searches for a specific log by transaction uuid or by free metadata (params). |
Dashboard — metrics consumed by the portal/UI
Documented in Resilience and operation.
| Method | Path | What it is for |
|---|---|---|
GET | /api/v1/info/responses | Summary of all the responses xPOS has recorded. |
GET | /api/v1/info/sii-responses | Only the responses received from the tax authority (API-ET). |
GET | /api/v1/info/errors | Summary of the recorded errors. |