🇵🇾 Paraguay

This sheet assumes you know the xPOS-Core communication protocol. Here we only document what is specific to Paraguay.

Summary

Aspect	Value
country code	py
Tax authority	SIFEN
Pattern	A — XML with XSD
Supported inputType	json, xml, xdoc, txt
Output	Signed tax XML
Supported flows	Mixed (sync-async) and Asynchronous — see below
Cancellations	✅ POST /api/v1/cancelation-event (exclusive to Paraguay)

🔀 Supported flows

Paraguay can operate under two integration models. The difference lies in who dialogues with the SIFEN, and it is chosen in the xPOS configuration. From the POS's point of view, the invocation protocol is the same in both models (same endpoint, same parameters, same response structure); what changes is the internal behavior and how the official status is obtained.

To understand the complete choreography with diagrams, see xPOS Global Architecture.

Comparison table

Aspect	Mixed model (sync-async)	Asynchronous model
Who sends to the SIFEN	xPOS Core	Gosocket Cloud
When the official status is known	xPOS Core queries the SIFEN after submission	Managed by the Gosocket cloud
Retries against the SIFEN	Done by xPOS Core	Done by the Gosocket cloud
Echo fields (statusCode, statusDescription, statusMessage) in the initial response	Empty in the first response. Filled in when xPOS Core queries the status.	xPOS Core does not return them (it does not dialogue with the SIFEN).
/api/v1/status	Returns the updated tax status after the xPOS query to the SIFEN.	xPOS Core cannot deliver the final tax status. It is queried directly in the Gosocket Inbox portal, Issued section.
Cancellations	POST /api/v1/cancelation-event applies in both models.	POST /api/v1/cancelation-event applies in both models.

Mixed model (sync-async)

Step-by-step flow:

1. POS → xPOS Core: sends the document (POST /api/v1/process-documents).
2. xPOS Core: validates XSD/Schematron, assigns folio and signs.
3. xPOS Core → SIFEN: delivers the DTE and receives an acknowledge of receipt. The DTE remains in the Inbox without tax status.
4. xPOS Core → POS: responds confirming that the document was accepted for processing.
5. Later: xPOS Core queries the status at the SIFEN and updates the DTE in the Inbox (Issued).
6. POS → xPOS Core: retrieves the official status via GET /api/v1/status.

When to choose it

When the customer wants xPOS to directly control communication with the SIFEN (retry logic, local auditing) and has stable connectivity to the tax authority.

Asynchronous model

Step-by-step flow:

1. POS → xPOS Core: sends the document (POST /api/v1/process-documents).
2. xPOS Core: validates XSD/Schematron, assigns folio and signs.
3. xPOS Core → Gosocket Cloud: delivers the DTE to the Gosocket API and receives an acknowledge from the cloud. Operational text: "Publishes for submission to SIFEN".
4. xPOS Core → POS: responds and synchronizes the Inbox (Issued).
5. Gosocket Cloud → SIFEN: the cloud sends the DTE asynchronously, manages retries and reconciles the official status.

When to choose it

When the customer prefers not to worry about connectivity with the SIFEN (the cloud manages retries and errors) or when the POS network toward the SIFEN is unstable.

How the model is configured

The selection between mixed model and asynchronous model is defined in the Gosocket administration portal during the customer's implementation stage. xPOS Core receives that flag through the onboarding data: it is not a parameter that travels in each call to /api/v1/process-documents.

XSLT mapping

XSLT	Use
input_to_dte_py.xslt	json and xml inputs → XML <root> → Gosocket XML.
other_to_dte_py.xslt	txt input → Gosocket XML. Does not go through input_to_dte.
xdoc_to_dte_py.xslt	xdoc input → Gosocket XML. Does not go through input_to_dte.
dte_to_fiscal_py.xslt	Gosocket XML → SIFEN tax DTE.
custom_response_py.xslt	Generates custom_response when applicable.

Document types (typeDoc)

WebSocket example uses typeDoc=1.

Paraguay-specific response fields

Paraguay returns a reduced subset of the core: the SIFEN responds asynchronously in both models, so the initial response does not bring the entity's echo.

Field	Status	Notes
barcodeText / barcodeBase64	✓	CDC QR.
countryIdentificationCode	✓	CDC (SIFEN Control Code, 44 digits).
statusCode / statusDescription / statusMessage	–	They do not come in the initial response. In the mixed model they are filled in with GET /api/v1/status after the xPOS query to the SIFEN. In the asynchronous model xPOS Core never returns them: the final tax status is queried in the Gosocket Inbox portal (Issued section).
applicationResponse, timeGeneration, timeValidation	–	Same (asynchronous in both models).
contingencyCode	–	Paraguay does not use contingencyCode in the xPOS Core response.

WebSocket example

Illustrative values. The structure is real; the data are examples. This is the initial response from xPOS Core; it applies to both flows (mixed and asynchronous) and does not bring the SIFEN echo — that status is queried later (see Supported flows).

{
"env": "sbx",
"operation": "consolidate",
"typeDoc": 1,
"country": "py",
"inputType": "json",
"origin": "<issuer taxId>",
"document": { /* DTE Paraguay */ }
}

Particular notes

• Status re-retrieval:
  • In the mixed model, use GET /api/v1/status with transactionId or docNumber + typeDoc to obtain the updated tax status.
  • In the asynchronous model, xPOS Core cannot deliver the final tax status. The query is made in the Gosocket Inbox portal, Issued section.
• Cancellations: Paraguay is the only country that triggers POST /api/v1/cancelation-event from the POS. It applies in both models. See Protocol · Cancellations.