Guías de Remisión - Sistema de Facturación Electrónica SUNAT

GET /api/guias-remision

Lista todas las guías de remisión de la empresa activa.

Autenticación

Requiere autenticación con token Bearer.

Parámetros de Consulta

No requiere parámetros. Los resultados están paginados (15 por página).

Respuesta

data

array

Lista paginada de guías de remisión

Show Estructura

integer

ID único de la guía

serie

string

Serie de la guía (T001)

numero

integer

Número correlativo

fecha_emision

string

Fecha de emisión

fecha_traslado

string

Fecha de inicio del traslado

destinatario_nombre

string

Nombre del destinatario

destinatario_documento

string

Documento del destinatario

motivo_traslado

string

Código del motivo (01-18)

mod_transporte

string

Modalidad: 01 (Público) o 02 (Privado)

peso_total

number

Peso total en kg

estado

string

Estado: pendiente, enviado, aceptado, rechazado

ticket_sunat

string

Ticket de SUNAT (para consultar estado)

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/guias-remision" \
  -H "Authorization: Bearer {token}"

POST /api/guias-remision

Crea una nueva guía de remisión electrónica.

Autenticación

Requiere autenticación con token Bearer.

Parámetros del Body

Datos Generales

id_venta

integer

ID de la venta relacionada (opcional)

fecha_traslado

string

required

Fecha de inicio del traslado (formato: YYYY-MM-DD)

motivo_traslado

string

required

Código del motivo de traslado (01-18). Use /api/guias-remision/motivos para la lista.

descripcion_motivo

string

Descripción adicional del motivo (máximo 255 caracteres)

mod_transporte

string

required

Modalidad de transporte:

01: Transporte público
02: Transporte privado

peso_total

number

required

Peso total de la carga en kg (mínimo 0.001)

und_peso_total

string

Unidad de peso (default: KGM)

observaciones

string

Observaciones adicionales

Destinatario

destinatario_tipo_doc

string

required

Tipo de documento: 1 (DNI) o 6 (RUC)

destinatario_documento

string

required

Número de documento del destinatario

destinatario_nombre

string

required

Nombre o razón social del destinatario

destinatario_direccion

string

required

Dirección del destinatario (punto de llegada)

destinatario_ubigeo

string

Código ubigeo del punto de llegada (6 dígitos)

Puntos de Partida y Llegada

ubigeo_partida

string

Ubigeo del punto de partida. Si no se envía, usa el ubigeo de la empresa.

dir_partida

string

Dirección del punto de partida. Si no se envía, usa la dirección de la empresa.

Transporte Público (mod_transporte = 01)

transportista_tipo_doc

string

required

Tipo de documento del transportista

transportista_documento

string

required

Documento del transportista

transportista_nombre

string

required

Nombre o razón social del transportista

transportista_nro_mtc

string

Número de registro MTC del transportista

Transporte Privado (mod_transporte = 02)

vehiculo_m1l

boolean

Indica si es vehículo categoría M1 o L (true = campos opcionales)

conductor_tipo_doc

string

Tipo de documento del conductor (requerido si no es M1/L)

conductor_documento

string

Documento del conductor (requerido si no es M1/L)

conductor_nombres

string

Nombres del conductor (requerido si no es M1/L)

conductor_apellidos

string

Apellidos del conductor (requerido si no es M1/L)

conductor_licencia

string

Número de licencia de conducir (requerido si no es M1/L)

vehiculo_placa

string

Placa del vehículo (requerido si no es M1/L)

Detalles de la Carga

detalles

array

required

Lista de bienes a transportar (mínimo 1)

Show Estructura

descripcion

string

required

Descripción del bien

cantidad

number

required

Cantidad (mínimo 0.001)

unidad

string

Código SUNAT de unidad (default: NIU)

codigo

string

Código interno del producto

id_producto

integer

ID del producto (opcional)

Proceso Automático

Al crear la guía de remisión:

Obtiene el próximo número correlativo para la serie T001
Genera el archivo XML firmado
Sincroniza el número en documentos_empresas
Asigna la fecha de emisión automáticamente (hoy)

Respuesta

success

boolean

Indica si la guía fue creada exitosamente

data

object

Objeto completo de la guía de remisión creada

xml

object

Información sobre la generación del XML

Ejemplo de Uso

curl -X POST "https://api.ejemplo.com/api/guias-remision" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "destinatario_tipo_doc": "6",
    "destinatario_documento": "20612706702",
    "destinatario_nombre": "EMPRESA DESTINO SAC",
    "destinatario_direccion": "AV. EJEMPLO 456",
    "destinatario_ubigeo": "150101",
    "motivo_traslado": "01",
    "mod_transporte": "02",
    "fecha_traslado": "2024-01-20",
    "peso_total": 50.5,
    "vehiculo_m1l": true,
    "detalles": [
      {
        "descripcion": "Laptops HP",
        "cantidad": 10,
        "unidad": "NIU",
        "codigo": "LAP001"
      }
    ]
  }'

