Ordenes

Los endpoints de ordenes te permiten crear envios, consultarlos, cancelarlos y descargar guias en PDF.

Crear Orden

POST /api/v1/orders

Scope requerido: orders:write

Crea un nuevo envio y genera la guia con el proveedor logistico.

curl

curl -X POST https://app.fletea.mx/api/v1/orders \
  -H "Authorization: Bearer flt_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pickupAddress": {
      "contactName": "Juan Lopez",
      "contactPhone": "5551234567",
      "email": "juan@empresa.com",
      "street": "Av. Reforma",
      "exteriorNumber": "222",
      "interiorNumber": "4B",
      "neighborhood": "Juarez",
      "city": "Ciudad de Mexico",
      "state": "Ciudad de Mexico",
      "postalCode": "06600"
    },
    "deliveryAddress": {
      "contactName": "Maria Garcia",
      "contactPhone": "8181234567",
      "email": "maria@cliente.com",
      "street": "Av. Gonzalitos",
      "exteriorNumber": "500",
      "neighborhood": "Mitras Centro",
      "city": "Monterrey",
      "state": "Nuevo Leon",
      "postalCode": "64460",
      "deliveryInstructions": "Tocar el timbre 2 veces"
    },
    "receiverName": "Maria Garcia",
    "receiverPhone": "8181234567",
    "package": {
      "weight": 2.5,
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 15
      },
      "contentDescription": "Ropa y accesorios",
      "declaredValue": 1500
    },
    "internalReference": "PEDIDO-001",
    "shipmentType": "standard",
    "isCod": false
  }'

TypeScript

const response = await fetch('https://app.fletea.mx/api/v1/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer flt_tu_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    pickupAddress: {
      contactName: 'Juan Lopez',
      contactPhone: '5551234567',
      email: 'juan@empresa.com',
      street: 'Av. Reforma',
      exteriorNumber: '222',
      neighborhood: 'Juarez',
      city: 'Ciudad de Mexico',
      state: 'Ciudad de Mexico',
      postalCode: '06600',
    },
    deliveryAddress: {
      contactName: 'Maria Garcia',
      contactPhone: '8181234567',
      street: 'Av. Gonzalitos',
      exteriorNumber: '500',
      neighborhood: 'Mitras Centro',
      city: 'Monterrey',
      state: 'Nuevo Leon',
      postalCode: '64460',
    },
    receiverName: 'Maria Garcia',
    receiverPhone: '8181234567',
    package: {
      weight: 2.5,
      dimensions: { length: 30, width: 20, height: 15 },
      contentDescription: 'Ropa y accesorios',
      declaredValue: 1500,
    },
    internalReference: 'PEDIDO-001',
    shipmentType: 'standard',
  }),
});

const order = await response.json();
// { orderId: "uuid", guideNumber: "HEX-123456", trackingNumber: "HEX-123456" }

Respuesta exitosa (201)

{
  "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "guideNumber": "HEX-123456789",
  "trackingNumber": "HEX-123456789"
}

Campos del request

pickupAddress (requerido)

Campo	Tipo	Requerido	Descripcion
`contactName`	string	Si	Nombre de quien entrega
`contactPhone`	string	Si	Telefono de contacto
`email`	string	No	Correo electronico
`street`	string	Si	Calle
`exteriorNumber`	string	Si	Numero exterior
`interiorNumber`	string	No	Numero interior
`neighborhood`	string	Si	Colonia
`city`	string	Si	Ciudad
`state`	string	Si	Estado (nombre completo)
`postalCode`	string	Si	Codigo postal

deliveryAddress (requerido)

Mismos campos que pickupAddress, mas:

Campo	Tipo	Requerido	Descripcion
`deliveryInstructions`	string	No	Instrucciones de entrega

package (requerido)

Campo	Tipo	Requerido	Descripcion
`weight`	number	Si	Peso en kg (0.1 - 70)
`dimensions.length`	number	No	Largo en cm (1 - 300, default: 10)
`dimensions.width`	number	No	Ancho en cm (1 - 300, default: 10)
`dimensions.height`	number	No	Alto en cm (1 - 300, default: 10)
`contentDescription`	string	No	Descripcion del contenido
`declaredValue`	number	No	Valor declarado en MXN

Campos adicionales

Campo	Tipo	Requerido	Descripcion
`receiverName`	string	No	Nombre del destinatario
`receiverPhone`	string	No	Telefono del destinatario
`internalReference`	string	No	Referencia interna de tu sistema
`shipmentType`	string	No	`standard` (default), `express`, `same_day`
`isCod`	boolean	No	Cobro contra entrega
`codAmount`	number	Condicional	Monto COD (requerido si `isCod` es `true`)

💡

Peso volumetrico

El peso volumetrico se calcula automaticamente como (largo x ancho x alto) / 5000. Se cobra el mayor entre el peso real y el volumetrico.

Listar Ordenes

GET /api/v1/orders

Scope requerido: orders:read

Parametros de query

Parametro	Tipo	Descripcion
`status`	string	Filtrar por estado (ej: `delivered`, `in_transit`)
`dateFrom`	string	Fecha inicio ISO 8601
`dateTo`	string	Fecha fin ISO 8601
`limit`	number	Resultados por pagina (default: 50, max: 100)
`cursor`	string	Cursor para paginacion

curl

curl "https://app.fletea.mx/api/v1/orders?status=in_transit&limit=20" \
  -H "Authorization: Bearer flt_tu_api_key"

