Saltar al contenido principal

Envío y respuestas de la SUNAT

FileSender envía un XML firmado a la SUNAT y te devuelve su respuesta. Representa a una empresa: lo creas con las URLs de los servicios y las credenciales, y lo reutilizas para todos sus comprobantes.

URLs: beta, producción u OSE​

import io.github.project.openubl.xsender.Credentials;
import io.github.project.openubl.xsender.FileSender;
import io.github.project.openubl.xsender.URLs;

Credentials credentials = Credentials.builder()
.username("12345678959MODDATOS")
.password("MODDATOS")
.build();

// Beta (sin guías de remisión)
FileSender beta = new FileSender(URLs.beta(), credentials);

// Producción
FileSender production = new FileSender(URLs.production(), credentials);

// URLs propias, por ejemplo un OSE
URLs ose = URLs.builder()
.invoice("https://ose.example.com/ol-ti-itcpe/billService")
.perceptionRetention("https://ose.example.com/otroscpe/billService")
.despatch(null) // API REST de guías, opcional
.build();
FileSender oseSender = new FileSender(ose, credentials);

Las URLs predefinidas son:

ServicioBetaProducción
Facturas, boletas, notas, resúmenes y bajas (invoice)https://e-beta.sunat.gob.pe/ol-ti-itcpfegem-beta/billServicehttps://e-factura.sunat.gob.pe/ol-ti-itcpfegem/billService
Percepciones, retenciones y reversiones (perception_retention)https://e-beta.sunat.gob.pe/ol-ti-itemision-otroscpe-gem-beta/billServicehttps://e-factura.sunat.gob.pe/ol-ti-itemision-otroscpe-gem/billService
Guías de remisión, API REST (despatch)No existehttps://api-cpe.sunat.gob.pe/v1/contribuyente/gem
  • Para un OSE solo cambias las URLs; el resto del código es igual. Las URLs del ejemplo son ficticias: usa las que te indique tu OSE.
  • xhandler arma las mismas peticiones SOAP que espera la SUNAT. Confirma con tu OSE que acepta ese mismo formato.
  • Si envías una guía con un FileSender sin URL de guías, obtienes un error. Revisa Guías de remisión.

El XML decide a dónde va​

No eliges el servicio ni la operación de la SUNAT: FileSender los deduce del XML firmado.

ComprobanteServicioOperaciónRespuesta
Factura, boleta, nota de crédito y de débitoinvoicesendBillCDR
Resumen diarioinvoicesendSummaryTicket
Comunicación de bajainvoice (o perception_retention si da de baja percepciones o retenciones)sendSummaryTicket
Percepción y retenciónperception_retentionsendBillCDR
Resumen de reversionesperception_retentionsendSummaryTicket
Guía de remisióndespatchAPI REST con OAuthTicket

También arma el zip con el nombre que exige la SUNAT ({ruc}-{tipo}-{serie-numero}.zip, por ejemplo 12345678912-01-F001-1.zip) a partir del contenido del XML, no del nombre del archivo en disco.

Enviar y procesar la respuesta​

La SUNAT responde de una de tres formas:

  • CDR: el comprobante fue procesado. Trae el estado, el código de respuesta, la descripción y las observaciones (notes).
  • Ticket: la SUNAT procesará el envío después. Consulta el ticket para obtener el CDR.
  • Error de la SUNAT (fault): la SUNAT no procesó el envío. Trae el código y el mensaje.
import io.github.project.openubl.xsender.models.Metadata;
import io.github.project.openubl.xsender.models.Status;
import io.github.project.openubl.xsender.models.SunatResponse;

import java.nio.file.Files;
import java.nio.file.Path;

SunatResponse response = beta.sendFile(signed); // byte[] o Path

if (response.isTicket()) {
// Resúmenes, bajas, reversiones y guías: consulta el ticket
String ticket = response.getSunat().getTicket();
response = beta.verifyFileTicket(signed, ticket);
}

