← MADeCa Manual de usuario · Versión 0.4.4

MADeCa

Plataforma para emitir, custodiar y servir a la inspección el Documento Electrónico de Control Administrativo (DeCA) del transporte de mercancías por carretera, con obtención de datos desde documentos, nubes, NAS y ERP.

1. Introducción y propósito

Desde el 5 de octubre de 2026 el documento de control administrativo del transporte público de mercancías por carretera es obligatoriamente digital (disposición transitoria octava de la Ley 9/2025, de Movilidad Sostenible). La Resolución de 5 de junio de 2026 de la Dirección General de Transporte por Carretera y Ferrocarril (BOE-A-2026-12784) fija cómo debe ser: un PDF nativo digital de hasta 5 MB, con un código QR que lleva a una URL https desde la que los agentes descargan el documento sin usuario ni contraseña, conservado al menos un año.

MADeCa resuelve todo ese ciclo para varias empresas a la vez (multiempresa): recibe los datos o el PDF de cada expedición, emite el DeCA, lo sirve en su URL pública, permite modificarlo durante el servicio, entrega la copia al conductor y a la otra parte, y lo conserva. Además obtiene los datos automáticamente de albaranes y cartas de porte (PDF, escaneo o foto), de carpetas en la nube o en un NAS y de los principales ERP, siempre con revisión humana antes de emitir.

MADeCa no sustituye la responsabilidad del cargador ni del transportista sobre los datos del documento (Art. 7 de la Orden FOM/2861/2012). Ver Aviso legal.

2. Características principales

📄
Dos caminos de emisiónPDF propio del ERP con QR estampado, o PDF redactado por MADeCa a partir de los datos.
🔍
Validación del Art. 6NIF/CIF con dígito de control, matrículas (actual, antigua, remolque, extranjeras en cabotaje), peso o magnitud.
🔗
QR y URL públicaDescarga directa sin credenciales ni límites para la inspección; desactivable 7 días después del servicio.
✏️
Modificación en rutaMétodo 1 del Apartado Quinto: misma URL y QR, datos anteriores marcados como no válidos.
🚚
Copia al conductor y a la otra partePDF y QR descargables; enlace privado de un año para cargador o transportista.
📝
Bandeja de revisiónLo obtenido de documentos o ERP se revisa junto al original antes de emitir; cada dato que falta enlaza a su campo y se señala en el documento dónde se leyó cada uno.
📋
Agenda de partesAl escribir un nombre o NIF se ofrecen cargadores, transportistas y destinatarios de DeCA anteriores.
📊
Inicio y avisosResumen del día y avisos de certificados por caducar, borradores atascados y fuentes con error; también por correo.
🕓
HistorialQuién emitió, modificó o finalizó cada expedición y cuándo.
📥
Exportar a ExcelLibro .xlsx de las expediciones que se ven en la lista, con sus filtros y totales.
📈
Historial y estadísticasSolo administradores: todo lo gestionado por día, semana, mes, trimestre, año o fechas a elegir, con desgloses que filtran al pulsarlos y Excel completo.
👁
Lectura de documentosTexto del PDF u OCR (Tesseract en el servidor; Azure solo con autorización).
☁️
Fuentes automáticasSharePoint/OneDrive, Google Drive, Dropbox, SFTP, carpeta del servidor, Business Central, Odoo, SAP Business One, Holded.
🏢
Conector localExtrae en la red del cliente y solo envía datos: los documentos no salen de su red.
🔑
Firma AdES opcionalCon el certificado .p12 de la empresa (guardado cifrado) cuando el DeCA tiene finalidad contractual.
👥
Multiempresa y rolesCada empresa ve solo lo suyo; roles administrador, operador y lectura; panel de operador aparte.
🛡️
SeguridadCredenciales cifradas, protección SSRF, sesiones revocables, claves fuertes obligatorias, cabeceras de seguridad.

3. Base legal y cómo se cumple

Normas comprobadas en el BOE y en EUR-Lex el 09/10/2026.

NormaExigenciaCómo lo cumple MADeCa
Ley 9/2025, DT 8.ªDeCA obligatoriamente digital desde el 05/10/2026.Todo el sistema.
Orden FOM/2861/2012, art. 6Datos esenciales a) a h).Validados en el camino de generación y en la bandeja (domicilio del cargador obligatorio, autorización especial de circulación cuando proceda).
Orden FOM/2861/2012, art. 7 (Orden TRM/282/2026)El cargador responde de a)–d) y h) propios; el transportista de e)–g) y h) propios.Nada obtenido automáticamente se emite sin revisión humana (bandeja).
Orden FOM/2861/2012, art. 9Conservación de al menos un año.RETENTION_DAYS=365; la purga es manual y no actúa antes.
Resolución BOE-A-2026-12784, PrimeroGenerar antes del servicio, registrar fecha y hora de creación y de cada modificación; URL única por fichero.Fecha de emisión y modificaciones registradas; un UUID por expedición.
Segundo.1PDF de hasta 5 MB; fechas de creación y modificación como metadatos.Límite de 5 MB en cada paso; /CreationDate y /ModDate en el PDF.
Segundo.2Nativo digital; no vale un escaneo.El camino 1 rechaza PDF que parecen escaneos; los escaneos solo sirven para extraer datos y generar un DeCA nativo.
Segundo.3QR con la URL en el PDF; puede ir también como fichero aparte.QR estampado o impreso; descarga del QR en PNG.
Segundo.4Ambas partes conservan un año; a la que no genera le basta con poder descargarlo.Enlace privado para la otra parte durante el plazo de conservación.
Tercero.1–4HTTPS (TLS 1.2+), sin credenciales, descarga directa, las medidas de seguridad no pueden impedirla./inspect/{id} sin login ni límite de peticiones; fuera de desarrollo MADeCa no arranca si APP_BASE_URL no es https. La lectura de escaneos no puede bloquear el visor (límite de tiempo por página).
Tercero.5La descarga puede desactivarse 7 días después del fin del servicio.PUBLIC_URL_DEACTIVATION_DAYS=7 desde «entregado» o «anulado»; el documento se sigue conservando.
CuartoFirma solo si hay finalidad contractual; como mínimo AdES.Firma PAdES-B con el certificado de la empresa; no firma con certificados caducados.
QuintoModificación durante el servicio (método 1 o 2) y entrega al conductor.Método 1 implementado; aviso de entrega al conductor.
SéptimoCopia para el conductor antes del servicio, electrónica o impresa, con QR.Descarga del PDF vigente y del QR (panel y API).
OctavoSe pueden usar otros documentos (carta de porte, ADR…) si contienen los datos del art. 6.Camino 1 (PDF propio); MADeCa no valida su contenido.
NovenoCon eFTI (Reglamento UE 2020/1056) no hace falta el DeCA en esta forma.No implementado (eFTI se aplica en pleno a partir del 09/07/2027).
RGPD art. 5 y 28Minimización, plazo de conservación, encargados y subencargados.Documentos originales borrados al resolver el borrador; IP de consultas borradas con la expedición; Azure solo con autorización expresa registrada.

4. Requisitos del sistema

ComponenteRequisitoNotas
ServidorDocker y Docker ComposeRecomendado. La imagen incluye Python 3.12, WeasyPrint (Pango/Cairo) y Tesseract con español.
Base de datosPostgreSQL 16Servicio db del compose. Mínimo PostgreSQL 13 (la migración usa gen_random_uuid()).
CachéRedis 7Límite de intentos de login compartido entre procesos.
PublicaciónDominio con HTTPS (TLS 1.2+) delante (nginx, traefik…)Obligatorio en producción (Apartado Tercero.1).
Sin DockerPython 3.12+, pip install -r requirements.txt, PostgreSQL y Redis accesiblesEn Windows, el PDF generado (WeasyPrint) necesita GTK; el resto funciona.
Conector localWindows con Python 3.12+; Tesseract si hay escaneosVer 12.
NavegadorCualquiera actualhtmx y unos pocos scripts propios (filtros, formulario, bandeja), servidos desde MADeCa; sin JavaScript en línea.
Correo (opcional)Servidor SMTPPara los avisos diarios a los administradores (SMTP_*, ver 13).
Excelopenpyxl (incluido en requirements.txt)Para exportar a .xlsx las Expediciones y el Historial.
Posiciones en PDF con texto (opcional)pypdfium2 (incluido en requirements.txt)Sin él, la revisión muestra esos PDF como siempre, sin señalar dónde se leyó cada dato.

