EnruTek API 1.0.0

Creá y rastreá guías en EnruTek desde cualquier sistema.

Dirección base: https://api.enrutek.com/v1. Contrato: https://api.enrutek.com/openapi.json y https://api.enrutek.com/openapi.yaml.

Empezá en 5 pasos

Todo va a https://api.enrutek.com/v1, con JSON y con tu llave en la cabecera Authorization.

1. Pedí tu llave. La crea tu operador logístico en EnruTek y se muestra una sola vez. Guardala en el servidor de tu sistema, nunca en una página web, una app ni un repositorio.

2. Mirá qué podés usar. /catalog devuelve tus tipos de carga con su precio y tus sucursales. El code de cada tipo de carga es lo que va en cargo_type.

curl https://api.enrutek.com/v1/catalog \
  -H "Authorization: Bearer $ENRUTEK_KEY"

3. Creá una guía. Responde 201 con el número de guía y el total calculado con tu tarifa.

curl -X POST https://api.enrutek.com/v1/shipments \
  -H "Authorization: Bearer $ENRUTEK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: factura-379671" \
  -d '{
    "external_reference": "379671",
    "recipient": { "name": "Farmacia Plaza Flamingo", "phone": "+50626545524" },
    "destination": {
      "country": "CR",
      "admin_area_1": "Guanacaste",
      "admin_area_2": "Santa Cruz",
      "address_line": "Playa Potrero, 200 metros sur del Hotel Bahía Esmeralda"
    },
    "packages": [{ "cargo_type": "seco", "quantity": 2 }]
  }'

4. Consultala. Trae el estado, el historial y, una vez entregada, la prueba de entrega. Es para cuando alguien la necesita ver, no para preguntar cada rato si cambió: para eso está el paso 5.

curl https://api.enrutek.com/v1/shipments/TF-261024ZXWPH2S \
  -H "Authorization: Bearer $ENRUTEK_KEY"

5. Enterate de los cambios. Suscribí una URL de tu sistema con POST /webhooks para no tener que estar preguntando.

Probar en Sandbox

Antes de conectar tu sistema a la operación real, probá en Sandbox, una empresa de pruebas dentro de EnruTek. Lo que creés ahí no le llega a ningún operador ni sale a la calle.

• Pedí acceso a tu operador logístico o a Alfa Tek. Te dan una llave de prueba para un cliente de pruebas propio: nadie más ve tus guías.
• Es la misma dirección y el mismo contrato: https://api.enrutek.com/v1, con los mismos campos, errores y límites. Solo cambia la llave.
• Las guías nacen con el prefijo SB-, así se distinguen de las reales.
• Nadie las recolecta ni las entrega: se quedan en created salvo que las canceles. Para probar tu receptor de webhooks usá POST /webhooks/{id}/test.
• Para pasar a producción, tu operador te crea la llave real y la cambiás en tu sistema. No hay que cambiar nada más.

Rigen las mismas reglas de uso responsable que en producción.

Uso responsable

El API comparte la base de datos con la operación de bodega y de los choferes. Por eso:

• Crear guías no tiene horario. Mandalas en el momento en que nacen en tu sistema; si son varias, en un lote con /shipments/batch.
• Para saber el estado, usá webhooks. EnruTek te avisa cada cambio y no tenés que preguntar.
• Si no podés recibir webhooks, consultá a lo sumo una vez por hora, con una sola llamada a GET /shipments?updated_since=<fecha> que trae todo lo que cambió desde la última vez.
• No consultés guía por guía en un ciclo, ni cada pocos segundos o minutos. Consultar una guía suelta está bien cuando una persona lo pide.

El límite técnico por llave (RateLimit-Limit) existe para absorber lotes y reintentos; no es una invitación a consultar todo el tiempo. EnruTek revisa el registro de llamadas de cada llave: un uso que afecte la operación puede llevar a que se baje el límite de la llave o se revoque, con aviso previo salvo que el daño sea inmediato.

Crear varias guías de una vez

Si un botón o un proceso de tu sistema manda varias guías juntas, usá POST /shipments/batch: una sola llamada, hasta 500 guías y una sola Idempotency-Key para todo el lote.

