Guías de Remisión Electrónica (GRE REST 2.0)

Emisión de Guías de Remisión Remitente (09) y Transportista (31) vía API REST oficial de SUNAT con OAuth 2.0 (R.S. 123-2022/SUNAT).

POST/v1/despatches

A diferencia de las facturas y boletas que operan mediante servicios SOAP tradicionales, la SUNAT dispuso que todas las Guías de Remisión Electrónica deben emitirse obligatoriamente a través de su API REST con autenticación OAuth 2.0.

YoEmito genera el XML UBL 2.1 (DespatchAdvice), firma digitalmente con el certificado del emisor, empaqueta el archivo ZIP con hash SHA-256 y realiza la autenticación OAuth 2.0 en tiempo real con SUNAT para obtener el ticket de envío y el correspondiente CDR de aceptación.

Plazo de SUNAT — antes del traslado, máximo 1 día calendario: la GRE debe contar con CDR-Aceptada antes de que inicie el traslado físico de los bienes, y a más tardar el día calendario siguiente a issue_date. Pasado ese plazo, el documento deja de tener calidad de GRE aunque ya lo hayas usado para sustentar el traslado. Nuestra API valida esto automáticamente: POST /v1/despatches devuelve un error 422 si issue_date ya está fuera de ese plazo, antes de siquiera consultar a SUNAT.

Requisito Obligatorio: Bloqueo por Defecto

En producción, el endpoint /v1/despatches está bloqueado por defecto si el emisor no tiene certificado, usuario/clave SOL y credenciales de API GRE (gre_client_id y gre_client_secret). Sandbox es simulado y no utiliza credenciales ni servicios reales de SUNAT.

Si intentas emitir una guía live sin haber configurado estas credenciales, la API responderá con estado 422 Unprocessable Entity:

{
  "type": "https://docs.yoemito.dev/errors/validation",
  "title": "Payload inválido",
  "status": 422,
  "detail": "El emisor (RUC 20513469129) no tiene habilitada la emisión de Guías de Remisión Electrónica. Registre las credenciales de API SUNAT (client_id y client_secret) del emisor en su configuración para activar este servicio.",
  "field": "gre_credentials"
}

Cómo obtener Client ID y Client Secret en SUNAT Operaciones en Línea (SOL)