5. Instalación y puesta en marcha

Configurar .env
docker compose up -d --build
alembic upgrade head
Crear operador
Alta de empresas
Copy-Item .env.example .env
# Edita .env: APP_ENV, APP_BASE_URL (https://...), APP_SECRET_KEY y JWT_SECRET_KEY (distintas, 32+ caracteres)
docker compose up -d --build
docker compose exec app alembic upgrade head
docker compose exec app python -m scripts.crear_superadmin --email operador@tudominio.es --password "una-clave-fuerte"

Servicios del docker-compose

ServicioFunción
dbPostgreSQL. Solo accesible desde la propia máquina (127.0.0.1:5432).
redisRedis. Solo accesible desde la propia máquina (127.0.0.1:6379).
appAplicación web (paneles, API, visor público) en el puerto 8000.
hotfolder-watcherVigila hotfolder_watch/incoming y emite los DeCA de lo que llegue.
conectoresLee periódicamente las fuentes de datos y deja lo nuevo en la bandeja.

Scripts de administración

ScriptParámetrosQué hace
scripts.crear_superadmin--email obligatorio --password obligatorioCrea el operador de la plataforma (acceso a /superadmin).
scripts.crear_tenant--nombre --nif --email --password todosAlta de una empresa y su primer administrador sin pasar por el panel.
scripts.cargar_demo--con-operador opcional --nuevas-claves opcionalEmpresa de demostración con un usuario por rol y clave de API. Se niega con APP_ENV=production.
scripts.purgar_expirados--confirmar opcionalSin parámetro, lista lo que se podría purgar (más antiguo que RETENTION_DAYS). Con --confirmar lo borra: expedición, consultas, modificaciones, borradores emitidos y PDF.

5.1 Paquete de instalación para clientes

Para instalar MADeCa en el servidor de un cliente hay un paquete en blanco (sin empresas, usuarios ni DeCA) que se instala con una sola orden y lleva el código compilado: la aplicación con Nuitka y las migraciones en bytecode, sin ningún .py. Se instala en cualquier entorno: cualquier Linux x86_64 (servidor propio, máquina virtual o VPS), Windows 10/11/Server con WSL2 (INSTALAR_EN_WINDOWS.bat, sin Docker Desktop) y sin internet (trae Docker, iptables, PostgreSQL, Redis y Caddy). El acceso puede ser con dominio público y Let's Encrypt, con certificado propio, detrás de un proxy HTTPS de la empresa o de prueba en la red local. El detalle, con capturas, está en paquete/GUIA_INSTALACION_MADeCa.html, que va dentro del paquete.

docker build -f Dockerfile.paquete
paquete/construir_paquete.sh
INSTALL/
sudo ./madeca.sh instalar
# En el equipo de Masoft.es, desde la raíz del proyecto (con Docker e internet):
docker build -f Dockerfile.paquete -t madeca:0.4.4 .
bash paquete/construir_paquete.sh          # deja INSTALL/ (Linux, Windows y sin internet)
# Linux (cualquier distribución x86_64, física, virtual o VPS):
tar xzf madeca-0.4.4.tar.gz && cd madeca-0.4.4
sudo ./madeca.sh instalar                     # pregunta el acceso: publico, propio, proxy o prueba
# Windows 10 (2004+), 11 o Server 2022/2025: doble clic en INSTALL\INSTALAR_EN_WINDOWS.bat (WSL2)
FicheroQué es
Dockerfile.paqueteImagen sin código fuente. Se comprueba al construirla: ni un .py en la imagen.
app/instalacion.pyÓrdenes de consola que usa madeca.sh: alta, clave, superadmin y estado. Las contraseñas se generan en el servidor y se muestran una vez (nunca por la línea de órdenes).
paquete/madeca.shInstalar, actualizar, estado, alta, clave, superadmin, certificado, copia, restaurar, parar/arrancar/reiniciar, registros y desinstalar. Accesos publico, propio, proxy y prueba; --sin-internet; puertos a elegir.
paquete/windows/madeca_windows.ps1, paquete/INSTALAR_EN_WINDOWS.batWindows: activa WSL2, crea la Ubuntu «MADeCa» desde el paquete, lanza madeca.sh, reenvía los puertos a la red, abre el cortafuegos y deja la tarea de arranque con el equipo (sin iniciar sesión).
paquete/herramientas/iptables.DockerfileCompila iptables estático (nf_tables) para los sistemas sin internet que no lo traen.
paquete/docker-compose.yml, Caddyfile, Caddyfile.propio, Caddyfile.pruebaServicios en /opt/madeca; solo Caddy publica los puertos (80 y 443 o los elegidos), con HTTPS de Let's Encrypt, del certificado propio o interno (TLS 1.2 o superior, Apartado Tercero.1). Con el acceso «proxy» no hay Caddy y el HTTPS lo pone el proxy de la empresa.
paquete/LICENCIA.txtLicencia MIT: software libre y gratuito.
En el paquete no van los scripts de scripts/ (demostración y purga de expedientes caducados): nada se borra solo, así que los DeCA se conservan más allá del año que exige el Apartado Segundo.4.

6. Roles y permisos

AcciónLecturaOperadorAdministrador
Ver expediciones, detalle, accesos, modificaciones✓✓✓
Descargar PDF y QR para el conductor✓✓✓
Crear expediciones (PDF propio, datos, lote)—✓✓
Modificar durante el servicio y marcar como entregado—✓✓
Ver la bandeja y revisar borradores✓ (sin formulario)✓✓
Subir documentos a la bandeja, emitir y descartar—✓✓
Ver integraciones y certificados✓✓✓
Crear y revocar claves de API; subir y desactivar certificados——✓
Fuentes de datos y autorización del OCR de Azure——✓
Usuarios de la empresa——✓

El rol se consulta en cada petición: un cambio de rol se aplica en la siguiente página que abra el usuario. El operador de plataforma (superadmin) es un acceso distinto, con su propia sesión, que no ve el contenido de las expediciones (ver 8).

7. Panel de empresa

7.1 Acceso y menú

Dirección: /login.

ElementoDescripción
Correo electrónico obligatorioCorreo del usuario (sin distinguir mayúsculas). Si el mismo correo existe en dos empresas, se entra en la cuenta cuya contraseña coincida.
Contraseña obligatorioAl crear un usuario, al menos 12 caracteres (y como máximo 72 bytes). 10 intentos de acceso por minuto y dirección IP.
Botón EntrarAbre el Inicio. Mensajes: «Credenciales incorrectas» o «Esta empresa está desactivada…».
Enlace Panel de operadorLleva a /superadmin/login.

La sesión dura JWT_EXPIRE_MINUTES (480 min por defecto). Menú superior:

OpciónVisible paraLleva a
InicioTodosResumen (abajo)
ExpedicionesTodos7.2
Bandeja de revisiónTodos7.5
Integraciones ERPTodos7.7
Fuentes de datosAdministrador7.6
CertificadosTodos7.8
HistorialAdministrador7.10
UsuariosAdministrador7.9
Cerrar sesiónTodosBorra la cookie de sesión y vuelve a /login.