curl -X POST https://api.enrutek.com/v1/shipments/batch \
  -H "Authorization: Bearer $ENRUTEK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: despacho-2026-11-10-tarde" \
  -d '{ "shipments": [ { "external_reference": "379671", "...": "..." },
                       { "external_reference": "379672", "...": "..." } ] }'

Cada guía se procesa por aparte: una inválida no detiene a las demás.

El lote responde 200 aunque alguna guía haya fallado. Revisá siempre failed y recorré results, que viene en el mismo orden en que mandaste las guías:

{
  "created": 1,
  "failed": 1,
  "results": [
    { "index": 0, "ok": true, "shipment": { "tracking_number": "TF-261024ZXWPH2S" } },
    { "index": 1, "ok": false, "error": { "code": "unknown_cargo_type", "message": "…", "field": "packages.0.cargo_type" } }
  ]
}

Si failed es mayor que cero, corregí esas guías y mandá solamente esas en un lote nuevo, con otra Idempotency-Key.

Reintentar sin duplicar

Las redes fallan. Hay dos protecciones y conviene usar las dos:

Las Idempotency-Key se guardan 24 horas. La external_reference es única por cliente entre las guías activas: al cancelar una guía, su referencia se puede volver a usar.

Recibir webhooks

EnruTek le manda un POST a tu URL cada vez que una guía cambia. Para probar tu receptor sin mover ninguna guía, usá POST /webhooks/{id}/test: el evento llega con "test": true.

Tu receptor tiene que:

1. Validar la firma con el cuerpo crudo, tal como llegó, antes de convertirlo a JSON.
2. Rechazar eventos con más de 5 minutos.
3. Responder cualquier 2xx en menos de 10 segundos y hacer el trabajo pesado después.
4. Descartar repetidos con event.id: un evento puede llegar más de una vez.
5. Ordenar con occurred_at, porque pueden llegar en desorden.

Si tu sistema no responde 2xx, EnruTek reintenta con espera creciente hasta por 24 horas. Una suscripción que lleva 24 horas fallando se apaga sola.

La cabecera EnruTek-Signature trae t=<segundos unix>,v1=<firma>. La firma es HMAC-SHA256 en hexadecimal de <t>.<cuerpo crudo>, con el secreto whsec_… que recibiste al crear la suscripción.

Node.js

import { createHmac, timingSafeEqual } from "node:crypto"

export function firmaValida(cuerpoCrudo, cabecera, secreto) {
  const partes = Object.fromEntries(cabecera.split(",").map((p) => p.split("=")))
  if (!partes.t || !partes.v1) return false
  if (Math.abs(Date.now() / 1000 - Number(partes.t)) > 300) return false
  const esperada = createHmac("sha256", secreto).update(`${partes.t}.${cuerpoCrudo}`).digest()
  const recibida = Buffer.from(partes.v1, "hex")
  return recibida.length === esperada.length && timingSafeEqual(recibida, esperada)
}

Python

import hashlib, hmac, time

def firma_valida(cuerpo_crudo: bytes, cabecera: str, secreto: str) -> bool:
    partes = dict(p.split("=", 1) for p in cabecera.split(","))
    if "t" not in partes or "v1" not in partes:
        return False
    if abs(time.time() - int(partes["t"])) > 300:
        return False
    mensaje = partes["t"].encode() + b"." + cuerpo_crudo
    esperada = hmac.new(secreto.encode(), mensaje, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperada, partes["v1"])

PHP

function firma_valida(string $cuerpoCrudo, string $cabecera, string $secreto): bool {
    parse_str(str_replace(',', '&', $cabecera), $partes);
    if (empty($partes['t']) || empty($partes['v1'])) return false;
    if (abs(time() - (int) $partes['t']) > 300) return false;
    $esperada = hash_hmac('sha256', $partes['t'] . '.' . $cuerpoCrudo, $secreto);
    return hash_equals($esperada, $partes['v1']);
}

Qué hacer con cada error

Todos los errores traen error.code, error.message, error.field y error.details. Programá contra code, que no cambia; message es para mostrárselo a una persona.

Si sos una IA ayudando a integrar

Estas reglas evitan los errores más comunes:

