Integra tu sistema con
Corhex Global

Conecta tu ERP, e-commerce o WMS directamente con nuestra plataforma de última milla: crea manifiestos y guías, consulta su estado, cancela y recibe notificaciones en tiempo real de cada cambio — sin pasar por el panel ni por sesiones de usuario. Si exportas, también puedes registrar envíos internacionales.

Conceptos clave

La integración usa tres secretos distintos. No los confundas: cada uno cumple un rol diferente y se entrega/usa de forma distinta.

Obtener credenciales

Las credenciales las provisiona el equipo de Corhex Global desde el panel de administración. Como cliente recibes:

• Tu par api_key + api_secret (para la API).
• Un whsec_ por cada endpoint de webhook que registres (para verificar).

Para solicitarlas o registrar/cambiar la URL de tus webhooks, contacta a tu representante o escribe a [email protected]. La rotación de credenciales de la API no genera downtime: tu cuenta puede tener varias credenciales activas a la vez, así que se emite la nueva, la adoptas y se revoca la anterior.

Entornos

Exponemos dos entornos independientes con la misma API: mismas rutas, mismos headers, misma firma y mismos payloads. Lo único que cambia entre uno y otro es el host.

Autenticación: firma HMAC

Cada petición se autentica con tu api_key y una firma HMAC-SHA256 calculada sobre el request entero — método, ruta, clave de idempotencia, timestamp y cuerpo —, no solo sobre el timestamp y el body. No usamos tokens de sesión.

Headers requeridos

Cómo se calcula la firma

La firma cubre el request entero, no solo el cuerpo. Se concatenan cinco campos separados por salto de línea (\n) en una cadena canónica que siempre tiene los cinco — ninguno se omite, aunque esté vacío — y se firma con HMAC-SHA256, usando tu api_secret tal cual como clave.

# canonical = "{MÉTODO}\n{request-target}\n{idempotency-key}\n{timestamp}\n{hex(sha256(body_crudo))}"
# firma     = HMAC_SHA256(api_secret, canonical)
# header    = X-TMS-Signature: sha256=<hex(firma)>

• request-target: la ruta más el query tal como viajan en la línea de petición (ej. /api/v1/external/manifests, o /api/v1/external/manifests?page=2). Firma exactamente los bytes que envías: mismo orden de parámetros y misma codificación.
• idempotency-key: el valor del header Idempotency-Key; cadena vacía cuando el header está ausente — independiente del método (si un GET lo envía, entra en la firma igual que en un POST).
• hex(sha256(body_crudo)): el hash SHA-256 del body crudo (los bytes exactos que envías, nunca un JSON re-serializado). Con cuerpo vacío — como en GET — es siempre la constante e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

Ejemplo: crear un manifiesto firmado

API_KEY="tms_live_xxx"
API_SECRET="xxxxxxxx"
METHOD="POST"
# Producción. Para pruebas: https://api-dev.corhex.app/api/v1/external
HOST="https://api.corhex.app"
TARGET="/api/v1/external/manifests"
TS=$(date +%s)
IDEM=$(uuidgen)
BODY='{"type":"pickup_and_delivery","items":[{"recipient_name":"Juan Pérez","recipient_phone":"+51999999999","delivery_address":"Av. Javier Prado 123, San Isidro","sla":"next-day"}]}'

# $NF (último campo) funciona con OpenSSL y con el LibreSSL de macOS,
# que imprime sólo el hash, sin el prefijo "SHA2-256(stdin)= ".
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $NF}')
CANONICAL=$(printf '%s\n%s\n%s\n%s\n%s' "$METHOD" "$TARGET" "$IDEM" "$TS" "$BODY_HASH")
SIG=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $NF}')

curl -sS "$HOST$TARGET" \
  -X "$METHOD" \
  -H "X-TMS-Api-Key: $API_KEY" \
  -H "X-TMS-Timestamp: $TS" \
  -H "X-TMS-Signature: sha256=$SIG" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  -d "$BODY"

import crypto from 'node:crypto';

