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. Para el cargador, gratis: además puede registrar todos sus albaranes para que le avisemos de los que se quedan sin DeCA.

REST + JSON

Base: https://app.portelisto.com/api/v1

Clave por empresa

Solo ve y toca los datos de esa empresa (o de ese cargador).

OpenAPI 3.1

openapi.json

NUEVO · v1.4Cruce de albaranes para cargadores. Tu programa nos manda todos tus albaranes y te avisamos, por sede, de los que se quedan sin DeCA o CMR de tu transportista. Sin emitir nada y sin coste. Cómo se hace ›

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.

Para registrar tus albaranes y cruzarlos con los DeCA (/shipper-notes) no hace falta la conexión: basta con que tu transportista trabaje contigo en PorteListo. Si la integración la hace tu informático o la empresa que te lleva el programa, también podemos crearle la clave nosotros: escríbenos a info@portelisto.com.

Envíala en cada petición:

Authorization: Bearer pl_live_TU_CLAVE

2. Operaciones

GET /decas · read
Lista de DeCA por fechas, estado o nº de albarán
POST /decas · write
Crea y emite un DeCA (PDF con QR) y lo envía al conductor por WhatsApp
GET /decas/{id o número} · read
Un DeCA, con su enlace al PDF y el estado del WhatsApp
POST /decas/{id o número}/cancel · write
Anula un DeCA emitido
POST /delivery-notes · write
Envía un albarán (PDF o fotos): se lee solo y queda en «Pendientes»
GET /drivers · read
Conductores activos (para indicar el conductor). No disponible con clave de cargador
GET /vehicles · read
Camiones y remolques activos. No disponible con clave de cargador
POST /cmrs · write
Crea un CMR (porte internacional) listo para imprimir y firmar. Plan Completo del transportista
GET /cmrs · /cmrs/{id o número} · read
Lista de CMR o uno concreto, con su PDF
POST /cmrs/{id o número}/cancel · write
Anula un CMR
GET /worksites · read
Obras con su cliente y ubicación. No disponible con clave de cargador
PATCH /worksites/{id o código} · write
Guarda la ubicación de una obra (p. ej. desde tu telemática). No disponible con clave de cargador
GET /load-sites · read
Lugares de carga con su ubicación. No disponible con clave de cargador
POST /shipper-notes · write
(Cargador) Registra los albaranes de tu programa (uno o hasta 200): PorteListo te avisa de los que se quedan sin DeCA/CMR
GET /shipper-notes · /shipper-notes/{número} · read
(Cargador) Tus albaranes con su estado: cubierto, esperando, sin_deca o eliminado
DELETE /shipper-notes/{número} · write
(Cargador) Albarán anulado en tu programa: deja de esperarse su DeCA
GET /carriers · read
(Cargador) Tus transportistas y si están conectados
POST /connections · write
(Cargador) Pedir la conexión a un transportista, o invitarle si no está en PorteListo

Método	Ruta	Qué hace	Permiso
GET	/decas	Lista de DeCA por fechas, estado o nº de albarán	read
POST	/decas	Crea y emite un DeCA (PDF con QR) y lo envía al conductor por WhatsApp	write
GET	/decas/{id o número}	Un DeCA, con su enlace al PDF y el estado del WhatsApp	read
POST	/decas/{id o número}/cancel	Anula un DeCA emitido	write
POST	/delivery-notes	Envía un albarán (PDF o fotos): se lee solo y queda en «Pendientes»	write
GET	/drivers	Conductores activos (para indicar el conductor). No disponible con clave de cargador	read
GET	/vehicles	Camiones y remolques activos. No disponible con clave de cargador	read
POST	/cmrs	Crea un CMR (porte internacional) listo para imprimir y firmar. Plan Completo del transportista	write
GET	/cmrs · /cmrs/{id o número}	Lista de CMR o uno concreto, con su PDF	read
POST	/cmrs/{id o número}/cancel	Anula un CMR	write
GET	/worksites	Obras con su cliente y ubicación. No disponible con clave de cargador	read
PATCH	/worksites/{id o código}	Guarda la ubicación de una obra (p. ej. desde tu telemática). No disponible con clave de cargador	write
GET	/load-sites	Lugares de carga con su ubicación. No disponible con clave de cargador	read
POST	/shipper-notes	(Cargador) Registra los albaranes de tu programa (uno o hasta 200): PorteListo te avisa de los que se quedan sin DeCA/CMR	write
GET	/shipper-notes · /shipper-notes/{número}	(Cargador) Tus albaranes con su estado: cubierto, esperando, sin_deca o eliminado	read
DELETE	/shipper-notes/{número}	(Cargador) Albarán anulado en tu programa: deja de esperarse su DeCA	write
GET	/carriers	(Cargador) Tus transportistas y si están conectados	read
POST	/connections	(Cargador) Pedir la conexión a un transportista, o invitarle si no está en PorteListo	write

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" }.

Cargador: que te avisemos de los albaranes sin DeCA