Metadata metadata = response.getMetadata();
switch (response.getStatus()) {
case ACEPTADO -> {
// Código 0, o 4000 en adelante si hay observaciones
System.out.println(metadata.getResponseCode() + " " + metadata.getDescription());
metadata.getNotes().forEach(System.out::println);
Files.write(Path.of("R-12345678912-01-F001-1.zip"), response.getSunat().getCdr()); // CDR
}
case RECHAZADO -> System.out.println("Rechazado " + metadata.getResponseCode() + ": " + metadata.getDescription());
case EXCEPCION -> System.out.println("Excepción " + metadata.getResponseCode() + ": " + metadata.getDescription());
case EN_PROCESO -> System.out.println("La SUNAT aún procesa el ticket, consulta más tarde");
default -> System.out.println(response.getStatus() + " " + metadata);
}
  • getStatus() devuelve ACEPTADO, RECHAZADO, BAJA, EXCEPCION, EN_PROCESO o UNKNOWN.
  • getMetadata() trae responseCode, description, notes y, en los errores de la SUNAT, httpStatus.
  • getSunat() trae el ticket o el cdr (el zip). Es null cuando la SUNAT respondió con un error.
  • Si la respuesta es un ticket, getStatus() y getMetadata() son null hasta que lo consultes.

Cómo se clasifica el código de la SUNAT​

CódigoEstadoQué significa
0ACEPTADOAceptado.
4000 en adelanteACEPTADOAceptado con observaciones, que llegan en las notes.
98EN_PROCESOEl ticket aún se está procesando. Consulta más tarde.
99 a 1999EXCEPCIONLa SUNAT no procesó el envío; puedes corregir y reenviar.
2000 a 3999RECHAZADOEl comprobante fue rechazado.

Guarda siempre el zip del CDR que devuelve la SUNAT: es la constancia de que el comprobante fue procesado. xhandler ya te da sus datos (estado, código, descripción, observaciones), así que no necesitas abrir el zip para leerlos.

Un rechazo no es un error​

Un comprobante rechazado o un error de la SUNAT no lanzan una excepción ni devuelven un error: llegan como parte de la respuesta, igual que una aceptación. Solo obtienes un error cuando la librería no pudo completar el envío: un XML que no es un comprobante, un fallo de red o una respuesta ilegible. Revisa Manejo de errores.

Consultar un ticket más tarde​

En los ejemplos anteriores, el ticket se consulta con el mismo XML que enviaste (verifyFileTicket): el XML indica en qué servicio consultarlo. Si la SUNAT responde que aún está en proceso (98), vuelve a consultar después de unos segundos.

Si guardaste el ticket pero ya no tienes el XML, indica tú el servicio:

import io.github.project.openubl.xsender.sunat.BillServiceDestination;

BillServiceDestination destination = BillServiceDestination.builder()
.url(URLs.beta().getInvoice())
.soapOperation(BillServiceDestination.SoapOperation.GET_STATUS)
.build();
SunatResponse status = beta.verifyTicket(destination, "1703154974517");

Usa el servicio donde enviaste el documento: invoice para resúmenes y bajas, perception_retention para reversiones y bajas de percepciones o retenciones.

Varias facturas en un zip (sendPack)​

La operación sendPack de la SUNAT recibe varias facturas en un solo zip y responde con un ticket. Le das el nombre del zip, sin la extensión .zip; la librería no genera ni valida ese nombre.

Solo en producción

La SUNAT solo acepta sendPack en producción. En beta responde con un error de la SUNAT con estado EXCEPCION. Por eso los ejemplos usan las URLs de producción, con credenciales de ejemplo.

import io.github.project.openubl.xsender.sunat.BillServiceDestination;

FileSender sender = new FileSender(
URLs.production(),
Credentials.builder().username("12345678912USUARIO").password("clave-sol").build()
);

SunatResponse response = sender.sendPack("12345678912-20261115-1", List.of(factura1, factura2)); // XML firmados

if (response.isTicket()) {
// El ticket de un lote se consulta en el servicio de facturas
SunatResponse status = sender.verifyTicket(
BillServiceDestination.builder()
.url(URLs.production().getInvoice())
.soapOperation(BillServiceDestination.SoapOperation.GET_STATUS)
.build(),
response.getSunat().getTicket());
System.out.println(status.getStatus());
}

verifyFileTicket no sirve para un lote, porque necesita un solo documento.

Reintentos y tiempos de espera​

El cliente HTTP incluido ya maneja los problemas más comunes de la SUNAT:

  • Si falla la conexión, reintenta una vez.
  • Si el proxy de la SUNAT limita las peticiones (una página 401 que no es SOAP, frecuente en beta), reintenta después de 1 y 2 segundos. Si sigue fallando, devuelve un error de rate limiting.
  • En las guías, pide el token OAuth, lo guarda en caché y lo renueva una vez si la SUNAT responde 401.
  • Espera hasta 30 segundos para conectar y 120 segundos por petición.