La sección en la que estás aparece resaltada. Al pie de todas las páginas: «MADeCa - Desarrollado por Masoft.es».

Inicio (resumen)
ElementoDescripción
IndicadoresPendientes de revisar (y cuántos con datos que faltan), En tránsito (y cuántos con transporte hoy), Emitidos este mes y Entregados este mes. Cada uno abre la lista ya filtrada.
Necesita atenciónCertificado activo caducado (urgente) o que caduca en 30 días (aviso), borradores sin revisar desde hace más de 24 h (aviso) y fuentes de datos con error en su última lectura (urgente). Cada aviso lleva icono, texto y enlace. Sin avisos: «Todo en orden». El administrador ve si los avisos se envían también por correo.
Pendientes de revisar / Últimas expedicionesLos cinco más recientes de cada uno, con Revisar o Ver.

Avisos por correo: con SMTP_HOST configurado, los administradores activos de cada empresa reciben una vez al día (desde AVISOS_CORREO_HORA, hora local) un correo con los mismos avisos, solo si hay alguno. No incluye datos de las partes de los DeCA.

7.2 Expediciones

Lista todas las expediciones de la empresa en páginas de 100 (por defecto, las emitidas más recientes primero) e indica cuántas cumplen los filtros en total. Al pie, el paginador (‹ Anterior, números con «…» y Siguiente ›) y «101–200 de 656»: conserva filtros y orden, y al cambiar un filtro u orden se vuelve a la página 1. Botón + Nueva expedición (operador y administrador). Todo se aplica al momento, sin botón de buscar.

Buscar
Fecha
Más filtros
Mostrar estados
Fichas activas ✕
Barra de filtros
ElementoComportamiento
Buscar opcionalCuadro con lupa. Busca el texto (sin distinguir mayúsculas) en la referencia, la matrícula del vehículo o del remolque, el nombre o NIF del cargador, transportista o destinatario, el origen, el destino o la mercancía. Filtra mientras escribes. Los caracteres % y _ se buscan tal cual. Máximo 100 caracteres.
Fecha Cualquier fechaBotón con calendario que muestra el filtro elegido («Este mes», «01/10/2026 – 11/10/2026»…) y se resalta en azul cuando hay uno. Abre un panel con: Aplicar a la fecha de Transporte / Emisión / Entrega (fin del servicio; las no entregadas no tienen); Periodo: Cualquier fecha, Hoy, Últimos 7 días, Últimos 30 días, Este mes, Mes anterior, Este año; Entre fechas: Desde / Hasta (basta una de las dos; «Hasta» incluye el día entero). Al escribir una fecha se desmarca el periodo, y al elegir un periodo se vacían las fechas. Los días se cuentan en la hora de la instalación (ZONA_HORARIA), la misma de la tabla. Si «Desde» es posterior a «Hasta» se avisa y no se filtra por fecha.
Más filtros opcionalPanel con Matrícula (vehículo o remolque), Referencia externa, Firma electrónica (Todas / Firmadas / Sin firmar) y ERP de origen (solo los que tienen expediciones). El botón indica cuántos hay activos.
Mostrar los tres marcadosCasillas de color En tránsito, Entregados y Anulados, cada una con el número de expediciones de ese estado que cumplen los demás filtros. Desmarca Entregados para ocultar los entregados (igual con los otros dos). Si no queda ninguno marcado, la lista lo indica.
Fichas activasSobre la tabla, una ficha por filtro aplicado («frutas», «Transporte: Este mes», «Firmadas»…). Su ✕ quita solo ese filtro. Limpiar filtros los quita todos.
OrdenarPulsa la cabecera Referencia, Matrícula, Fecha transporte o Estado: un clic ordena, otro invierte y un tercero vuelve al orden por defecto. La flecha azul indica la columna y el sentido.
Panel desplegableSe cierra al pulsar fuera, con Esc o al abrir el otro.
Exportar a ExcelAdministrador y operador. Descarga un libro .xlsx con la hoja Resumen (filtros aplicados y totales por estado) y la hoja Expediciones (tabla de Excel con cabecera fija, filtros en cada columna, fechas y números con formato y fila de totales que se recalcula al filtrar), con las expediciones que cumplen los filtros —todas las páginas—, en el mismo orden, hasta 100.000: referencia, ERP, estado, fechas de transporte, emisión y entrega, matrículas, cargador, transportista y destinatario con sus NIF, origen, destino, mercancía, peso u otra magnitud, bultos, firma, URL pública y escaneos. Contiene datos personales: trátalo como tal.

Los filtros quedan en la dirección de la página: al recargar, volver atrás o guardar en favoritos se mantienen, y se pueden compartir con un compañero de la empresa. Solo cambian lo que se ve: no modifican ni borran ningún DeCA. Los enlaces antiguos con ?estado= u ?ocultar_entregados=1 siguen funcionando.

Columnas
ColumnaContenido
ReferenciaReferencia externa (nº de albarán del ERP).
ERPOrigen: generico, a3erp, sigrid, sap, dynamics365, odoo, sage.
MatrículaMatrícula del vehículo (tractora).
Fecha transporte / HoraFecha (DD/MM/AAAA) y hora peninsular del transporte, en columnas separadas.
EstadoEn tránsito, Entregado o Anulado.
URL públicaactiva o inactiva (anulada, desactivada o más de 7 días tras el fin del servicio).
Firmado«AdES» si se firmó; «—» si no.
EscaneosNúmero de consultas registradas (visor público y descargas de la otra parte).
VerAbre el detalle (7.4).

7.3 Nueva expedición

Tres pestañas: Subir PDF propio, Generar documento con MADeCa y Carga por lotes. Si hay un error, el formulario vuelve con lo escrito (salvo el fichero, que el navegador no permite recordar).

Subir PDF propio (camino 1)

El PDF lo genera el ERP o el programa de la empresa; MADeCa le añade el QR en la primera página sin tocar el resto, conserva su fecha de creación y fija la de modificación.

CampoDescripción
Fichero PDF obligatorioPDF nativo digital. Se rechaza si parece un escaneo (página sin texto que solo contiene una imagen) o si con el QR supera 5 MB.
Referencia obligatorioNº de albarán/factura, hasta 200 caracteres. No se puede repetir en la empresa (mismo ERP).
Matrícula del vehículo obligatorio1234BCD, M1234AB o R1234BCD; con país distinto de ES, alfanumérica de 2 a 12.
Matrícula del remolque opcionalObligatoria en la práctica en conjuntos articulados (Art. 6.g).
País de las matrículas ESDos casillas (vehículo y remolque), código de dos letras. Distinto de ES solo en cabotaje.
Fecha y hora del transporte obligatorioHora peninsular.
Finalidad contractual casillaSi se marca, se firma con AdES; exige un certificado activo y vigente.
Botón Crear expediciónEmite y abre el detalle.
Generar documento con MADeCa (camino 2)

MADeCa redacta el PDF con todos los datos del Art. 6. Es el mismo formulario que usa la bandeja de revisión.

