Skip to content
Nexus API

Developer Documentation

Nexus API

LogisticsOne single REST/JSON integration to quote, generate guides, cancel, collect and track with more than 30 Mexican carriers.

v1 · stable JSON · UTF-8 HTTPS · TLS 1.2+ Test mode included
Start here

Quick start in 3 steps

1. Generate your keys

Enter your panel → Integrations → API REST — My keys. Create a test key for development and one for production for real guides. The Secret Key is shown only once.

2. Make your first call

Quotation and tracking are public: you can test them now, without keys, directly in the browser or from your server.

3. Generate your first guide

With the keys in the headers, send the chosen rate and shipment data. You receive tracking number, PDF, and remaining balance.

First request: quote from CDMX (06600) to Guadalajara (45050) a package of 2.5 kg.

request
curl -X POST "https://peshipping.peshipping.bhgcnexuslogistics.com/functions/publicQuoteShipments" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_cp": "06600",
    "dest_cp": "45050",
    "weight_kg": 2.5,
    "length_cm": 30,
    "width_cm": 20,
    "height_cm": 15
  }'
response 200
{
  "rates": [
    {
      "carrier": "DHL",
      "service": "Express Nacional",
      "total_cost": 189.20,
      "currency": "MXN",
      "transit_days": 1,
      "source": "envia"
    }
  ]
}

Do you prefer to see the complete guide with keys and examples by language? Authentication · Languages · API capabilities

Security

Authentication with integrator keys

Each integrator generates its own keys in Integrations → API REST — My keys. All calls operate with the balance and permissions of the account owner of the key, and the generated guides are assigned to that account. Franchise and SaaS tenants of the hybrid system can also integrate, each with their own keys.

HeaderUsage
X-BHGC-API-KeyPublic API Key of the integrator.
X-BHGC-SecretPrivate Secret Key (validated by SHA-256 hash on the server).
Content-Typeapplication/json; charset=utf-8

Test Key

Returns simulated guides with fictional tracking (prefix TEST): does not debit balance, does not call the carrier and does not issue PDF. Ideal for building and testing your integration without cost.

Production Key

Generates real guides, debits balance and issues the carrier's PDF label. Without sufficient balance, the API responds 402 instead of simulating the guide.

Authenticated call
curl -X POST "https://peshipping.peshipping.bhgcnexuslogistics.com/functions/apiIntegration" \
  -H "Content-Type: application/json" \
  -H "X-BHGC-API-Key: $API_KEY" \
  -H "X-BHGC-Secret: $API_SECRET" \
  -d '{ "action": "balance" }'
Response
{
  "ok": true,
  "mode": "******",
  "currency": "MXN",
  "balance": 1240.50,
  "can_generate_labels": true,
  "wallet_mode": "per_user"
}

Best practices

  • · Store the Secret Key in environment variables or a vault; never in the frontend or in repositories.
  • · Validation is by SHA-256 hash: if you lose it, regenerate it and the previous one is invalidated instantly.
  • · One key per environment and per application; this way you can revoke one without affecting the others.
  • · Suspended accounts and deactivated keys respond 403.
Reference

API v1 Endpoints

7 endpoints
POST/publicQuoteShipmentssin llaves

Get a shipping quote

Tarifas disponibles para una ruta, peso y dimensiones. Sin llaves. Límite de 120 solicitudes por minuto por IP.

Campos del cuerpo
  • origin_cprequeridoCP de origen (5 dígitos en México).
  • dest_cprequeridoCP de destino (5 dígitos en México).
  • weight_kgrequeridoPeso real en kg.
  • length_cm / width_cm / height_cmopcionalDimensiones en cm (peso volumétrico).
  • package_typeopcionalsobre · paquete · tarima · pallet · camion. Paquete hasta 70 kg; tarima, pallet y camión hasta 1,000 kg.
  • origin_country / dest_countryopcionalPaís de origen y destino (default: México).