Respuesta

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "internal_reference": "PEDIDO-001",
      "receiver_name": "Maria Garcia",
      "status": "in_transit",
      "provider_tracking_number": "HEX-123456789",
      "created_at": "2026-03-01T10:00:00Z",
      "status_updated_at": "2026-03-02T14:30:00Z",
      "is_cod": false,
      "total_cost": 185
    }
  ],
  "nextCursor": "eyJjcmVhdGVkX2F0Ijo..."
}

Detalle de Orden

GET /api/v1/orders/:id

Scope requerido: orders:read

curl

curl "https://app.fletea.mx/api/v1/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer flt_tu_api_key"

Respuesta

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organization_id": "org-uuid",
  "internal_reference": "PEDIDO-001",
  "provider": "fletea",
  "provider_tracking_number": "HEX-123456789",
  "status": "in_transit",
  "shipment_type": "standard",
  "receiver_name": "Maria Garcia",
  "receiver_phone": "8181234567",
  "pickup_address": { "..." },
  "delivery_address": { "..." },
  "package_weight": 2.5,
  "package_dimensions": { "length": 30, "width": 20, "height": 15 },
  "total_cost": 185,
  "estimated_delivery_at": "2026-03-05T18:00:00Z",
  "tracking_events": [
    {
      "status": "created",
      "description": "Guia generada",
      "occurred_at": "2026-03-01T10:00:00Z",
      "location": "CDMX"
    },
    {
      "status": "picked_up",
      "description": "Paquete recolectado",
      "occurred_at": "2026-03-02T09:15:00Z",
      "location": "CDMX"
    },
    {
      "status": "in_transit",
      "description": "En transito a destino",
      "occurred_at": "2026-03-02T14:30:00Z",
      "location": "Queretaro"
    }
  ],
  "created_at": "2026-03-01T10:00:00Z",
  "status_updated_at": "2026-03-02T14:30:00Z"
}

Cancelar Orden

POST /api/v1/orders/:id/cancel

Scope requerido: orders:write

Solo se pueden cancelar ordenes que aun no han sido recolectadas (pending o created).

curl

curl -X POST "https://app.fletea.mx/api/v1/orders/a1b2c3d4-.../cancel" \
  -H "Authorization: Bearer flt_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Cliente cancelo el pedido" }'

TypeScript

const response = await fetch(
  `https://app.fletea.mx/api/v1/orders/${orderId}/cancel`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer flt_tu_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ reason: 'Cliente cancelo el pedido' }),
  }
);

Respuesta exitosa (200)

{
  "message": "Orden cancelada exitosamente"
}

⚠️

Ordenes ya recolectadas

Las ordenes que ya fueron recolectadas (picked_up, in_transit, etc.) no pueden cancelarse por API. Contacta a soporte para estos casos.

Descargar Guia (PDF)

GET /api/v1/orders/:id/label

Scope requerido: orders:read

Devuelve la guia de envio en formato PDF.

curl

curl "https://app.fletea.mx/api/v1/orders/a1b2c3d4-.../label" \
  -H "Authorization: Bearer flt_tu_api_key" \
  -o guia.pdf

TypeScript

const response = await fetch(
  `https://app.fletea.mx/api/v1/orders/${orderId}/label`,
  {
    headers: { 'Authorization': 'Bearer flt_tu_api_key' },
  }
);

const pdfBlob = await response.blob();
// Guardar o mostrar el PDF

La respuesta tiene Content-Type: application/pdf.

🚀

Whitelabel en guias

Si tu organizacion tiene whitelabel habilitado, la guia incluira el logotipo y nombre de tu marca automaticamente.

Estados de Orden

Estado	Etiqueta	Descripcion
`pending`	Pendiente	Orden creada, pendiente de procesamiento
`created`	Creada	Guia generada con el proveedor
`picked_up`	Recolectada	Paquete recolectado por el mensajero
`in_transit`	En Transito	Paquete en camino al destino
`out_for_delivery`	En Reparto	Paquete asignado para entrega final
`delivered`	Entregada	Entrega exitosa
`failed`	Fallida	No se pudo entregar
`cancelled`	Cancelada	Orden cancelada
`return_requested`	Devolucion Solicitada	El destinatario solicito devolucion
`return_approved`	Devolucion Aprobada	Devolucion autorizada, guia de retorno generada
`returned`	Retorno Completado	El paquete de retorno fue entregado al origen

Flujo de estados

🆕pending

→

📋created

→

🚚picked_up

→

📦in_transit

→

🏍️out_for_delivery

→

✅delivered

→

Tambien puede ocurrir:

Desde out_for_delivery se puede pasar a failed si la entrega falla
Desde delivered se puede solicitar devolucion: return_requested -> return_approved -> returned
Desde pending o created se puede pasar a cancelled

Crear Orden​

curl​

TypeScript​

Respuesta exitosa (201)​

Campos del request​

pickupAddress (requerido)​

deliveryAddress (requerido)​

package (requerido)​

Campos adicionales​

Listar Ordenes​

Parametros de query​

curl​

Respuesta​

Detalle de Orden​

curl​

Respuesta​

Cancelar Orden​

curl​

TypeScript​

Respuesta exitosa (200)​

Descargar Guia (PDF)​

curl​

TypeScript​

Estados de Orden​

Flujo de estados​

Crear Orden

curl

TypeScript

Respuesta exitosa (201)

Campos del request

pickupAddress (requerido)

deliveryAddress (requerido)

package (requerido)

Campos adicionales

Listar Ordenes

Parametros de query

curl

Respuesta

Detalle de Orden

curl

Respuesta

Cancelar Orden

curl

TypeScript

Respuesta exitosa (200)

Descargar Guia (PDF)

curl

TypeScript

Estados de Orden

Flujo de estados