Guías de remisión

La guía de remisión sustenta el traslado de bienes. Hay dos, y las emite la misma ruta, POST /v1/despatch_advices:

Guía	Tipo	Serie	La emite
Remitente	09	T001	Quien envía los bienes
Transportista	31	V001	Quien los transporta

No hace falta enviar type: la serie ya lo dice. Una guía no tiene moneda ni importes: currency y total vuelven null.

En modo de prueba, la aceptación es simulada

SUNAT no tiene ambiente de pruebas para guías. Con una llave sk_test_… Emitay valida la guía, la arma y la firma como una real, pero no la envía a SUNAT: responde accepted con sunat.simulated: true, sin CDR ni QR, y el PDF lleva la leyenda «ACEPTACIÓN SIMULADA». Sirve para probar tu integración; no dice que SUNAT la aceptaría.

Guía de remitente con transporte privado

El remitente traslada los bienes en su propio vehículo (transport_mode: "02"): la guía lleva la placa, el conductor y la fecha de inicio del traslado.

curl

curl https://api.emitay.com/v1/despatch_advices \
  -H "Authorization: Bearer $EMITAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "series": "T001",
    "recipient": {
      "document_type": "6",
      "document_number": "20100066603",
      "name": "CLIENTE S.A."
    },
    "reason_code": "01",
    "transport_mode": "02",
    "start_date": "2030-01-15",
    "gross_weight": "12.500",
    "packages": 4,
    "origin": { "ubigeo": "150101", "address": "AV. AREQUIPA 123, LIMA" },
    "destination": { "ubigeo": "150122", "address": "AV. LARCO 456, MIRAFLORES" },
    "vehicles": [{ "plate": "ABC123" }],
    "drivers": [
      {
        "document_type": "1",
        "document_number": "45678912",
        "first_name": "JUAN",
        "last_name": "PÉREZ ROJAS",
        "license": "Q45678912"
      }
    ],
    "related_documents": [{ "type": "01", "number": "F001-1" }],
    "items": [{ "description": "Caja de repuestos", "quantity": 4 }]
  }'

PowerShell

$cabeceras = @{
  Authorization = "Bearer $env:EMITAY_API_KEY"
}
$cuerpo = @'
{
  "series": "T001",
  "recipient": {
    "document_type": "6",
    "document_number": "20100066603",
    "name": "CLIENTE S.A."
  },
  "reason_code": "01",
  "transport_mode": "02",
  "start_date": "2030-01-15",
  "gross_weight": "12.500",
  "packages": 4,
  "origin": { "ubigeo": "150101", "address": "AV. AREQUIPA 123, LIMA" },
  "destination": { "ubigeo": "150122", "address": "AV. LARCO 456, MIRAFLORES" },
  "vehicles": [{ "plate": "ABC123" }],
  "drivers": [
    {
      "document_type": "1",
      "document_number": "45678912",
      "first_name": "JUAN",
      "last_name": "PÉREZ ROJAS",
      "license": "Q45678912"
    }
  ],
  "related_documents": [{ "type": "01", "number": "F001-1" }],
  "items": [{ "description": "Caja de repuestos", "quantity": 4 }]
}
'@
Invoke-RestMethod -Method Post `
  -Uri https://api.emitay.com/v1/despatch_advices `
  -Headers $cabeceras `
  -ContentType "application/json; charset=utf-8" `
  -Body $cuerpo

TypeScript

import { Emitay } from "emitay";

const emitay = new Emitay(); // toma la llave de EMITAY_API_KEY

const guia = await emitay.despatchAdvices.create({
  series: "T001",
  recipient: {
    document_type: "6",
    document_number: "20100066603",
    name: "CLIENTE S.A.",
  },
  reason_code: "01",
  transport_mode: "02",
  start_date: "2030-01-15",
  gross_weight: "12.500",
  packages: 4,
  origin: { ubigeo: "150101", address: "AV. AREQUIPA 123, LIMA" },
  destination: { ubigeo: "150122", address: "AV. LARCO 456, MIRAFLORES" },
  vehicles: [{ plate: "ABC123" }],
  drivers: [
    {
      document_type: "1",
      document_number: "45678912",
      first_name: "JUAN",
      last_name: "PÉREZ ROJAS",
      license: "Q45678912",
    },
  ],
  related_documents: [{ type: "01", number: "F001-1" }],
  items: [{ description: "Caja de repuestos", quantity: 4 }],
});

