📤 Issue documents

The main flow — issuing a document from the POS — is invoked with POST /api/v1/process-documents. This is the endpoint your POS will call on every sale.

Prefer to start from the code? The same flow is implemented in 8 languages in Integration examples.

🔗 REST integration

What parameters it carries in the URL

They all go as query params (?env=…&operation=…&…) and all five are required.

AtributoTipoDescripción

envsbx | prdOperating environment. Must match the one set during onboarding — see Operating model in Concepts and connection.

operationtest | consolidatetest validates without issuing; consolidate issues and records for real (see flow below).

typeDocstringDocument type (invoice, receipt, credit note, debit note, etc.). Each country uses its own table — see the country sheet.

countrycl | co | cr | sv | gt | pa | py | doISO code of the country operating the xPOS.

inputTypejson | xml | xdoc | txtFormat of the document you send in the body. Each country supports a subset — see the country sheet.

What goes in the body

The POS document, in the format declared in inputType:

• json: sent as is, as JSON.
• xml / xdoc / txt: sent encoded in base64 when the country requires it.

What xPOS Core does with your document

xPOS applies one of three internal patterns depending on the country. The difference lies in whether the final tax format is XML or JSON, and whether there is branching by document type.

Pattern A — XML with XSD (most countries)

When a document arrives with operation=consolidate:

1. Receives the input (json, xml, xdoc or txt).
2. If the input is not XML, transforms it into XML <root>.
3. Applies input_to_dte_<country>.xslt → Gosocket XML.
4. Applies dte_to_fiscal_<country>.xslt → tax DTE.
5. Validates the result against the official XSD.
6. Assigns a folio (if the Folio Manager is active).
7. Signs the DTE.
8. Sends it to the tax authority.
9. Returns the response to the POS.
10. Publishes the DTE in Gosocket (Inbox).

Pattern B — JSON with JSON Schema

Same as Pattern A, but steps 4 and 5 generate tax JSON and validate against JSON Schema instead of XSD.

Pattern C — dual XML

Same as Pattern A, but step 4 branches according to the document type (tax DTE vs. equivalent, each with its own XSLT).

What changes with operation = test

test executes only steps 1–5 (transformation + validation). It does not assign a folio, does not sign, does not send to the tax authority and does not publish in Gosocket. It serves to validate that the document is well formed before issuing it for real.

🔄 Socket integration

note

The Socket channel does not appear in the Swagger (OpenAPI 3.0 does not model WebSockets). The functional contract described here is the implementation agreement for the ws://localhost:3200 integration.

Same functional flow as REST, with the difference that the parameters travel inside the request object (not in query params).

How it is sent

An object is assembled with the same content as the REST POST:

{"env":"sbx","operation":"consolidate","typeDoc":<N>,"country":"<XX>","inputType":"json","document":{...}}

That object is serialized to a string and the string is sent in base64. The server processes it and also responds in base64; upon decoding, the structure is equivalent to the REST response.

📬 And the response?

Regardless of the channel (REST or Socket), xPOS Core returns the same JSON object. It is documented field by field — including the error-handling contract — in Response and error handling.