Para cambiar el cliente HTTP (proxy, tiempos de espera) o compartirlo entre varias empresas, revisa Varias empresas.

Sin cliente HTTP (Rust)​

Por defecto, el crate de Rust incluye un cliente HTTP (la feature http). Si quieres usar tu propio cliente, por ejemplo en Android, iOS o WebAssembly, desactívala:

Cargo.toml
[dependencies]
xhandler = { version = "6.0.0-alpha.1", default-features = false }

Así obtienes una librería Rust pura: crear y firmar funcionan igual, pero desaparecen SunatClient y los métodos async de FileSender (send_file, send_pack, verify_ticket, verify_file_ticket). En su lugar, el módulo xsender::exchange arma las peticiones HTTP y lee las respuestas; tú solo las envías.

use xhandler::prelude::*;
use xhandler::xsender::exchange::{Answer, Call, HttpRequest, HttpResponse};

/// Envía la petición con tu cliente HTTP y devuelve status, headers y body,
/// también cuando la SUNAT responde HTTP 500 (así llegan sus errores SOAP).
fn my_http_send(request: &HttpRequest) -> anyhow::Result<HttpResponse> {
let _ = (&request.method, &request.url, &request.headers, &request.body);
todo!("enviar con tu cliente HTTP")
}

fn send(signed: Vec<u8>, credentials: &Credentials) -> anyhow::Result<()> {
let ubl = UblFile::from_bytes(signed)?;

// 1. Preparar: zip, servicio de envío y servicio para consultar el ticket
let prepared = prepare_send_file(&ubl, &Urls::beta())?;

// 2. Armar la petición (las guías necesitan antes un token OAuth)
let call = Call::SendFile {
target: prepared.send_file_target.clone(),
file: prepared.file.clone(),
};
let token = if call.needs_token() {
let token_call = Call::Token { url: None };
let response = my_http_send(&token_call.request(credentials, None)?)?;
match token_call.parse(&response)? {
Answer::Token(token) => Some(token.access_token),
_ => unreachable!(),
}
} else {
None
};
let request = call.request(credentials, token.as_deref())?;

// 3. Enviar con tu cliente y 4. leer la respuesta
let response = my_http_send(&request)?;
let Answer::SendFile(answer) = call.parse(&response)? else { unreachable!() };
match SendFileAggregatedResponse::try_from(answer)? {
SendFileAggregatedResponse::Cdr(_, cdr) => println!("{} {}", cdr.status(), cdr.description),
SendFileAggregatedResponse::Ticket(ticket) => {
// Consulta luego con Call::VerifyTicket { target: prepared.verify_ticket_target.unwrap(), ticket }
println!("ticket {ticket}");
}
SendFileAggregatedResponse::Fault(fault) => println!("{} {}", fault.code, fault.message),
}
Ok(())
}
  • prepare_send_pack y file_verify_ticket_target también están disponibles sin la feature http.
  • Call tiene variantes para todas las operaciones: SendFile, VerifyTicket, GetStatus, GetStatusCdr, ValidateCdp, ValidateFile y Token.
  • Call, Answer, HttpRequest, HttpResponse y HttpMethod no están en el prelude: impórtalos desde xhandler::xsender::exchange.
  • Lo que hace el cliente incluido y ahora te toca a ti: reintentar una vez si falla la conexión, reintentar tras 1 y 2 segundos cuando parse devuelve SunatClientError::RateLimited, guardar el token hasta 60 segundos antes de que venza (expires_in) y pedir uno nuevo si una llamada REST recibe 401.

Es el mismo mecanismo que usan por dentro las librerías de Java, Python y Go.

Python y asyncio​

La librería de Python solo tiene API síncrona: no hay métodos async. Es thread-safe, así que desde código asyncio puedes delegar el envío a un hilo con asyncio.to_thread de la biblioteca estándar:

import asyncio

from xhandler.xsender import Credentials, FileSender, URLs

sender = FileSender(URLs.beta(), Credentials(username="12345678959MODDATOS", password="MODDATOS"))


async def enviar(signed: bytes):
return await asyncio.to_thread(sender.send_file, signed)