De la cotización
a la entrega.

Tu primera conexión

Necesitas una cuenta activa y una llave creada en Integraciones → API Propia → Generar llave. La llave permite únicamente las operaciones nacionales descritas en esta referencia y los datos de tu propia cuenta. No da acceso al panel administrativo ni a otras integraciones. Al suspender la cuenta se bloquea también la llave. Se muestra completa una sola vez. Guárdala en el servidor de tu aplicación, como una variable de entorno.

https://api.dcenvios.lat

Envía X-API-Key: dc_live_... o Authorization: Bearer dc_live_.... Elige una de las dos formas. Para solicitudes con cuerpo, incluye Content-Type: application/json.

export DC_API_KEY="TU_LLAVE_PRIVADA"
curl https://api.dcenvios.lat/api/v1/balance \
  --header "X-API-Key: $DC_API_KEY"

Los ejemplos de nombres, guías e importes son ficticios. La tarifa aplicable es la que devuelve la cotización de tu cuenta.

Un flujo completo, paso a paso

1. Ejecuta GET /api/v1/balance.
2. Consulta GET /api/v1/cp/64000 y el CP de destino; selecciona las colonias.
3. Busca GET /api/v1/sat/buscar?q=pantalones y confirma el producto.
4. Envía POST /api/v1/quote con los datos definitivos.
5. Muestra las tarifas al usuario y usa el token de la elegida en POST /api/v1/label.
6. Si el resultado está completo, conserva id y numero_guia. Si está pendiente, consulta /labels.
7. Consulta /label-pdf/{id} y decodifica la etiqueta. Luego utiliza /tracking/{guia}.

En Postman, importa la colección, configura api_key localmente y copia el token elegido a token_cotizacion. Para comprar, establece confirmar_compra=true después de revisar la tarifa. Las solicitudes de cancelación y recolección tienen confirmaciones separadas. Usa una versión actual de Postman con soporte para pm.execution.skipRequest(); estos controles pertenecen a la colección y no son restricciones del servidor. Cambia la fecha de ejemplo por una fecha disponible.

Direcciones y contenido

Estas son las entradas recomendadas para una integración completa. Las restricciones particulares de la paquetería pueden producir rechazos adicionales; no existe un límite de longitud universal garantizado para todos los servicios.

Dirección: remitente y destinatario

Paquete

Pesos e importes

Usa kg y cm. El cálculo actual de peso volumétrico es largo × ancho × alto / 5000; el peso cobrable toma el mayor entre peso real y volumétrico, redondeado hacia arriba. Utiliza siempre la tarifa devuelta.

Los importes están en MXN. precio y precio_venta son los importes de venta de tu cuenta. Los campos heredados costo_envio y costo_proteccion también representan importes al cliente. La respuesta no desglosa subtotal e IVA por separado; no recalcules el total con una tasa adicional. El comprobante fiscal se gestiona por el proceso de facturación de tu cuenta.

Sobrepesos y ajustes posteriores

Si el saldo no alcanza, solo se descuenta la parte disponible y el resto queda pendiente. Ejemplo: un cargo de $150 con $100 disponibles produce un descuento de $100 y deja $50 pendientes. Consultar la API no cobra, no carga una tarjeta bancaria y no realiza cobros a tus compradores.

No hay webhook de sobrepesos para clientes en esta versión. La integración es una consulta periódica desde tu servidor. Puedes comenzar solamente con saldo y guías y agregar la conciliación después.

La tarifa inicial se calcula con el peso y las medidas declarados. Si la paquetería registra diferencias de peso o dimensiones, puede reportar un ajuste posterior. El importe depende del servicio y del cargo registrado; no hay una cuota fija universal.

Declara las medidas exteriores del paquete ya cerrado, incluido el embalaje. El peso volumétrico también puede generar diferencias aunque el peso físico sea menor. Conserva fotografías del paquete, medidas y lectura de la báscula para una posible aclaración.