BloqueCampoReglas
Referencia externa obligatorioHasta 200 caracteres, única en la empresa.
Cargador contractual (6.a)Nombre / razón social obligatorioHasta 300 caracteres.
NIF/CIF obligatorioNIF, NIE o CIF con dígito de control correcto.
Domicilio obligatorioHasta 500 caracteres.
Transportista efectivo (6.b)Nombre / razón social obligatorio
NIF/CIF obligatorioCon dígito de control.
DestinatarioNombre, NIF/CIF, Domicilio opcionalNo lo exige el Art. 6. Solo se imprime si se indican nombre y NIF.
Origen y destino (6.c)Lugar de origen obligatorioHasta 500 caracteres.
Lugar de destino obligatorioHasta 500 caracteres.
Mercancía (6.d)Naturaleza obligatorioHasta 500 caracteres.
Peso bruto (kg)Mayor que 0; admite coma decimal. Obligatorio salvo que se indique la magnitud alternativa.
Magnitud alternativaSolo si el peso exacto no es determinable por la forma de carga.
Bultos opcionalEntero ≥ 0.
ADR — nº ONU opcionalSi se indica, también la denominación.
ADR — denominación opcionalSi se indica, también el nº ONU.
Vehículo y fecha (6.e–g)Matrícula del vehículo obligatorioComo en el camino 1.
Matrícula del remolque opcional
País de las matrículas ESCabotaje.
Autorización especial de circulación opcionalSolo si el vehículo circula amparado por una (6.e). Hasta 100 caracteres.
Fecha y hora del transporte obligatorioHora peninsular.
6.hObservaciones opcionalHasta 2000 caracteres.
Finalidad contractual casillaFirma AdES.
Carga por lotes
CampoDescripción
Ficheros PDF obligatorioVarios PDF propios a la vez (camino 1).
Fichero de metadatos obligatorioCSV (UTF-8) o JSON con una fila por PDF. Columnas: archivo (nombre exacto del PDF), referencia_externa, matricula_vehiculo, matricula_remolque (opcional), fecha_transporte, finalidad_contractual (opcional, true/false), pais_matricula_vehiculo/pais_matricula_remolque (opcionales).

Resultado: «N de M expediciones creadas» y una tabla Fila / Fichero / Resultado con «creada» o «error» y el motivo; Ver abre cada una creada. Las filas con error no impiden las demás.

7.4 Detalle de la expedición

Estado y disponibilidad
ElementoDescripción
Estado / URL pública / FirmaEstado de la expedición, si la URL del QR está activa y si va firmada con AdES.
URL públicaLa que contiene el QR (/inspect/{id}).
Ver PDF públicoAbre el PDF como lo verá el agente (registra un acceso).
Descargar PDF para el conductorPDF vigente, con sus modificaciones (Apartado Séptimo).
Descargar QRPNG con el QR (fichero independiente permitido por el Segundo.3).
Marcar como entregadoSolo en tránsito (operador y administrador). Fija la fecha de fin del servicio: la URL podrá desactivarse 7 días después.
Enlace para la otra parteEnlace privado /descarga/{token} para el cargador o transportista que no emite; válido durante el plazo de conservación. No publicarlo.
Texto de servicio finalizadoFecha y hora del fin del servicio y recordatorio del plazo de 7 días.
Metadatos

Referencia externa, ERP de origen, Matrícula (vehículo / remolque), Fecha transporte, Hora transporte y Tamaño del PDF. En el camino 1 el contenido completo está en el propio PDF.

Modificaciones durante el servicio (Apartado Quinto, método 1)

Historial: N.º, Fecha, Hora, Motivo, Cambios (dato: anterior → nuevo) y Origen (panel con el correo de quien lo hizo, o api). Formulario visible solo con la expedición en tránsito y para operador o administrador:

CampoDescripción
Motivo de la modificación obligatorioDe 3 a 1000 caracteres. Se imprime en el PDF.
Dato 1 obligatorio, Dato 2 y Dato 3 opcionalesDesplegable: Matrícula del vehículo, Matrícula del remolque, Fecha del transporte (se actualizan también en MADeCa y se validan) u Otro dato (escribe su nombre en «Nombre del dato si es Otro»). Cada uno con Valor anterior y Valor nuevo (hasta 500 caracteres). La fecha nueva en formato AAAA-MM-DDTHH:MM.
Añadir modificación al DeCAAñade al final del PDF la página «MODIFICACIÓN N.º X» con fecha, hora, motivo y los valores anteriores marcados «NO VÁLIDO». Misma URL y QR. Guarda la versión anterior. Si estaba firmado, se vuelve a firmar. Aviso: entregar el PDF modificado al conductor.
Si con la página añadida el PDF superase 5 MB, la modificación se rechaza: emite entonces un DeCA nuevo (método 2 del Apartado Quinto) conservando el original.
Actividad

Línea de tiempo con cada paso: DeCA emitido, Modificado durante el servicio, Marcado como entregado o Anulado, con fecha, hora, quién (correo del usuario, «API», «Carpeta compartida») y el detalle (p. ej. «Bandeja de revisión: albaran.pdf» o el motivo de la modificación). En expediciones anteriores a la v0.3.0 se reconstruye con lo que constaba; si no se sabe quién fue, lo indica.

Registro de accesos (auditoría)

Columnas Fecha, Hora (con segundos), IP, Resultado (concedido, denegado_desactivado, contraparte) y User-Agent. Se borra junto con la expedición en la purga.

7.5 Bandeja de revisión

Documento o ERP
Lectura de datos
Borrador pendiente
Revisión humana
Emitir DeCA (camino 2)
ElementoDescripción
Aviso superiorRecuerda que nada se emite sin revisión e indica el OCR en uso: «en el servidor de MADeCa» o «Azure (autorizado por tu empresa)».
Subir documentosOperador y administrador. PDF, PNG, JPG, TIF, BMP, WEBP o TXT, varios a la vez, hasta DOCUMENTO_ORIGEN_MAX_BYTES (20 MB) cada uno. Botón Leer y añadir a la bandeja. Los no admitidos se indican en el aviso.
PestañasPendientes, Emitidos, Descartados, cada una con el número de borradores que cumplen los filtros. Al cambiar de pestaña los filtros se mantienen. Páginas de 100 con paginador, como en Expediciones.
ColumnasFecha, Hora de llegada; Documento (nombre o referencia de origen); Origen (Subido en el panel, API (documento), API (conector_local), Fuente: <nombre de la fuente>); Datos («Completo» en verde o «Faltan N» en ámbar); en Emitidos y Descartados, Resuelto (fecha, hora y usuario); en Emitidos, Expedición (su estado actual); Revisar (pendientes) o Ver expedición (emitidos).
Filtros de la bandeja (se aplican al momento)
ElementoComportamiento
Buscar opcionalBusca en el nombre del documento, su referencia de origen, el usuario que lo resolvió y los datos leídos (referencia, matrículas, cargador, transportista, destinatario y sus NIF, origen, destino, mercancía).
Origen Todos los orígenesDesplegable con los orígenes que tienen borradores, con el nombre de la fuente de datos.
Fecha Cualquier fechaMismo panel que en Expediciones. En Emitidos y Descartados se elige además si se aplica a la Recepción o a la Resolución.
Solo con datos que faltan apagadoInterruptor: muestra solo los borradores con algún aviso.
Ocultar entregados apagadoInterruptor que aparece solo en Emitidos: quita los borradores cuya expedición ya está entregada.
OrdenarCabeceras Recibido (por defecto, más recientes primero), Documento, Origen y Datos (primero los que tienen más avisos).
Fichas activasComo en Expediciones: ✕ quita ese filtro; Limpiar filtros los quita todos.
Varios pendientes a la vez

En Pendientes (operador y administrador), marca las casillas de las filas o la de la cabecera (todas). Aparece una barra con el número de seleccionados:

AcciónComportamiento
Emitir los completosPide marcar «He comprobado sus datos con los documentos originales» (el cargador responde de su exactitud, Art. 7.2). Solo emite los que tienen todos los datos obligatorios y válidos; el resto sigue pendiente y el aviso lo indica. Hasta 50 por vez.
✕ DescartarPide confirmar; los descarta y borra sus documentos originales.
Cancelar / Quitar selecciónVuelve atrás sin hacer nada.
Pantalla de revisión
ElementoDescripción
CabeceraVuelta a la bandeja y cuántos pendientes quedan.
Aviso de posible duplicadoSi ya hay una expedición con la misma referencia, con su fecha, estado y enlace.
Aviso de responsabilidadRecuerda qué datos responde cada parte (Art. 7).
Panel de comprobación«Faltan N de 11 datos obligatorios» (Art. 6: nombre, NIF y domicilio del cargador; nombre y NIF del transportista; origen; destino; naturaleza y peso —u otra magnitud, Art. 6.d—; fecha; matrícula). Cada dato que falta es un enlace: lleva al campo, lo enfoca y lo resalta, e indica el artículo y quién responde. Al rellenarlo se tacha con ✓ y el panel se pone verde cuando están todos. Debajo, Datos que no son válidos (tras intentar emitir). La autorización especial (6.e) y el remolque (6.g) no son siempre exigibles y no se marcan.
Campos en rojoObligatorio vacío o dato no válido, con el motivo debajo; vuelve a su color al corregirlo. Los datos leídos no se marcan.
Comprobación al escribirAl salir de un campo se comprueba con las mismas reglas que al emitir: NIF/CIF con dígito de control (también NIF-IVA de la UE en cabotaje), matrícula según el país, peso, bultos y fecha. La referencia avisa si ya existe.
Agenda de partesAl escribir 2 letras del nombre o del NIF de una parte se proponen las de DeCA anteriores de la empresa (una por NIF, las más usadas primero). Con el ratón o con ↑ ↓ e Intro rellena nombre, NIF y domicilio.
Documento originalA la izquierda, fijo a la vista al bajar por el formulario (solo mientras está pendiente), con el método de lectura y Abrir a tamaño real. Cuando se conocen las posiciones (escaneos y fotos leídos por OCR; PDF con texto si está pypdfium2), se muestra por páginas y al entrar en un campo su dato se recuadra en el documento y el visor se desplaza hasta él; al pulsar un recuadro se va a su campo. Ver dónde se leyó cada dato muestra todos los recuadros. Se localiza aunque esté escrito distinto (1.250,5 kg, R-5678-BBC, 10/10/2026).
Formulario de datosEl de 7.3, precargado, por secciones (cargador, transportista, destinatario, origen y destino, mercancía, vehículo y fecha, otros). Corrige lo necesario.
Emitir el DeCASi falta algo o hay un dato no válido no envía: lleva al primero. Valida (Art. 6) y emite por el camino 2. El borrador pasa a «emitido», queda enlazado a la expedición y el documento original se borra.
Emitir el DeCA y revisar el siguienteIgual, y abre el siguiente pendiente con el aviso de lo emitido (o vuelve a la bandeja si no quedan).
✕ Descartar este borrador / Descartar y revisar el siguienteLo pasa a «descartado» y borra el original.
Cómo se leen los documentos

Se buscan las etiquetas habituales de albaranes, cartas de porte y CMR (cargador, remitente, sender; transportista, carrier; destinatario, consignee; lugar de carga/entrega; mercancía; peso bruto; bultos; fecha de carga; matrícula; remolque; nº de albarán; autorización especial…). Los NIF/CIF solo se aceptan con su dígito de control; las matrículas con su formato; el peso admite «1.250,5 kg» o toneladas. Lo que no aparece queda vacío con su aviso: no se inventa nada.

7.6 Fuentes de datos

Solo administrador. MADeCa lee cada fuente activa cada N minutos (servicio conectores) y deja lo nuevo en la bandeja. Las credenciales se guardan cifradas y nunca se vuelven a mostrar; al editar, deja vacío un secreto para conservarlo.

Lista «Tus fuentes»
Columna / botónDescripción
NombreEnlace a la edición.
TipoTipo de fuente.
EstadoActiva o Pausada, y cada cuántos minutos se lee.
Última lectura / HoraFecha y hora de la última pasada.
Resultado«N nuevo(s) en la bandeja (M leído(s))» o el error en rojo.
ProbarComprueba credenciales y acceso sin traer nada.
Leer ahoraEjecuta una pasada inmediata.
Pausar / ActivarDetiene o reanuda la lectura periódica.
✕Elimina la fuente. Sus borradores siguen en la bandeja.
Campos comunes al crear o editar

Nombre de esta fuente obligatorio (hasta 150) y Leer cada (minutos) 15 (de 5 a 1440).

TipoCamposFuncionamiento
SharePoint / OneDriveId del inquilino de Microsoft; Id de la aplicación registrada en Entra ID; Secreto de la aplicación (secreto); Id de la unidad (biblioteca); Carpeta dentro de la unidad (p. ej. Albaranes/Pendientes).Microsoft Graph con permiso de aplicación Files.Read.All (el mínimo documentado). Lee los cambios de la unidad y toma los ficheros cuyo padre es esa carpeta (no entra en subcarpetas).
Google DriveJSON de la cuenta de servicio (secreto); Id de la carpeta (final de su URL).Comparte la carpeta con el correo de la cuenta de servicio. Ignora documentos nativos de Google.
DropboxApp key; App secret (secreto); Refresh token (secreto); Carpeta (p. ej. /Albaranes).App con permiso files.content.read.
SFTP (NAS / servidor)Servidor; Puerto (22); Usuario; Contraseña (secreto, opcional); Clave privada OpenSSH (secreto, opcional); Huella SHA256 del servidor obligatorio; Carpeta.Sin la huella correcta no conecta (evita suplantaciones). El NAS debe ser accesible desde internet; si no, usa el conector local.
Carpeta del servidorSubcarpeta (opcional).Solo instalaciones propias con FUENTES_CARPETA_BASE. Cada empresa solo ve <base>/<id_empresa>.
Business CentralId del inquilino; Id de la aplicación; Secreto (secreto); Entorno (production); Id de la empresa (GUID); Transportista habitual (nombre y NIF, opcionales).API v2.0: albaranes de venta registrados. Cargador y origen = empresa de BC; destino y destinatario = envío y cliente. No trae peso, matrícula ni hora: se avisa.
Odoo 19+ (API JSON-2)Dirección de Odoo (https); Base de datos (opcional); Clave de API (secreto); Transportista habitual.Entregas de salida preparadas o hechas. Fecha en UTC: revisar la hora.
SAP Business OneDirección del Service Layer (https); CompanyDB; Usuario; Contraseña (secreto); Correspondencia de campos (JSON); Cargador (nombre, NIF, domicilio) y Origen habitual; Transportista habitual.Entregas (DeliveryNotes), todas las páginas del Service Layer. La correspondencia de serie está por verificar con la instalación real (/b1s/v1/$metadata).
HoldedClave de API (secreto); Correspondencia de campos (JSON); Cargador y Origen habitual; Transportista habitual.Albaranes (waybill) de la API v1; relee los 2 días anteriores por si se crea un albarán con fecha pasada. Correspondencia por verificar con la cuenta real.

Correspondencia de campos (SAP y Holded): JSON {"campo_madeca": "campo_del_erp"}; los campos del ERP admiten rutas con puntos (Lineas.0.Peso). Campos de MADeCa: referencia_externa, cargador.nombre_razon_social, cargador.nif_cif, cargador.domicilio, transportista.nombre_razon_social, transportista.nif_cif, destinatario.nombre_razon_social, destinatario.nif_cif, destinatario.domicilio, origen_direccion, destino_direccion, mercancia.naturaleza, mercancia.peso_kg, mercancia.bultos, fecha_transporte, matricula_vehiculo, matricula_remolque, observaciones.

Lectura sin pérdidas: cada pasada lee hasta 50 documentos o albaranes y la siguiente sigue donde se quedó, aunque muchos compartan la misma hora (copias masivas al NAS, validaciones en lote). Lo ya leído no se duplica en la bandeja.

NIF de los ERP: si el ERP guarda el NIF-IVA (ESB00345678), MADeCa usa el NIF (B00345678). Los NIF extranjeros se dejan tal cual y se revisan en la bandeja.