request
POST https://peshipping.peshipping.bhgcnexuslogistics.com/functions/publicQuoteShipments

{
  "origin_cp": "06600",
  "dest_cp": "45050",
  "weight_kg": 2.5,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 15,
  "package_type": "paquete"
}
Response
{
  "rates": [
    {
      "carrier": "DHL",
      "service": "Express Nacional",
      "total_cost": 189.20,
      "currency": "MXN",
      "transit_days": 1,
      "source": "envia"
    }
  ],
  "dimFiltered": [],
  "disabledSources": []
}
POST/publicTrackShipmentsin llaves

Track shipment

Estatus y línea de tiempo de una guía. Datos públicos: sin nombres ni direcciones completas.

Campos del cuerpo
  • tracking_numberrequeridoNúmero de guía.
request
POST https://peshipping.peshipping.bhgcnexuslogistics.com/functions/publicTrackShipment

{ "tracking_number": "1234567890" }
Response
{
  "found": true,
  "shipment": {
    "tracking_number": "1234567890",
    "carrier": "DHL",
    "service": "Express Nacional",
    "status": "en_transito",
    "origin_cp": "06600",
    "dest_cp": "45050"
  },
  "events": [{ "status": "en_transito", "date": "2026-09-18T09:12:00Z" }]
}
POST/createShipmentLabelrequiere llaves

Generate prepaid guide

Genera la guía, debita el saldo y devuelve rastreo + PDF. En la misma llamada puedes asegurar la mercancía, declarar datos aduanales y agrupar guías. Con llave de prueba la guía es simulada (prefijo TEST) y no cuesta.

Campos del cuerpo
  • raterequeridoObjeto de tarifa tal como llegó en la cotización.
  • shipmentrequeridoDatos del envío: CP, peso, medidas, contenido y direcciones.
  • shipment.sender_*requeridoNombre, calle, número, colonia, ciudad, estado y teléfono del remitente.
  • shipment.recipient_*requeridoMismos campos del destinatario.
  • shipment.package_typeopcionalsobre · paquete · tarima · pallet · camion (default: paquete).
  • shipment.declared_valueopcionalValor declarado en MXN. Base de la protección y de la declaración aduanal.
  • shipment.insurance_amountopcionalProtección interna por el monto indicado; el cargo se descuenta del saldo junto con la guía.
  • shipment.cudo_insurance_enabledopcionaltrue contrata la protección adicional de Cudo sobre el valor declarado (queda pendiente de aprobación).
  • shipment.hs_code / manufacture_country / export_reason / incotermopcionalDeclaración aduanal del envío internacional: código HS, país de fabricación, razón de exportación y términos de venta.
  • shipment.customs_items / invoice_rateopcionalPartidas declaradas (descripción, HS, cantidad, valor unitario) y tipo de cambio MXN→USD del Commercial Invoice.
  • group_idopcionalAgrupa varias guías de una misma operación para consultarlas y rastrearlas juntas.
  • quantityopcionalCantidad de guías idénticas (1 por default).
request
POST https://peshipping.peshipping.bhgcnexuslogistics.com/functions/createShipmentLabel

{
  "rate": { "carrier": "DHL", "service": "Express Nacional", "total_cost": 189.20, "source": "envia" },
  "shipment": {
    "origin_cp": "06600",
    "dest_cp": "45050",
    "weight_kg": 2.5,
    "content": "Mercancía",
    "declared_value": 500,
    "sender_name": "Juan Pérez",
    "sender_street": "Av. Reforma",
    "sender_number": "100",
    "sender_colony": "Centro",
    "sender_city": "CDMX",
    "sender_state": "CDMX",
    "sender_phone": "5512345678",
    "recipient_name": "María García",
    "recipient_street": "Av. Hidalgo",
    "recipient_number": "200",
    "recipient_colony": "Centro",
    "recipient_city": "Zapopan",
    "recipient_state": "Jalisco",
    "recipient_phone": "3312345678"
  }
}
Response
{
  "success": true,
  "shipment": {
    "id": "a1b2c3d4-...",
    "carrier": "DHL",
    "tracking_number": "1234567890",
    "tracking_url": "https://.../?rastrear=1234567890",
    "status": "generada",
    "total_cost": 189.20
  },
  "label_pdf_url": "https://.../guia_1234567890.pdf",
  "simulated": false,
  "new_balance": 810.80
}
POST/bulkCreateShipmentsrequiere llaves