Conexión sencilla, sin webhooks

1. Desde tu servidor consulta GET /api/v1/movimientos y GET /api/v1/balance. Puedes programar una consulta cada 5 minutos para un volumen bajo o moderado y consultar al abrir tu pantalla de saldo. Evita consultas simultáneas y respeta el límite global por IP.
2. Los descuentos ya aplicados se identifican con tipo: cargo_adicional. El origen puede ser ajuste_paqueteria. Guarda cada movimiento por id, con una restricción única por cuenta, para no contabilizarlo dos veces.
3. Usa el saldo que devuelve /balance. El cargo ya está incluido: no lo vuelvas a descontar. Para interpretar un movimiento usa saldo_anterior y saldo_nuevo, no solo el signo de monto.
4. Para relacionar ajustes con cada guía y separar importes cobrados de pendientes, descarga GET /api/v1/labels/reporte.csv. La referencia del movimiento es un texto descriptivo, no un identificador estructurado garantizado de la guía.
5. Un ajuste sin saldo cobrado puede no aparecer en movimientos. El reporte incluye lo pendiente. Registrar un pendiente no equivale a cobrarlo; no supongas que se cobrará automáticamente al recargar.

curl 'https://api.dcenvios.lat/api/v1/movimientos' \
  --header "X-API-Key: $DC_API_KEY"

curl 'https://api.dcenvios.lat/api/v1/balance' \
  --header "X-API-Key: $DC_API_KEY"

// Node.js 20 o superior. Ejecutar solo en tu servidor.
// Lectura de una instantánea: no aplica cargos ni modifica el saldo.
const key = process.env.DC_API_KEY;
if (!key) throw new Error('Configura DC_API_KEY en tu servidor.');

async function leer(ruta) {
  const r = await fetch('https://api.dcenvios.lat' + ruta, {
    headers: { 'X-API-Key': key },
    signal: AbortSignal.timeout(15000)
  });
  if (r.status === 429) {
    throw new Error('Espera Retry-After: ' + (r.headers.get('retry-after') || 'no indicado'));
  }
  if (!r.ok) throw new Error('DC Envíos respondió HTTP ' + r.status);
  return r.json();
}

const historial = await leer('/api/v1/movimientos');
const balance = await leer('/api/v1/balance');
const cargos = historial.movimientos.filter(m => m.tipo === 'cargo_adicional');
console.log(JSON.stringify({ saldo_actual: balance.saldo, cargos_aplicados: cargos }, null, 2));
// En tu integración: guarda cada movimiento con clave única (cuenta_dc, id).
// No vuelvas a restar estos cargos a saldo_actual.
// Las dos lecturas son independientes; puede haber actividad entre ellas.

Aclarar un cargo

Reporta la diferencia en el apartado de soporte del portal, categoría Cargo por sobrepeso, o a contacto@dcenvios.lat. Incluye número e ID de guía, fecha, importe del ajuste, peso y medidas declarados y evidencias del paquete. Abrir una aclaración no cancela automáticamente el cargo ni garantiza un reembolso; conserva el folio y verifica la resolución.

API internacional · Próximamente

La función internacional del portal, disponible para cuentas habilitadas, es independiente. No uses un token de sesión del navegador ni credenciales de administración en tu integración.

Decodificar una etiqueta

Ejemplo para Node.js 18 o posterior. Configura DC_API_KEY y DC_GUIA_ID en tu servidor. No presupone que el contenido siempre será PDF.