const API_KEY = process.env.TMS_API_KEY;
const API_SECRET = process.env.TMS_API_SECRET;
// Producción. Para pruebas: https://api-dev.corhex.app/api/v1/external
const HOST = process.env.TMS_API_HOST ?? 'https://api.corhex.app';
const BASE_PATH = '/api/v1/external';

function sign(method, target, idempotencyKey, ts, body) {
  const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
  const canonical = [method, target, idempotencyKey, ts, bodyHash].join('\n');
  return 'sha256=' + crypto.createHmac('sha256', API_SECRET).update(canonical).digest('hex');
}

async function call(method, path, bodyObj) {
  const target = BASE_PATH + path;
  const body = bodyObj ? JSON.stringify(bodyObj) : '';
  const ts = Math.floor(Date.now() / 1000).toString();
  const idempotencyKey = method === 'POST' ? crypto.randomUUID() : '';
  const headers = {
    'X-TMS-Api-Key': API_KEY,
    'X-TMS-Timestamp': ts,
    'X-TMS-Signature': sign(method, target, idempotencyKey, ts, body),
  };
  if (method === 'POST') {
    headers['Idempotency-Key'] = idempotencyKey;
    headers['Content-Type'] = 'application/json';
  }
  const res = await fetch(HOST + target, { method, headers, body: method === 'POST' ? body : undefined });
  return res.json();
}

await call('POST', '/manifests', {
  type: 'pickup_and_delivery',
  items: [{ recipient_name: 'Juan Pérez', recipient_phone: '+51999999999',
            delivery_address: 'Av. Javier Prado 123', sla: 'next-day' }],
});

import hashlib, hmac, json, os, time, uuid, requests

API_KEY = "tms_live_xxx"
API_SECRET = "xxxxxxxx"
# Producción. Para pruebas: https://api-dev.corhex.app/api/v1/external
HOST = os.getenv("TMS_API_HOST", "https://api.corhex.app")
BASE_PATH = "/api/v1/external"

def sign(method, target, idempotency_key, ts, body):
    body_hash = hashlib.sha256(body).hexdigest()
    canonical = "\n".join([method, target, idempotency_key, ts, body_hash])
    return "sha256=" + hmac.new(API_SECRET.encode(), canonical.encode(), hashlib.sha256).hexdigest()

def call(method, path, body_obj=None):
    target = BASE_PATH + path
    # Firma y envía exactamente los mismos bytes.
    body = json.dumps(body_obj, separators=(",", ":")).encode() if body_obj is not None else b""
    ts = str(int(time.time()))
    idempotency_key = str(uuid.uuid4()) if method == "POST" else ""
    headers = {
        "X-TMS-Api-Key": API_KEY,
        "X-TMS-Timestamp": ts,
        "X-TMS-Signature": sign(method, target, idempotency_key, ts, body),
    }
    if method == "POST":
        headers["Idempotency-Key"] = idempotency_key
        headers["Content-Type"] = "application/json"
    data = body if method == "POST" else None
    return requests.request(method, HOST + target, data=data, headers=headers).json()

call("POST", "/manifests", {
    "type": "pickup_and_delivery",
    "items": [{"recipient_name": "Juan Pérez", "recipient_phone": "+51999999999",
                "delivery_address": "Av. Javier Prado 123", "sla": "next-day"}],
})

Anatomía de una petición

Más allá de la firma, dos mecanismos hacen la integración robusta:

Idempotencia (POST)

Todo POST exige Idempotency-Key (sin él: 400). Si reintentas con el mismo key, el mismo endpoint y el mismo cuerpo, te devolvemos la respuesta original: no se crea nada dos veces. Guardamos sólo las respuestas 2xx, durante 7 días; si la respuesta original no fue 2xx, la clave se libera y puedes reusarla tras corregir el cuerpo. La clave es única por cuenta, compartida entre todas tus credenciales: genera un UUID nuevo por operación.

El 409 Conflict tiene tres motivos:

1. El mismo key con otro cuerpo u otro endpoint — sin Retry-After. Genera una clave nueva (o corrige el payload) antes de reintentar.
2. La petición original todavía en curso — con Retry-After: 5.
3. Un conflicto transitorio interno que se resuelve solo — también con Retry-After: 5.

Regla práctica: con Retry-After, reintenta con la misma clave; sin él, algo del pedido cambió.

Ventana anti-replay

El X-TMS-Timestamp debe estar dentro de ±5 minutos del reloj del servidor. Fuera de ventana — o un timestamp en milisegundos — → 401. Mantén tu servidor sincronizado por NTP.

Envoltura de respuesta

Las respuestas JSON usan el sobre estándar. En éxito el campo error no viene; en error no viene data y error es un texto.

{ "success": true, "data": { /* … */ } }
{ "success": false, "error": "items[0]: recipient_name is required" }

Dos excepciones, ambas en /intl: sus errores agregan data.error_code (un código estable para decidir en tu código), y la factura comercial se descarga como PDF crudo, sin sobre.

Límites de uso

Las respuestas llevan X-RateLimit-Limit y X-RateLimit-Remaining. Ante un 429, espera los segundos de Retry-After antes de reintentar.

Flujo end-to-end

El recorrido típico de una integración, de principio a fin:

Crear un manifiesto

Un manifiesto agrupa una o más guías (hasta 1000). La creación es atómica: si algo falla, no se crea nada. Un JSON mal formado, o sin type/items, responde 400; un error de validación responde 422 con un mensaje de texto. Los SLA inválidos se informan todos juntos (fila N, desde 1); el resto de las validaciones informa el primer error encontrado (items[N], desde 0). Los campos desconocidos se ignoran sin error: revisa bien los nombres.

El lote se agrupa por SLA: se crea un manifiesto por cada SLA distinto, todos en la misma transacción. Si tu cuenta tiene horas de corte configuradas, los manifiestos se activan solos en la próxima.

Tipos de manifiesto

A nivel de manifiesto también puedes enviar notes (texto libre).

Campos por guía (items[])

Respuesta

{
  "codes": ["MAN-20260929-AB12CD34"],        // uno por SLA distinto
  "manifests": [ { /* manifiesto completo */ } ],
  "shipments": [
    {
      "tracking_number": "CHX-20260929-7KQ2M9XA",     // tracking TMS: para consultar y cancelar
      "barcode": "EXT-0001",                  // el tracking_number que enviaste
      "client_tracking_id": "ORD-99821",
      "manifest_code": "MAN-20260929-AB12CD34"
    }
  ]
}

shipments[] no sigue el orden de items[]: empareja cada guía con tu ítem por barcode (tu tracking_number) o por client_tracking_id. Si vas a necesitar el tracking TMS, envía al menos uno de los dos.

Modo casillero abierto

Si prefieres enviar las guías de a una, a medida que se generan tus órdenes, Corhex puede activar en tu cuenta el modo casillero abierto. Cada sucursal tiene un manifiesto abierto (su «casillero») por combinación de sucursal, SLA y flujo; las guías se van acumulando en él y el casillero se cierra solo a tu hora de corte. Sin el modo activo, estos dos endpoints responden 422.

• warehouse_code debe ser el código de un almacén activo de tu cuenta.
• flow: pickup_and_delivery (recogemos en tu sucursal) o cd_pickup (cross-docking con recolección). Si lo omites se usa el flujo por defecto de tu cuenta; sin ninguno, 422.
• Vigila manifest_code y outcome: un warehouse_code o un SLA distinto abre un casillero nuevo, y así lo detectas el mismo día.

Datos de referencia

Antes de crear guías, consulta los códigos válidos para tu cuenta. Todos van firmados con GET (body vacío) y están scoped a tu cliente.

Consultar y cancelar

Consultar