• recipient es el destinatario; aquí sí se indica document_type.
• reason_code es el motivo del traslado (catálogo 20, abajo).
• origin y destination llevan el ubigeo del distrito (6 dígitos del INEI) y la dirección.
• gross_weight va en kilogramos (KGM) salvo que weight_unit diga TNE.
• vehicles y drivers: el primero es el principal; puedes añadir hasta dos secundarios. La placa va sin guion (ABC123).
• related_documents cita la factura o boleta de la venta, por su número impreso.

La fecha de inicio no puede ser anterior a la de emisión, y SUNAT recibe una guía solo hasta el día siguiente a su fecha de emisión: emítela cuando vaya a salir. La fecha del ejemplo está lejos para que funcione al pegarlo; pon la tuya.

Guía de remitente con transporte público

Se contrata a un transportista (transport_mode: "01"): la guía lleva sus datos y la fecha en que se le entregan los bienes, y no lleva placa ni conductor.

curl

curl https://api.emitay.com/v1/despatch_advices \
  -H "Authorization: Bearer $EMITAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "series": "T001",
    "recipient": {
      "document_type": "6",
      "document_number": "20100066603",
      "name": "CLIENTE S.A."
    },
    "reason_code": "01",
    "transport_mode": "01",
    "handover_date": "2030-01-15",
    "carrier": { "ruc": "20512345671", "name": "TRANSPORTES DEL SUR S.A.C." },
    "gross_weight": "250",
    "origin": { "ubigeo": "150101", "address": "AV. AREQUIPA 123, LIMA" },
    "destination": {
      "ubigeo": "040101",
      "address": "CALLE MERCADERES 210, AREQUIPA"
    },
    "items": [{ "description": "Caja de repuestos", "quantity": 40 }]
  }'

PowerShell

$cabeceras = @{
  Authorization = "Bearer $env:EMITAY_API_KEY"
}
$cuerpo = @'
{
  "series": "T001",
  "recipient": {
    "document_type": "6",
    "document_number": "20100066603",
    "name": "CLIENTE S.A."
  },
  "reason_code": "01",
  "transport_mode": "01",
  "handover_date": "2030-01-15",
  "carrier": { "ruc": "20512345671", "name": "TRANSPORTES DEL SUR S.A.C." },
  "gross_weight": "250",
  "origin": { "ubigeo": "150101", "address": "AV. AREQUIPA 123, LIMA" },
  "destination": {
    "ubigeo": "040101",
    "address": "CALLE MERCADERES 210, AREQUIPA"
  },
  "items": [{ "description": "Caja de repuestos", "quantity": 40 }]
}
'@
Invoke-RestMethod -Method Post `
  -Uri https://api.emitay.com/v1/despatch_advices `
  -Headers $cabeceras `
  -ContentType "application/json; charset=utf-8" `
  -Body $cuerpo

TypeScript

import { Emitay } from "emitay";

const emitay = new Emitay(); // toma la llave de EMITAY_API_KEY

const guia = await emitay.despatchAdvices.create({
  series: "T001",
  recipient: {
    document_type: "6",
    document_number: "20100066603",
    name: "CLIENTE S.A.",
  },
  reason_code: "01",
  transport_mode: "01",
  handover_date: "2030-01-15",
  carrier: { ruc: "20512345671", name: "TRANSPORTES DEL SUR S.A.C." },
  gross_weight: "250",
  origin: { ubigeo: "150101", address: "AV. AREQUIPA 123, LIMA" },
  destination: { ubigeo: "040101", address: "CALLE MERCADERES 210, AREQUIPA" },
  items: [{ description: "Caja de repuestos", quantity: 40 }],
});

Guía de transportista

La emite la empresa de transporte. Lleva al remitente (sender), el vehículo y el conductor; no lleva motivo ni modalidad.

curl

curl https://api.emitay.com/v1/despatch_advices \
  -H "Authorization: Bearer $EMITAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "series": "V001",
    "sender": {
      "document_type": "6",
      "document_number": "20601234565",
      "name": "COMERCIAL ANDINA S.A.C."
    },
    "recipient": {
      "document_type": "6",
      "document_number": "20100066603",
      "name": "CLIENTE S.A."
    },
    "start_date": "2030-01-15",
    "gross_weight": "250",
    "origin": { "ubigeo": "150101", "address": "AV. AREQUIPA 123, LIMA" },
    "destination": {
      "ubigeo": "040101",
      "address": "CALLE MERCADERES 210, AREQUIPA"
    },
    "vehicles": [{ "plate": "V1A456" }],
    "drivers": [
      {
        "document_type": "1",
        "document_number": "45678912",
        "first_name": "JUAN",
        "last_name": "PÉREZ ROJAS",
        "license": "Q45678912"
      }
    ],
    "items": [{ "description": "Caja de repuestos", "quantity": 40 }]
  }'