GET /api/guias-remision/

Obtiene el detalle completo de una guía de remisión.

Autenticación

Requiere autenticación con token Bearer.

Parámetros de Ruta

integer

required

ID de la guía de remisión

Respuesta

Objeto completo de la guía con detalles, venta y empresa.

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/guias-remision/78" \
  -H "Authorization: Bearer {token}"

POST /api/guias-remision//enviar

Envía la guía de remisión a SUNAT (GRE API - asincrónico).

Autenticación

Requiere autenticación con token Bearer.

Parámetros de Ruta

integer

required

ID de la guía de remisión

Requisitos

La guía debe tener el XML generado
La empresa debe tener:
- Certificado digital configurado
- Client ID y Client Secret de GRE configurados (SUNAT_GRE_CLIENT_ID, SUNAT_GRE_CLIENT_SECRET)

Proceso de Envío (Asincrónico)

Obtiene token OAuth2 de SUNAT
Envía el XML firmado al GRE API
SUNAT devuelve un ticket (número de seguimiento)
Guarda el ticket en la guía
Estado queda en “enviado” hasta consultar el ticket

Nota: A diferencia de facturas/boletas, las guías NO reciben CDR inmediatamente. Debe consultarse el ticket posteriormente.

Respuesta

success

boolean

Indica si el envío fue exitoso

ticket

string

Número de ticket de SUNAT para consultar el estado

Ejemplo de Uso

curl -X POST "https://api.ejemplo.com/api/guias-remision/78/enviar" \
  -H "Authorization: Bearer {token}"

GET /api/guias-remision//ticket

Consulta el estado del ticket en SUNAT y obtiene el CDR.

Autenticación

Requiere autenticación con token Bearer.

Parámetros de Ruta

integer

required

ID de la guía de remisión

Requisitos

La guía debe tener un ticket de SUNAT

Proceso

Consulta el estado del ticket en SUNAT
Si está aceptado: descarga el CDR y actualiza el estado a “aceptado”
Si está rechazado: actualiza el estado a “rechazado” con el motivo
Si está en proceso: devuelve estado “pendiente”

Respuesta

success

boolean

Indica si la consulta fue exitosa

estado

string

Estado actual: pendiente, aceptado, rechazado

codigo_sunat

string

Código de respuesta de SUNAT (si está procesado)

mensaje_sunat

string

Mensaje de SUNAT

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/guias-remision/78/ticket" \
  -H "Authorization: Bearer {token}"

GET /api/guias-remision//cdr

Descarga el archivo CDR de SUNAT.

Autenticación

Requiere autenticación con token Bearer.

Parámetros de Ruta

integer

required

ID de la guía de remisión

Respuesta

Descarga directa del archivo ZIP con el CDR.

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/guias-remision/78/cdr" \
  -H "Authorization: Bearer {token}" \
  -o cdr-guia.zip

GET /api/guias-remision/xml/

Descarga el archivo XML de la guía.

Autenticación

Requiere autenticación con token Bearer.

Parámetros de Ruta

nombre

string

required

Nombre del archivo XML

Respuesta

Archivo XML con Content-Type: application/xml.

GET /api/guias-remision/proximo-numero

Obtiene el próximo número correlativo disponible.

Autenticación

Requiere autenticación con token Bearer.

Respuesta

success

boolean

Indica si la operación fue exitosa

numero

integer

Próximo número correlativo

numero_completo

string

Número completo (ej: T001-00000042)

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/guias-remision/proximo-numero" \
  -H "Authorization: Bearer {token}"

GET /api/guias-remision/motivos

Obtiene la lista de motivos de traslado según catálogo SUNAT.

Autenticación

Requiere autenticación con token Bearer.

Respuesta

Lista de motivos activos ordenados por código.

Motivos Principales SUNAT

01: Venta
02: Compra
03: Venta sujeta a confirmación
04: Consignación
05: Devolución
06: Traslado entre establecimientos de la misma empresa
07: Traslado de bienes para transformación
08: Recojo de bienes
09: Traslado por emisor itinerante CP
13: Otros
14: Venta con entrega a terceros
18: Traslado de bienes para exportación

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/guias-remision/motivos" \
  -H "Authorization: Bearer {token}"

GET /api/guias-remision/empresa

Obtiene los datos de la empresa activa para autocompletar punto de partida.

Autenticación

Requiere autenticación con token Bearer.

Respuesta

success

boolean

Indica si la operación fue exitosa

data

object

Razón social de la empresa

