Para qué sirve
- Emitir la guía de cada despacho desde tu sistema de almacén o ERP.
- Generar guías de transportista para tu flota o empresa de transporte.
- Documentar traslados entre almacenes o locales de la misma empresa.
- Automatizar guías de envíos de tu tienda online.
- Llevar el control de qué guías aceptó SUNAT.
Cómo funciona el flujo de guías
Las guías de remisión electrónicas se envían a SUNAT por un canal propio, distinto al de facturas, que usa autenticación OAuth2 y procesamiento asíncrono. Por eso el flujo tiene cinco pasos:
- Token SUNAT: obtienes el token OAuth2 que SUNAT exige para el envío de guías.
- Generar el XML de la guía remitente o transportista.
- Enviar la guía generada a SUNAT; la respuesta trae un ticket.
- Consultar el ticket con el nombre del documento (
RUC-09-SERIE-NUMERO) hasta obtener el resultado. - Guardar la CDR que confirma la aceptación.
Guía remitente o guía transportista
| Tipo | tipoDoc | Quién la emite |
|---|---|---|
| Remitente | 09 | Quien envía los bienes: el vendedor, o la empresa que traslada entre sus propios locales. Incluye destinatario y, si corresponde, transportista. |
| Transportista | 31 | La empresa de transporte que presta el servicio de traslado. |
En el comprobante se indican fechas de emisión y de traslado, el motivoTraslado (por ejemplo 01 venta) y la modalidadTraslado (01 transporte público, 02 transporte privado) según los catálogos de SUNAT, el peso total con su unidad, y los puntos de partida y llegada con su ubigeo de 6 dígitos y dirección. Los items describen los bienes trasladados.
Según la modalidad y el motivo, SUNAT exige datos adicionales (por ejemplo, del vehículo o del conductor). Revisa los requisitos vigentes para tu caso.
Cómo empezar
- Crea tu cuenta gratis en miapi.cloud; el plan gratuito te permite probar sin tarjeta.
- Copia tu token desde el panel admin.miapi.cloud.
- Envíalo en cada petición en la cabecera
Authorization: Bearer TU_TOKEN, siempre por HTTPS.
Para guías en producción necesitas además las credenciales que SUNAT asigna para el envío de guías y tu certificado digital configurados en tu cuenta. Si necesitas ayuda para activarlo, escríbenos.
La cantidad de consultas disponibles depende de tu plan; revisa los planes en miapi.cloud/#planes. Si tienes dudas para integrarla, escríbenos por WhatsApp.
Buenas prácticas
- Reutiliza el token SUNAT mientras esté vigente en lugar de pedir uno nuevo por cada guía.
- Valida los ubigeos de partida y llegada y el RUC del destinatario y del transportista con la API RUC.
- Guarda el ticket y consulta el estado con reintentos espaciados, no en bucle.
- Emite la guía antes del traslado y conserva XML y CDR.
- Genera el PDF para el conductor con la API XML a PDF.
Llama a estos endpoints solo desde tu servidor, nunca desde el navegador.
Referencia de la API
Todas las peticiones llevan tu token en la cabecera Authorization: Bearer TU_TOKEN.
Lo copias desde tu panel en admin.miapi.cloud después de
crear tu cuenta gratis. Más detalles en la documentación.
Generar Token SUNAT para Guías
Obtiene el token OAuth2 de SUNAT necesario para enviar guías de remisión.
POST https://miapi.cloud/apifact/despatch/token
curl -X POST "https://miapi.cloud/apifact/despatch/token" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"claveSecreta":"TU_CLAVE_SECRETA"}'const respuesta = await fetch("https://miapi.cloud/apifact/despatch/token", {
method: "POST",
headers: {
"Authorization": "Bearer TU_TOKEN",
"Content-Type": "application/json"
},
body: JSON.stringify({
"claveSecreta": "TU_CLAVE_SECRETA"
}),
});
const datos = await respuesta.json();
console.log(datos);<?php
$ch = curl_init("https://miapi.cloud/apifact/despatch/token");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer TU_TOKEN",
"Content-Type: application/json"
],
CURLOPT_POSTFIELDS => json_encode([
"claveSecreta" => "TU_CLAVE_SECRETA"
]),
]);
$datos = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($datos);import requests
respuesta = requests.post(
"https://miapi.cloud/apifact/despatch/token",
headers={
"Authorization": "Bearer TU_TOKEN",
"Content-Type": "application/json"
},
json={
"claveSecreta": "TU_CLAVE_SECRETA"
},
timeout=30,
)
print(respuesta.json()) Generar XML Guía Remitente
Genera el XML de una guía de remisión remitente (tipo 09).
POST https://miapi.cloud/apifact/despatch/remitent
curl -X POST "https://miapi.cloud/apifact/despatch/remitent" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"claveSecreta":"TU_CLAVE_SECRETA","comprobante":{"tipoDoc":"09","serie":"T001","correlativo":"1","fechaEmision":"2023-02-14","fechaTraslado":"2023-02-15","motivoTraslado":"01","modalidadTraslado":"01","pesoTotal":50.5,"unidadMedida":"KGM","ubigeoPartida":"150101","direccionPartida":"AV. DE EJEMPLO 123","ubigeoLlegada":"150102","direccionLlegada":"AV. DE EJEMPLO 123"},"destinatario":{"tipoDoc":"6","numDoc":"20000000002","rznSocial":"EMPRESA DE EJEMPLO S.A.C."},"transportista":{"tipoDoc":"6","numDoc":"20000000002","rznSocial":"EMPRESA DE EJEMPLO S.A.C."},"items":[{"codProducto":"PRD01","descripcion":"CAJAS DE REPUESTOS","unidad":"NIU","cantidad":10}]}'const respuesta = await fetch("https://miapi.cloud/apifact/despatch/remitent", {
method: "POST",
headers: {
"Authorization": "Bearer TU_TOKEN",
"Content-Type": "application/json"
},
body: JSON.stringify({
"claveSecreta": "TU_CLAVE_SECRETA",
"comprobante": {
"tipoDoc": "09",
"serie": "T001",
"correlativo": "1",
"fechaEmision": "2023-02-14",
"fechaTraslado": "2023-02-15",
"motivoTraslado": "01",
"modalidadTraslado": "01",
"pesoTotal": 50.5,
"unidadMedida": "KGM",
"ubigeoPartida": "150101",
"direccionPartida": "AV. DE EJEMPLO 123",
"ubigeoLlegada": "150102",
"direccionLlegada": "AV. DE EJEMPLO 123"
},
"destinatario": {
"tipoDoc": "6",
"numDoc": "20000000002",
"rznSocial": "EMPRESA DE EJEMPLO S.A.C."
},
"transportista": {
"tipoDoc": "6",
"numDoc": "20000000002",
"rznSocial": "EMPRESA DE EJEMPLO S.A.C."
},
"items": [
{
"codProducto": "PRD01",
"descripcion": "CAJAS DE REPUESTOS",
"unidad": "NIU",
"cantidad": 10
}
]
}),
});
const datos = await respuesta.json();
console.log(datos);<?php
$ch = curl_init("https://miapi.cloud/apifact/despatch/remitent");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer TU_TOKEN",
"Content-Type: application/json"
],
CURLOPT_POSTFIELDS => json_encode([
"claveSecreta" => "TU_CLAVE_SECRETA",
"comprobante" => [
"tipoDoc" => "09",
"serie" => "T001",
"correlativo" => "1",
"fechaEmision" => "2023-02-14",
"fechaTraslado" => "2023-02-15",
"motivoTraslado" => "01",
"modalidadTraslado" => "01",
"pesoTotal" => 50.5,
"unidadMedida" => "KGM",
"ubigeoPartida" => "150101",
"direccionPartida" => "AV. DE EJEMPLO 123",
"ubigeoLlegada" => "150102",
"direccionLlegada" => "AV. DE EJEMPLO 123"
],
"destinatario" => [
"tipoDoc" => "6",
"numDoc" => "20000000002",
"rznSocial" => "EMPRESA DE EJEMPLO S.A.C."
],
"transportista" => [
"tipoDoc" => "6",
"numDoc" => "20000000002",
"rznSocial" => "EMPRESA DE EJEMPLO S.A.C."
],
"items" => [
[
"codProducto" => "PRD01",
"descripcion" => "CAJAS DE REPUESTOS",
"unidad" => "NIU",
"cantidad" => 10
]
]
]),
]);
$datos = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($datos);import requests
respuesta = requests.post(
"https://miapi.cloud/apifact/despatch/remitent",
headers={
"Authorization": "Bearer TU_TOKEN",
"Content-Type": "application/json"
},
json={
"claveSecreta": "TU_CLAVE_SECRETA",
"comprobante": {
"tipoDoc": "09",
"serie": "T001",
"correlativo": "1",
"fechaEmision": "2023-02-14",
"fechaTraslado": "2023-02-15",
"motivoTraslado": "01",
"modalidadTraslado": "01",
"pesoTotal": 50.5,
"unidadMedida": "KGM",
"ubigeoPartida": "150101",
"direccionPartida": "AV. DE EJEMPLO 123",
"ubigeoLlegada": "150102",
"direccionLlegada": "AV. DE EJEMPLO 123"
},
"destinatario": {
"tipoDoc": "6",
"numDoc": "20000000002",
"rznSocial": "EMPRESA DE EJEMPLO S.A.C."
},
"transportista": {
"tipoDoc": "6",
"numDoc": "20000000002",
"rznSocial": "EMPRESA DE EJEMPLO S.A.C."
},
"items": [
{
"codProducto": "PRD01",
"descripcion": "CAJAS DE REPUESTOS",
"unidad": "NIU",
"cantidad": 10
}
]
},
timeout=30,
)
print(respuesta.json()) Generar XML Guía Transportista
Genera el XML de una guía de remisión transportista (tipo 31).
POST https://miapi.cloud/apifact/despatch/transport
curl -X POST "https://miapi.cloud/apifact/despatch/transport" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"claveSecreta":"TU_CLAVE_SECRETA","comprobante":{"tipoDoc":"31","serie":"V001","correlativo":"1","fechaEmision":"2023-02-14","fechaTraslado":"2023-02-15","motivoTraslado":"01","modalidadTraslado":"02","pesoTotal":100,"unidadMedida":"KGM","ubigeoPartida":"150101","direccionPartida":"AV. DE EJEMPLO 123","ubigeoLlegada":"150105","direccionLlegada":"AV. DE EJEMPLO 123"},"items":[{"codProducto":"CRT20","descripcion":"CARGA GENERAL","unidad":"NIU","cantidad":1}]}'const respuesta = await fetch("https://miapi.cloud/apifact/despatch/transport", {
method: "POST",
headers: {
"Authorization": "Bearer TU_TOKEN",
"Content-Type": "application/json"
},
body: JSON.stringify({
"claveSecreta": "TU_CLAVE_SECRETA",
"comprobante": {
"tipoDoc": "31",
"serie": "V001",
"correlativo": "1",
"fechaEmision": "2023-02-14",
"fechaTraslado": "2023-02-15",
"motivoTraslado": "01",
"modalidadTraslado": "02",
"pesoTotal": 100,
"unidadMedida": "KGM",
"ubigeoPartida": "150101",
"direccionPartida": "AV. DE EJEMPLO 123",
"ubigeoLlegada": "150105",
"direccionLlegada": "AV. DE EJEMPLO 123"
},
"items": [
{
"codProducto": "CRT20",
"descripcion": "CARGA GENERAL",
"unidad": "NIU",
"cantidad": 1
}
]
}),
});
const datos = await respuesta.json();
console.log(datos);<?php
$ch = curl_init("https://miapi.cloud/apifact/despatch/transport");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer TU_TOKEN",
"Content-Type: application/json"
],
CURLOPT_POSTFIELDS => json_encode([
"claveSecreta" => "TU_CLAVE_SECRETA",
"comprobante" => [
"tipoDoc" => "31",
"serie" => "V001",
"correlativo" => "1",
"fechaEmision" => "2023-02-14",
"fechaTraslado" => "2023-02-15",
"motivoTraslado" => "01",
"modalidadTraslado" => "02",
"pesoTotal" => 100,
"unidadMedida" => "KGM",
"ubigeoPartida" => "150101",
"direccionPartida" => "AV. DE EJEMPLO 123",
"ubigeoLlegada" => "150105",
"direccionLlegada" => "AV. DE EJEMPLO 123"
],
"items" => [
[
"codProducto" => "CRT20",
"descripcion" => "CARGA GENERAL",
"unidad" => "NIU",
"cantidad" => 1
]
]
]),
]);
$datos = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($datos);import requests
respuesta = requests.post(
"https://miapi.cloud/apifact/despatch/transport",
headers={
"Authorization": "Bearer TU_TOKEN",
"Content-Type": "application/json"
},
json={
"claveSecreta": "TU_CLAVE_SECRETA",
"comprobante": {
"tipoDoc": "31",
"serie": "V001",
"correlativo": "1",
"fechaEmision": "2023-02-14",
"fechaTraslado": "2023-02-15",
"motivoTraslado": "01",
"modalidadTraslado": "02",
"pesoTotal": 100,
"unidadMedida": "KGM",
"ubigeoPartida": "150101",
"direccionPartida": "AV. DE EJEMPLO 123",
"ubigeoLlegada": "150105",
"direccionLlegada": "AV. DE EJEMPLO 123"
},
"items": [
{
"codProducto": "CRT20",
"descripcion": "CARGA GENERAL",
"unidad": "NIU",
"cantidad": 1
}
]
},
timeout=30,
)
print(respuesta.json()) Envío de Guías a SUNAT
Envía a SUNAT una guía de remisión remitente o transportista ya generada.
POST https://miapi.cloud/apifact/despatch/send
curl -X POST "https://miapi.cloud/apifact/despatch/send" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"claveSecreta":"TU_CLAVE_SECRETA","comprobante":{"tipoDoc":"09","serie":"T001","correlativo":"1"}}'const respuesta = await fetch("https://miapi.cloud/apifact/despatch/send", {
method: "POST",
headers: {
"Authorization": "Bearer TU_TOKEN",
"Content-Type": "application/json"
},
body: JSON.stringify({
"claveSecreta": "TU_CLAVE_SECRETA",
"comprobante": {
"tipoDoc": "09",
"serie": "T001",
"correlativo": "1"
}
}),
});
const datos = await respuesta.json();
console.log(datos);<?php
$ch = curl_init("https://miapi.cloud/apifact/despatch/send");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer TU_TOKEN",
"Content-Type: application/json"
],
CURLOPT_POSTFIELDS => json_encode([
"claveSecreta" => "TU_CLAVE_SECRETA",
"comprobante" => [
"tipoDoc" => "09",
"serie" => "T001",
"correlativo" => "1"
]
]),
]);
$datos = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($datos);import requests
respuesta = requests.post(
"https://miapi.cloud/apifact/despatch/send",
headers={
"Authorization": "Bearer TU_TOKEN",
"Content-Type": "application/json"
},
json={
"claveSecreta": "TU_CLAVE_SECRETA",
"comprobante": {
"tipoDoc": "09",
"serie": "T001",
"correlativo": "1"
}
},
timeout=30,
)
print(respuesta.json()) Consultar Ticket de Envío (Guías)
Verifica el estado del ticket que devuelve SUNAT tras enviar una guía.
POST https://miapi.cloud/apifact/despatch/consult
curl -X POST "https://miapi.cloud/apifact/despatch/consult" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"claveSecreta":"TU_CLAVE_SECRETA","nombreDoc":"RUC-09-SERIE-NUMERO","ticket":"TU_TICKET"}'const respuesta = await fetch("https://miapi.cloud/apifact/despatch/consult", {
method: "POST",
headers: {
"Authorization": "Bearer TU_TOKEN",
"Content-Type": "application/json"
},
body: JSON.stringify({
"claveSecreta": "TU_CLAVE_SECRETA",
"nombreDoc": "RUC-09-SERIE-NUMERO",
"ticket": "TU_TICKET"
}),
});
const datos = await respuesta.json();
console.log(datos);<?php
$ch = curl_init("https://miapi.cloud/apifact/despatch/consult");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer TU_TOKEN",
"Content-Type: application/json"
],
CURLOPT_POSTFIELDS => json_encode([
"claveSecreta" => "TU_CLAVE_SECRETA",
"nombreDoc" => "RUC-09-SERIE-NUMERO",
"ticket" => "TU_TICKET"
]),
]);
$datos = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($datos);import requests
respuesta = requests.post(
"https://miapi.cloud/apifact/despatch/consult",
headers={
"Authorization": "Bearer TU_TOKEN",
"Content-Type": "application/json"
},
json={
"claveSecreta": "TU_CLAVE_SECRETA",
"nombreDoc": "RUC-09-SERIE-NUMERO",
"ticket": "TU_TICKET"
},
timeout=30,
)
print(respuesta.json()) Errores frecuentes
| Código | Qué significa |
|---|---|
401 | Token de MiAPI inválido o ausente, o token SUNAT vencido. Revisa Authorization: Bearer TU_TOKEN y genera un nuevo token SUNAT. |
400 / 422 | Datos incompletos o inválidos: ubigeos, motivo o modalidad de traslado, peso, documento del destinatario o del transportista. |
429 | Alcanzaste el límite de tu plan o enviaste demasiadas peticiones seguidas. |
5xx | El servicio de SUNAT no está disponible. Reintenta más tarde; si ya tienes ticket, reintenta solo la consulta. |
Preguntas frecuentes
¿Qué diferencia hay entre guía remitente y guía transportista?
La guía remitente (09) la emite quien envía los bienes. La guía transportista (31) la emite la empresa que presta el servicio de transporte.
¿Por qué necesito un token SUNAT aparte?
Porque SUNAT recibe las guías de remisión electrónicas por un servicio que exige autenticación OAuth2. El endpoint de token lo obtiene por ti.
¿Por qué la guía no se acepta al instante?
El envío de guías es asíncrono: SUNAT devuelve un ticket y el resultado se consulta después con ese ticket.
¿Qué es el ubigeo de partida y llegada?
Es el código de 6 dígitos del distrito de origen y de destino del traslado, que SUNAT exige junto con la dirección.
¿Puedo probar antes de emitir guías reales?
Sí. Regístrate gratis en miapi.cloud y prueba la integración. Los límites dependen de tu plan; revísalos en miapi.cloud/#planes.
APIs relacionadas
-
API Facturación Electrónica
Emite facturas y boletas electrónicas desde tu propio software: envías los datos en JSON, generamos y firmamos el XML y lo enviamos a SUNAT.
-
API XML a PDF
Convierte el XML de tus comprobantes electrónicos en una representación impresa en PDF, en formato A4 o ticket, uno por uno o varios a la vez en un ZIP.
-
API RUC
Consulta razón social, estado, condición y domicilio fiscal de cualquier RUC de 11 dígitos, con versiones detallada y completa de la ficha tributaria y consulta masiva.
Empieza gratis hoy
Crea tu cuenta gratis, copia tu token y haz tu primera consulta en minutos. Sin tarjeta de crédito.