Saltar al contenido principal

Guías de remisión

La guía de remisión electrónica sustenta el traslado de bienes: indica quién envía, quién recibe, desde dónde y hacia dónde se mueve la mercadería, cuándo empieza el traslado y cómo se transporta. La emite el remitente (serie T…, tipo 09) o el transportista (serie V…, tipo 31).

Las guías funcionan distinto al resto de comprobantes:

  • Se envían a la API REST de la SUNAT, no al servicio SOAP de facturas.
  • Además de tu usuario y clave SOL, necesitas un client_id y un client_secret de la API, que generas desde el portal SOL.
  • La SUNAT no tiene entorno beta para guías: solo puedes enviarlas a producción, con datos y credenciales reales.
  • La respuesta siempre es un ticket, que consultas después, como en la comunicación de baja.

Crear la guía​

Este ejemplo es una guía de remisión remitente por venta (motivo 01 del Catálogo 20) con transporte privado (modalidad 02 del Catálogo 18), con vehículo y conductor propios.

DespatchAdvice guia = DespatchAdvice.builder()
.serieNumero("T001-1") // serie T: guía remitente (tipo "09")
.remitente(Remitente.builder()
.ruc("12345678912")
.razonSocial("Softgreen S.A.C.")
.build())
.destinatario(Destinatario.builder()
.tipoDocumentoIdentidad("6")
.numeroDocumentoIdentidad("12121212121")
.nombre("Carlos Feria")
.build())
.envio(Envio.builder()
.tipoTraslado("01") // Catálogo 20: venta
.tipoModalidadTraslado("02") // Catálogo 18: transporte privado
.fechaTraslado(LocalDate.of(2026, 11, 15)) // obligatoria
.pesoTotal(new BigDecimal("25.5"))
.pesoTotalUnidadMedida("KGM")
.partida(Partida.builder().ubigeo("150101").direccion("Av. Los Olivos 123").build())
.destino(Partida.builder().ubigeo("040101").direccion("Jr. Arequipa 456").build())
.vehiculo(Vehiculo.builder().placa("ABC123").build())
.choferes(List.of(Chofer.builder()
.tipo("CONDUCTOR_PRINCIPAL")
.tipoDocumentoIdentidad("1")
.numeroDocumentoIdentidad("12345678")
.nombres("Carlos")
.apellidos("Feria")
.licencia("Q12345678")
.build()))
.build())
.detalles(List.of(DespatchAdviceItem.builder()
.descripcion("Item")
.cantidad(new BigDecimal("2"))
.unidadMedida("NIU")
.codigo("P001")
.build()))
.build();

String xml = new XBuilder().build(guia);

La fecha de traslado es obligatoria: sin ella, la creación de la guía falla con un error de validación. Otros valores se completan solos: el tipo de comprobante a partir de la serie (T → 09, V → 31) y el firmante a partir del remitente.

Los datos de placa, licencia y ubigeos del ejemplo son ficticios. xhandler genera el XML con los datos que le das, pero qué combinación de campos exige cada modalidad de transporte lo valida la SUNAT al recibir la guía. Para transporte público (modalidad 01), en lugar de vehículo y conductores se indica el transportista (transportista, con su número de registro MTC).

Enviar y consultar el ticket​

Usa las URLs de producción y unas credenciales con usuario SOL, clave SOL, client_id y client_secret. xhandler pide el token OAuth a la SUNAT con esas credenciales, lo reutiliza mientras sea válido y lo renueva cuando vence; no tienes que gestionarlo tú.

Los valores en mayúsculas del ejemplo son marcadores: reemplázalos por tus credenciales reales.

SigningKey key = SigningKey.fromPkcs12(Files.readAllBytes(Path.of("certificado.pfx")), "password");
byte[] signed = new XSigner().sign(xml.getBytes(StandardCharsets.UTF_8), key);

FileSender sender = new FileSender(
URLs.production(), // no hay beta para guías
Credentials.builder()
.username("12345678912MIUSUARIO") // RUC + usuario SOL
.password("MI_CLAVE_SOL")
.clientId("MI_CLIENT_ID")
.clientSecret("MI_CLIENT_SECRET")
.build()
);

SunatResponse sent = sender.sendFile(signed);
if (!sent.isTicket()) {
// Errores de la API, por ejemplo HTTP 422 con el código 1033 (comprobante ya registrado)
throw new IllegalStateException(sent.getStatus() + " " + sent.getMetadata().getDescription());
}
String ticket = sent.getSunat().getTicket();

SunatResponse result = sender.verifyFileTicket(signed, ticket);
while (result.getStatus() == Status.EN_PROCESO) {
Thread.sleep(5_000);
result = sender.verifyFileTicket(signed, ticket);
}
System.out.println(result.getStatus() + " " + result.getMetadata().getDescription());

Los errores de la API REST (por ejemplo, un HTTP 422 porque la guía ya fue registrada) no son excepciones: llegan como parte de la respuesta, con el código y el mensaje de la SUNAT.

No uses las URLs beta para guías

Las URLs beta dejan vacía la URL de guías, porque la SUNAT no tiene entorno de pruebas para ellas. Si envías una guía con las URLs beta, el envío falla antes de llegar a la SUNAT con un error de entrada inválida (FileSenderError::NoDespatchUrl en Rust). Las URLs de producción apuntan a https://api-cpe.sunat.gob.pe/v1/contribuyente/gem.

Credenciales y token​

  • Sin client_id y client_secret, el envío de una guía falla con un error.
  • El token se pide a https://api-seguridad.sunat.gob.pe, se guarda en memoria y se reutiliza hasta un minuto antes de que venza. Si la SUNAT responde HTTP 401, xhandler pide un token nuevo y reintenta una vez.
  • Si ya obtienes el token por tu cuenta, pásalo en el campo token de las credenciales (Credentials.builder().token(...) en Java, token en Rust y Python, Token en Go); se usa tal cual.

Diferencias entre lenguajes​

  • Los ítems de la guía son DespatchAdviceItem, no el Detalle de la factura: la descripción es opcional (Option<String> en Rust, *string en Go), y el código y la unidad de medida son textos simples.
  • En Rust, Envio.destino es del tipo Destino, que es un alias de Partida; por eso el ejemplo usa Partida para los dos.
  • Los nombres de las credenciales siguen la convención de cada lenguaje: clientId / clientSecret en Java, client_id / client_secret en Rust y Python, ClientID / ClientSecret en Go.

Siguientes pasos​