API de DR Express

Conecta tus envíos desde tu propio código

Cotiza, crea guías, rastrea y descarga etiquetas desde tu tienda, tu ERP o lo que tengas montado. Con un banco de pruebas para que montes la integración entera sin generar un solo envío real.

Cómo se empieza

Pide una cuenta en solicitar acceso y marca que vas a integrar por API. Revisamos y te respondemos al correo.
Saca una llave de pruebas desde tu portal, en «Llaves de API». Se enseña una sola vez: si la pierdes, la revocas y creas otra.
Monta tu integración contra ella. Las guías se crean, se rastrean y se anulan, pero no llegan a la transportadora, no cuestan flete y no salen en tus cifras.
Pídenos la llave de producción cuando esté lista. Es una conversación de cinco minutos: miramos tu modo de pago y tu saldo, porque a partir de ahí cada guía es real.

Autenticarse

La llave va en la cabecera Authorization, como un bearer. No caduca y se revoca desde el portal cuando quieras.

curl https://api.drexpress.app/v1/public/cities \
  -H "Authorization: Bearer drexpress_test_…"

El prefijo dice contra qué estás trabajando

drexpress_test_ simula y no llega a nadie. drexpress_live_ crea guías de verdad, que se transmiten y se facturan. Es lo primero que hay que mirar al abrir un fichero de configuración.

Lo que puede hacer una llave

Esta lista la sirve el servidor y es exactamente la que aplica: lo que no está aquí responde 403. Mover dinero, cambiar la cuenta bancaria de destino o tocar la identidad de la cuenta no se hacen con una llave; se hacen con una persona delante, en el portal.

Pidiéndole la lista al servidor…

Crear una guía

El servidor resuelve por ti la ciudad, el servicio y el flete. Tú mandas a quién va y qué pesa.

curl -X POST https://api.drexpress.app/v1/shipments \
  -H "Authorization: Bearer drexpress_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "name": "Ana Gómez",
      "phone": "3001112233",
      "address": "Carrera 7 #15-29",
      "city": "BOGOTA"
    },
    "parcels": [{ "weight": 1, "height": 10, "width": 10, "length": 10 }],
    "paymentMode": "prepaid"
  }'

Responde con la guía y su referencia. A partir de ahí se rastrea con GET /v1/tracking/{referencia} y se descarga la etiqueta con GET /v1/shipments/{id}/label.

Manda el mismo remitente que cotizaste

El flete lo pone el servidor y lo vuelve a calcular al crear la guía: el precio que mandes no se usa, porque decide lo que se te cobra. Y lo calcula desde sender.city. Si cotizas con origin y luego creas la guía sin sender, la guía sale desde la ciudad de DR Express y el precio cambia — tu comprador vio uno y a ti se te cobra otro.

Las dos respuestas dicen de qué ciudad hablan, así que lo puedes comprobar tú: route.origin en la cotización y sender.city en la guía tienen que ser la misma.

Avisos: que te contemos, en vez de preguntar

Registra una dirección en tu portal y te mandamos un POST cada vez que una guía tuya cambia de estado. Preguntar en bucle es la forma más cara de enterarse tarde: con cien guías vivas son cien peticiones cada vuelta y la entrega ocurrió hace nueve minutos.

POST https://tu-servidor/drexpress
X-DrExpress-Evento: shipment.status
X-DrExpress-Id:     7f3c…
X-DrExpress-Firma:  a91b…

{
  "event": "shipment.status",
  "at": "2026-10-10T14:21:08.411Z",
  "data": {
    "reference": "VA24-000418",
    "status": "delivered",
    "state": "Entregada",
    "description": "Entregada a Ana Gómez",
    "location": "BOGOTA",
    "at": "2026-10-10T14:21:02.000Z"
  }
}

Comprueba la firma antes de creerte nada

X-DrExpress-Firma es el HMAC-SHA256 del cuerpo tal cual llega, con el secreto que te dimos al registrar la dirección. Sin comprobarla, cualquiera que adivine tu URL puede decirte que una guía se entregó y que sueltes el producto.

Lo que hacemos si no contestas

Reintentamos seis veces, esperando cada vez más: medio minuto, dos, ocho… hasta media hora. Un reinicio tuyo no te cuesta el aviso.
Si respondes 4xx no reintentamos: eso no se arregla insistiendo. Lo verás en tu portal con el motivo.
Contesta 2xx rápido y procesa después. Cortamos a los diez segundos.
El mismo aviso no se manda dos veces, pero diseña para recibirlo repetido: usa el X-DrExpress-Id como llave. Es la regla de toda integración seria.

Límites y errores

300 peticiones por minuto por llave. Los errores vienen con error en castellano y, cuando la causa es un campo, con details diciendo cuál. Un 402 es saldo insuficiente, un 403 es que la llave no alcanza esa ruta o no tiene permiso de escritura, y un 409 suele ser que esa misma guía ya existe.

¿Dudas?

Escríbenos a soporte@drexpress.app con el nombre de tu cuenta y lo que estás intentando hacer. Si ya tienes llave, dinos el prefijo —los primeros caracteres—, nunca la llave entera.