Inicia sesión en SUNAT Operaciones en Línea (SOL) con tu RUC, usuario y clave SOL.
En el menú lateral, dirígete a: Empresas → Comprobantes de Pago → Guía de Remisión Electrónica → Registro de Aplicación REST.
Completa los datos del formulario de registro:
- Nombre de su aplicación: Ingresa un identificador claro (ejemplo: YoEmito Facturacion).
- URL de su aplicación: Ingresa la URL de tu plataforma o dominio corporativo (ejemplo: https://yoemito.pe).
- Alcance: Selecciona la opción Web.
En la lista de servicios API, marca obligatoriamente la casilla:
[X] GRE Emision de Comprobantes /v1/contribuyente/gem
Haz clic en Guardar. El portal de SUNAT te entregará inmediatamente dos valores:
- ID (Client ID): Cadena UUID (ejemplo: eacca6d5-c02f-4e83-9046-1cf109d39498).
- CLAVE (Client Secret): Cadena Base64 de 16 bytes (ejemplo: Ik6U+entJqqeQcgavu57vg==).
Configura estos dos valores en YoEmito, ya sea desde el panel web (sección Emisores → Editar → Credenciales API SUNAT) o mediante los endpoints POST /v1/issuers / PUT /v1/issuers/:id.

Modalidades de Transporte y Estructura UBL 2.1

El Catálogo 18 de SUNAT define dos modalidades principales en el campo transport_mode_code:

Transporte Privado (Código 02)

El traslado lo realiza el propio remitente con sus propios vehículos y choferes. Requiere obligatoriamente:

vehicle.license_plate: Placa del vehículo principal (ej: ABC-123).
vehicle.secondary_license_plate: Carreta, remolque o semirremolque secundario (opcional).
vehicle.tuc: Tarjeta Única de Circulación o autorización MTC (opcional).
driver.doc_type: Tipo de documento (ej: 1 DNI).
driver.doc_number: Número de documento del chofer.
driver.name: Nombre completo del chofer.
driver.license_number: Número de brevete o licencia de conducir (ej: Q45678912).

Transporte Público (Código 01)

El traslado se delega a una empresa de transporte tercerizada formal. Requiere obligatoriamente:

carrier.doc_type: Siempre 6 (RUC) — una empresa de transporte formal se identifica obligatoriamente con RUC ante SUNAT.
carrier.doc_number: RUC de 11 dígitos de la empresa de transporte.
carrier.name: Razón social de la empresa transportista.
carrier.mtc_registration: Registro de transporte ante el MTC (opcional).

Guía Transportista (31): el remitente NO es el emisor

Cuando despatch_type_code es "31", quien emite el documento es la empresa transportista, no el dueño de la carga. Por eso esta guía exige el objeto sender (el remitente real) además de recipient, y driver/vehicle son siempre obligatorios, sin importar transport_mode_code — el transportista siempre declara su propio vehículo y conductor. El campo carrier se ignora en este caso (el sistema identifica al transportista con los datos del propio emisor automáticamente).

{
  "despatch_type_code": "31",
  "series": "V001",
  "sender": { "doc_type": "6", "doc_number": "20100070970", "name": "DISTRIBUIDORA NORTE S.A." },
  "recipient": { "doc_type": "6", "doc_number": "20200080123", "name": "CLIENTE FINAL S.A.C." },
  "driver": { "doc_type": "1", "doc_number": "45678912", "license_number": "Q45678912" },
  "vehicle": { "license_plate": "ABC-123" }
  ⋮
}

Parámetros del Endpoint /v1/despatches

Campo	Tipo	Requerido	Descripción
issuer_id	string	Sí*	ID del emisor (*no requerido si se usa una API Key restringida a emisor).
despatch.series	string	No	Serie de la guía: `T###` para Remitente (09) o `V###` para Transportista (31). Defecto: `T001` o `V001` según el tipo.
despatch.number	number	No	Correlativo. Si se omite, YoEmito lo autoincrementa atómicamente.
despatch.despatch_type_code	string	No	`09` para Guía Remitente o `31` para Guía Transportista. Defecto: `09`.
despatch.reason_code	string	Sí	Código del Catálogo 20 (`01` Venta, `02` Compra, `04` Traslado entre establecimientos, etc.).
despatch.gross_weight	string / number	Sí	Peso bruto total acumulado de la carga (ej: `1250.50`).
despatch.gross_weight_unit	string	No	Unidad de medida según Catálogo 03. Defecto: `KGM` (Kilogramos).
despatch.transport_mode_code	string	Sí	`01` para Público o `02` para Privado.
despatch.start_transport_date	string	Sí	Fecha programada de inicio del traslado (formato `AAAA-MM-DD`).
despatch.recipient	object	Sí	Destinatario del traslado: `doc_type`, `doc_number`, `name`.
despatch.sender	object	Condicional	Obligatorio solo en Guía Transportista (`despatch_type_code: "31"`): identifica al remitente real (dueño de la carga), ya que en ese caso el emisor del documento es el transportista, no quien envía la mercadería. `doc_type`, `doc_number`, `name`. No aplica en Guía Remitente (09), donde el emisor y el remitente son la misma entidad.
despatch.origin_address	object	Sí	Punto de partida: `ubigeo` (6 dígitos) y `address` (dirección exacta).
despatch.destination_address	object	Sí	Punto de llegada: `ubigeo` (6 dígitos) y `address` (dirección exacta).
despatch.driver	object	Condicional	Obligatorio si `transport_mode_code = "02"`, o siempre en Guía Transportista (31) sin importar el modo. Incluye `license_number` (brevete).
despatch.vehicle	object	Condicional	Obligatorio si `transport_mode_code = "02"`, o siempre en Guía Transportista (31) sin importar el modo. Incluye `license_plate` (placa).
despatch.carrier	object	Condicional	Obligatorio si `transport_mode_code = "01"` en Guía Remitente (09): RUC y razón social del transportista contratado. En Guía Transportista (31) este campo se ignora — el `CarrierParty` del XML se completa automáticamente con los datos del propio emisor.
despatch.lines	array	Sí	Lista de bienes: `quantity`, `unit_code` (Catálogo 03), `description`.