Para desarrolladores

API de PorteListo

Conecta tu programa de gestión (ERP, facturación, gestión de flota) con PorteListo para crear y emitir DeCA, consultarlos, anularlos o enviar albaranes sin pasar por el panel. Incluida en los planes Completo y Empresa.

1. Consigue tu clave

El responsable de la empresa la crea en el panel: Ajustes → API para tu programa de gestión. Elige si puede solo leer o también crear y anular. La clave (pl_live_…) se muestra una sola vez: guárdala como una contraseña. Si se filtra, revócala y crea otra.

¿Eres el cargador? Tu clave es gratis: créala en cargador.portelisto.com/programa (tu empresa tiene que estar verificada) y pide la conexión a cada transportista. En cada POST indica el transportista con carrier_nif: solo se acepta si ese transportista tiene la conexión activa (va incluida en su plan Completo). Con tu clave emites y consultas tus DeCA y envías albaranes; no ves conductores ni vehículos: el conductor es el habitual de ese camión en PorteListo.

Envíala en cada petición:

Authorization: Bearer pl_live_TU_CLAVE

2. Operaciones

3. Crear y emitir un DeCA

Con los datos del porte, PorteListo crea el DeCA, genera el PDF con su QR y lo envía por WhatsApp al conductor. El conductor se indica con driver_id (de GET /drivers) o con driver_phone. Al emitir por API, tu programa es el que revisa los datos: lo que envíes es lo que se emite.

curl -X POST https://app.portelisto.com/api/v1/decas \
  -H "Authorization: Bearer pl_live_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ALB-10231" \
  -d '{
    "service_date": "2026-10-07",
    "shipper": { "name": "Cargador Ejemplo, S.L.", "nif": "B12345678", "address": "Pol. Ind. Ejemplo, calle A, 1, 00000 Ejemplo" },
    "tractor_plate": "1234BCD",
    "trailer_plate": "R5678BCD",
    "driver_phone": "600000000",
    "shipments": [{
      "origin": "Planta de Ejemplo, Pol. Ind. Ejemplo, 00000 Ejemplo",
      "destination": "Obra calle Mayor 10, Ejemplo",
      "goods": "Viguetas de hormigón",
      "weight_kg": 18450,
      "delivery_note_ref": "ALB-10231"
    }]
  }'

Respuesta 201:

{
  "data": {
    "id": "7b0c…",
    "number": "TEJ-2026-000128",
    "status": "emitido",
    "pdf_url": "https://d.portelisto.com/Xk3p9QvT2mLr8sWz4bNc7a",
    "shipper": { "name": "Cargador Ejemplo, S.L.", "nif": "B12345678", "address": "…" },
    "tractor_plate": "1234BCD",
    "driver": { "id": "…", "name": "Conductor de ejemplo" },
    "shipments": [{ "origin": "…", "destination": "…", "goods": "…", "weight_kg": 18450, "delivery_note_ref": "ALB-10231" }],
    "whatsapp": { "status": "enviado", "at": "2026-10-07T07:42:10Z" }
  },
  "whatsapp": "enviado"
}

Si el porte va fuera de España no lleva DeCA sino CMR: POST /decas responde 422 y tienes que crear el CMR (apartado siguiente).

CMR para portes internacionales

Con POST /cmrs PorteListo genera la carta de porte CMR rellena, con sus 24 casillas, en PDF listo para imprimir los 3 ejemplares y firmarlos. Con clave de cargador indica carrier_nif: el remitente eres tú. El transportista necesita el plan Completo.

curl -X POST https://app.portelisto.com/api/v1/cmrs \
  -H "Authorization: Bearer pl_live_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ALB-10240" \
  -d '{
    "sender": { "name": "Cargador Ejemplo, S.L.", "nif": "B12345678", "address": "Pol. Ind. Ejemplo, calle A, 1, 00000 Ejemplo" },
    "consignee": { "name": "Client Exemple SARL", "nif": "FR57382743391", "address": "Zone Industrielle, 64100 Bayonne", "country": "FR" },
    "pickup": { "place": "Planta de Ejemplo, 00000 Ejemplo", "date": "2026-10-07" },
    "delivery": { "place": "Chantier Les Jardins, 64310 Ascain", "country": "FR" },
    "goods": "Viguetas pretensadas de hormigón",
    "packages": "18 paquetes",
    "weight_kg": 21400,
    "delivery_note_ref": "ALB-10240",
    "tractor_plate": "1234BCD",
    "trailer_plate": "R5678BCD"
  }'

La respuesta 201 trae el número y pdf_url. Consulta con GET /cmrs (por fecha de carga) y anula con POST /cmrs/{id o número}/cancel.

4. Enviar un albarán para que lo revise la oficina

Si prefieres que la oficina revise antes de emitir, envía el albarán (PDF o fotos, hasta 8 archivos y 10 MB). Se lee solo y aparece en Pendientes del panel, como un albarán recibido por email. Sirve también para el programa de tu cargador.

curl -X POST https://app.portelisto.com/api/v1/delivery-notes \
  -H "Authorization: Bearer pl_live_TU_CLAVE" \
  -F "reference=ALB-10231" \
  -F "file=@albaran-10231.pdf"

