🇵🇪 Peru

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

New country in version 2.7.0

Peru joins the xPOS family in xPOS-Core 2.7.0, with the same principles of the platform: the sale never stops, and operation with several issuers on the same device is available from day one.

Summary

Aspect	Value
country code	pe
Tax authority	SUNAT / OSE
Pattern	A — XML with XSD
Supported inputType	json, xml
Extra endpoint	–
Output	Signed tax XML (UBL 2.1)

Peru's particularities are documented in the following sections: two submission paths (with a synchronous verdict on both), input formats (txt and xdoc not available) and particular notes (cancellations do not apply).

🔀 Two submission paths: direct SUNAT or OSE

Peru supports two destinations for the same document, depending on how the issuer is configured:

• Direct SUNAT: submission of the voucher to the authority's services.
• OSE (Electronic Services Operator): submission through the OSE, for companies operating under that modality.

Both paths speak the same protocol and return the Receipt Confirmation (CDR) in the same call: the difference between the two lanes is the destination and the credentials, not the integration model. From the POS point of view the contract is identical.

How the submission path is configured

The destination is defined in the Gosocket administration portal, in the issuer's configuration, per document type: each typeDoc can be routed to SUNAT or to the OSE. With no rule defined for a type, the destination is SUNAT. xPOS receives these rules with the onboarding data: it is not a parameter that travels in each call.

Document types (typeDoc)

The WebSocket example uses typeDoc=1 (electronic invoice).

typeDoc	Document
1	Electronic Invoice
3	Electronic Sales Receipt (Boleta de Venta)
5	Air Transport Ticket
7	Electronic Credit Note
8	Electronic Debit Note
9	Sender's Dispatch Guide (Guía de Remisión Remitente)
14	Electronic Public Services
25	Attribution document
30 / 42	DAE Acquirer
31	Carrier's Dispatch Guide (Guía de Remisión Transportista)
34	DAE Operator
56	SEAE payment voucher

All types share the same transformation path; what changes per type is the UBL validation schema (Invoice / CreditNote / DebitNote / DespatchAdvice) and the SUNAT service it is sent to (guides 9 and 31 go to the Dispatch Guide service).

Voiding Communication and Daily Summary are internal

The RA (Voiding Communication) and RC (Daily Summary) events are not issued from the POS: xPOS itself builds and sends them. The Daily Summary is documented below.

Input formats (inputType)

inputType	Supported	Detail
json	✓	Full transformation path (root → generic DTE → fiscal UBL).
xml	✓	The POS sends xPOS's generic DTE, not SUNAT's UBL: the first transformations are skipped and only the conversion to fiscal UBL runs.
txt	✗	Not available in Peru. Use json or xml.
xdoc	✗	Not available in Peru. Use json or xml.

XSLT mapping

Peru's sheets are distributed compiled (.sef format — xPOS does not compile templates in the store) and arrive from the portal with the issuer's configuration:

Sheet	Use
input_to_dte_pe.sef	json input → generic DTE. With inputType=xml this step is skipped.
dte_to_fiscal_pe.sef	Generic DTE → SUNAT fiscal UBL. Always runs.
create_response_pe.sef	Custom response in GET /api/v1/status, when the issuer's output mode is Personalizada.
summary_documents_pe	Builds the Daily Summary from the day's signed UBLs. It ships packaged inside the product, not through the configuration channel: changing the summary's shape requires an xPOS update.

Numbering: the series and correlative travel in the document

In Peru the voucher's identity is its series-correlative (F001-00000001), which travels inside the document (the UBL's cbc:ID). xPOS extracts it from the signed document and returns it in series, number, docNumber and countryIdentificationCode.

Peru-specific response fields

Peru returns the core + partial tax echo (statusCode and statusMessage, without statusDescription) + applicationResponse + timeGeneration + series.