• GET /manifests/:code — el manifiesto y, en shipments[], el tracking TMS de cada una de sus guías.
• GET /manifests?page=1&page_size=20 — tus manifiestos, del más reciente al más antiguo. page_size hasta 100; la respuesta ({ items, total, page, page_size }) devuelve los valores aplicados. El listado no trae las guías de cada manifiesto.
• GET /shipments/:tracking — el estado de una guía. :tracking es el tracking TMS (el de shipments[] y de los webhooks), no tu tracking_number ni tu client_tracking_id.

Cancelar

POST /shipments/:tracking/cancel, con cuerpo opcional { "notes": "…" } e Idempotency-Key como todo POST. Cancela la guía mientras no esté en un estado final (entregada, devuelta, fallida o ya cancelada):

• Si aún no fue recolectada, queda cancelled.
• Si ya estaba en nuestra custodia o en ruta, queda cancelled_after_pickup y vuelve a origen (luego recibes shipment.returned).

Responde 200 con la solicitud de cancelación. Revisa items[0].status: una guía que ya no se puede cancelar vuelve como rejected con rejection_reason: "ineligible_status" — no es un error HTTP. Una cancelación aceptada dispara shipment.cancellation_requested.

Endpoints de la API

Todos cuelgan de la base de tu entorno — producción https://api.corhex.app/api/v1/external, pruebas https://api-dev.corhex.app/api/v1/external. Para esquemas de request/response completos, parámetros y ejemplos por endpoint, consulta la referencia OpenAPI ↗.

Envíos internacionales

Si exportas con Corhex, /intl/* te permite registrar y seguir tus envíos internacionales desde tu sistema. Usa la misma credencial, la misma firma, la misma cuota y la misma Idempotency-Key que el resto de la API.

• Evita duplicados con client_reference: es tu número de orden, único de por vida en tu cuenta. Una repetida responde 409 client_reference_taken con data.existing_code, así un reintento no crea un segundo envío.
• Decide por stage, que es cerrado: registered, transit, customs, attention, closed. status (16 valores, puede crecer) es para mostrar.
• Decide los errores por data.error_code. Un error sin él viene de la autenticación, de la habilitación de la cuenta (404) o de la infraestructura.
• No hay webhooks internacionales todavía. Para sincronizar, consulta el listado con ?updated_since= el último updated_at que viste, con unos segundos de solapamiento.

Los campos, filtros y códigos de error completos están en la referencia OpenAPI ↗.

Cómo funcionan los webhooks

Cuando el estado de una guía o manifiesto cambia, hacemos un POST con el evento a la URL que registraste. Es la forma recomendada de mantener tu sistema sincronizado — sin polling.

Catálogo de eventos

Te suscribes evento por evento (ver Configurar un webhook). La columna data.previous.status muestra el estado anterior más habitual; puede variar según el recorrido de la guía.

Guías — shipment.*

• shipment.cancellation_requested: revisa data.object.status. cancelled si la guía no se había recolectado; cancelled_after_pickup si ya estaba en nuestra custodia, y en ese caso luego recibes shipment.returned.
• Estados que comparten evento: una visita que agotó sus intentos (visit_not_completed) llega como shipment.failed, y una cancelada ya devuelta (cancelled_returned) como shipment.returned. El estado crudo viaja en data.object.status.
• La recepción en nuestro almacén (received) no genera evento.

Manifiestos — manifest.*

Servicios adicionales

Sólo aplican si tienes contratado el servicio de auditoría de puntos o de visitas; si no, no te suscribas a ellos.

Estructura del payload

Todos los eventos comparten un sobre (envelope) estilo Stripe: el recurso completo en data.object y, en las transiciones de guía, el estado anterior en data.previous.

{
  "id": "evt_3f2a9c0e8b1d4e7fa2c65b0d9e4f1a73",  // idempotencia (= X-TMS-Event-Id); opaco, no lo ordenes
  "type": "shipment.delivered",
  "api_version": "2026-06-07",
  "occurred_at": "2026-06-07T17:42:10.482Z",    // cuándo se emitió el evento, RFC3339 UTC
  "data": {
    "object": { /* recurso completo: shipment o manifest */ },
    "previous": { "status": "in_transit" }    // sólo en transiciones de guía
  }
}

