Saltar al contenido principal

Envíos y Transportistas

La API de Envíos te permite calcular tarifas de transporte basadas en dimensiones y peso del paquete, crear envíos asociados a órdenes de compra, generar etiquetas de envío y actualizar la información de seguimiento.

Estructura de Dirección (Address)​

Varios endpoints de la API requieren o devuelven un objeto de dirección estructurado con los siguientes campos:

{
  "name": "Juan Pérez",
  "line1": "Av. Larco 123",
  "line2": "Dpto 402",
  "city": "Lima",
  "state": "Lima",
  "postal_code": "15074",
  "country": "PE",
  "phone": "+51999888777"
}
  • Campos requeridos: name, line1, city, postal_code, country (código de país ISO 3166-1 alfa-2 de 2 letras).

Calcular Tarifas​

Permite consultar las tarifas de envío y los tiempos estimados de entrega ofrecidos por los transportistas integrados (ej. DHL, FedEx, Olva Courier).

POST /shipping/rates/calculate

Payload de entrada:

{
  "weight_g": 1500,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 15,
  "origin_address": {
    "name": "Almacén Central",
    "line1": "Calle Falsa 123",
    "city": "Lima",
    "postal_code": "15001",
    "country": "PE"
  },
  "destination_address": {
    "name": "María Gómez",
    "line1": "Calle Las Flores 456",
    "city": "Arequipa",
    "postal_code": "04001",
    "country": "PE"
  }
}

Respuesta 200 OK: Retorna un arreglo de tarifas disponibles.

[
  {
    "id": "a9c3d2b2-f046-40d3-852f-423089c73ba3",
    "tenant_id": "8a1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "carrier": "olva_courier",
    "service_name": "Olva Express Nacional",
    "service_code": "olva_express",
    "currency": "PEN",
    "amount": 1500,
    "estimated_days": 2,
    "weight_g": 1500,
    "origin_country": "PE",
    "destination_country": "PE",
    "created_at": "2026-06-02T20:45:00Z",
    "updated_at": "2026-06-02T20:45:00Z"
  }
]

Envíos (Shipments)​

Crear envío​

Genera un nuevo registro de envío (shipment) vinculado a una orden. Inicialmente se crea en estado draft o pending.

POST /shipping/shipments

Payload de entrada:

{
  "order_id": "42c3d0b2-4d2b-42fa-9d10-8b1b8b6a7a50",
  "carrier": "olva_courier",
  "service_code": "olva_express",
  "weight_g": 1500,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 15,
  "origin_address": {
    "name": "Almacén Central",
    "line1": "Calle Falsa 123",
    "city": "Lima",
    "postal_code": "15001",
    "country": "PE"
  },
  "destination_address": {
    "name": "María Gómez",
    "line1": "Calle Las Flores 456",
    "city": "Arequipa",
    "postal_code": "04001",
    "country": "PE"
  }
}

Respuesta 201 Created:

{
  "id": "f8d3d2b2-f046-40d3-852f-423089c73ba3",
  "tenant_id": "8a1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "order_id": "42c3d0b2-4d2b-42fa-9d10-8b1b8b6a7a50",
  "carrier": "olva_courier",
  "service_code": "olva_express",
  "status": "pending",
  "origin_address": {
    "name": "Almacén Central",
    "line1": "Calle Falsa 123",
    "city": "Lima",
    "postal_code": "15001",
    "country": "PE"
  },
  "destination_address": {
    "name": "María Gómez",
    "line1": "Calle Las Flores 456",
    "city": "Arequipa",
    "postal_code": "04001",
    "country": "PE"
  },
  "weight_g": 1500,
  "dimensions": {
    "length_cm": 30,
    "width_cm": 20,
    "height_cm": 15
  },
  "events": [],
  "created_at": "2026-06-02T20:45:00Z",
  "updated_at": "2026-06-02T20:45:00Z"
}

Listar envíos​

GET /shipping/shipments

Obtener envío​

GET /shipping/shipments/:id

Muestra toda la información del envío, incluyendo el estado actual (pending, label_generated, shipped, delivered, failed), el número de seguimiento (tracking number) y la lista histórica de eventos de rastreo.

Generar Etiqueta de Envío​

Asocia el número de seguimiento oficial del transportista y el enlace al documento PDF/imagen de la etiqueta de envío. Cambia el estado del envío a label_generated.

POST /shipping/shipments/:id/label

Payload de entrada:

{
  "tracking_number": "OLVA987654321",
  "label_url": "https://storage.omnibuy.net/labels/olva987654321.pdf"
}

Respuesta 200 OK: Retorna el envío actualizado.

Actualizar Seguimiento (Tracking)​

Añade un nuevo evento en el historial de tránsito del envío (ej. "En sucursal", "En ruta de entrega").

PATCH /shipping/shipments/:id/tracking

Payload de entrada:

{
  "status": "shipped",
  "location": "Centro de Distribución Lima Sur",
  "description": "El paquete ha salido rumbo a la ciudad de destino.",
  "timestamp": "2026-06-02T22:00:00Z"
}

Respuesta 200 OK: Retorna el envío actualizado con el nuevo evento en la lista de events.

Marcar como Entregado​

Establece el estado final del envío como entregado (delivered).

POST /shipping/shipments/:id/delivered

Respuesta 200 OK

Marcar como Fallido​

Establece el estado del envío como fallido (failed) e indica el motivo de la imposibilidad de entrega.

POST /shipping/shipments/:id/failed

Payload de entrada:

{
  "reason": "Destinatario ausente tras 3 visitas"
}

Respuesta 200 OK