Bulk guide upload

Genera varias guías en una sola llamada. Cada elemento usa el mismo formato que createShipmentLabel.

Campos del cuerpo
  • shipmentsrequeridoArreglo de { rate, shipment }.
request
POST https://peshipping.peshipping.bhgcnexuslogistics.com/functions/bulkCreateShipments

{
  "shipments": [
    { "rate": { "carrier": "DHL", "service": "Express Nacional", "total_cost": 189.20 }, "shipment": { "...": "mismo formato" } },
    { "rate": { "carrier": "FedEx", "service": "Nacional", "total_cost": 169.00 }, "shipment": { "...": "mismo formato" } }
  ]
}
Response
{
  "success": true,
  "created": 2,
  "failed": 0,
  "shipments": [{ "tracking_number": "1234567890", "status": "generada" }],
  "new_balance": 641.80
}
POST/cancelShipmentrequiere llaves

Cancel guide

Solicita o ejecuta la cancelación. Si el carrier la confirma, el saldo se reembolsa.

Campos del cuerpo
  • shipment_idrequeridoID del envío.
  • actionopcionalrequest · approve · reject · cancel (default: cancel).
  • reasonopcionalMotivo de la cancelación.
request
POST https://peshipping.peshipping.bhgcnexuslogistics.com/functions/cancelShipment

{
  "shipment_id": "a1b2c3d4-...",
  "action": "cancel",
  "reason": "Ya no se requiere el envío"
}
Response
{
  "success": true,
  "carrier_cancelled": true,
  "confirmation": "CNCL-12345",
  "refunded": 189.20,
  "status": "cancelada"
}
POST/schedulePickuprequiere llaves

Schedule pickup

Agenda la recolección en el origen en la fecha y ventana horaria indicadas.

Campos del cuerpo
  • shipment_idrequeridoID del envío a recolectar.
  • pickup_daterequeridoFecha YYYY-MM-DD.
  • pickup_time_start / pickup_time_endrequeridoVentana horaria HH:mm.
  • contact_name / contact_phonerequeridoPersona y teléfono de contacto.
  • notesopcionalInstrucciones para el mensajero.
request
POST https://peshipping.peshipping.bhgcnexuslogistics.com/functions/schedulePickup

{
  "shipment_id": "a1b2c3d4-...",
  "pickup_date": "2026-09-20",
  "pickup_time_start": "10:00",
  "pickup_time_end": "14:00",
  "contact_name": "Juan Pérez",
  "contact_phone": "5512345678",
  "notes": "Preguntar por recepción"
}
Response
{
  "success": true,
  "pickup": {
    "status": "programada",
    "confirmation": "PICK-67890",
    "pickup_date": "2026-09-20"
  }
}
POST/apiIntegrationrequiere llaves

Balance, guides and webhooks

Consulta saldo, lista y detalle de guías, entregas de webhook y catálogo de eventos. El campo action elige la operación.

Campos del cuerpo
  • actionrequeridobalance · shipments · shipment · deliveries · webhook_test · events
  • tracking_number / shipment_idopcionalPara action=shipment.
  • status / carrieropcionalFiltros de action=shipments.
  • from / toopcionalRango de fechas ISO 8601.
  • limit / cursoropcionalPaginación (máx. 100 por página).
  • liveopcionalCon action=shipment consulta el rastreo en vivo.
request
POST https://peshipping.peshipping.bhgcnexuslogistics.com/functions/apiIntegration