data.previous es informativo: puede faltar (en la primera transición de la guía, y en los eventos de manifiesto nunca viene). No lo uses para reconstruir el orden de los eventos.

Recurso shipment

{
  "id": "5f3c2b1a-...",
  "object": "shipment",
  "tracking_number": "CHX-20260605-7KQ2M9XA",  // tracking TMS
  "client_tracking_id": "ORD-99821",        // tu referencia, o null
  "status": "delivered",
  "shipment_type": "ooh",
  "sla": { "code": "next_day", "name": "Día siguiente" },  // null si es on-demand
  "recipient": { "name": "María Pérez", "phone": "+51987654321",
                  "email": "[email protected]", "document": "12345678" },
  "destination": { "address": "Av. Javier Prado 123", "district": "San Isidro",
                    "lat": -12.0931, "lng": -77.0465 },
  "package": { "weight_kg": 2.5, "volume_cm3": 18000, "quantity": 1, "declared_value": 99.9 },
  "delivery_attempts": 1,
  "failure_reason": null,                    // texto legible, sólo en failed
  "failure_code": null,                      // código estable del motivo, sólo en failed
  "proof_of_delivery": {                       // sólo en delivered
    "received_by": "María Pérez",
    "notes": "Recibió en portería",
    "photo_url": "https://.../pod/photo-1.jpg",   // la primera foto
    "photo_urls": ["https://.../pod/photo-1.jpg", "https://.../pod/photo-2.jpg"],
    "signature_url": "https://.../pod/sign.png",
    "delivered_at": "2026-06-07T17:42:09Z"
  },
  "created_at": "2026-06-05T09:00:00Z",
  "updated_at": "2026-06-07T17:42:10Z"
}

• sla.code es el code de GET /sla, no el alias que enviaste.
• failure_reason es un texto legible (motivo, intento, conductor), no un código estable: muéstralo, no lo compares. Para decidir, usa failure_code.
• failure_code es el motivo que eligió el conductor, como código estable (tabla abajo). Igual que failure_reason, sólo trae valor en una guía fallida (shipment.failed) y es null en el resto.
• proof_of_delivery sólo viene en shipment.delivered; en los demás eventos la clave no aparece. recipient.email, recipient.document y destination.district se omiten si están vacíos.
• Las URLs de la prueba de entrega son enlaces permanentes: descárgalas y guárdalas en tu sistema.

Motivos de fallo — failure_code

El catálogo puede crecer: trata un código que no conoces como un fallo genérico, no como un error (responde 2xx igual).

Ejemplo shipment.address_changed

data.previous lleva los datos anteriores; data.object ya refleja los nuevos. lat/lng pueden venir null si la nueva dirección quedó pendiente de re-geocodificación.

{
  "type": "shipment.address_changed",
  "data": {
    "object": {
      "object": "shipment",
      "tracking_number": "CHX-20260605-7KQ2M9XA",
      "status": "assigned",                  // el estado NO cambia
      "destination": { "address": "Av. Arequipa 4500, Miraflores", "lat": null, "lng": null },
      "recipient": { "name": "María Pérez", "phone": "+51999111222" }
    },
    "previous": {                              // datos anteriores, no status
      "delivery_address": "Av. Javier Prado 123, San Isidro",
      "recipient_phone": "+51987654321"
    }
  }
}

Recurso manifest

{
  "id": "9a8b7c6d-...",
  "object": "manifest",
  "code": "MAN-20260607-AB12CD34",
  "client_id": "1c2d3e4f-...",
  "type": "pickup_and_delivery",
  "status": "completed_with_discrepancy",
  "warehouse": { "id": "3333-...", "name": "Almacén Lima Norte" },  // null si no tiene
  "sla": { "code": "same_day", "name": "Mismo día" },
  "counts": { "expected": 50, "received": 48, "driver_scanned": 48 },
  "discrepancy_flag": true,
  "created_at": "2026-06-07T06:00:00Z",
  "updated_at": "2026-06-07T11:30:00Z",
  "completed_at": "2026-06-07T11:30:00Z"
}