// Node.js 18+ · ejecutar en tu servidor
import { writeFile } from 'node:fs/promises';
const base = 'https://api.dcenvios.lat';
const key = process.env.DC_API_KEY;
const id = process.env.DC_GUIA_ID;
if (!key || !id) throw new Error('Configura DC_API_KEY y DC_GUIA_ID');
const res = await fetch(base + '/api/v1/label-pdf/' + encodeURIComponent(id), {
  headers: { 'X-API-Key': key }
});
const body = await res.json();
if (!res.ok) throw new Error(body.error || 'Error HTTP ' + res.status);
if (!body.base64) throw new Error('Etiqueta pendiente. Consulta después; no compres otra guía.');
const raw = body.base64.replace(/^data:[^,]*;base64,/i, '');
const bytes = Buffer.from(raw, 'base64');
const ext = bytes.subarray(0, 4).toString() === '%PDF' ? 'pdf'
  : bytes.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10])) ? 'png'
  : bytes[0] === 255 && bytes[1] === 216 ? 'jpg' : 'bin';
await writeFile('etiqueta.' + ext, bytes);

Duplicados, tiempos de espera y estados pendientes

La generación controla duplicados por cuenta y cotización. Mientras el token sea válido, repetir el mismo token puede devolver la guía original con idempotente:true, un conflicto GUIDE_PROCESSING o un resultado pendiente. No se documenta soporte para un encabezado Idempotency-Key.

Recomendación de cliente: usa un timeout de hasta 90 segundos para cotizar o generar y trata su vencimiento como resultado desconocido. Para consultas, aplica espera progresiva y respeta Retry-After. Estos tiempos son recomendaciones de integración, no una garantía de disponibilidad.

Generación y entrega son estados distintos

generada indica que hay una guía; etiqueta_pendiente que el documento está pendiente; por_revisar requiere conciliación. Ninguno confirma recolección o entrega. El rastreo puede informar recolectada, en_transito, en_reparto, entregada u otros estados normalizados. Tolera valores nuevos y conserva la descripción de los eventos.

Errores y límites

Las respuestas de error son JSON con error. Algunas añaden code o codigo; lee ambos. No automatices decisiones basadas únicamente en el texto del mensaje.

{
  "error": "La guía ya se está procesando. Consulta tus guías.",
  "code": "GUIDE_PROCESSING"
}

Códigos específicos

Límite de solicitudes

El límite global configurado es de 60 solicitudes por minuto por IP. Considera que varios procesos pueden compartir la misma salida a Internet. Al recibir 429, espera el valor de Retry-After cuando esté presente; evita reintentos simultáneos.

Saldo y devolución

La generación verifica y descuenta saldo antes de completar la compra. Los fallos confirmados pueden restituirlo; una operación en revisión puede conservar el cargo. No supongas devolución por recibir un error: consulta /balance, /labels y las indicaciones del resultado. Solicitar cancelación tampoco acredita saldo de inmediato.

Qué puedes integrar hoy

Esta referencia cubre las operaciones nacionales verificadas con la llave API: saldo, movimientos, catálogos, cotización, guías, etiqueta, rastreo, cancelaciones, recolecciones y reporte de ajustes. Los servicios y embalajes disponibles dependen de la cuenta, ruta y paquetería.

• API internacional · Próximamente: todavía no disponible con la llave API. El portal tiene una activación independiente por cuenta. Consulta los requisitos y el alcance.
• Sandbox: no hay un entorno público de pruebas documentado. Consultar catálogos y saldo permite validar la conexión sin emitir una guía. Coordina cualquier prueba de compra con soporte.
• Webhooks para clientes: esta versión no publica un contrato de suscripción. Integra rastreo por consulta.
• Multipieza: no se documenta un parámetro de cantidad en /quote. Gestiona una cotización por operación soportada.
• Compatibilidad: acepta campos adicionales en las respuestas y estados desconocidos. Conserva el contrato publicado de los campos que consumes.

Antes de salir a producción

Comprueba autenticación, selección de colonia y SAT, lectura de tarifas, manejo de 202/409/429, recuperación de etiquetas pendientes y conciliación de guías. Una prueba de compra genera un envío real.

Soporte

Escribe a contacto@dcenvios.lat con fecha y hora, endpoint, HTTP, código de error e ID de guía si existe. Nunca compartas tu API key.

Descargas: OpenAPI 3.0 · Postman · Ejemplo de etiqueta.