{
  "action": "shipment",
  "tracking_number": "1234567890",
  "live": true
}
Response
{
  "ok": true,
  "mode": "******",
  "simulated": false,
  "shipment": {
    "tracking_number": "1234567890",
    "status": "en_transito",
    "total_cost": 189.20
  },
  "events": [{ "status": "en_transito", "date": "2026-09-18T09:12:00Z" }],
  "live_checked": true
}
Sandbox

Prueba la API aquí mismo

Esta consola llama al endpoint público real de cotización (sin llaves). Para probar la generación de guías usa una llave de prueba: el ciclo completo funciona y devuelve una guía simulada sin costo.

respuesta en vivo
// Ejecuta la cotización para ver la respuesta real
Compatibility

Formatos de datos

Todo el contrato es JSON UTF-8 con convenciones fijas. Respetarlas evita el 90% de los errores de integración (montos como texto, códigos postales sin ceros, fechas locales o teléfonos numéricos).

ElementoRegla
Cuerpo de peticiones y respuestasJSON UTF-8 (`application/json; charset=utf-8`). No se acepta form-data ni XML.
MontosNúmero decimal en MXN (ej. 189.2). Nunca string, nunca con símbolo ni separador de miles.
FechasISO 8601 en UTC con sufijo Z (ej. 2026-09-18T09:12:00Z). Los rangos de filtro aceptan el mismo formato.
Códigos postalesString, siempre con ceros a la izquierda ("06600"). Nunca los envíes como número.
TeléfonosString de 10 dígitos (México) o E.164 con +. Nunca number.
IdentificadoresUUID v4 en `id`. El `tracking_number` es string y puede contener letras.
Booleanos y nulos`true` / `false` reales. Un campo nulo puede no aparecer: no asumas su presencia.
EnumeracionesMinúsculas sin acentos (generada, en_transito, entregado, cancelada). Tolera valores nuevos con un caso por defecto.
Campos nuevosPueden agregarse en cualquier respuesta. Ignora los desconocidos; nunca falles por un campo extra.
correcto
{
  "origin_cp": "06600",
  "weight_kg": 2.5,
  "declared_value": 500,
  "sender_phone": "5512345678",
  "created_date": "2026-09-18T09:12:00Z"
}
incorrecto
{
  "origin_cp": 6600,              // pierde el cero inicial
  "weight_kg": "2,5 kg",          // string con unidad y coma
  "declared_value": "$500.00",    // símbolo y separador
  "sender_phone": 5512345678,     // number: pierde dígitos
  "created_date": "18/09/2026"    // formato local, sin zona
}
Compatibility

Protocolos y transporte

01 · Tu servidor

POST HTTPS con cuerpo JSON y headers de llave.

02 · API

Valida llave, plan, saldo y datos. Responde JSON con el resultado o un error tipado.

03 · Webhook

Cuando el estatus cambia, la plataforma notifica a tu URL con firma HMAC.

AspectComportamiento
ProtocoloHTTPS obligatorio (TLS 1.2 o superior) sobre HTTP/2 o HTTP/1.1. No hay endpoint por HTTP plano ni SOAP.
Método y rutaPOST con cuerpo JSON en todos los endpoints. No se usan parámetros en la URL.
Tiempos de esperaLa cotización consulta varios proveedores: configura 30 s. Guías, cancelación y recolección responden en menos de 60 s.
ReintentosReintenta solo consultas (cotizar, rastrear, saldo) con backoff exponencial 1s, 2s, 4s. No reintentes a ciegas una generación de guía: antes consulta action=shipments para evitar duplicados.
Compresión y cachéSe acepta gzip y br. Las respuestas de cotización son datos vivos: no las caches más de unos minutos.
CORSLos endpoints públicos pueden llamarse desde el navegador. Las llaves deben usarse siempre desde tu servidor, nunca en el frontend.
WebhooksPOST JSON a tu URL, con X-BHGC-Event y X-BHGC-Webhook-Signature (HMAC-SHA256 del cuerpo exacto). Responde 2xx en menos de 5 s.