• Trabajá contra este documento y https://api.enrutek.com/openapi.json. No inventés rutas ni campos: los objetos de entrada rechazan los campos desconocidos.
• Probá primero con una llave de Sandbox (guías SB-): mismo contrato y misma dirección que producción.
• No le pidás a la persona que pegue su llave en el chat. Usá una variable de entorno o el almacén de secretos de su sistema.
• La llave va solo en el servidor; nunca en código que corra en un navegador o en una app.
• No intentés fijar el precio: lo calcula EnruTek con la tarifa del cliente.
• Antes de crear guías, llamá a /catalog para conocer los cargo_type y las sucursales reales.
• Con una llave de cliente no mandés customer_id; con una de operador es obligatorio al crear.
• Usá external_reference con el identificador del sistema del cliente y Idempotency-Key en cada POST.
• Para los cambios de estado, proponé webhooks. Si no se puede, una sola consulta con updated_since a lo sumo cada hora. Nunca escribás un ciclo que consulte guía por guía ni cada pocos segundos o minutos: la llave se puede limitar o revocar.
• Con varias guías a la vez, usá /shipments/batch y revisá failed y results, aunque la respuesta sea 200.
• La etiqueta por API todavía responde 501. Por ahora solo se aceptan direcciones de Costa Rica (country: CR).
• Los traslados entre sucursales de un mismo cliente no se crean por API.

Reglas generales

Los nombres del API (rutas, campos, parámetros, estados y códigos de error) van en inglés; las explicaciones, en español.

EnruTek es una plataforma de logística para operadores logísticos (en el API, operator: la empresa que usa EnruTek). Este API le permite a cualquier sistema externo (un ERP como SAP, una tienda en línea, un sistema de bodega) crear guías, darles seguimiento y recibir sus cambios de estado.

Autenticación

Cada solicitud lleva una llave (API key) en la cabecera Authorization:

Authorization: Bearer ek_live_3Fh8...

Las llaves se crean en EnruTek y se muestran una sola vez. Hay dos tipos:

• Llave de cliente: pertenece a un cliente del operador. Solo puede crear y leer las guías de ese cliente. Nunca se manda customer_id.
• Llave de operador: pertenece al operador. Puede trabajar para cualquiera de los clientes del operador; al crear, customer_id es obligatorio.

Sandbox

Para probar sin tocar la operación real hay una empresa de pruebas, Sandbox: misma dirección, mismo contrato y mismos límites; solo cambia la llave, que se pide al operador o a Alfa Tek. Sus guías nacen con el prefijo SB-, nadie las recolecta ni las entrega, y para probar los webhooks está POST /webhooks/{id}/test.

Convenciones

• JSON de entrada y de salida, en UTF-8. Nombres de campos en snake_case.
• Fechas y horas en ISO 8601 con desfase (2026-10-24T14:05:00-06:00).
• Teléfonos en E.164 (+50688887777).
• Montos como { "amount": "3000.00", "currency": "CRC" } (ISO 4217; el monto es un texto decimal para evitar redondeos).
• Las direcciones no dependen del país: country (ISO 3166-1 alfa-2) y hasta tres niveles administrativos. En Costa Rica: admin_area_1 = provincia, admin_area_2 = cantón, admin_area_3 = distrito.
• El precio siempre lo calcula EnruTek con la tarifa del cliente; no se puede fijar por el API.

Idempotencia

Mandá una cabecera Idempotency-Key (cualquier texto único de hasta 100 caracteres) en las solicitudes POST. Si reintentás con la misma llave, recibís el resultado original en vez de crear una segunda guía. Las llaves se guardan 24 horas. Además, external_reference es única por cliente entre las guías activas: una segunda guía con la misma referencia se rechaza con duplicate_reference y el número de guía que ya existe.

Errores

Los errores traen un code estable, para máquinas (en inglés), y un message para personas. El mensaje viene en español por defecto; mandá Accept-Language: en para recibirlo en inglés.

Límites de uso

Cada llave tiene un máximo de solicitudes por minuto (rate limit). Cada respuesta trae RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Si se pasa del límite, el API responde 429 con Retry-After.

Uso responsable

El API comparte la base con la operación. Crear guías no tiene horario (varias juntas, en /shipments/batch). Para los cambios de estado usá webhooks; si no podés recibirlos, consultá a lo sumo una vez por hora con una sola llamada a GET /shipments?updated_since=…. No consultés guía por guía en un ciclo ni cada pocos segundos o minutos. El límite por llave existe para lotes y reintentos, no para consultar todo el tiempo: un uso que afecte la operación puede llevar a que se baje el límite de la llave o se revoque, con aviso previo salvo que el daño sea inmediato.