El DeCA lo hace tu transportista (a veces el propio conductor en una tablet del muelle), pero tú eres corresponsable. Si tu programa nos manda todos tus albaranes al emitirlos, PorteListo los cruza por su número con los DeCA y CMR de tu transportista y en tu portal ves, por sede, cuáles se han quedado sin DeCA. No emite nada: es solo la lista para comprobar. No hace falta la conexión de pago con el transportista: basta con que trabaje contigo en PorteListo.

curl -X POST https://app.portelisto.com/api/v1/shipper-notes \
  -H "Authorization: Bearer pl_live_TU_CLAVE_DE_CARGADOR" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "568482",
    "issued_at": "2026-09-29T08:15:00+02:00",
    "site": "Huarte",
    "destination": "Obra Calle Mayor 12, Pamplona",
    "client": "Construcciones Ejemplo SL",
    "carrier_nif": "B00000000",
    "transport_company_name": "Transportes Ejemplo SL",
    "transport_company_nif": "B00000000",
    "tractor_plate": "1234BCD",
    "trailer_plate": "R5678BCD"
  }'

Campo	¿Hace falta?	Para qué
number	Obligatorio	El nº impreso en el albarán: es con lo que se cruza con el DeCA.
issued_at	Muy recomendable	Fecha y hora del albarán (sin zona horaria, hora de España). Sin él, la hora a la que nos llega la primera vez. De ahí salen las 6 horas de «esperando».
site	Muy recomendable	Sede o centro de carga (p. ej. «Huarte»): en tu portal cada sede es una pestaña.
goods · weight_kg	Recomendado	Mercancía (líneas separadas por «; ») y peso total en kg: el DeCA puede salir con los datos exactos de tu programa en vez de leerlos de la foto.
destination · client	Recomendado	Obra y dirección de descarga, y cliente: para el DeCA y para reconocer el albarán en la lista.
destination_country · client_address · client_nif · packages · worksite_code	Recomendado	País de descarga (ISO-2), dirección y NIF/VAT del cliente, bultos y código de obra: con ellos el transportista emite también el CMR sin leer la foto del albarán.
origin	Opcional	Dirección de carga, si no es la de la sede.
carrier_nif	Recomendado	El NIF del transportista que lo lleva. Si trabajas con uno solo en PorteListo, se pone él; si hay varios y no lo indicas, el albarán no le llega a ninguno (sale un aviso en la respuesta).
transport_company_name · transport_company_nif	Recomendado	Lo que imprime el albarán en «Transportista»: quién pone el camión. Si tu transportista subcontrata el viaje a un autónomo o agencia, es ese; así su DeCA sale con el transportista efectivo correcto.
tractor_plate · trailer_plate	Recomendado	Matrículas del camión o tractora y del remolque, tal como se teclean. Si llegan, el DeCA usa estas en vez de leerlas de la foto del albarán.

Para varios a la vez: { "notes": [ { … }, { … } ] } (hasta 200). Si mandas otra vez el mismo número, se actualiza, no se duplica; un campo que no mandes o mandes vacío conserva lo que ya tenía. La respuesta es siempre 200 y trae los que no se han podido guardar en errors (con su posición) y los avisos en warnings; revisa errors aunque sea 200. Trae el status de cada uno: cubierto (ya tiene DeCA o CMR, en document), esperando (menos de 6 horas desde el albarán: puede hacerse antes de que salga el camión), sin_deca o eliminado. Si un DeCA del mismo día tiene el número casi igual (una cifra mal leída en la foto), sale en possible_match para confirmarlo en el portal.

Consulta el estado con GET /shipper-notes?from=2026-09-29&to=2026-09-29&status=sin_deca. Si anulas un albarán en tu programa, avísanos con DELETE /shipper-notes/568482 (el número tal cual, también con barras: /shipper-notes/AV/568482); si luego lo vuelves a mandar, vuelve a contar. El país (destination_country) va en dos letras (ES, FR, PT); otro formato se ignora. En el portal puedes quitar a mano uno que no toca (otro transportista, un error).

Qué ves en tu portal: en cada pestaña de sede, «Albaranes de tu programa» con el recuento y, arriba, los que faltan en rojo. Los de «número casi igual» salen aparte, en ámbar, con el botón «Sí, es ese» para confirmarlo. Cada albarán se puede quitar con su motivo (lo lleva otro transportista o el cliente, es un error, se anuló) y recuperar después. Tu transportista ve los mismos avisos en su pantalla de «Hoy» para arreglarlo a tiempo.

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 /decas y POST /cmrs. 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. En POST /shipper-notes no hace falta (y se ignora): el mismo número siempre actualiza el mismo albarán.

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, más de 3.000 albaranes nuevos al día por cargador, o más de 20 claves no válidas por minuto desde la misma dirección IP (se bloquea 10 minutos)
400 el cuerpo no es JSON válido o pasa de 2 MB

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. Descarga el plugin gratis en la tienda de FacturaScripts (qué hace y cómo se instala) y súbelo en Administrador → Plugins de tu 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.