También admite JSON: { "files": [{ "filename": "alb.pdf", "content_base64": "…" }], "reference": "ALB-10231" }.

5. Consultar y anular

curl "https://app.portelisto.com/api/v1/decas?from=2026-10-01&to=2026-10-07&status=emitido" \
  -H "Authorization: Bearer pl_live_TU_CLAVE"

Parámetros de la lista: from, to (fecha del servicio, YYYY-MM-DD; por defecto los últimos 30 días), status, delivery_note_ref, limit (máx. 200) y offset. También plate (matrícula de la tractora o del remolque, con o sin espacios ni guiones), worksite (código o id de la obra) y los de sincronización del apartado siguiente.

curl -X POST https://app.portelisto.com/api/v1/decas/TEJ-2026-000128/cancel \
  -H "Authorization: Bearer pl_live_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Porte cancelado por el cliente" }'

Sincronizar con tu programa o tu telemática

Para tener una copia al día sin descargarlo todo cada vez, pide los DeCA cambiados en orden y guarda el cursor. Con changed_since (fecha ISO 8601) recibes los creados, emitidos, modificados o anulados después de esa fecha, sin el límite de 30 días. Con order=changed_asc la respuesta trae next_cursor: guárdalo y úsalo en la siguiente petición (cada 60 s, por ejemplo). Si viene null, ya estás al día: repite con el último cursor que tengas. Así no se salta ni se repite ningún DeCA.

# 1ª vez: todo lo cambiado desde una fecha
curl "https://app.portelisto.com/api/v1/decas?changed_since=2026-10-01T00:00:00Z&order=changed_asc&limit=200" \
  -H "Authorization: Bearer pl_live_TU_CLAVE"

# Cada 60 s: sigue desde el último next_cursor guardado
curl "https://app.portelisto.com/api/v1/decas?order=changed_asc&limit=200&cursor=MjAyNi0xMC0wN1Qw…" \
  -H "Authorization: Bearer pl_live_TU_CLAVE"

{
  "data": [{
    "number": "TEJ-2026-000128", "status": "emitido", "changed_at": "2026-10-07T07:42:10.123456+00:00",
    "tractor_plate": "1234BCD", "trailer_plate": "R5678BCD",
    "service_start_at": null, "service_end_at": null,
    "worksite": { "id": "…", "code": "202115", "name": "Obra de ejemplo", "address": "…",
      "client": { "name": "Cliente Ejemplo, S.L.", "nif": "B87654321" },
      "location": { "lat": 43.1, "lon": -1.6, "source": "telematica", "updated_at": "…" } }
  }],
  "total": 1, "limit": 200, "offset": 0, "next_cursor": null
}

Cada DeCA trae changed_at, la worksite (obra, con su cliente y ubicación si la tiene) y service_start_at/service_end_at. Para cruzarlo con tu telemática, usa la matrícula (plate) y la ubicación de la obra. Los envíos por WhatsApp o la regeneración del PDF no cuentan como cambio.

Si tu telemática sabe dónde está cada obra, guárdalo con PATCH /worksites/{id o código}. Una ubicación puesta a mano en el panel no se sobrescribe salvo que envíes "force": true (si no, 409).

curl -X PATCH https://app.portelisto.com/api/v1/worksites/202115 \
  -H "Authorization: Bearer pl_live_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{ "location": { "lat": 43.1, "lon": -1.6, "source": "telematica", "radius_m": 150 } }'

6. Reintentos sin duplicados

Añade la cabecera Idempotency-Key (por ejemplo, tu nº de albarán) en POST. Si la petición se repite —por un corte de red o un reintento—, recibes la misma respuesta y no se crea un segundo DeCA.

7. Errores y límites

Los errores devuelven un código HTTP y un mensaje en español:

{ "error": { "code": "validation", "message": "Falta: NIF del cargador." } }

• 401 clave no válida o revocada · 403 sin permiso o plan sin API
• 404 no existe en tu empresa · 409 estado que no lo permite
• 422 datos incompletos o incorrectos (el mensaje dice qué falta)
• 429 más de 120 peticiones por minuto por clave, o más de 20 claves no válidas por minuto desde la misma dirección IP (se bloquea 10 minutos)

8. Datos personales

Los DeCA contienen datos de conductores. Usa la clave solo en tu servidor (nunca en una web o app pública), con HTTPS, y guarda solo lo que necesites. PorteListo actúa como encargado del tratamiento según el contrato de servicio.

9. Plugin para FacturaScripts

Si usas FacturaScripts (2025 o posterior), no hace falta programar: instala el plugin PorteListo, pega tu clave en Administrador → Conexiones PorteListo y en cada albarán de cliente tendrás una pestaña PorteListo. Como cargador eliges el transportista y emites el DeCA (y si no está conectado, se lo pides desde ahí); como transportista eliges además el conductor. Si el destino está fuera de España, la misma pestaña crea el CMR listo para imprimir y firmar. También puedes enviar el albarán a revisar, ver si el conductor lo ha recibido y anular. Descárgalo gratis en la tienda de plugins de FacturaScripts.

¿Vas a integrar otro programa (Dolibarr, Odoo u otro)? Escríbenos a info@portelisto.com y te ayudamos. Si eres cargador, mira también cómo emitir el DeCA desde tu programa de albaranes.