PowerShell

$cabeceras = @{
  Authorization = "Bearer $env:EMITAY_API_KEY"
}
$cuerpo = @'
{
  "series": "V001",
  "sender": {
    "document_type": "6",
    "document_number": "20601234565",
    "name": "COMERCIAL ANDINA S.A.C."
  },
  "recipient": {
    "document_type": "6",
    "document_number": "20100066603",
    "name": "CLIENTE S.A."
  },
  "start_date": "2030-01-15",
  "gross_weight": "250",
  "origin": { "ubigeo": "150101", "address": "AV. AREQUIPA 123, LIMA" },
  "destination": {
    "ubigeo": "040101",
    "address": "CALLE MERCADERES 210, AREQUIPA"
  },
  "vehicles": [{ "plate": "V1A456" }],
  "drivers": [
    {
      "document_type": "1",
      "document_number": "45678912",
      "first_name": "JUAN",
      "last_name": "PÉREZ ROJAS",
      "license": "Q45678912"
    }
  ],
  "items": [{ "description": "Caja de repuestos", "quantity": 40 }]
}
'@
Invoke-RestMethod -Method Post `
  -Uri https://api.emitay.com/v1/despatch_advices `
  -Headers $cabeceras `
  -ContentType "application/json; charset=utf-8" `
  -Body $cuerpo

TypeScript

import { Emitay } from "emitay";

const emitay = new Emitay(); // toma la llave de EMITAY_API_KEY

const guia = await emitay.despatchAdvices.create({
  series: "V001",
  sender: {
    document_type: "6",
    document_number: "20601234565",
    name: "COMERCIAL ANDINA S.A.C.",
  },
  recipient: {
    document_type: "6",
    document_number: "20100066603",
    name: "CLIENTE S.A.",
  },
  start_date: "2030-01-15",
  gross_weight: "250",
  origin: { ubigeo: "150101", address: "AV. AREQUIPA 123, LIMA" },
  destination: { ubigeo: "040101", address: "CALLE MERCADERES 210, AREQUIPA" },
  vehicles: [{ plate: "V1A456" }],
  drivers: [
    {
      document_type: "1",
      document_number: "45678912",
      first_name: "JUAN",
      last_name: "PÉREZ ROJAS",
      license: "Q45678912",
    },
  ],
  items: [{ description: "Caja de repuestos", quantity: 40 }],
});

Motivos de traslado (catálogo 20)

reason_code	Motivo
01	Venta
02	Compra
03	Venta con entrega a terceros
04	Traslado entre establecimientos de la misma empresa
05	Consignación
06	Devolución
07	Recojo de bienes transformados
13	Otros (exige reason_description)
14	Venta sujeta a confirmación del comprador
17	Traslado de bienes para transformación
18	Traslado emisor itinerante de comprobantes de pago

Los motivos 08 (importación), 09 (exportación) y 19 (mercancía extranjera) aún no se ofrecen: piden datos aduaneros que el contrato no recibe.

El motivo decide quiénes participan. Emitay lo comprueba y responde 422 con el campo:

• En una venta (01), una consignación o una devolución, el destinatario es otro que el remitente; entre establecimientos de la misma empresa (04) es el mismo.
• supplier (proveedor) va con los motivos 02, 07 y 13; buyer (comprador), con 03 y 13.
• Con 04, los puntos de partida y de llegada llevan su establishment_code.

Lo que Emitay completa

Donde las reglas de SUNAT no dejan duda, no se pide: el RUC dueño de un establecimiento (establishment_ruc), el emisor de un documento relacionado (issuer_ruc) y la descripción del tipo de documento relacionado.

En producción

• La empresa necesita, además del certificado y el usuario SOL, las credenciales de la API de SUNAT para guías (client_id y client_secret), que se generan en SUNAT Operaciones en Línea. Sin ellas la API responde 409 company_not_configured. Los pasos están en Pasar a producción.
• El envío de una guía siempre es asíncrono: SUNAT entrega un ticket y responde después. Prefer: wait vuelve en cuanto hay ticket, con la guía aún pending; el veredicto llega por webhook.
• El QR de una guía es el que SUNAT devuelve al aceptarla: un PDF pedido antes sale sin él.
• Una guía no se anula por la API. SUNAT no ofrece ese servicio: la baja se registra en SUNAT Operaciones en Línea, antes de iniciar el traslado o si cambia el destinatario. POST /v1/documents/{id}/void responde 409 y lo explica.

Todos los campos, por tipo de guía, están en la referencia.