Protección SSRF: las direcciones de Odoo, SAP y SFTP no pueden apuntar a redes privadas, a la propia máquina ni a direcciones de metadatos de la nube. Error: «apunta a una red privada… Usa el conector local». En instalaciones propias se puede permitir con FUENTES_PERMITIR_RED_PRIVADA=true.
OCR de documentos escaneados

Por defecto el OCR se hace en el servidor de MADeCa (Tesseract). Si el operador ha configurado Azure AI Document Intelligence, el administrador puede autorizarlo marcando «Autorizo a Microsoft (Azure, región UE) como subencargado del tratamiento…» y pulsando Autorizar OCR con Azure. Queda registrado quién y cuándo; Retirar la autorización vuelve al OCR del servidor. Sin Azure configurado se indica «Esta instalación no tiene Azure configurado».

7.7 Integraciones ERP (claves de API)

ElementoDescripción
Nombre descriptivo obligatorioP. ej. «a3ERP producción». Hasta 150 caracteres.
ERP de origenGenérico / integración a medida, a3ERP, Sigrid, SAP, Microsoft Dynamics 365, Odoo, Sage. Informativo.
Generar API keySolo administrador. La clave completa (mad_live_…) se muestra una sola vez en la propia página; en la base de datos solo se guarda su huella.
TablaNombre, ERP, Prefijo (inicio de la clave), Estado (activa/revocada), Último uso y Hora.
RevocarSolo administrador. Deja de funcionar al instante.

7.8 Certificados de firma

ElementoDescripción
Nombre descriptivo obligatorioP. ej. «Sello de empresa 2026».
Fichero .p12/.pfx obligatorioCertificado con su clave privada.
Contraseña del certificado obligatorioSe comprueba al subirlo; se guarda cifrada.
Subir y validarSolo administrador. Error si la contraseña o el fichero no son válidos. El fichero se guarda cifrado en disco.
TablaNombre, Titular (sujeto del certificado), Caduca, Estado (activo o desactivado, y «caducado» si ya pasó la fecha).
Buscar opcionalContiene el texto en el nombre o en el titular.
Caducidad TodosVigentes (incluye los que no indican fecha) / Caducan en 30 días / Caducados.
Ocultar desactivados desmarcadaMuestra solo los activos. Quitar filtros vuelve a verlos todos.
DesactivarDeja de usarse para firmar.

Para firmar se usa el certificado activo y vigente que caduque más tarde. Si no hay ninguno, un DeCA con finalidad contractual se rechaza con un mensaje claro. Sin finalidad contractual no se firma (la norma no lo exige).

7.9 Usuarios

ElementoDescripción
Correo electrónico obligatorioÚnico dentro de la empresa.
Contraseña inicial obligatorioHasta 72 bytes.
Rol OperadorOperador, Administrador o Lectura (ver 6).
Crear usuarioAlta inmediata.
TablaCorreo, Rol (desplegable + Cambiar; tu propio rol no se puede cambiar), Estado, Alta.
Buscar opcionalContiene el texto en el correo.
Rol (filtro) TodosSolo los usuarios de ese rol.
Ocultar desactivados desmarcadaMuestra solo los activos. Quitar filtros vuelve a verlos todos.
Desactivar / ActivarUn usuario desactivado no puede entrar y su sesión abierta deja de valer. No puedes desactivarte a ti mismo.

7.10 Historial (solo administradores)

Estadísticas de todo lo gestionado —expediciones y bandeja de revisión, en todos sus estados— en el periodo elegido. Se trabaja con lo que MADeCa guarda: no hay conductor (el Art. 6 no lo pide) y en las expediciones del camino 1 (PDF propio del ERP) solo constan sus metadatos, así que salen como «Sin dato» en partes, direcciones y mercancía.

Periodo
Fecha que cuenta
Totales y evolución
Desglose (pulsar = filtrar)
Registros / Excel
ElementoComportamiento
Periodo MensualDiario, Semanal (lunes a domingo), Mensual, Trimestral, Anual o A elegir (Desde / Hasta, ambos incluidos). Flechas ‹ › para el periodo anterior o siguiente y Hoy para volver al actual. Días en la hora de la instalación (ZONA_HORARIA).
Fecha de TransporteQué fecha de cada expedición decide si entra en el periodo: Transporte, Emisión o Entrega (solo las finalizadas). La bandeja cuenta siempre por fecha de recepción.
Totales de expedicionesTotal, en tránsito, entregadas y anuladas (con su %), firmadas (AdES), modificadas durante el servicio, con lecturas del QR (y nº de lecturas), mercancía peligrosa (con nº ONU), peso total en toneladas (y cuántas no tienen peso: otra magnitud o PDF propio), bultos, tiempo medio de emisión a entrega y destinatarios y vehículos distintos. Las tarjetas de estado, firma, modificadas, lecturas y ADR filtran al pulsarlas (otra vez para quitarlo).
EvoluciónBarras por día (periodos de hasta 31 días), por semana (hasta 92) o por mes. Al pasar por encima, número y toneladas; al pulsar una barra se filtra ese tramo.
DesgloseDestinatarios, cargadores y transportistas (con NIF), vehículos y remolques (matrícula), provincias de destino y de origen (por el código postal de la dirección), destinos y orígenes (dirección completa), mercancías, ERP o canal de origen y quién emitió (usuario, API, carpeta compartida; «No consta» en las anteriores al registro de actividad). Cada uno con nº de grupos, expediciones con su barra de porcentaje y toneladas; los 8 primeros a la vista y Ver todos para el resto. Pulsar una fila filtra todo el historial por ella (queda resaltada); pulsarla otra vez quita el filtro. Los filtros se combinan.
Bandeja de revisiónRecibidos, pendientes, emitidos, descartados (pulsables), con datos que faltan y tiempo medio de revisión; desglose por origen de los documentos (con el nombre de la fuente) y por quién los resolvió.
Fichas activasCada filtro aplicado (también el tramo) con su ✕; Quitar filtros deja solo el periodo.
RegistrosPestañas Expediciones y Bandeja con los registros que cumplen todo lo anterior, en páginas de 50, con enlace a cada uno.
Exportar a ExcelLibro .xlsx con todo lo de la consulta: Resumen (periodo, fecha que cuenta, filtros y todos los totales), Evolución, una hoja por cada desglose (todas las filas, con NIF, %, peso y bultos), Expediciones (todas las columnas de la exportación de Expediciones más «Emitida por») y Bandeja, cada una como tabla de Excel con filtros, formatos y totales. Hasta 100.000 filas por hoja.
Los filtros y el periodo quedan en la dirección de la página: se pueden guardar en favoritos o compartir con otro administrador de la empresa.

8. Panel de operador

Dirección /superadmin/login. Sesión y cookie distintas de las de empresa. Enlace «Soy una empresa cliente» para volver a /login.

PantallaElementos
Empresas → Dar de altaNombre / razón social, NIF/CIF (con dígito de control, único), Correo del administrador inicial, Contraseña inicial; botón Crear empresa.
Empresas existentesNombre, NIF/CIF, Usuarios, Expediciones, Estado, Alta; botones Usuarios, Desactivar (bloquea al instante login y claves de API, también el hot-folder y las fuentes) / Activar.
Usuarios de una empresaAlta con Correo y Rol: la contraseña se genera sola y se muestra una vez. Tabla con Rol (desplegable + Cambiar), Estado, Alta; botones Resetear contraseña (nueva contraseña mostrada una vez y cierre de las sesiones abiertas de ese usuario), Desactivar / Activar.
Cerrar sesiónEn la barra superior.

9. Visor público y descarga de la otra parte

DirecciónQuiénComportamiento
GET /inspect/{id}Agentes de inspección (QR)PDF directo, sin login, sin límite de peticiones. 404 si no existe; 410 si la URL está desactivada (anulada o más de 7 días tras el fin del servicio), indicando que el documento sigue conservado. Cada consulta queda registrada.
GET /descarga/{token}La otra parte (cargador o transportista)Descarga el PDF durante RETENTION_DAYS desde la emisión; 404 si el token no existe; 410 fuera de plazo. Se registra como «contraparte».