Verificar la firma

Cada entrega llega con estos headers (además de Content-Type: application/json). Verifica siempre X-TMS-Signature antes de procesar.

Fórmula

# firma = HMAC_SHA256(whsec, "{t}.{body_crudo}")
# header = X-TMS-Signature: t=<unix>,v1=<hex(firma)>

Token Bearer (opcional)

Si tu infraestructura exige autenticar cada POST entrante (un API gateway, un listener compartido), registramos tu token en la suscripción y lo enviamos en Authorization: Bearer <token> en cada entrega, en los reintentos, en los reenvíos manuales y en el evento de prueba.

• No reemplaza la firma. El token prueba que quien llama lo conoce; la firma prueba además que el body no se alteró y que no es un reenvío viejo. Valida el token si tu gateway lo exige, y verifica la firma igual.
• Compáralo en tiempo constante y responde 401 si no coincide. Ojo: un 401 se reintenta como cualquier no-2xx (ver Reintentos), así que un token mal configurado termina en dead-letter: valídalo con el evento de prueba antes de salir a producción.
• Formato: entre 8 y 4096 caracteres, sin espacios. Puedes pasárnoslo con o sin el prefijo Bearer .

Receptor que verifica

import express from 'express';
import crypto from 'node:crypto';

const WHSEC = process.env.TMS_WEBHOOK_SECRET; // whsec_...
const app = express();
app.use(express.raw({ type: 'application/json' })); // ¡body crudo (Buffer)!

app.post('/webhooks/corhex', (req, res) => {
  const header = req.get('X-TMS-Signature') || '';
  const p = Object.fromEntries(header.split(',').map(x => x.split('=')));
  const t = Number(p.t), v1 = p.v1 || '';

  // (opcional) si nos diste un token Bearer, valida req.get('Authorization') aquí

  // 0) header bien formado (si no, timingSafeEqual lanzaría y responderías 500)
  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(v1)) return res.sendStatus(401);

  // 1) ventana anti-replay (5 min)
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > 300) return res.sendStatus(401);

  // 2) recomputar sobre los bytes crudos y comparar en tiempo constante
  const expected = crypto.createHmac('sha256', WHSEC)
    .update(`${p.t}.`).update(req.body).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) return res.sendStatus(401);

  const event = JSON.parse(req.body);
  // 3) idempotencia por event.id; procesa event.type / event.data.object
  //    (webhook.test es el evento de prueba: sólo responde 2xx)
  //    (guarda y responde rápido; procesa pesado en segundo plano)

  res.sendStatus(200); // 2xx confirma la entrega
});

app.listen(4000);

import hmac, hashlib, time
from flask import Flask, request, abort

WHSEC = "whsec_..."
app = Flask(__name__)

@app.post("/webhooks/corhex")
def corhex():
    # (opcional) si nos diste un token Bearer, valida request.headers["Authorization"] aquí
    header = request.headers.get("X-TMS-Signature", "")
    try:
        p = dict(x.split("=", 1) for x in header.split(","))
        t, v1 = int(p["t"]), p["v1"]
    except (ValueError, KeyError):
        abort(401)  # header malformado

    # 1) ventana anti-replay (5 min)
    if abs(int(time.time()) - t) > 300:
        abort(401)

    # 2) recomputar sobre el body crudo + comparar en tiempo constante
    raw = request.get_data()
    expected = hmac.new(WHSEC.encode(), f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, v1):
        abort(401)

    event = request.get_json()
    # 3) idempotencia por event["id"]; procesa event["type"] / event["data"]["object"]
    #    (webhook.test es el evento de prueba: sólo responde 2xx)
    return "", 200

t, v1   = parse("t=...,v1=...")          # del header X-TMS-Signature (malformado → 401)
esperado = HMAC_SHA256(whsec, t + "." + body_crudo)