Webhooks

EnruTek puede avisarle a tu sistema cuando una guía cambia de estado (por webhook). Cada envío es un POST con un WebhookEvent en JSON y la cabecera EnruTek-Signature: t=<segundos unix>,v1=<HMAC-SHA256 en hex>, calculada sobre <t>.<cuerpo tal cual> con el secreto de la suscripción. Rechazá los eventos de hace más de 5 minutos. Respondé cualquier 2xx en menos de 10 segundos; si no, EnruTek reintenta con espera exponencial durante hasta 24 horas. Un evento puede llegar más de una vez y en desorden: usá event.id para descartar repetidos y occurred_at para ordenarlos.

Referencia de rutas

Guías

Crear, consultar y cancelar guías.

GET /shipments

Listar guías.

Las más recientes primero, paginadas por cursor. Para sincronizar, usá updated_since con el updated_at de la última guía que viste. Sin webhooks, sincronizá a lo sumo una vez por hora (ver "Uso responsable").

Parámetros:

Respuestas:

• 200: Una página de guías (sin events; pedí la guía individual para ver su historial).
• 400: El cuerpo o un parámetro no es válido (invalid_request, invalid_field).
• 401: Falta la llave, no existe o fue revocada (unauthorized).
• 429: Se pasó del límite de uso (rate_limited). Ver Retry-After.

POST /shipments

Crear una guía.

Crea una guía. Nace en created (un chofer la recoge en la sucursal de origen). La respuesta trae el número de guía, el precio calculado con la tarifa y el enlace a la etiqueta 100×100.

Parámetros:

Cuerpo (JSON):

Ejemplo:

{
  "external_reference": "379671",
  "recipient": {
    "name": "Farmacia Plaza Flamingo",
    "phone": "+50626545524"
  },
  "destination": {
    "country": "CR",
    "admin_area_1": "Guanacaste",
    "admin_area_2": "Santa Cruz",
    "admin_area_3": "Tempate",
    "postal_code": "50304",
    "address_line": "Playa Potrero, 200 metros sur del Hotel Bahía Esmeralda"
  },
  "notes": "Entregar en horario de oficina",
  "packages": [
    {
      "cargo_type": "seco",
      "quantity": 1
    }
  ]
}

Respuestas:

• 200: Misma Idempotency-Key que una solicitud anterior; se devuelve la guía original.
• 201: Creada.
• 400: El cuerpo o un parámetro no es válido (invalid_request, invalid_field).
• 401: Falta la llave, no existe o fue revocada (unauthorized).
• 403: La llave no puede hacer esto (forbidden, customer_not_allowed, module_disabled).
• 409: duplicate_reference, invalid_status o idempotency_conflict (misma llave, cuerpo distinto).
• 422: JSON válido que EnruTek no puede usar (invalid_address, unknown_cargo_type, no_rate_for_cargo_type, branch_not_found, invalid_webhook_url).
• 429: Se pasó del límite de uso (rate_limited). Ver Retry-After.

POST /shipments/batch

Crear hasta 500 guías.

Cada elemento se procesa por aparte: uno inválido no detiene a los demás. La respuesta trae un resultado por elemento, en el mismo orden. Usá una Idempotency-Key para todo el lote; al reintentar recibís los mismos resultados.

Parámetros:

Cuerpo (JSON):

Respuestas:

• 200: Un resultado por elemento.
• 400: El cuerpo o un parámetro no es válido (invalid_request, invalid_field).
• 401: Falta la llave, no existe o fue revocada (unauthorized).
• 413: Más de 500 elementos.
• 429: Se pasó del límite de uso (rate_limited). Ver Retry-After.

GET /shipments/{tracking_number}

Consultar una guía con su historial.

Parámetros:

Respuestas:

• 200: La guía, con events y, una vez entregada, proof_of_delivery (prueba de entrega).
• 401: Falta la llave, no existe o fue revocada (unauthorized).
• 404: No existe, o esta llave no lo puede ver (not_found).
• 429: Se pasó del límite de uso (rate_limited). Ver Retry-After.