10. API REST

Autenticación con la cabecera X-API-Key: mad_live_…. La empresa se deduce de la clave, nunca de la petición. Documentación interactiva en /docs.

Método y rutaParámetrosRespuesta
POST /api/v1/expediciones
camino 1 (multipart)
archivo PDF obligatorio; referencia_externa obligatorio; matricula_vehiculo obligatorio; fecha_transporte ISO 8601 obligatorio; matricula_remolque, pais_matricula_vehiculo/pais_matricula_remolque ES, finalidad_contractual false, erp_origen generico.201 con la expedición. Si la referencia ya existe, devuelve la existente (idempotente). 422 PDF inválido, escaneo o > 5 MB; 409 sin certificado.
POST /api/v1/expediciones/datos
camino 2 (JSON)
Cuerpo con los campos de 7.3 (ver ejemplo en 14); query erp_origen generico.201; 422 datos inválidos (lista de errores); 503 si el motor de PDF no está disponible.
POST /api/v1/expediciones/{id}/modificaciones{"motivo": "...", "cambios": [{"campo", "anterior", "nuevo"}]}, de 1 a 20 cambios. campo = matricula_vehiculo, matricula_remolque, fecha_transporte o cualquier otro nombre.200 con la expedición; 409 si no está en tránsito o falta certificado; 422 si supera 5 MB.
PATCH /api/v1/expediciones/{id}/finalizarquery estado_final = entregado por defecto o anulado.200; 409 si ya estaba finalizada o el estado no es válido.
GET /api/v1/expediciones/{id}/pdf—PDF vigente (copia para el conductor).
GET /api/v1/expediciones/{id}/qr.png—QR en PNG.
POST /api/v1/borradoresreferencia_fuente obligatorio; origen conector_local; nombre_documento; datos (forma del camino 2, máx. 64 KB); confianza; avisos (máx. 50).201 {"id", "estado", "creado"}; creado=false si ya existía (misma referencia).
POST /api/v1/borradores/documentoarchivo (multipart) obligatorio; referencia_fuente opcional.201; MADeCa extrae los datos y crea el borrador.
GET /salud—{"estado": "ok"}.

Salida de una expedición: id, tenant_id, referencia_externa, erp_origen, estado, fecha_transporte, fecha_emision, matricula_vehiculo, matricula_remolque, url_publica, firmado, numero_escaneos, url_contraparte. Errores de autenticación: 401 clave inválida o revocada; 403 empresa desactivada.

11. Hot-folder

Para ERP sin API que exportan ficheros. Servicio hotfolder-watcher.

hotfolder_watch\ ├── incoming\<id_empresa>\<erp_origen>\ │ ├── pdf\ ALB-001.pdf + ALB-001.json (o .csv): PDF propio + metadatos (camino 1) │ └── datos\ pedido.json / .csv con datos completos, una fila por envío (camino 2) ├── processed\ lo procesado, con la misma estructura └── errores\ lo que falló + fichero .errores.txt con el motivo

En un CSV cada columna es un dato y los datos agrupados se escriben con punto: referencia_externa, cargador.nombre_razon_social, cargador.nif_cif, cargador.domicilio, transportista.nombre_razon_social, transportista.nif_cif, origen_direccion, destino_direccion, mercancia.naturaleza, mercancia.peso_kg, fecha_transporte, matricula_vehiculo… (los mismos nombres que el JSON). Las celdas vacías cuentan como dato no indicado. En pdf\ el fichero de metadatos solo lleva referencia_externa, matricula_vehiculo, matricula_remolque y fecha_transporte.

En pdf\ el PDF y su fichero de metadatos pueden llegar en cualquier orden; se procesan cuando ambos están completos. Al arrancar se procesa lo que hubiera pendiente. Una empresa inexistente o desactivada se rechaza a errores\. Para a3ERP y Sigrid hay correspondencias de campos orientativas que deben verificarse con la exportación real del cliente.

12. Conector local

Carpeta conector_local\. Se instala en un equipo de la red del cliente, lee sus carpetas (NAS, unidades de red), extrae los datos allí y solo envía datos a POST /api/v1/borradores.

Sección / clave de conector.iniDescripción
[madeca] url obligatorioDirección https de MADeCa (http solo hacia localhost para pruebas).
MADECA_API_KEY (variable de entorno) obligatorioClave de API. Solo como último recurso en [madeca] api_key.
[carpetas] rutas obligatorioCarpetas separadas por punto y coma (admite \\NAS\...).
[carpetas] mover_procesados_a opcionalMueve cada documento enviado a esa carpeta.
[carpetas] intervalo_segundos 120Mínimo 30.
[ocr] tesseract_ruta opcionalRuta de tesseract.exe. Sin Tesseract, los escaneos llegan sin datos y con aviso.
[estado] fichero / registroFicheros ya enviados (para no repetir) y registro de actividad.

Ejecución: python conector.py --config conector.ini (continuo) o --una-vez (para el Programador de tareas). Si MADeCa rechaza la clave, la pasada se detiene sin mover ni perder nada.

13. Parámetros de configuración (.env)

ParámetroPor defectoDescripción
APP_ENVdevelopmentFuera de development: cookies solo https y claves robustas obligatorias.
APP_SECRET_KEY obligatorio—Cifra contraseñas de certificados, certificados y credenciales de fuentes. 32+ caracteres aleatorios. Si cambia, lo cifrado no se puede recuperar.
JWT_SECRET_KEY obligatorio—Firma las sesiones. Distinta de la anterior.
JWT_EXPIRE_MINUTES480Duración de la sesión.
APP_BASE_URL obligatorio—Base de las URL del QR. Debe ser https (salvo http://localhost en pruebas).
DATABASE_URL / REDIS_URL— / redis://localhost:6379/0Conexiones (el compose las fija).
STORAGE_BACKENDlocallocal o s3 (con S3_ENDPOINT_URL, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY).
STORAGE_LOCAL_PATH / CERTS_LOCAL_PATH./storage/pdfs / ./certsCarpetas de PDF y certificados.
RETENTION_DAYS365Conservación mínima (no bajar de 365) y validez del enlace de la otra parte.
PUBLIC_URL_DEACTIVATION_DAYS7Días tras el fin del servicio en que se desactiva la URL pública.
HOTFOLDER_INCOMING_PATH / _PROCESSED_PATH / _ERROR_PATH./hotfolder_watch/…Carpetas del hot-folder.
TESSERACT_RUTAvacíoRuta de Tesseract si no está en el PATH.
OCR_LIMITE_SEGUNDOS60Tiempo máximo de lectura por página. Si se supera, el documento llega a la bandeja con el aviso de revisarlo a mano.
OCR_SIMULTANEOS2Lecturas a la vez por servicio; el resto espera su turno.
ZONA_HORARIAEurope/MadridHora de las fechas que llegan sin zona y del panel. Atlantic/Canary para Canarias (una hora menos). Cada DeCA guarda e imprime la zona de su transporte.
FORWARDED_ALLOW_IPS127.0.0.1IP del proxy HTTPS (o * si solo el proxy llega a MADeCa), para conocer la IP real de cada usuario: límite de intentos de acceso y registro de lecturas del QR.
AZURE_DI_ENDPOINT / AZURE_DI_CLAVEvacíoAzure AI Document Intelligence (región UE). Solo para empresas que lo autoricen.
DOCUMENTO_ORIGEN_MAX_BYTES20971520Tamaño máximo de un documento de origen (20 MB).
FUENTES_PERMITIR_RED_PRIVADAfalseSolo instalaciones propias: permite fuentes en redes privadas.
FUENTES_CARPETA_BASEvacíoSolo instalaciones propias: activa la fuente «Carpeta del servidor».
CONECTORES_CICLO_SEGUNDOS60Cada cuánto el servicio de conectores comprueba qué fuentes toca leer (mínimo 15).
SMTP_HOST opcionalvacíoServidor de correo para los avisos diarios. Vacío = avisos por correo desactivados.
SMTP_PUERTO587587 con STARTTLS, 465 con SSL.
SMTP_USUARIO / SMTP_CLAVEvacíoCredenciales del buzón que envía. Solo en el .env.
SMTP_REMITENTESMTP_USUARIODirección «De» de los avisos.
SMTP_SEGURIDADstarttlsstarttls, ssl o ninguna (solo en red interna).
AVISOS_CORREO_HORA8Hora local (0-23) a partir de la que se envía el resumen del día. Uno al día por empresa (marca en Redis).

14. Ejemplos de uso

Camino 1: PDF del ERP (PowerShell 7)

Invoke-RestMethod "https://deca.tudominio.es/api/v1/expediciones" -Method Post -Headers @{ "X-API-Key" = $env:MADECA_API_KEY } -Form @{
    referencia_externa = "ALB-2026-001"
    matricula_vehiculo = "1234BCD"
    fecha_transporte   = "2026-10-10T08:00:00"
    archivo            = Get-Item .\albaran.pdf
}

Camino 2: datos completos (curl)

curl -X POST "https://deca.tudominio.es/api/v1/expediciones/datos" \
  -H "X-API-Key: mad_live_..." -H "Content-Type: application/json" \
  -d '{"referencia_externa": "ALB-2026-002",
       "cargador": {"nombre_razon_social": "Distribuciones Demo SL", "nif_cif": "B00345678", "domicilio": "Calle Industria 14, Madrid"},
       "transportista": {"nombre_razon_social": "Transportes Demo SL", "nif_cif": "B00654327"},
       "origen_direccion": "Getafe (Madrid)", "destino_direccion": "Sevilla",
       "mercancia": {"naturaleza": "Palés de material eléctrico", "peso_kg": 850.5},
       "fecha_transporte": "2026-10-10T08:00:00", "matricula_vehiculo": "1234BCD", "matricula_remolque": "R5678BBC"}'

