Guías de remisión

POST /v1/waybills emite una guía de remisión (XML 1.1.0): el comprobante que ampara la mercadería mientras viaja, desde un punto de partida hasta uno o más destinatarios.

Solicitud

curl https://api.flashpi.com.ec/v1/waybills \
  -H "Authorization: Bearer $FLASHPI_API_KEY" \
  -H "Idempotency-Key: shipment-SH-7710" \
  -H "Content-Type: application/json" \
  -d @waybill.json

waybill.json

{
  "issuerId": "01a0fd6a-d098-76ca-b492-1bcb6505a7bd",
  "establishment": "001",
  "emissionPoint": "001",
  "issueDate": "2026-10-15",
  "departureAddress": "Km 12 vía a Daule, Guayaquil",
  "carrier": {
    "idType": "ruc",
    "id": "0190000000001",
    "name": "Transportes Andinos Cía. Ltda."
  },
  "licensePlate": "GBA1234",
  "transportStartDate": "2026-10-15",
  "transportEndDate": "2026-10-16",
  "recipients": [
    {
      "id": "1790000000001",
      "name": "Supermercados La Pradera S.A.",
      "address": "Av. Amazonas N34-12, Quito",
      "transferReason": "Sale",
      "destinationEstablishment": "003",
      "route": "Guayaquil - Santo Domingo - Quito",
      "supportingDocument": {
        "type": "invoice",
        "number": "001-001-000000123",
        "authorizationNumber": "1510202601179000000000110010010000001239052713811",
        "issueDate": "2026-10-15"
      },
      "items": [
        { "code": "CAF-500", "description": "Ground coffee 500 g", "quantity": "24" },
        { "code": "CAF-GR1", "description": "Coffee beans 1 kg", "quantity": "10" }
      ]
    }
  ]
}

Campo	Obligatorio	Notas
departureAddress	Sí	Dónde empieza el traslado.
carrier	Sí	Quién transporta la mercadería: idType (no final_consumer), id y name.
licensePlate	Sí	La placa del vehículo, hasta 20 caracteres.
transportStartDate, transportEndDate	Sí	El inicio, no antes de la fecha de emisión, y el fin, no antes del inicio.
recipients	Sí	De 1 a 100 destinos, ver abajo.

Cada destinatario tiene:

Campo	Obligatorio	Notas
id, name, address	Sí	Quién recibe la mercadería, y dónde.
transferReason	Sí	El motivo del traslado (una venta, un traslado entre establecimientos, una devolución…).
items	Sí	De 1 a 1000 bienes, cada uno con description y quantity (hasta 6 decimales) y, opcionalmente, code, auxiliaryCode y hasta 3 additionalDetails.
supportingDocument	No	El comprobante que sustenta el traslado, normalmente la factura de venta: type, number, authorizationNumber (10, 37 o 49 dígitos) e issueDate.
destinationEstablishment	No	El código del establecimiento del destinatario.
route	No	La ruta.
customsDocument	No	El documento aduanero único (DAU), en importaciones y exportaciones.

Una guía de remisión no tiene precios, impuestos ni pagos, así que no acepta expectedTotal. Los campos que comparten todas las solicitudes funcionan igual que en todos los comprobantes.

Respuesta

202 Accepted. Los totals de una guía de remisión son null, su counterparty es el transportista y su email.status es skipped, porque una solicitud de guía de remisión no tiene correo:

{
  "id": "01a14182-44ab-71bb-ad6d-76fbecb9ee53",
  "type": "waybill",
  "environment": "test",
  "status": "processing",
  "issuerId": "01a0fd6a-d098-76ca-b492-1bcb6505a7bd",
  "establishment": "001",
  "emissionPoint": "001",
  "sequential": 45,
  "number": "001-001-000000045",
  "accessKey": "1510202606179000000000110010010000000458031462713",
  "issueDate": "2026-10-15",
  "xmlVersion": "1.1.0",
  "counterparty": { "id": "0190000000001", "name": "Transportes Andinos Cía. Ltda." },
  "totals": null,
  "authorization": { "number": null, "authorizedAt": null },
  "ride": { "status": "pending", "template": null, "generatedAt": null },
  "email": { "requested": true, "status": "skipped", "deliveries": [], "warnings": [] },
  "sriMessages": [],
  "failure": null,
  "voidedAt": null,
  "createdAt": "2026-10-15T21:40:18.731Z",
  "updatedAt": "2026-10-15T21:40:18.731Z"
}

El XML de la guía de remisión no tiene una fecha de emisión propia, así que su RIDE imprime las fechas del traslado. Descarga el RIDE con GET /v1/documents/{id}/pdf para que acompañe a la mercadería. Con options.waitForAuthorization la respuesta puede ser 200 OK con el estado final (Modo síncrono y asíncrono). Los webhooks waybill.authorized y waybill.rejected informan la decisión del SRI.

Para referenciar la guía en la factura de la misma mercadería, envía su número como waybillNumber de la factura.

Errores

Respuesta	Cuándo
422 validation_failed	Por ejemplo transportStartDate anterior a la fecha de emisión (date_too_early), transportEndDate anterior al inicio, o un transportista identificado como consumidor final.
409 sequential_already_used, sequentials_exhausted	Consulta Secuenciales.