POST /shipments/{tracking_number}/cancel

Cancelar una guía.

Solo mientras esté en created (nadie la ha recogido).

Parámetros:

Cuerpo (JSON):

Respuestas:

• 200: Cancelada (o ya estaba cancelada).
• 401: Falta la llave, no existe o fue revocada (unauthorized).
• 404: No existe, o esta llave no lo puede ver (not_found).
• 409: duplicate_reference, invalid_status o idempotency_conflict (misma llave, cuerpo distinto).
• 429: Se pasó del límite de uso (rate_limited). Ver Retry-After.

GET /shipments/{tracking_number}/label

Obtener la etiqueta 100×100.

Una página por bulto. Por ahora en PDF; más adelante, ZPL para impresoras térmicas. Todavía no está disponible: responde 501 not_implemented (después de revisar que la llave puede ver la guía). Mientras tanto, imprimí las etiquetas desde EnruTek.

Parámetros:

Respuestas:

• 200: La etiqueta.
• 401: Falta la llave, no existe o fue revocada (unauthorized).
• 404: No existe, o esta llave no lo puede ver (not_found).
• 501: Todavía no está disponible (not_implemented).

Catálogo

Tipos de carga, sucursales y división territorial que puede usar una guía.

GET /catalog

Lo que puede usar una guía.

Los tipos de carga con el precio del cliente y las sucursales del cliente (orígenes). Con llaves de operador, customer_id es obligatorio.

Parámetros:

Respuestas:

• 200: El catálogo.
• 401: Falta la llave, no existe o fue revocada (unauthorized).

GET /catalog/admin-areas

División territorial de un país.

Los valores válidos de admin_area_1..3, en forma de árbol.

Parámetros:

Respuestas:

• 200: El árbol.

Webhooks

Suscripciones para recibir los cambios de estado de las guías.

GET /webhooks

Listar las suscripciones de webhook de esta llave.

Respuestas:

• 200: Las suscripciones (sin el secreto).
• 401: Falta la llave, no existe o fue revocada (unauthorized).

POST /webhooks

Suscribir una URL a los eventos de las guías.

El secret se devuelve solo en esta respuesta.

Alcance. Una llave de cliente recibe solo los eventos de sus propias guías. Una llave de operador puede indicar customer_id para recibir solo los eventos de ese cliente; sin él, recibe los eventos de todas las guías del operador. customer_id tiene que ser un cliente del operador de la llave (si no, 422 customer_not_found), y si una llave de cliente lo manda se rechaza (403 customer_not_allowed): nunca amplía lo que una llave puede ver. El alcance no se puede cambiar después.

Reglas de la URL (se revisan al crear y otra vez en cada envío): solo https, sin usuario ni contraseña en la URL, un nombre de host (no una IP literal) que resuelva solo a direcciones públicas (se rechazan loopback, privadas RFC 1918, link-local 169.254.0.0/16, CGNAT 100.64.0.0/10, loopback/ULA/link-local de IPv6 y las direcciones de metadatos de la nube). No se siguen redirecciones. Una URL que no cumple estas reglas se rechaza con invalid_webhook_url.

Cuerpo (JSON):

Respuestas:

• 201: Creada.
• 400: El cuerpo o un parámetro no es válido (invalid_request, invalid_field).
• 401: Falta la llave, no existe o fue revocada (unauthorized).
• 403: La llave no puede hacer esto (forbidden, customer_not_allowed, module_disabled).
• 422: JSON válido que EnruTek no puede usar (invalid_address, unknown_cargo_type, no_rate_for_cargo_type, branch_not_found, invalid_webhook_url).

DELETE /webhooks/{id}

Detener una suscripción.

Parámetros:

Respuestas:

• 204: Detenida.
• 401: Falta la llave, no existe o fue revocada (unauthorized).
• 404: No existe, o esta llave no lo puede ver (not_found).

POST /webhooks/{id}/test

Enviar un evento de prueba.

Parámetros:

Respuestas:

• 202: En cola.
• 401: Falta la llave, no existe o fue revocada (unauthorized).
• 404: No existe, o esta llave no lo puede ver (not_found).

Evento de webhook

Lo que EnruTek le manda a la URL suscrita.