Field	Status	Notes
statusCode / statusMessage	✓	Read from the SUNAT/OSE CDR. statusCode: "0" = voucher accepted.
statusDescription	–	Not emitted in Peru.
applicationResponse	✓	The CDR in base64. In contingency it does not come (the authority has not responded yet).
countryIdentificationCode	✓	The voucher's series-correlative (F001-00000001), equal to docNumber. Peru has no additional authority-assigned identifier.
series	✓	The voucher's series (F001). Peru-specific field.
timeGeneration	✓	ISO 8601. In contingency, the voucher's issuance date/time.
timeValidation	–	Not emitted in Peru.
barcodeText / barcodeBase64	–	Not returned in Peru: barcodeText does not come in the response and barcodeBase64 arrives as the literal string "null" (it does not contain a code).
contingencyCode	✓	Only when the document went to contingency: 1 = automatic, 2 = manual.
custom_response	–	Arrives as the string "null": Peru's Custom output operates in GET /api/v1/status, not on issuance.
partnerNumber	–	Always null in Peru.

WebSocket example

Illustrative values. The structure is real; the data are examples (fictitious RUC, series and UUIDs).

{
"env": "sbx",
"operation": "consolidate",
"typeDoc": 1,
"country": "pe",
"inputType": "json",
"origin": "20123456789",
"document": { /* Peru voucher */ }
}

Notes about the response:

• output and signedXml are the same value: the signed UBL in base64.
• On success, statusCode: "0" is the acceptance verdict read from the CDR.
• In contingency, message becomes "Operation Successful en contingencia", applicationResponse does not come, and contingencyCode is added.

🕒 Contingency

If SUNAT or the OSE is unavailable, the voucher is generated, signed and stored locally, and the POS receives its response without waiting for the authority — the sale never blocks.

The later regularization operates through the Daily Summary: sales receipts (boletas) issued in contingency are declared to SUNAT in the summary corresponding to their issuance date.

📋 Daily Summary of receipts (boletas)

SUNAT receives sales receipts (boletas) grouped in a Daily Summary (RC-YYYYMMDD-NNNNN), with its own asynchronous cycle: the summary is sent, the authority returns a ticket, and with that ticket xPOS later queries the confirmation (CDR).

xPOS builds and sends the summaries automatically, with no POS or store intervention:

• One summary covers a single issuance date. Receipts issued in contingency are declared in the summary of their issuance date: a store that spent three days in contingency generates three summaries, sent in successive cycles.
• The identifier's correlative is daily and per company: on multi-company devices, each issuer keeps its own summary series, with no crossings.
• A voucher already declared in a previous summary is not declared again.
• The outcome (CDR of acceptance or rejection of the summary) is visible in the dashboard, in the TA Response view, with the summary identifier as document number, and the status is synchronized with the Gosocket portal.

Authority errors, readable

SUNAT's and the OSE's services respond in SOAP: a failure on the authority's side does not arrive as an HTTP error but as a SOAP Fault inside a technically successful response. xPOS extracts the fault's code and description, so that:

• A voucher rejected by the authority is not marked as successfully sent.
• The rejection reason reaches the POS (error_description), the dashboard and the portal in readable form.

The stage catalog and the frequent SUNAT/OSE codes are in Error codes · Peru.

Particular notes

• Publishes in Inbox-Gosocket (or through the System Integrator channel when the organization has it enabled).
• Re-retrieval via GET /api/v1/status with transactionId or with docNumber + typeDoc. For Peru, docNumber is the series-correlative with a hyphen (F001-00000001). With more than one issuer installed, the folio query also requires origin.
• The issuer is validated against origin: if the RUC of the issuer inside the document does not match the request's origin, the issuance fails at VALIDATE_ISSUER_STAGE.
• Voiding: POST /api/v1/cancelation-event does not apply to Peru. The voiding of a Peruvian voucher is declared to SUNAT through a Voiding Communication, which travels through the same asynchronous ticket cycle as the Daily Summary and is built by the platform itself — its enablement is in preparation; today there is no parameter with which the POS can request a voiding. Coordinate voiding cases with your Gosocket contact.
• Peru's custom client data node is DocPersonalizado, and it is preserved inside the signed document.