Enviadores Public API

Cotizar en todas las paqueterías

Cotiza con todas las paqueterías activas y devuelve tarifas con id (rate_id) listas para POST /shipments. Requiere scope rates:read. Solo rutas domésticas MX (country ≠ MX → 422). Bultos: UN paquete (package) o VARIOS en un mismo envío (packages, 2–10 bultos; mandar ambos → 422). Con packages solo se devuelven ofertas reservables como envío multi-bulto (los servicios que no lo soportan no aparecen) y el peso facturable es la SUMA de los bultos. Códigos postales: deben existir en el catálogo SEPOMEX — un CP inexistente (p. ej. 99999) responde 422 nombrando from.postal_code/to.postal_code ANTES de consultar a las paqueterías (antes se cotizaba por zona a ciegas). Las tarifas de referencia de mostrador (market) NO se incluyen: todo rate_id devuelto es enviable. Seguro: insurance.insured_value (alias obsoleto declared_value) contrata cobertura para el envío: la póliza de la plataforma (prima incluida y firmada dentro de pricing.total_price) o, si esa póliza no está disponible, la cobertura de la propia paquetería — el precio mostrado ya la incluye y cada tarifa lo indica con insurance_included / insurance_not_supported. *Insurance: insured_value buys coverage; when the platform policy is unavailable the carrier's own coverage is used and the price shown already includes it.* Vista agrupada: ?view=grouped devuelve cada servicio distinto UNA sola vez (paquetería + nivel de servicio) con su rango de precios y sus opciones reservables (ver RatesGroupedResponse); la forma plana por defecto no cambia. La respuesta es la MISMA para toda llave (los costos de proveedor nunca se exponen).

{
  "from": {
    "postal_code": "01000"
  },
  "to": {
    "postal_code": "64000"
  },
  "package": {
    "weight_kg": 1,
    "length_cm": 20,
    "width_cm": 15,
    "height_cm": 10
  }
}

{
  "success": true,
  "data": {
    "services": [
      {
        "id": "e2etest_E2ETestCarrier_E2EStandard_ab12cd34",
        "carrier": "Estafeta",
        "service_name": "Terrestre",
        "service_type": "standard_economy",
        "tier": "standard_economy",
        "delivery_window": "ground",
        "pickup_included": false,
        "address_delivery": true,
        "pricing": {
          "total_price": 145.5,
          "currency": "MXN",
          "iva_included": true,
          "insurance_premium": 0,
          "insured_value": null
        },
        "delivery": {
          "estimated_days": "3-5",
          "estimated_date": null,
          "min_days": 3,
          "max_days": 5
        },
        "insurance_included": false,
        "insurance_not_supported": false,
        "zona_extendida": false
      },
      {
        "id": "e2etest_E2ETestCarrier_E2EExpress_7f0a16b2",
        "carrier": "FedEx",
        "service_name": "Express Nacional",
        "service_type": "express",
        "tier": "express",
        "delivery_window": "next_day",
        "pickup_included": true,
        "address_delivery": true,
        "pricing": {
          "total_price": 289,
          "currency": "MXN",
          "iva_included": true,
          "insurance_premium": 0,
          "insured_value": null
        },
        "delivery": {
          "estimated_days": "1-2",
          "estimated_date": null,
          "min_days": 1,
          "max_days": 2
        },
        "insurance_included": false,
        "insurance_not_supported": false,
        "zona_extendida": false
      }
    ],
    "fetched_at": "2026-07-13T18:42:05Z",
    "stale_after": "2026-07-13T18:47:05Z",
    "meta": {
      "billable_weight": 1,
      "volumetric_weight": 0.6,
      "zone": 5
    },
    "rate_id_expires_in_seconds": 1800
  },
  "requestId": "req_a1b2c3d4e5"
}

Listar envíos (paginado)

Por defecto: solo envíos creados por el usuario de la llave, para TODOS los roles — una llave admin ve únicamente sus propios envíos de cuenta de servicio.

Alcance por PDV (opt-in). Una llave admin que envía X-PDV-ID y tiene el scope shipments:read:pdv lista en cambio los envíos de ese punto de venta, sin importar qué operador los creó — el mismo fondo que ya responden /senders, /recipients y /balance bajo ese header. Sin el scope, el header no amplía nada y sigues viendo solo lo tuyo (los integradores que ya lo envían no cambian de resultados).

Cambio de contrato (2026-07): X-PDV-ID ahora se valida en esta ruta aunque no amplíe nada. Antes se ignoraba por completo, así que un PDV inexistente o fuera de la allowlist de la llave respondía 200 con lista vacía mientras /senders respondía 403; ahora responde 403 PDV_NOT_ALLOWED como todas las rutas hermanas.

Orden: más recientes primero. Requiere scope shipments:read (+ shipments:read:pdv para el alcance por PDV).

