🩺 Resilience and operation

Everything you need after integrating issuance: recovering lost responses, monitoring the service's health, reloading configuration and querying the operational history.

🔁 Status re-retrieval

Did the POS lose the original response (network problem, restart, audit)? There is no need to resend the document: with any of the following identifiers the original response is retrieved.

• Method: GET
• Endpoint: http://localhost:3200/api/v1/status

Query params

AtributoTipoDescripción

transactionIdstring (UUID) — optionalTransaction UUID returned in the original issuance. It must be a valid UUID; otherwise it returns 400.

docNumberstring — optionalNumber or folio of the document. Used together with typeDoc: without typeDoc, the query is interpreted by transactionId.

typeDocstring — optionalDocument type. Used together with docNumber.

originstring — conditionalIssuer taxId. Required in the docNumber + typeDoc query when the device has more than one issuer installed (400 if missing; 404 if it does not correspond to an installed issuer).

formatmaster — optionalReturns the master response untransformed, always as application/xml. Useful for developing custom response templates.

At least one parameter is needed to identify the document. Some countries require specific combinations — see the country sheet.

Precedence between identifiers

typeDoc + docNumber take precedence: if both are sent, transactionId is ignored.

The response format may vary

If the issuer has the Personalizada output mode configured, this endpoint responds with the format defined by its template, not with the standard JSON. See Custom response.

Response

The Swagger declares the following fields in the 200 response:

AtributoTipoDescripción

inputstringSource document.

custom_responsestringOutput of custom_response_<country>.xslt when applicable.

messagestringResult of the query.

pdf417stringPDF417 (Chile only).

signedXmlstringSigned XML of the document.

Response 400: { date, message, stage, uuid, _id }.

🩺 Healthcheck

"Is it alive and healthy?" Returns the operational status of the xPOS Core so that any external monitor can verify it without touching the operation.

• Method: GET
• Endpoint: /api/v1/health

The 200 response includes:

• status, message (ok when everything is healthy).
• cwd, xposVersion, schemaVersion (Realm).
• checks.company — { taxId, name } of the company.
• checks.onboarding — { uuid, country, environment } of the current onboarding.
• checks.files — flags per critical file: xslt, xsd, schematron, templates, tmp.
• checks.certificates — list of certificates with valid and expires.
• checks.connections — connection status with taxEntity, folioManager, mqtt.
• checks.folios — current and next folios per type, with series, from, to, currentFolio, lastUsed, xml, resolution.
• lastDownload — date and time of the last download of auxiliary files.

Integrate it into your monitor

A 500 response or a status other than ok indicates that the xPOS is not ready to issue. It is advisable to alert when a certificate close to expiring appears or when checks.connections.taxEntity is false.

🔁 Configuration re-retrieval

Forces xPOS Core to re-download its configuration from the administrative portal. Useful when product changes the customer's parameters and you don't want to wait for the next automatic refresh.

• Method: PUT
• Endpoint: /api/v1/reobtain-config
• Requires no query params or body.

❌ Cancellations (Paraguay only)

Applies only to Paraguay

This endpoint is only used for Paraguay integrations. The rest of the countries handle cancellation through other channels (see the country sheet).

Notifies xPOS Core that an already-issued document was canceled in the POS. It serves so that the cancellation is recorded in xPOS and, when applicable, propagated.

• Method: POST
• Endpoint: /api/v1/cancelation-event

AtributoTipoDescripción

uuidstring — requiredxPOS UUID.

envsbx | prd — optionalOperating environment.

countrystring — optionalISO code of the country (py).

application/json body:

{
"countryDocumentId": "<tax-id>",
"status": "<status>",
"description": "<description>"
}

🧾 Onboarding

Endpoints to query the xPOS onboarding information against the Gosocket portal.

Method	Endpoint	What it is for
GET	/api/v1/onboarding	Brings the xPOS information published in the portal. Query: uuid, env. Response: { message, data }.
GET	/api/v1/onboarding/summary	Returns the last onboarding executed. Useful to validate what the service was initialized against.

📋 Log record

Operational logs are persisted in /databases/dbLogs.realm and queried via REST. Applies to all supported countries.

Query by date range

Lists all logs in a time window, filtering by type.

• Method: GET
• Endpoint: /api/v1/db-data/logs

AtributoTipoDescripción

logTypestring — requiredLog category (see list below).

startDatestring — requiredStart date of the range.

endDatestring — requiredEnd date of the range.

Supported values for logType:

• Api-SendDocument — submissions to the tax authority.
• Api-SendDocumentToSave — submissions to the Gosocket Inbox.
• Api-SendContingenciesToPortal — contingency errors dispatched to the Gosocket Inbox.

Specific query by UUID or metadata

Ideal when you already have the transactionId or some property that identifies the operation.

• Method: GET
• Endpoint: /api/v1/db-data/logs/search

AtributoTipoDescripción

uuidstring — optionalTransaction UUID.

paramsstring — optionalFree filter by metadata (e.g. {"XPosId":"…"}).

📊 Dashboard

Internal endpoints designed to feed the local xPOS dashboard with operational counters and summaries. Generally not consumed by the POS.

Method	Endpoint	What it is for
GET	/api/v1/info/responses	Processed documents.
GET	/api/v1/info/sii-responses	Responses received from the tax authority (API-ET).
GET	/api/v1/info/errors	Failed documents.
GET	/api/v1/info/contingencies	Recorded contingencies.

On multiroot installations they return only the issuer in view

From version 2.7.0 onwards, when the device has several issuers installed these views return only the data of the issuer selected in the dashboard, not the whole device. The filter is applied on the server.

Pagination, filters and sorting

The four endpoints accept the same set of parameters. All of them are optional: with none, they return the unfiltered view with the historical sort order.

AtributoTipoDescripción

page / pageSizenumberServer-side pagination.

sortBydate | typeDoc | docNumber | folio | partnerFolio | stageSort field, validated against an allow list. An unknown value is ignored and the historical order is kept. Sorting is applied over the full set, not over the loaded page.

sortDirasc | descSort direction.

typeDocstringFilters by document type. Normalized to two digits, as it travels in the documents.

statusaceptado | aceptado_condicional | rechazado | en_procesoStatus before the tax authority, computed on the server. aceptado_condicional applies only to the Dominican Republic.

stagestringError stage. Only on /info/errors.

docNumberstringSearches by document number and also by transaction identifier.

startDate / endDatedateDate range.

Backward compatible

Without the new parameters, these endpoints behave exactly as they did before version 2.7.0.

🌐 Behavior on corporate networks

Since version 2.7.0:

• The typical outages of proxies and managed networks are recognized as temporary and resolved with automatic retry, without POS intervention.
• The signing certificate is validated early, as a step prior to document processing: a certificate problem is detected before issuing, not mid-flow.

📡 System Integrator publication channel

Version 2.7.0 lays the foundation of a new document publication channel towards the Gosocket cloud, with real-time status confirmation.

Gradual enablement

The channel will be enabled gradually and per organization, coordinated by the Gosocket team. As long as an organization does not have it active, xPOS publishes through the current channel with no change to the integration.