Modificación durante el servicio

curl -X POST "https://deca.tudominio.es/api/v1/expediciones/{id}/modificaciones" -H "X-API-Key: mad_live_..." \
  -H "Content-Type: application/json" \
  -d '{"motivo": "Cambio de vehículo por avería", "cambios": [{"campo": "matricula_vehiculo", "anterior": "1234BCD", "nuevo": "5678CDF"}]}'
# Después: GET /api/v1/expediciones/{id}/pdf y entregar ese PDF al conductor

Borrador desde un sistema propio (como el conector local)

curl -X POST "https://deca.tudominio.es/api/v1/borradores" -H "X-API-Key: mad_live_..." \
  -H "Content-Type: application/json" \
  -d '{"referencia_fuente": "TMS-778", "origen": "mi_tms", "datos": {"referencia_externa": "778", "matricula_vehiculo": "1234BCD"}}'

Purga tras el plazo de conservación

docker compose exec app python -m scripts.purgar_expirados             # solo lista
docker compose exec app python -m scripts.purgar_expirados --confirmar # borra

15. Ciclo de vida y plazos

Emisión (antes del servicio)
Copia al conductor
En tránsito: modificaciones
Entregado / anulado
+7 días: URL pública desactivable
+1 año: purga posible
EstadoURL públicaModificableEnlace otra parte
en_transitoActivaSíActivo
entregadoActiva hasta 7 días despuésNoActivo hasta 1 año desde la emisión
anuladoInactiva al momentoNoActivo hasta 1 año desde la emisión

16. Resolución de problemas

ProblemaCausaSolución
«El PDF parece resultado de escanear…»Página sin texto con solo una imagen.Genera el PDF directamente desde el ERP, o sube el escaneo a la bandeja para que se emita un DeCA nativo.
«Ya existe una expedición para referencia_externa…»Referencia repetida.Usa otra referencia o, si hay que cambiar datos, una modificación.
«…no tiene ningún certificado de firma activo y vigente»Finalidad contractual sin certificado válido.Sube un certificado vigente en Certificados o desmarca la finalidad contractual.
«Falta el domicilio del cargador contractual (Art. 6.a)»Dato esencial vacío.Complétalo.
«Formato de matrícula no reconocido»Matrícula extranjera con país ES, o error de escritura.Indica el país (cabotaje) o corrígela.
MADeCa no arranca: «APP_BASE_URL debe empezar por https://»Modo producción con una dirección sin HTTPS (Apartado Tercero.1).Pon MADeCa detrás de un proxy HTTPS y usa su dirección https:// en APP_BASE_URL.
En la bandeja: «la lectura automática superó 60 s por página»Foto o escaneo difícil de leer; se corta para que MADeCa siga respondiendo.Completa los datos a mano mirando el documento, o súbelo con mejor calidad. El límite se ajusta con OCR_LIMITE_SEGUNDOS.
La hora del DeCA no coincide con la del albaránZona horaria distinta (Canarias tiene una hora menos).Elige la zona en el formulario o fija ZONA_HORARIA en la instalación; el ERP puede enviar la hora con su desfase o el campo zona_horaria.
«Solo se puede modificar un DeCA durante el servicio»Expedición entregada o anulada.Ya no admite cambios; si procede, emite un DeCA nuevo.
La URL del QR responde «ya no está disponible»Anulada o pasados 7 días desde el fin del servicio.Normal. El documento se conserva; la otra parte usa su enlace.
Borrador vacío con «No se pudo leer el documento»Imagen ilegible, formato no soportado o sin OCR disponible.Rellena los datos a mano mirando el original, o revisa Tesseract/Azure.
Fuente en rojo: «Entra ID rechazó las credenciales»Id o secreto incorrectos o caducados.Revisa el registro de la aplicación en Entra ID y el permiso Files.Read.All o el de Business Central.
Fuente en rojo: «apunta a una red privada»Protección SSRF.Usa el conector local o, en instalación propia, FUENTES_PERMITIR_RED_PRIVADA=true.
SFTP: «La huella del servidor no coincide»Huella mal copiada o servidor distinto.Copia la huella SHA256 exacta del servidor (ssh-keygen -lf).
La API responde 401 / 403Clave inválida o revocada / empresa desactivada.Genera otra clave / contacta con el operador.
La aplicación no arranca: «APP_SECRET_KEY debe ser…»Claves de ejemplo o cortas fuera de desarrollo.Pon claves aleatorias propias de 32+ caracteres y distintas.
Hot-folder: ficheros en errores\Ver el .errores.txt de al lado.Corrige y vuelve a dejarlos en incoming\.
No llegan los avisos por correoSin SMTP_HOST, sin avisos ese día, sin administradores activos, antes de AVISOS_CORREO_HORA o Redis caído.Revisa el inicio (dice si están activados) y el registro del servicio conectores; si falla el envío se reintenta en la siguiente pasada.
La revisión no recuadra los datos en el documentoPDF con texto sin pypdfium2, documento leído antes de la v0.3.0 o dato que no aparece escrito tal cual.Instala las dependencias de requirements.txt; los documentos nuevos ya guardan las posiciones.
«Marca la confirmación de que has comprobado los datos»Emisión de varios sin la casilla de confirmación.Márcala tras comprobar los documentos.
Las horas no cuadranSe muestran en hora peninsular.Las fechas sin zona que envíe un sistema se interpretan como hora peninsular en el PDF generado.

MADeCa · Versión 0.4.4 · Actualizado el 16/11/2026
Aplicación desarrollada por Masoft.es