assert tiempo_constante_igual(esperado, v1)   # firma válida
assert abs(ahora() - t) <= 300               # ventana anti-replay (5 min)
assert no_visto_antes(event.id)               # idempotencia

responder 200                                 # 2xx confirma

Reintentos y entrega

Si tu endpoint no responde 2xx (o no responde en 10 s), reintentamos automáticamente con backoff exponencial. Cada espera se cuenta desde el intento anterior y es aproximada (±15 s):

inmediato → 30s → 2m → 10m → 1h → 6h

• Sólo 2xx confirma la entrega. No seguimos redirecciones: un 3xx cuenta como fallo. Un 4xx también se reintenta — incluido el 401 por firma o token Bearer inválidos.
• Tras agotar los intentos, la entrega queda en dead-letter y el equipo de Corhex puede reenviarla manualmente desde el panel, con el mismo X-TMS-Event-Id y el mismo X-TMS-Delivery-Id.

Configurar un webhook

Las suscripciones las registra el equipo de Corhex desde su panel; tú no llamas a ningún endpoint para darlas de alta. La configuración se reparte así:

Paso a paso

1. Implementa el receptor: verificación de firma sobre el body crudo, token Bearer si aplica, idempotencia por X-TMS-Event-Id, respuesta 2xx en menos de 10 s, y traducción de nuestros eventos a tus estados.
2. Envíanos los datos de pruebas (URL, eventos y, si aplica, token) por un canal seguro — no pegues tokens en un correo en texto plano.
3. Recibe y guarda el whsec_ de pruebas en tu gestor de secretos.
4. Evento de prueba: lo enviamos a tu URL y debe responder 2xx. Un 401 casi siempre es el token Bearer o el whsec_ equivocados.
5. Prueba de punta a punta: crea guías en pruebas y comprueba que cada evento llega y se refleja en tu sistema.
6. Producción: repite los pasos 2–4 con la URL, el token y el whsec_ de producción. Cada entorno tiene sus propias suscripciones y secretos.

Puedes tener varias suscripciones por entorno (ej. una por sistema o por equipo), cada una con su propio secreto, token y lista de eventos. Si agregamos eventos nuevos al catálogo, pide sumarlos a tu suscripción.

Errores y códigos

En /intl, los errores de negocio traen además data.error_code (ej. client_reference_taken, pickup_not_allowed): decide por ese código. La lista completa por endpoint está en la referencia OpenAPI ↗.

Checklist de integración

• ☐ Guardé api_key, api_secret y whsec_ en mi gestor de secretos.
• ☐ Firmo cada petición con HMAC_SHA256(api_secret, canonical) sobre la cadena canónica de 5 campos (método, request-target, idempotency-key, timestamp, hash del body) y mando los 3 headers de autenticación.
• ☐ Envío una Idempotency-Key nueva en cada POST, y reuso la misma sólo para reintentar esa operación.
• ☐ Mi servidor está sincronizado por NTP (ventana ±5 min) y mando el timestamp en segundos.
• ☐ Validé la firma con GET /me y consulté GET /sla para mis tipos de entrega.
• ☐ Guardo el tracking TMS de cada guía (de shipments[] o del webhook): es el que uso para consultar y cancelar.
• ☐ Mi receptor de webhooks verifica X-TMS-Signature sobre el body crudo y rechaza con 401 un header malformado.
• ☐ Si mi receptor exige token Bearer, se lo di a Corhex por canal seguro y lo valido en tiempo constante (sin dejar de verificar la firma).
• ☐ Deduplico eventos por X-TMS-Event-Id y respondo 2xx rápido.
• ☐ Traduzco type / data.object.status (y failure_code en los fallos) a los estados de mi sistema, e ignoro (con 2xx) los eventos que no uso.
• ☐ Mi endpoint respondió 2xx al evento de prueba en pruebas y en producción.
• ☐ Reconcilio contra mi sistema usando client_tracking_id.
• ☐ Respeto Retry-After en los 429 y 409.
• ☐ Validé el flujo completo en pruebas y tengo la base URL en configuración para cambiar a producción.