API de proveedores

Cómo funciona

1. Consulta los envíos nuevos: GET /guias?estado=solicitada trae los envíos que ALCO te asignó y que aún no tienen tu guía, con origen, destino, bultos, peso, medidas y fecha de recolección.
2. Regresa tu guía: POST /guias/{folio}/guia con tu número de guía y, si la tienes, la etiqueta en PDF.
3. Informa los movimientos: POST /guias/{folio}/eventos al recolectar, en tránsito, al entregar o si hay una incidencia.
4. Opcional: POST /guias/{folio}/recepcion con el peso y las medidas reales al recibir.

Cada envío trae su folio ALCO (ALCO + fecha + 4 dígitos); con él identificas el envío en todas las llamadas. El cliente imprime y pega tu guía, así que conviene mandar la etiqueta en PDF al regresar la guía.

Autenticación

ALCO te entrega una llave de API. Mándala en cada llamada:

Authorization: Bearer alcop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Guárdala como secreto en tu servidor y nunca la pongas en una página web ni en una app.
• Si crees que se filtró, pide a ALCO que la revoque y te dé una nueva.
• Cada llave solo ve y modifica las guías de tu paquetería.
• Límite: 120 llamadas por minuto por llave.

Llave de pruebas: ALCO también puede darte una llave de pruebas. Funciona igual, pero trabaja sobre dos envíos simulados (ALCOPRUEBA01 y ALCOPRUEBA02) y no toca envíos reales; sus respuestas traen "pruebas": true. Para dejarlos como al inicio: POST /pruebas/reiniciar.

Dirección base: https://alco-envios.web.app/api/v1/proveedor. Todo va y viene en JSON (Content-Type: application/json).

GET/guias

Tus guías, de la más nueva a la más vieja.

curl "https://alco-envios.web.app/api/v1/proveedor/guias?estado=curso" \
  -H "Authorization: Bearer $LLAVE"

{
  "ok": true,
  "total": 1,
  "guias": [{
    "id": "q1W2e3R4t5Y6u7I8",
    "folio": "ALCO2610300427",
    "guia": "",
    "creado": "2026-10-30T15:20:00.000Z",
    "etapa": "solicitada",
    "estadoTexto": "Guía generada",
    "servicio": "Terrestre",
    "origen":  { "cp": "27000", "colonia": "Centro", "ciudad": "Torreón", "estado": "Coahuila" },
    "destino": { "cp": "64000", "colonia": "Centro", "ciudad": "Monterrey", "estado": "Nuevo León" },
    "paquetes": [{ "empaque": "caja", "cantidad": 1, "peso": 25, "largo": 120, "ancho": 100, "alto": 100 }],
    "recoleccion": { "fecha": "2026-10-31", "hora": "10:00", "enSucursal": false },
    "costo": 420.41,
    "recepcion": null,
    "historia": [{ "fecha": "2026-10-30T15:20:00.000Z", "descripcion": "Solicitud de envío recibida" }]
  }]
}

costo es lo que te corresponde cobrar según tu convenio con ALCO.

GET/guias/{folio o guía}

Una guía, buscada por el folio ALCO (el código de barras de la etiqueta) o por tu número de guía. Responde { "ok": true, "guia": { … } } con los mismos campos que la lista.

curl https://alco-envios.web.app/api/v1/proveedor/guias/ALCO2610300427 \
  -H "Authorization: Bearer $LLAVE"

POST/guias/{folio}/guia

Regresa tu número de guía para el envío. El cliente lo ve de inmediato en su panel y en el rastreo, y puede descargar tu etiqueta si la mandas.

curl -X POST https://alco-envios.web.app/api/v1/proveedor/guias/ALCO2610300427/guia \
  -H "Authorization: Bearer $LLAVE" -H "Content-Type: application/json" \
  -d '{ "guia": "RG-558120" }'

{ "ok": true, "folio": "ALCO2610300427", "guia": "RG-558120", "estado": "recoleccion", "etiqueta": false }

Si la mandas otra vez con un número distinto, se corrige. No se acepta en envíos cancelados (409).

POST/guias/{folio o guía}/eventos

Informa un movimiento del envío. Se agrega al historial y se ve de inmediato en el rastreo del cliente.

curl -X POST https://alco-envios.web.app/api/v1/proveedor/guias/ALCO2610300427/eventos \
  -H "Authorization: Bearer $LLAVE" -H "Content-Type: application/json" \
  -d '{ "estado": "transito", "guia": "RG-558120", "descripcion": "Salió de Torreón rumbo a Monterrey" }'

{ "ok": true, "folio": "ALCO2610300427", "guia": "RG-558120", "estado": "transito" }

No se aceptan eventos en guías canceladas o ya entregadas (responde 409).

POST/guias/{folio o guía}/recepcion

Lo que pesaste y mediste al recibir el envío, y lo que vas a cobrar. ALCO lo usa para conciliar contra tu factura; no cambia nada de lo que ve el cliente.

curl -X POST https://alco-envios.web.app/api/v1/proveedor/guias/ALCO2610300427/recepcion \
  -H "Authorization: Bearer $LLAVE" -H "Content-Type: application/json" \
  -d '{ "paquetes": [{ "peso": 26, "largo": 120, "ancho": 100, "alto": 110 }], "costo": 462.44 }'

{ "ok": true, "folio": "ALCO2610300427", "costoConvenio": 420.41, "costoProveedor": 462.44, "diferencia": 42.03 }

Errores

Cuando algo falla, la respuesta trae { "ok": false, "error": "…" } con el motivo en español.

Soporte

Dudas sobre la integración: WhatsApp o teléfono 871 727 2781.