🇵🇪 Perú
Esta ficha asume que conoces el protocolo de comunicación xPOS-Core. Aquí solo documentamos lo especifico de Perú.
Perú se suma a la familia xPOS en xPOS-Core 2.7.0, con los mismos principios de la plataforma: la venta nunca se detiene, y la operación con varios emisores en un mismo equipo está disponible desde el primer día.
Resumen
| Aspecto | Valor |
|---|---|
Código country | pe |
| Entidad tributaria | SUNAT / OSE |
| Patrón | A — XML con XSD |
inputType soportados | json, xml |
| Endpoint extra | – |
| Output | XML tributario (UBL 2.1) firmado |
Las particularidades de Perú se documentan en las secciones siguientes: doble vía de envío (con veredicto síncrono en ambas), formatos de entrada (txt y xdoc no disponibles) y notas particulares (las cancelaciones no aplican).
🔀 Dos vías de envío: SUNAT directo u OSE
Perú admite dos destinos para el mismo documento, según cómo esté configurado el emisor:
- SUNAT directo: envío del comprobante a los servicios de la autoridad.
- OSE (Operador de Servicios Electrónicos): envío a través del OSE, para las empresas que operan bajo esa modalidad.
Ambas vías hablan el mismo protocolo y devuelven la Constancia de Recepción (CDR) en la misma llamada: la diferencia entre los dos carriles es el destino y las credenciales, no el modelo de integración. De cara al POS el contrato es idéntico.
El destino se define en el portal de administración de Gosocket, en la configuración del emisor, por tipo de documento: cada typeDoc puede rutearse a SUNAT o al OSE. Sin regla definida para un tipo, el destino es SUNAT. El xPOS recibe estas reglas con los datos de onboarding: no es un parámetro que viaje en cada llamada.
Tipos de documento (typeDoc)
El ejemplo WebSocket usa
typeDoc=1(factura electrónica).
typeDoc | Documento |
|---|---|
| 1 | Factura Electrónica |
| 3 | Boleta de Venta Electrónica |
| 5 | Boleto de Transporte Aéreo |
| 7 | Nota de Crédito Electrónica |
| 8 | Nota de Débito Electrónica |
| 9 | Guía de Remisión Remitente |
| 14 | Servicios Públicos Electrónicos |
| 25 | Documento de atribución |
| 30 / 42 | DAE Adquiriente |
| 31 | Guía de Remisión Transportista |
| 34 | DAE Operador |
| 56 | Comprobante de pago SEAE |
Todos los tipos comparten el mismo camino de transformación; lo que cambia según el tipo es el esquema UBL de validación (Invoice / CreditNote / DebitNote / DespatchAdvice) y el servicio de SUNAT al que se envía (las guías 9 y 31 van al servicio de Guía de Remisión).
Los eventos RA (Comunicación de Baja) y RC (Resumen Diario) no se emiten desde el POS: los construye y envía el propio xPOS. El Resumen Diario se documenta más abajo.
Formatos de entrada (inputType)
inputType | Soportado | Detalle |
|---|---|---|
json | ✓ | Camino completo de transformación (root → DTE genérico → UBL fiscal). |
xml | ✓ | El POS envía el DTE genérico de xPOS, no el UBL de SUNAT: se omiten las primeras transformaciones y solo corre la conversión a UBL fiscal. |
txt | ✗ | No disponible en Perú. Usar json o xml. |
xdoc | ✗ | No disponible en Perú. Usar json o xml. |
Mapeo de XSLT
Las hojas de Perú se distribuyen compiladas (formato .sef — xPOS no compila plantillas en la tienda) y llegan desde el portal con la configuración del emisor:
| Hoja | Uso |
|---|---|
input_to_dte_pe.sef | Entrada json → DTE genérico. Con inputType=xml este paso se omite. |
dte_to_fiscal_pe.sef | DTE genérico → UBL fiscal de SUNAT. Corre siempre. |
create_response_pe.sef | Respuesta Personalizada en GET /api/v1/status, cuando el modo de salida del emisor es Personalizada. |
summary_documents_pe | Arma el Resumen Diario a partir de los UBL firmados del día. Va empaquetada en el producto, no en el canal de configuración: cambiar la forma del resumen requiere una actualización de xPOS. |
Numeración: la serie y el correlativo viajan en el documento
En Perú la identidad del comprobante es su serie-correlativo (F001-00000001), que viaja dentro del documento (el cbc:ID del UBL). xPOS la extrae del documento firmado y la devuelve en series, number, docNumber y countryIdentificationCode.
Campos del response específicos de Perú
Perú devuelve el nucleo + eco tributario parcial (statusCode y statusMessage, sin statusDescription) + applicationResponse + timeGeneration + series.
| Campo | Estado | Notas |
|---|---|---|
statusCode / statusMessage | ✓ | Leídos de la CDR de SUNAT/OSE. statusCode: "0" = comprobante aceptado. |
statusDescription | – | No se emite en Perú. |
applicationResponse | ✓ | La CDR en base64. En contingencia no viene (la autoridad aún no respondió). |
countryIdentificationCode | ✓ | El serie-correlativo del comprobante (F001-00000001), igual a docNumber. Perú no tiene un identificador adicional asignado por la autoridad. |
series | ✓ | La serie del comprobante (F001). Campo propio de Perú. |
timeGeneration | ✓ | ISO 8601. En contingencia, la fecha/hora de emisión del comprobante. |
timeValidation | – | No se emite en Perú. |
barcodeText / barcodeBase64 | – | No se devuelven en Perú: barcodeText no viene en el response y barcodeBase64 llega como la cadena literal "null" (no contiene un código). |
contingencyCode | ✓ | Solo cuando el documento fue a contingencia: 1 = automática, 2 = manual. |
custom_response | – | Llega como la cadena "null": la salida Personalizada de Perú opera en GET /api/v1/status, no en la emisión. |
partnerNumber | – | Siempre null en Perú. |
Ejemplo WebSocket
Valores ilustrativos. La estructura es real; los datos son ejemplos (RUC, series y UUID ficticios).
{
"env": "sbx",
"operation": "consolidate",
"typeDoc": 1,
"country": "pe",
"inputType": "json",
"origin": "20123456789",
"document": { /* comprobante Perú */ }
}Notas sobre el response:
outputysignedXmlson el mismo valor: el UBL firmado en base64.- En éxito,
statusCode: "0"es el veredicto de aceptación leído de la CDR. - En contingencia,
messagepasa a"Operation Successful en contingencia", no vieneapplicationResponsey se agregacontingencyCode.
🕒 Contingencia
Si SUNAT o el OSE no están disponibles, el comprobante se genera, se firma y se guarda localmente, y el POS recibe su respuesta sin esperar a la autoridad — la venta no se bloquea.
La regularización posterior opera a través del Resumen Diario: las boletas de venta emitidas en contingencia se declaran ante SUNAT en el resumen correspondiente a su fecha de emisión.
📋 Resumen Diario de boletas
SUNAT recibe las boletas de venta agrupadas en un Resumen Diario (RC-AAAAMMDD-NNNNN), con un ciclo asincrónico propio: se envía el resumen, la autoridad devuelve un ticket, y con ese ticket xPOS consulta después la constancia (CDR).
xPOS arma y envía los resúmenes automáticamente, sin intervención del POS ni de la tienda:
- Un resumen cubre una sola fecha de emisión. Las boletas emitidas en contingencia se declaran en el resumen de su fecha de emisión: una tienda que estuvo tres días en contingencia genera tres resúmenes, que se envían en ciclos sucesivos.
- El correlativo del identificador es diario y por empresa: en equipos multiempresa, cada emisor lleva su propia serie de resúmenes, sin cruces.
- Un comprobante ya declarado en un resumen anterior no se vuelve a declarar.
- El desenlace (CDR de aceptación o rechazo del resumen) se ve en el dashboard, en la vista Respuesta ET, con el identificador del resumen como número de documento, y el estado queda sincronizado con el portal de Gosocket.
Errores de la autoridad, legibles
Los servicios de SUNAT y del OSE responden en SOAP: una falla del lado de la autoridad no llega como error HTTP sino como un SOAP Fault dentro de una respuesta técnicamente exitosa. xPOS extrae el código y la descripción del fault, de modo que:
- Un comprobante rechazado por la autoridad no queda marcado como enviado con éxito.
- El motivo del rechazo llega al POS (
error_description), al dashboard y al portal en forma legible.
El catálogo de etapas y los códigos frecuentes de SUNAT/OSE están en Códigos de errores · Perú.
Notas particulares
- Publica en Inbox-Gosocket (o por el canal System Integrator cuando la organización lo tenga habilitado).
- Reobtención vía
GET /api/v1/statuscontransactionIdo condocNumber + typeDoc. Para Perú,docNumberes el serie-correlativo con guión (F001-00000001). Con más de un emisor instalado, la consulta por folio exige ademásorigin. - El emisor se valida contra
origin: si el RUC del emisor dentro del documento no coincide con eloriginde la petición, la emisión falla enVALIDATE_ISSUER_STAGE. - Anulaciones:
POST /api/v1/cancelation-eventno aplica a Perú. La anulación de un comprobante peruano se declara ante SUNAT mediante una Comunicación de Baja, que viaja por el mismo ciclo asíncrono por ticket que el Resumen Diario y la construye la propia plataforma — su habilitación está en preparación; no existe hoy un parámetro con el que el POS pueda solicitar una baja. Coordina los casos de anulación con tu contacto de Gosocket. - El nodo de datos personalizados del cliente en Perú es
DocPersonalizado, y se conserva dentro del documento firmado.