ruc

string

RUC de la empresa

direccion

string

Dirección de la empresa

ubigeo

string

Código ubigeo

departamento

string

Departamento

provincia

string

Provincia

distrito

string

Distrito

GET /api/guias-remision/ubigeos

Busca códigos ubigeo por nombre o código.

Autenticación

Requiere autenticación con token Bearer.

Parámetros de Consulta

string

Término de búsqueda (nombre o código ubigeo)

Respuesta

Lista de hasta 20 ubigeos que coinciden con la búsqueda.

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/guias-remision/ubigeos?q=lima" \
  -H "Authorization: Bearer {token}"

Códigos de Error

400 Bad Request: La guía no tiene XML generado.
404 Not Found: Guía no encontrada o CDR no disponible.
422 Unprocessable Entity: Error de validación.
500 Internal Server Error: Error en el servidor o al comunicarse con SUNAT.

Notas Importantes

Envío asincrónico: A diferencia de facturas/boletas, las guías usan el API GRE que es asincrónico. Debe consultarse el ticket posteriormente.
Serie fija: Todas las guías usan la serie T001.
Vehículos M1/L: Si marca vehiculo_m1l: true, todos los campos del conductor y vehículo son opcionales.
Transporte público vs privado: Los campos requeridos varían según la modalidad.
La guía se puede crear sin estar vinculada a una venta (id_venta es opcional).

Autenticación

Endpoints

Recursos

​GET /api/guias-remision

​Autenticación

​Parámetros de Consulta

​Respuesta

​Ejemplo de Uso

​POST /api/guias-remision

​Autenticación

​Parámetros del Body

​Datos Generales

​Destinatario

​Puntos de Partida y Llegada

​Transporte Público (mod_transporte = 01)

​Transporte Privado (mod_transporte = 02)

​Detalles de la Carga

​Proceso Automático

​Respuesta

​Ejemplo de Uso

​GET /api/guias-remision/

​Autenticación

​Parámetros de Ruta

​Respuesta

​Ejemplo de Uso

​POST /api/guias-remision//enviar

​Autenticación

​Parámetros de Ruta

​Requisitos

​Proceso de Envío (Asincrónico)

​Respuesta

​Ejemplo de Uso

​GET /api/guias-remision//ticket

​Autenticación

​Parámetros de Ruta

​Requisitos

​Proceso

​Respuesta

​Ejemplo de Uso

​GET /api/guias-remision//cdr

​Autenticación

​Parámetros de Ruta

​Respuesta

​Ejemplo de Uso

​GET /api/guias-remision/xml/

​Autenticación

​Parámetros de Ruta

​Respuesta

​GET /api/guias-remision/proximo-numero

​Autenticación

​Respuesta

​Ejemplo de Uso

​GET /api/guias-remision/motivos

​Autenticación

​Respuesta

​Motivos Principales SUNAT

​Ejemplo de Uso

​GET /api/guias-remision/empresa

​Autenticación

​Respuesta

​GET /api/guias-remision/ubigeos

​Autenticación

​Parámetros de Consulta

​Respuesta

​Ejemplo de Uso

​Códigos de Error

​Notas Importantes

Build docs developers (and LLMs) love

GET /api/guias-remision

Autenticación

Parámetros de Consulta

Respuesta

Ejemplo de Uso

POST /api/guias-remision

Autenticación

Parámetros del Body

Datos Generales

Destinatario

Puntos de Partida y Llegada

Transporte Público (mod_transporte = 01)

Transporte Privado (mod_transporte = 02)

Detalles de la Carga

Proceso Automático

Respuesta

Ejemplo de Uso

GET /api/guias-remision/

Autenticación

Parámetros de Ruta

Respuesta

Ejemplo de Uso

POST /api/guias-remision//enviar

Autenticación

Parámetros de Ruta

Requisitos

Proceso de Envío (Asincrónico)

Respuesta

Ejemplo de Uso

GET /api/guias-remision//ticket

Autenticación

Parámetros de Ruta

Requisitos

Proceso

Respuesta

Ejemplo de Uso

GET /api/guias-remision//cdr

Autenticación

Parámetros de Ruta

Respuesta

Ejemplo de Uso

GET /api/guias-remision/xml/

Autenticación

Parámetros de Ruta

Respuesta

GET /api/guias-remision/proximo-numero

Autenticación

Respuesta

Ejemplo de Uso

GET /api/guias-remision/motivos

Autenticación

Respuesta

Motivos Principales SUNAT

Ejemplo de Uso

GET /api/guias-remision/empresa

Autenticación

Respuesta

GET /api/guias-remision/ubigeos

Autenticación

Parámetros de Consulta

Respuesta

Ejemplo de Uso

Códigos de Error

Notas Importantes