{
  "success": true,
  "data": {
    "shipments": [
      {
        "id": "20260713-000123",
        "guia": "1234567890",
        "carrier": "Estafeta",
        "service": "Terrestre",
        "status": "in_transit",
        "status_label": "En tránsito",
        "total": 145.5,
        "currency": "MXN",
        "created_at": "2026-07-13T18:45:12Z",
        "tracking_pending": false,
        "label_url": "/api/v1/labels/20260713-000123",
        "packages": [
          {
            "weight_kg": 1,
            "length_cm": 20,
            "width_cm": 15,
            "height_cm": 10
          }
        ],
        "billable_weight_kg": 1,
        "declared_value": null,
        "content": "Ropa",
        "sender": {
          "name": "Juan Pérez",
          "city": "Ciudad de México",
          "state": "CDMX",
          "postal_code": "01000"
        },
        "recipient": {
          "name": "María López",
          "city": "Monterrey",
          "state": "Nuevo León",
          "postal_code": "64000"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1
    }
  },
  "requestId": "req_e5f6a7b8c9"
}

Crear un envío (genera la guía y cobra créditos)

Crea el envío contra un rate_id vigente (≤ 30 min) cotizado con la MISMA llave (y mismo PDV, si aplica). Solo domésticos MX (customs/ocurre, country ≠ MX o campos desconocidos → 422). Bultos: los MISMOS que se cotizaron — package (uno) o packages (2–10 en un solo envío; ambos → 422); un conjunto distinto al cotizado responde 409 RATE_PACKAGE_MISMATCH. CP: origen/destino inline deben existir en SEPOMEX (422 nombrando from.postal_code/to.postal_code, antes de retener saldo). Seguro vs. valor declarado (no son lo mismo): insurance.insured_value es la póliza de plataforma que YA se cotizó — debe coincidir con la cotización (422 INSURANCE_MISMATCH si difiere o falta; el total firmado nunca se recalcula al crear); declared_value es el valor de la mercancía que se declara a la paquetería (MXN, informativo; algunos servicios lo exigen — DECLARED_VALUE_REQUIRED). Remitente/destinatario van inline (la plataforma crea o reutiliza los registros del directorio con dedupe exacto normalizado) o por referencia (from_id/to_id del directorio — la fila guardada se usa tal cual). El cargo sigue el ciclo autorizar→capturar/anular — un envío rechazado nunca deja fondos retenidos. Usa `Idempotency-Key` en todo intento.

{
  "rate_id": "e2etest_E2ETestCarrier_E2EStandard_ab12cd34",
  "from": {
    "name": "Juan Pérez",
    "phone": "5512345678",
    "street": "Av. Insurgentes Sur",
    "number": "600",
    "colonia": "Del Valle",
    "city": "Ciudad de México",
    "state": "CDMX",
    "postal_code": "01000"
  },
  "to": {
    "name": "María López",
    "phone": "8187654321",
    "street": "Av. Constitución",
    "number": "400",
    "colonia": "Centro",
    "city": "Monterrey",
    "state": "Nuevo León",
    "postal_code": "64000"
  },
  "package": {
    "weight_kg": 1
  },
  "contenido": "Ropa"
}

{
  "success": true,
  "data": {
    "shipment": {
      "id": "20260713-000123",
      "guia": "1234567890",
      "carrier": "Estafeta",
      "service": "Terrestre",
      "status": "created",
      "total": 145.5,
      "currency": "MXN",
      "label_url": "/api/v1/labels/20260713-000123",
      "tracking_pending": false,
      "created_at": "2026-07-13T18:45:12Z"
    }
  },
  "requestId": "req_b2c3d4e5f6"
}

Consultar un envío

Misma visibilidad que el listado: propios por defecto, o los del PDV con X-PDV-ID + scope shipments:read:pdv. Devuelve exactamente los mismos campos que cada elemento de GET /shipments (incluyendo packages, pesos y remitente) — el detalle no es más rico que la lista, por diseño. Si solo tienes el número de guía, usa GET /shipments?guia=….

{
  "success": true,
  "data": {
    "shipment": {
      "id": "20260713-000123",
      "guia": "1234567890",
      "carrier": "Estafeta",
      "service": "Terrestre",
      "status": "in_transit",
      "status_label": "En tránsito",
      "total": 145.5,
      "currency": "MXN",
      "created_at": "2026-07-13T18:45:12Z",
      "tracking_pending": false,
      "label_url": "/api/v1/labels/20260713-000123",
      "packages": [
        {
          "weight_kg": 1,
          "length_cm": 20,
          "width_cm": 15,
          "height_cm": 10
        }
      ],
      "billable_weight_kg": 1,
      "declared_value": null,
      "content": "Ropa",
      "sender": {
        "name": "Juan Pérez",
        "city": "Ciudad de México",
        "state": "CDMX",
        "postal_code": "01000"
      },
      "recipient": {
        "name": "María López",
        "city": "Monterrey",
        "state": "Nuevo León",
        "postal_code": "64000"
      }
    }
  },
  "requestId": "req_f6a7b8c9d0"
}

Rastrear cualquier guía

Datos públicos de rastreo (mismo payload PII-mínimo de la página pública: estatus canónico, ciudad/estado de origen y destino, línea de tiempo con nombres de receptor depurados). No requiere que la guía sea propia. Agnóstico al modo de la llave (funciona igual con ek_test_). Requiere scope tracking:read.

{
  "success": true,
  "data": {
    "guia": "1234567890",
    "carrier": "Estafeta",
    "status": "in_transit",
    "status_label": "En tránsito",
    "origin": {
      "city": "Ciudad de México",
      "state": "CDMX"
    },
    "destination": {
      "city": "Monterrey",
      "state": "Nuevo León"
    },
    "created_at": "2026-07-13T18:45:12Z",
    "events": [
      {
        "timestamp": "2026-07-13T20:10:00Z",
        "description": "Recolectado",
        "location": "Ciudad de México, CDMX"
      },
      {
        "timestamp": "2026-07-14T09:30:00Z",
        "description": "En tránsito al destino",
        "location": "Querétaro, QRO"
      }
    ]
  },
  "requestId": "req_c3d4e5f6a7"
}

Solicitar la cancelación de un envío propio

Crea una solicitud de cancelación (estado inicial pending). El avance del estado es operado por el staff/los procesos de la plataforma — consulta GET /cancellations/{id}. El reembolso esperado es lo que se cobró por el envío. Requiere scope cancellations:write.

{
  "shipment_id": "20260713-000123",
  "reason_code": "customer_changed_mind"
}

{
  "success": true,
  "data": {
    "id": 42,
    "display_id": "CR00000042",
    "status": "pending",
    "refund_status": "not_applicable",
    "refund_amount_expected": 145.5,
    "cancellation_deadline": "2026-07-14T18:45:12Z"
  },
  "requestId": "req_a7b8c9d0e1"
}

Consultar una solicitud de cancelación

Visibilidad idéntica a la del envío que cancela (propios por defecto; los del PDV con X-PDV-ID + scope shipments:read:pdv) — deliberadamente en paralelo, para que un envío que puedes leer nunca tenga una cancelación que no.

Máquina de estados: pending → approved → in_progress → cancelled | rejected_by_carrier; otros estados: not_cancellable (la guía no admite cancelación vía API — terminal), reported_to_carrier (reporte manual ante la paquetería, sigue abierta), rejected, failed, expired. Reembolso: not_applicable → refund_in_progress → refunded | refund_denied (los reembolsos son pass-through de la paquetería; refunded cubre también el reembolso manual por override administrativo). Requiere scope cancellations:read.

{
  "success": true,
  "data": {
    "cancellation": {
      "id": 42,
      "display_id": "CR00000042",
      "shipment_id": "20260713-000123",
      "status": "cancelled",
      "refund_status": "refunded",
      "reason_code": "customer_changed_mind",
      "reason_text": null,
      "refund_amount_expected": 145.5,
      "refund_amount_actual": 145.5,
      "cancellation_deadline": "2026-07-14T18:45:12Z",
      "created_at": "2026-07-13T19:02:33Z",
      "updated_at": "2026-07-15T10:12:05Z",
      "resolved_at": "2026-07-15T10:12:05Z"
    }
  },
  "requestId": "req_b8c9d0e1f2"
}

Listar tus solicitudes de recolección

Las solicitudes de recolección de la cuenta, de la más reciente a la más antigua — qué pediste, para cuándo, y si nuestro equipo ya la gestionó.

Visibilidad idéntica a la del listado de envíos: por omisión las recolecciones de los envíos que creó el usuario de la llave; con X-PDV-ID validado y el scope ampliado shipments:read:pdv, las de ese punto de venta (las dos ramas son EXCLUYENTES). Mientras la programación de recolecciones no esté habilitada en la cuenta, este listado responde 200 con una página vacía — un listado de algo que no puedes usar no tiene nada que reportar. Requiere scope pickups:read.

{
  "success": true,
  "data": {
    "pickups": [
      {
        "id": 42,
        "display_id": "PR00000042",
        "shipment_id": "20260830-000123",
        "status": "awaiting_confirmation",
        "carrier": "Estafeta",
        "requested_window_start": "2026-08-31T16:00:00Z",
        "requested_window_end": "2026-08-31T23:00:00Z",
        "confirmed_window_start": null,
        "confirmed_window_end": null,
        "confirmation_number": null,
        "created_at": "2026-08-30T10:00:00Z",
        "updated_at": "2026-08-30T10:00:02Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1
    }
  },
  "requestId": "req_a7b8c9d0e1"
}

Solicitar la recolección de un envío propio

Solicita que la paquetería pase por el paquete al domicilio del remitente, en lugar de que el remitente lo lleve a sucursal.

Esto es una solicitud, no una reserva. No agendamos con la paquetería de forma automática: el equipo de Enviadores la gestiona y avisa por correo al solicitante cuando queda. Por eso la respuesta siempre regresa status: awaiting_confirmation — nunca reportes al usuario que ya hay mensajero confirmado. Consulta GET /pickups/{id} para el estado final, o espera el correo.

Por qué. Un 200 de una paquetería no es prueba de que el mensajero vaya a llegar, y el peor error posible aquí es decirle a alguien que su recolección está confirmada y dejarlo esperando. Preferimos ser lentos y ciertos.

Disponible sólo para Estafeta, DHL, FedEx y Paquetexpress (422 PICKUP_CARRIER_NOT_ELIGIBLE para el resto; el paquete siempre puede entregarse en sucursal). Una sola recolección abierta por envío.

pickup_date, ready_time y close_time son hora local de México (America/Mexico_City); la respuesta devuelve las ventanas en UTC (Z).

La recolección no cobra saldo; cualquier cargo de la paquetería llega después por la vía de sobrecargos, igual que en el carril web.

La dirección de recolección es la del propio envío — este endpoint no la cambia. Requiere scope pickups:write.

{
  "shipment_id": "20260830-000123",
  "pickup_date": "2026-08-31",
  "ready_time": "10:00",
  "close_time": "17:00",
  "notes": "Timbre azul, preguntar por Ana"
}

{
  "success": true,
  "data": {
    "pickup": {
      "id": 42,
      "display_id": "PR00000042",
      "shipment_id": "20260830-000123",
      "status": "awaiting_confirmation",
      "carrier": "Estafeta",
      "requested_window_start": "2026-08-31T16:00:00Z",
      "requested_window_end": "2026-08-31T23:00:00Z",
      "confirmed_window_start": null,
      "confirmed_window_end": null,
      "confirmation_number": null,
      "created_at": "2026-08-30T10:00:00Z",
      "updated_at": "2026-08-30T10:00:02Z"
    }
  },
  "requestId": "req_a7b8c9d0e1"
}

Consultar una recolección

Estado de una solicitud de recolección propia — úsalo para dar seguimiento mientras está en awaiting_confirmation (el solicitante también recibe un correo cuando se resuelve). Visibilidad idéntica a la del envío al que pertenece, en paralelo deliberado con GET /cancellations/{id}. Requiere scope pickups:read.

{
  "success": true,
  "data": {
    "pickup": {
      "id": 42,
      "display_id": "PR00000042",
      "shipment_id": "20260830-000123",
      "status": "awaiting_confirmation",
      "carrier": "Estafeta",
      "requested_window_start": "2026-08-31T16:00:00Z",
      "requested_window_end": "2026-08-31T23:00:00Z",
      "confirmed_window_start": null,
      "confirmed_window_end": null,
      "confirmation_number": null,
      "created_at": "2026-08-30T10:00:00Z",
      "updated_at": "2026-08-30T10:00:02Z"
    }
  },
  "requestId": "req_a7b8c9d0e1"
}

Consultar el saldo que cargarían tus envíos

Sin X-PDV-ID: el saldo del usuario de la llave. Con X-PDV-ID (llaves admin, misma allowlist que POST /shipments): el fondo del punto de venta — exactamente el principal que un envío bajo ese header cargaría. available es lo gastable; held son autorizaciones pendientes; balance = available + held. Requiere scope balance:read.

{
  "success": true,
  "data": {
    "balance": 4820.5,
    "held": 145.5,
    "available": 4675,
    "currency": "MXN",
    "scope": {
      "type": "user",
      "id": "U0000001"
    }
  },
  "requestId": "req_d4e5f6a7b8"
}

Descargar la etiqueta de un envío propio

Transmite la copia de la etiqueta que guarda la plataforma (PDF/ZPL); si aún no existe, la obtiene de la paquetería, la guarda y la transmite. Nunca redirige a la URL de la paquetería. Con ?format=json responde JSON (LabelLink) en lugar de bytes. Solo envíos creados por el usuario de la llave (todos los roles). Requiere scope labels:read.

Listar remitentes del directorio

Remitentes visibles para la llave. Visibilidad: llaves de cliente y llaves admin SIN X-PDV-ID ven solo los registros creados por el usuario de la llave; una llave admin con X-PDV-ID validado ve exactamente el directorio de ese punto de venta (el mismo que usa el personal de mostrador). Nunca hay lectura global en este carril. Requiere scope addresses:read. Este endpoint SÍ devuelve dirección completa y teléfono — el guardián es la visibilidad, no el recorte de campos.

{
  "success": true,
  "data": {
    "senders": [
      {
        "id": "C0012345",
        "name": "Juan Pérez",
        "apellido_paterno": null,
        "apellido_materno": null,
        "company": null,
        "rfc": null,
        "phone": "5512345678",
        "email": "[email protected]",
        "street": "Av. Insurgentes Sur",
        "number": "600",
        "colonia": "Del Valle",
        "city": "Ciudad de México",
        "state": "CDMX",
        "postal_code": "01000",
        "created_at": "2026-07-13T18:40:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1
    }
  },
  "requestId": "req_c9d0e1f2a3"
}

Crear (o reutilizar) un remitente

Create-or-reuse con el MISMO dedupe exacto normalizado que usa POST /shipments al registrar direcciones inline, evaluado sobre las filas visibles para la llave: si ya existe un remitente idéntico visible, se devuelve ese (created: false, 200); si no, se crea (created: true, 201). El postal_code debe tener 5 dígitos y EXISTIR en el catálogo postal (SEPOMEX); si city/state vienen, deben ser coherentes con el CP (un desajuste responde 422 nombrando el valor esperado) y si se omiten se AUTOCOMPLETAN del catálogo — la misma validación de exactitud que POST /contacts/import. Requiere scope addresses:write. Con X-PDV-ID (llave admin), la fila creada pertenece al directorio de ese PDV y queda visible para su personal.

{
  "name": "Juan Pérez García",
  "phone": "5512345678",
  "email": "[email protected]",
  "street": "Av. Insurgentes Sur",
  "number": "600",
  "colonia": "Del Valle",
  "city": "Ciudad de México",
  "state": "CDMX",
  "postal_code": "01000"
}

{
  "success": true,
  "data": {
    "sender": {
      "id": "C0012345",
      "name": "Juan Pérez",
      "apellido_paterno": null,
      "apellido_materno": null,
      "company": null,
      "rfc": null,
      "phone": "5512345678",
      "email": "[email protected]",
      "street": "Av. Insurgentes Sur",
      "number": "600",
      "colonia": "Del Valle",
      "city": "Ciudad de México",
      "state": "CDMX",
      "postal_code": "01000",
      "created_at": "2026-07-13T18:40:00Z"
    },
    "created": false
  },
  "requestId": "req_e1f2a3b4c5"
}

{
  "success": true,
  "data": {
    "sender": {
      "id": "C0012345",
      "name": "Juan Pérez",
      "apellido_paterno": null,
      "apellido_materno": null,
      "company": null,
      "rfc": null,
      "phone": "5512345678",
      "email": "[email protected]",
      "street": "Av. Insurgentes Sur",
      "number": "600",
      "colonia": "Del Valle",
      "city": "Ciudad de México",
      "state": "CDMX",
      "postal_code": "01000",
      "created_at": "2026-07-13T18:40:00Z"
    },
    "created": true
  },
  "requestId": "req_d0e1f2a3b4"
}

Consultar un remitente

Requiere scope addresses:read. 404 idéntico para inexistente y no-visible (sin oráculo).

{
  "success": true,
  "data": {
    "sender": {
      "id": "C0012345",
      "name": "Juan Pérez",
      "apellido_paterno": null,
      "apellido_materno": null,
      "company": null,
      "rfc": null,
      "phone": "5512345678",
      "email": "[email protected]",
      "street": "Av. Insurgentes Sur",
      "number": "600",
      "colonia": "Del Valle",
      "city": "Ciudad de México",
      "state": "CDMX",
      "postal_code": "01000",
      "created_at": "2026-07-13T18:40:00Z"
    }
  },
  "requestId": "req_f2a3b4c5d6"
}

Editar un remitente

Actualización PARCIAL de un remitente visible. Requiere scope addresses:write. Solo los campos presentes cambian; se debe enviar al menos uno. Los requeridos pueden cambiarse pero no vaciarse; los opcionales aceptan null para limpiarse. Los apellidos NO forman parte del dedupe, así que PATCH es la forma de completarlos en una fila creada sin ellos. 404 idéntico para inexistente y no-visible (sin oráculo).

{
  "name": "Juan Pérez García",
  "email": null
}

{
  "success": true,
  "data": {
    "sender": {
      "id": "C0012345",
      "name": "Juan Pérez García",
      "apellido_paterno": null,
      "apellido_materno": null,
      "company": null,
      "rfc": null,
      "phone": "5512345678",
      "email": "[email protected]",
      "street": "Av. Insurgentes Sur",
      "number": "600",
      "colonia": "Del Valle",
      "city": "Ciudad de México",
      "state": "CDMX",
      "postal_code": "01000",
      "created_at": "2026-07-13T18:40:00Z"
    }
  },
  "requestId": "req_a3b4c5d6e7"
}

Listar destinatarios del directorio

Misma visibilidad que GET /senders. Un destinatario siempre pertenece a un remitente (sender_id). Requiere scope addresses:read.

{
  "success": true,
  "data": {
    "recipients": [
      {
        "id": "D0067890",
        "sender_id": "C0012345",
        "alias": "Oficina",
        "name": "María López",
        "phone": "8187654321",
        "email": null,
        "street": "Av. Constitución",
        "number": "400",
        "colonia": "Centro",
        "city": "Monterrey",
        "state": "Nuevo León",
        "postal_code": "64000",
        "referencia": "Edificio azul, junto a la farmacia",
        "delivery_instructions": "Entregar en recepción",
        "created_at": "2026-07-13T18:41:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1
    }
  },
  "requestId": "req_b4c5d6e7f8"
}

Crear (o reutilizar) un destinatario

Create-or-reuse bajo el remitente sender_id (debe ser visible para la llave; si no → 404 ciego). Mismo dedupe normalizado que el carril de envíos; en una reutilización, alias/referencia/delivery_instructions NO se aplican (no forman parte de la identidad — la fila existente se devuelve intacta). El postal_code debe tener 5 dígitos y EXISTIR en el catálogo postal (SEPOMEX); si city/state vienen, deben ser coherentes con el CP (un desajuste responde 422 nombrando el valor esperado) y si se omiten se AUTOCOMPLETAN del catálogo — la misma validación de exactitud que POST /contacts/import. Requiere scope addresses:write.

{
  "sender_id": "C0012345",
  "alias": "Oficina",
  "name": "María López",
  "phone": "8187654321",
  "street": "Av. Constitución",
  "number": "400",
  "colonia": "Centro",
  "city": "Monterrey",
  "state": "Nuevo León",
  "postal_code": "64000",
  "referencia": "Edificio azul, junto a la farmacia",
  "delivery_instructions": "Entregar en recepción"
}

{
  "success": true,
  "data": {
    "recipient": {
      "id": "D0067890",
      "sender_id": "C0012345",
      "alias": "Oficina",
      "name": "María López",
      "phone": "8187654321",
      "email": null,
      "street": "Av. Constitución",
      "number": "400",
      "colonia": "Centro",
      "city": "Monterrey",
      "state": "Nuevo León",
      "postal_code": "64000",
      "referencia": "Edificio azul, junto a la farmacia",
      "delivery_instructions": "Entregar en recepción",
      "created_at": "2026-07-13T18:41:00Z"
    },
    "created": false
  },
  "requestId": "req_d6e7f8a9b0"
}

{
  "success": true,
  "data": {
    "recipient": {
      "id": "D0067890",
      "sender_id": "C0012345",
      "alias": "Oficina",
      "name": "María López",
      "phone": "8187654321",
      "email": null,
      "street": "Av. Constitución",
      "number": "400",
      "colonia": "Centro",
      "city": "Monterrey",
      "state": "Nuevo León",
      "postal_code": "64000",
      "referencia": "Edificio azul, junto a la farmacia",
      "delivery_instructions": "Entregar en recepción",
      "created_at": "2026-07-13T18:41:00Z"
    },
    "created": true
  },
  "requestId": "req_c5d6e7f8a9"
}

Consultar un destinatario

Requiere scope addresses:read. 404 idéntico para inexistente y no-visible (sin oráculo).

{
  "success": true,
  "data": {
    "recipient": {
      "id": "D0067890",
      "sender_id": "C0012345",
      "alias": "Oficina",
      "name": "María López",
      "phone": "8187654321",
      "email": null,
      "street": "Av. Constitución",
      "number": "400",
      "colonia": "Centro",
      "city": "Monterrey",
      "state": "Nuevo León",
      "postal_code": "64000",
      "referencia": "Edificio azul, junto a la farmacia",
      "delivery_instructions": "Entregar en recepción",
      "created_at": "2026-07-13T18:41:00Z"
    }
  },
  "requestId": "req_e7f8a9b0c1"
}

Editar un destinatario

Actualización PARCIAL de un destinatario visible. Requiere scope addresses:write. sender_id es inmutable (no se re-asigna de remitente). Solo los campos presentes cambian; al menos uno. Los requeridos pueden cambiarse pero no vaciarse; los opcionales aceptan null. 404 idéntico para inexistente y no-visible.

{
  "phone": "8187654322",
  "delivery_instructions": null
}

{
  "success": true,
  "data": {
    "recipient": {
      "id": "D0067890",
      "sender_id": "C0012345",
      "alias": "Oficina",
      "name": "María López",
      "phone": "8187654322",
      "email": null,
      "street": "Av. Constitución",
      "number": "400",
      "colonia": "Centro",
      "city": "Monterrey",
      "state": "Nuevo León",
      "postal_code": "64000",
      "referencia": "Edificio azul, junto a la farmacia",
      "delivery_instructions": "Entregar en recepción",
      "created_at": "2026-07-13T18:41:00Z"
    }
  },
  "requestId": "req_f8a9b0c1d2"
}

Validar un código postal y listar sus colonias

Resuelve un código postal mexicano (catálogo SEPOMEX) en su estado, municipio y el conjunto de colonias/asentamientos — justo lo que se necesita para llenar una dirección antes de POST /senders o POST /shipments. Requiere scope addresses:read. Datos de referencia públicos y de solo lectura: responde IDÉNTICo con llaves ek_live_ y ek_test_ (no hay nada que simular). 422 si el CP no son 5 dígitos; 404 si no existe en el catálogo; 200 con los datos si es válido.

{
  "success": true,
  "data": {
    "postal_code": "64000",
    "state": "Nuevo León",
    "state_code": "NL",
    "municipality": "Monterrey",
    "city": "Monterrey",
    "colonias": [
      {
        "name": "Centro",
        "settlement_type": "Colonia"
      }
    ]
  },
  "requestId": "req_a9b0c1d2e3"
}

Importar contactos al directorio en bloque (remitentes y destinatarios)

Importación masiva del directorio — pensada para migrar contactos desde una hoja de cálculo, otra plataforma o una lista fotografiada, típicamente a través de un asistente de IA. Requiere scope addresses:write (es el mismo alcance de POST /senders / POST /recipients: una importación son esos dos creates en bloque).

Dos carriles de entrada, mutuamente excluyentes: - contacts: arreglo de filas {type: 'sender'|'recipient', name, phone, street, number?, colonia, city?, state?, postal_code, email?, company?, rfc?} — el mismo vocabulario de campos que POST /senders / POST /recipients (los destinatarios además aceptan sender_id?, alias?, referencia?, delivery_instructions?). El cliente (p. ej. el modelo) debe mapear los datos del usuario TAL CUAL, nunca inventar valores. - raw_csv: el contenido del CSV del usuario, VERBATIM (UTF-8, BOM opcional, máx. 256KB). El servidor lo interpreta de forma determinista: delimitador coma/punto y coma/tabulador (detectado), fila de encabezado obligatoria con las columnas de la plantilla tipo,nombre,telefono,calle,numero,colonia,ciudad,estado,codigo_postal,email,empresa,rfc (coincidencia insensible a mayúsculas y acentos, cualquier orden; columnas desconocidas → 422, nunca adivinadas). tipo acepta remitente/destinatario (o sender/recipient).

Dos fases sin estado: dry_run: true (el DEFAULT — el modo seguro) valida todo y devuelve la vista previa normalizada sin escribir nada; dry_run: false re-valida e inserta. La seguridad ante reintentos viene del DEDUPE POR CONTENIDO, no de claims: una fila idéntica (tupla normalizada nombre+teléfono+dirección+CP — el MISMO dedupe de POST /senders) a un contacto existente visible se reporta duplicate y se omite, así que repetir un commit jamás duplica el directorio.

Validación por fila (nunca aborta el lote completo): codigo_postal de 5 dígitos y existente en el catálogo SEPOMEX; si ciudad/estado vienen, deben ser coherentes con el CP (un desajuste nombra el valor esperado) y si faltan se AUTOCOMPLETAN del catálogo; telefono se normaliza a 10 dígitos (se toleran espacios, guiones y el prefijo +52/521); email con formato válido cuando venga. Cada fila responde status: ok|duplicate|invalid con issues[] en español nombrando campo y motivo.

Padre de los destinatarios: un destino siempre pertenece a un remitente. Orden de resolución: sender_id explícito de la fila → el PRIMER remitente válido del mismo lote → el remitente más reciente del directorio. Sin candidato, la fila es invalid con instrucciones.

Topes: máximo 200 filas por llamada (más → 422 pidiendo trocear el lote) y 256KB de raw_csv.

Conteos (invariantes): received = valid + invalid, valid = filas ok + duplicates; en commit además created y skipped con received = created + skipped + invalid — imposible perder filas en silencio.

Con una llave ek_test_ la importación escribe en el directorio del sandbox (mismas reglas, mismos formatos de respuesta). La visibilidad/destino de las filas es la misma de POST /senders: llaves de cliente y llaves admin sin X-PDV-ID escriben como el usuario de la llave; una llave admin con X-PDV-ID validado escribe en el directorio de ese punto de venta.

{
  "success": true,
  "data": {
    "dry_run": false,
    "rows": [
      {
        "index": 0,
        "line": 2,
        "type": "sender",
        "name": "Juan Pérez",
        "status": "ok",
        "issues": [],
        "contact": {
          "type": "sender",
          "name": "Juan Pérez",
          "phone": "5512345678",
          "street": "Av. Insurgentes Sur",
          "number": "600",
          "colonia": "San Ángel",
          "city": "Ciudad de México",
          "state": "Ciudad de México",
          "postal_code": "01000"
        },
        "id": "C0012399"
      },
      {
        "index": 1,
        "line": 3,
        "type": "recipient",
        "name": "Ana López",
        "status": "duplicate",
        "issues": [
          "ya existe un contacto idéntico en tu directorio (se omite)"
        ],
        "contact": null,
        "id": "D0045012"
      },
      {
        "index": 2,
        "line": 4,
        "type": "sender",
        "name": "Mal Teléfono",
        "status": "invalid",
        "issues": [
          "telefono: debe tener 10 dígitos después de quitar espacios, guiones y el prefijo +52 (recibido «123»)"
        ],
        "contact": null,
        "id": null
      }
    ],
    "summary": {
      "received": 3,
      "valid": 2,
      "invalid": 1,
      "duplicates": 1,
      "created": 1,
      "skipped": 1
    }
  },
  "requestId": "req_f1e2d3c4b5"
}

Listar webhooks

Todos los webhooks de la cuenta en el modo de la llave (live o sandbox), incluidos los desactivados automáticamente — status, failure_count (fallos consecutivos) y last_delivery_* explican por qué dejaron de llegar eventos. Nunca incluye secretos. Requiere scope webhooks:read.

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": "wh_0f3a9c1d2e4b5a6978c0d1e2",
        "url": "https://hooks.mitienda.com/enviadores",
        "events": [
          "shipment.created",
          "shipment.delivered"
        ],
        "mode": "live",
        "status": "active",
        "failure_count": 0,
        "last_delivery_at": "2026-09-04T16:05:12Z",
        "last_delivery_status": 200,
        "created_at": "2026-09-04T16:00:00Z",
        "disabled_at": null,
        "disabled_reason": null
      }
    ],
    "max_active": 5,
    "events": [
      "shipment.created",
      "shipment.collected",
      "shipment.in_transit",
      "shipment.out_for_delivery",
      "shipment.delivered",
      "shipment.exception",
      "shipment.returned",
      "shipment.cancelled",
      "pickup.resolved"
    ]
  },
  "requestId": "req_a7b8c9d0e1"
}

Registrar un webhook

Registra un endpoint https:// público que recibirá un POST firmado por cada evento suscrito. El `secret` se devuelve UNA sola vez en esta respuesta: no se almacena (se deriva bajo una llave del servidor) y no vuelve a mostrarse; guárdalo al recibirlo. Máximo 5 webhooks activos por cuenta y modo (409 WEBHOOK_LIMIT_REACHED). La URL se valida contra SSRF: solo https://, hostname público (se rechazan localhost, .local, .internal, literales IP privadas/loopback/link-local y hosts que resuelvan a ellas) y sin credenciales embebidas; en cada entrega se vuelve a resolver el host y la conexión se fija a la IP pública verificada. Con llave ek_test_ el webhook es de sandbox (solo shipment.created/shipment.cancelled del carril de pruebas + ping). Requiere scope webhooks:write.

{
  "url": "https://hooks.mitienda.com/enviadores",
  "events": [
    "shipment.created",
    "shipment.delivered",
    "shipment.exception"
  ]
}

{
  "success": true,
  "data": {
    "webhook": {
      "id": "wh_0f3a9c1d2e4b5a6978c0d1e2",
      "url": "https://hooks.mitienda.com/enviadores",
      "events": [
        "shipment.created",
        "shipment.delivered",
        "shipment.exception"
      ],
      "mode": "live",
      "status": "active",
      "failure_count": 0,
      "last_delivery_at": null,
      "last_delivery_status": null,
      "created_at": "2026-09-04T16:00:00Z",
      "disabled_at": null,
      "disabled_reason": null
    },
    "secret": "whsec_9f2c…(64 hex)"
  },
  "requestId": "req_a7b8c9d0e1"
}

Consultar un webhook

Un webhook propio (misma cuenta y mismo modo que la llave). Requiere scope webhooks:read.

Eliminar un webhook

Elimina el webhook. Las entregas se detienen de inmediato y los eventos pendientes en cola para él se descartan. Volver a registrar la misma URL genera un id y un secret NUEVOS. Requiere scope webhooks:write.

{
  "success": true,
  "data": {
    "deleted": true,
    "id": "wh_0f3a9c1d2e4b5a6978c0d1e2"
  },
  "requestId": "req_a7b8c9d0e1"
}

Probar un webhook (ping)

Entrega un {"event":"ping"} firmado de forma síncrona (mismos headers y misma firma que un evento real; data = {webhook_id}) y reporta el resultado. Un ping fallido NO cuenta para la desactivación automática — repítelo con libertad mientras ajustas el endpoint. Sin cuerpo. Requiere scope webhooks:write.

{
  "success": true,
  "data": {
    "delivered": false,
    "response_status": 500,
    "error": "HTTP 500",
    "event_id": "evt_4a5b6c7d8e9f0a1b2c3d4e5f"
  },
  "requestId": "req_a7b8c9d0e1"
}

Identificar la llave y la cuenta (whoami)

Quién eres desde el punto de vista de la API: la cuenta, si la conexión es de prueba (ek_test_) o de producción (ek_live_), los scopes que la llave realmente porta en ESTA petición, el saldo disponible y las capacidades de la superficie.

Es el endpoint de autodiagnóstico: cuando algo responde 403 INSUFFICIENT_SCOPE, compara key.scopes con el scope que nombró el error; cuando dudes si una guía es real, mira account.mode.

Cualquier llave válida puede llamarlo, sin importar sus scopes — un whoami que pudiera responder 403 por falta de permiso no serviría para su único propósito. Aun así no expone nada nuevo: balance.available es el mismo número de GET /balance (misma lectura), y el resto son hechos sobre tu propia llave. Nunca devuelve el secreto ni su hash ni su prefijo, ni la allowlist de PDVs, ni correo/teléfono/rol.

key.scopes es el conjunto EFECTIVO: una llave creada con "los permisos por omisión" (scopes_mode: default) se re-resuelve contra los scopes por omisión vigentes en cada petición, así que aquí ves lo que el gate acaba de aplicar. Una llave que alguien restringió a mano (scopes_mode: explicit) queda congelada como se creó.

account.tier_label es el escalón de verificación de las cuentas de registro propio (T1…T4); es null para cuentas creadas por nuestro equipo, que no están en esa escalera, y también si la consulta de verificación no está disponible.

capabilities describe la superficie, no la cuenta: pickups sigue el interruptor de recolecciones (siempre true en sandbox), y international/multi_package se derivan de las mismas validaciones que aplica POST /shipments, así que no pueden desincronizarse de la realidad.

En modo de prueba, balance.available es el saldo COMPUTADO del sandbox.

{
  "success": true,
  "data": {
    "account": {
      "id": "U0000001",
      "name": "Comercializadora Ejemplo SA de CV",
      "mode": "live",
      "account_type": "customer",
      "tier_label": "T3"
    },
    "key": {
      "id": "AK0123456789abcdef",
      "label": "Servidor de producción",
      "mode": "live",
      "scopes": [
        "rates:read",
        "shipments:write",
        "shipments:read",
        "tracking:read",
        "cancellations:write",
        "cancellations:read",
        "balance:read",
        "labels:read",
        "addresses:read",
        "addresses:write",
        "pickups:write",
        "pickups:read"
      ],
      "scopes_mode": "default",
      "spend_cap_daily_mxn": 5000,
      "rate_limit_tier": "standard"
    },
    "balance": {
      "available": 4675,
      "currency": "MXN"
    },
    "capabilities": {
      "pickups": true,
      "international": false,
      "multi_package": false,
      "webhooks": false
    }
  },
  "requestId": "req_d4e5f6a7b8"
}

Listar los movimientos de saldo

El libro mayor detrás de GET /balance: cargos por guías, reembolsos por cancelación, recargas y ajustes manuales, del más reciente al más antiguo. Es la respuesta a "¿en qué se fue el saldo?".

Mismo principal que `GET /balance`, por construcción. Sin header: el saldo PERSONAL del usuario de la llave. Con X-PDV-ID validado (llaves admin, misma allowlist): el libro mayor de ese fondo de punto de venta. Las consultas cruzadas por user_id del endpoint interno NO existen aquí: una llave lee exactamente el fondo que cargarían sus envíos.

amount viene con SIGNO en MXN (negativo = salió dinero) y balance_after es el saldo tras ese movimiento. type usa un vocabulario público de cuatro palabras (charge, refund, topup, adjustment) que resume el enum interno; los detalles internos (qué reventa, qué pierna de una corrección, qué programa) no se exponen.

En modo de prueba el listado se DERIVA de los envíos sandbox — un cargo al crear, un reembolso al cancelar — de modo que la suma cuadra exactamente con el saldo computado del sandbox. Requiere scope balance:read.

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "TX00012345",
        "type": "charge",
        "amount": -184.5,
        "balance_after": 4675,
        "shipment_id": "20260830-000123",
        "description": "Guía Estafeta Terrestre",
        "created_at": "2026-08-30T10:00:02Z"
      },
      {
        "id": "TX00012344",
        "type": "topup",
        "amount": 2000,
        "balance_after": 4859.5,
        "shipment_id": null,
        "description": "Recarga en línea",
        "created_at": "2026-08-29T18:12:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2
    }
  },
  "requestId": "req_b1c2d3e4f5"
}