Reintento con backoff para consultas (nunca para generar guías sin verificar antes):

javascript
async function conReintentos(fn, intentos = 3) {
  for (let i = 0; i < intentos; i++) {
    const res = await fn();
    if (res.status !== 429 && res.status < 500) return res;
    await new Promise((r) => setTimeout(r, 1000 * 2 ** i)); // 1s, 2s, 4s
  }
  return fn();
}
Compatibility

Compatibilidad con versiones anteriores

La API pública opera hoy en v1. La regla es simple: dentro de una versión el contrato solo crece. Tu integración no debe romperse cuando nosotros agregamos capacidades.

Aditivo, nunca destructivo

Dentro de v1 solo se agregan campos, valores de enumeración y endpoints. Nunca se renombran ni se eliminan campos, ni cambia el significado de uno existente.

Deprecación avisada

Si algo debe retirarse, se marca como deprecado en el OpenAPI y en esta página, se anuncia con al menos 6 meses de anticipación y convive con la alternativa durante ese periodo.

Versión en la ruta

Los cambios incompatibles se publican como v2 en su propio documento de OpenAPI. v1 sigue disponible y estable durante todo el aviso.

Tolerancia obligatoria

Tu cliente debe ignorar campos y valores que no conozca. Agregar un dato nuevo no es una ruptura de contrato y no se anuncia como tal.

CambioImpacto
Agregar un campo a una respuestaSeguro
Agregar un valor nuevo a una enumeraciónSeguro (usa caso por defecto)
Agregar un endpoint nuevoSeguro
Renombrar o eliminar un campo existenteSolo en una versión mayor
Cambiar el tipo o el significado de un campoSolo en una versión mayor
Cambiar la ruta de un endpoint v1No ocurre

Cómo publicamos una versión nueva

  • · Se anuncia aquí y en la especificación OpenAPI con su propio documento.
  • · v1 sigue operando sin cambios durante todo el periodo de aviso (mínimo 6 meses).
  • · Migrar es opcional y por endpoint: no hay un “apagón” global.

Lo que tu cliente debe hacer

  • · Ignorar campos desconocidos al deserializar (no fallar por un campo nuevo).
  • · No depender del orden de las claves ni del orden de las tarifas.
  • · Guardar el valor crudo de los estatus y mapearlo con un caso por defecto.
  • · Registrar el código HTTP y el mensaje de `error` para diagnóstico.
Diagnóstico

Errores y límites

HTTPSignificado
400Solicitud inválidaFalta un campo, el CP no tiene 5 dígitos o el peso está fuera de rango. Revisa el mensaje en `error`.
401No autenticadoFaltan los headers X-BHGC-API-Key / X-BHGC-Secret o la secret no coincide.
402Saldo insuficienteLa llave de producción no tiene saldo para la guía. Recarga la billetera.
403Acceso bloqueadoLlave desactivada, cuenta suspendida, plan sin acceso a API o restricción de origen.
404No encontradoLa guía no existe o no pertenece al dueño de la llave.
429Demasiadas solicitudesSe superó el límite (120/min por IP en cotización pública). Espera y reintenta con backoff.
500Error internoFalla inesperada. Reintenta una vez; si persiste, conserva el `id` de la respuesta y contacta soporte.
502Falla del proveedorEl carrier o el webhook de destino no respondió correctamente.
forma del error
{
  "error": "Peso debe estar entre 0.1 y 70 kg"
}
manejo recomendado
const res = await fetch(url, opts);
const data = await res.json().catch(() => ({}));

if (!res.ok) {
  // 400/401/403/404 → no reintentes, corrige la petición
  // 402 → saldo insuficiente: recarga la billetera
  // 429 → espera y reintenta con backoff
  // 5xx → reintenta una vez y reporta con el mensaje
  throw new Error(data.error || `HTTP ${res.status}`);
}

