ENVIADORES

API para desarrolladores

Centro de ayuda

Enviadores tiene una API REST pública para integrar tus envíos desde tu propio servidor: cotizar tarifas, generar guías, rastrear paquetes, descargar etiquetas y solicitar cancelaciones, sin usar el panel web.

Es una API server-to-server: se autentica con una clave secreta que debe vivir únicamente en tu backend. No la uses en un navegador ni en una app móvil.

Cómo crear una clave

  1. Entra a Mi cuenta → Claves de API (disponible para cuentas de administrador y de cliente).
  2. Presiona Crear clave, ponle un nombre para identificarla y elige el modo (Producción o Prueba).
  3. Al crearla se te muestra la clave secreta completa una sola vez. Cópiala y guárdala en un lugar seguro: no volveremos a mostrarla. Si la pierdes, revócala y crea una nueva.

Cada cuenta puede tener hasta 10 claves activas. Puedes revocar una clave en cualquier momento; al hacerlo deja de funcionar de inmediato.

Autenticación

Manda tu clave en el header Authorization de cada petición:

Authorization: Bearer ek_live_tu_clave

Las claves de producción empiezan con ek_live_ y las de prueba con ek_test_. Nunca envíes la clave por la URL (query string).

Producción vs. prueba (sandbox)

  • Producción (ek_live_): crea guías reales y cobra tu saldo de créditos.
  • Prueba (ek_test_): opera en un entorno aislado (sandbox). Usa los mismos permisos y límites, pero no mueve dinero real y no toca tus envíos ni tu saldo de producción. Cada respuesta tiene el mismo formato que en producción, así que puedes ensayar tu integración con confianza.

En el sandbox: el saldo de prueba es una asignación fija de $10,000 MXN por clave (menos tus envíos de prueba no cancelados); las guías usan el prefijo SBX; la cancelación es inmediata; y el rastreo no se simula (GET /tracking solo resuelve guías reales). Los datos de prueba (envíos del sandbox) se depuran a los 30 días. Puedes forzar fallas de prueba (fondos insuficientes, tarifa expirada, error de paquetería) para ejercitar tu manejo de errores — ve la referencia.

Flujo básico

  1. Cotiza con POST /rates (mandas origen, destino y paquete). Recibes tarifas, cada una con un id (el rate_id).
  2. Crea el envío con POST /shipments usando ese rate_id. El rate_id es válido 30 minutos y debe usarse con la misma clave con la que cotizaste.
  3. Descarga la etiqueta con GET /labels/{envio_id}.
  4. Cancela con POST /cancellations si lo necesitas.

Encuentra los ejemplos completos con curl, los parámetros de cada endpoint y los esquemas en la referencia de la API.

Directorio de direcciones

Puedes guardar tus remitentes y destinatarios una sola vez y reutilizarlos por id:

  • Registra con POST /senders y POST /recipients (cada destinatario pertenece a un remitente). Si mandas una dirección idéntica a una ya guardada, te devolvemos la existente en lugar de duplicarla.
  • Consulta con GET /senders y GET /recipients (filtros por CP, nombre y remitente).
  • Cotiza y envía por id: en POST /rates y POST /shipments manda from_id / to_id en lugar de la dirección. La cotización usa los datos completos guardados (ciudad, estado y colonia), y el envío usa la fila guardada tal cual. En POST /shipments, to_id requiere from_id (el destinatario pertenece a ese remitente).

Estos endpoints usan los scopes addresses:read y addresses:write. Los scopes de una clave se fijan al crearla: si tu clave es anterior al directorio, crea una clave nueva para usarlo.

Idempotencia

En POST /shipments incluye siempre un header Idempotency-Key con un UUID nuevo por cada envío. Si reintentas con la misma clave, repetimos la respuesta original sin generar un segundo cargo ni una segunda guía. Si recibes un error POST_COMMIT_ERROR (500), no reintentes con una llave nueva: el envío ya es real y el cargo no se revierte; consulta GET /shipments para recuperar la guía.

Límites de tasa

El límite es por clave. Cada respuesta incluye los headers X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Si te pasas, recibes un 429 con un header Retry-After (segundos): espera ese tiempo y reintenta con backoff exponencial.

Cancelaciones y reembolsos

Al solicitar una cancelación, si procede, el importe cobrado por el envío se regresa como saldo de créditos en tu cuenta. El dinero nunca sale de la plataforma: los reembolsos siempre son a tu saldo, para usarlo en tus próximos envíos.

Soporte

¿Dudas con tu integración? Escríbenos desde Contacto y soporte con tu requestId (viene en cada respuesta y en el header X-Request-Id) para ayudarte más rápido.