Límite de 120 solicitudes por minuto por IP en la cotización pública y en el rastreo. Las llamadas autenticadas se contabilizan por llave. Al superarlo la API responde 429; evita bucles de reintento inmediato.

Eventos

Webhooks firmados

Configura tu URL en el panel de llaves y la plataforma te notifica cada cambio de estatus con un POST JSON. Cada entrega incluye X-BHGC-Event y X-BHGC-Webhook-Signature (HMAC-SHA256 del cuerpo exacto con tu secret).

Evento
shipment.createdGuía generada con éxito (real en producción, simulada con llave de prueba).
shipment.status_changedLa guía cambió de estatus (en_transito, entregado, intento fallido).
shipment.cancelledLa guía se canceló y el saldo se reembolsó cuando aplicó.
webhook.testEvento de prueba solicitado desde tu panel o con action=webhook_test.
payload
POST https://tu-sistema.com/webhooks/envios
X-BHGC-Event: shipment.status_changed
X-BHGC-Webhook-Signature: 8f14e45fceea167a5a36dedd4bea2543...

{
  "event": "shipment.status_changed",
  "mode": "******",
  "timestamp": "2026-09-18T09:12:00Z",
  "tracking_number": "1234567890",
  "status": "en_transito",
  "carrier": "DHL"
}
verificar firma · node
import crypto from "node:crypto";

const firma = req.headers["x-bhgc-webhook-signature"];
const esperado = crypto
  .createHmac("sha256", process.env.API_SECRET)
  .update(rawBody) // cuerpo crudo, sin parsear
  .digest("hex");

if (!crypto.timingSafeEqual(Buffer.from(firma), Buffer.from(esperado))) {
  return res.status(401).end();
}

Reglas de entrega

  • · Responde 2xx en menos de 5 s; el cuerpo de tu respuesta se ignora.
  • · Trata los eventos como idempotentes: un mismo cambio puede llegar más de una vez.
  • · Valida la firma con el cuerpo crudo antes de parsear el JSON.
  • · Las entregas fallidas quedan registradas y puedes probar tu endpoint con action=webhook_test.
  • · Si no usas webhooks, consulta el estatus con /publicTrackShipment o action=shipment.
Compatibility

Plataformas y lenguajes

No necesitas un SDK propietario: cualquier cliente HTTP sirve. La misma petición funciona igual en servidor, serverless, contenedores o herramientas no-code.

curl -X POST "$BASE_URL/createShipmentLabel" \
  -H "Content-Type: application/json" \
  -H "X-BHGC-API-Key: $API_KEY" \
  -H "X-BHGC-Secret: $API_SECRET" \
  -d @guia.json
PlatformSupportNota
Node.js 18+ / Deno / BunYesfetch nativo y AbortSignal.timeout.
Python 3.9+Yesrequests o httpx.
PHP 7.4+ (WooCommerce, PrestaShop)YescURL o Guzzle.
Java 11+ / KotlinYesjava.net.http o OkHttp.
.NET 6+ / C#YesHttpClient + System.Text.Json.
Go 1.20+ / Ruby 3Yesnet/http o Faraday.
Postman, Insomnia, Swagger UIYesImporta el OpenAPI 3.1 de esta misma página.
n8n, Make, Zapier (HTTP Request)YesHeaders personalizados con la API Key y la Secret.

Importa el contrato a tu herramienta

Descarga el OpenAPI 3.1 de esta página y en Postman elige Import → Link o File con el JSON. En Swagger UI, Insomnia o generadores de clientes (openapi-generator) basta apuntar al mismo documento. Los endpoints con llave quedan listos para configurar como variables de entorno.

¿Listo para integrar?

Genera tus llaves en el panel y usa el modo prueba para desarrollar sin costo. Si tu caso es especial, el equipo de integraciones te acompaña.