MADeCa
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.
2. Características principales
3. Base legal y cómo se cumple
Normas comprobadas en el BOE y en EUR-Lex el 09/10/2026.
| Norma | Exigencia | Có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. 6 | Datos 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. 9 | Conservació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, Primero | Generar 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.1 | PDF 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.2 | Nativo 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.3 | QR con la URL en el PDF; puede ir también como fichero aparte. | QR estampado o impreso; descarga del QR en PNG. |
| Segundo.4 | Ambas 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–4 | HTTPS (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.5 | La 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. |
| Cuarto | Firma solo si hay finalidad contractual; como mínimo AdES. | Firma PAdES-B con el certificado de la empresa; no firma con certificados caducados. |
| Quinto | Modificación durante el servicio (método 1 o 2) y entrega al conductor. | Método 1 implementado; aviso de entrega al conductor. |
| Séptimo | Copia para el conductor antes del servicio, electrónica o impresa, con QR. | Descarga del PDF vigente y del QR (panel y API). |
| Octavo | Se pueden usar otros documentos (carta de porte, ADR…) si contienen los datos del art. 6. | Camino 1 (PDF propio); MADeCa no valida su contenido. |
| Noveno | Con 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 28 | Minimizació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
| Componente | Requisito | Notas |
|---|---|---|
| Servidor | Docker y Docker Compose | Recomendado. La imagen incluye Python 3.12, WeasyPrint (Pango/Cairo) y Tesseract con español. |
| Base de datos | PostgreSQL 16 | Servicio db del compose. Mínimo PostgreSQL 13 (la migración usa gen_random_uuid()). |
| Caché | Redis 7 | Límite de intentos de login compartido entre procesos. |
| Publicación | Dominio con HTTPS (TLS 1.2+) delante (nginx, traefik…) | Obligatorio en producción (Apartado Tercero.1). |
| Sin Docker | Python 3.12+, pip install -r requirements.txt, PostgreSQL y Redis accesibles | En Windows, el PDF generado (WeasyPrint) necesita GTK; el resto funciona. |
| Conector local | Windows con Python 3.12+; Tesseract si hay escaneos | Ver 12. |
| Navegador | Cualquiera actual | htmx y unos pocos scripts propios (filtros, formulario, bandeja), servidos desde MADeCa; sin JavaScript en línea. |
| Correo (opcional) | Servidor SMTP | Para los avisos diarios a los administradores (SMTP_*, ver 13). |
| Excel | openpyxl (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
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
| Servicio | Función |
|---|---|
| db | PostgreSQL. Solo accesible desde la propia máquina (127.0.0.1:5432). |
| redis | Redis. Solo accesible desde la propia máquina (127.0.0.1:6379). |
| app | Aplicación web (paneles, API, visor público) en el puerto 8000. |
| hotfolder-watcher | Vigila hotfolder_watch/incoming y emite los DeCA de lo que llegue. |
| conectores | Lee periódicamente las fuentes de datos y deja lo nuevo en la bandeja. |
Scripts de administración
| Script | Parámetros | Qué hace |
|---|---|---|
| scripts.crear_superadmin | --email obligatorio --password obligatorio | Crea el operador de la plataforma (acceso a /superadmin). |
| scripts.crear_tenant | --nombre --nif --email --password todos | Alta de una empresa y su primer administrador sin pasar por el panel. |
| scripts.cargar_demo | --con-operador opcional --nuevas-claves opcional | Empresa de demostración con un usuario por rol y clave de API. Se niega con APP_ENV=production. |
| scripts.purgar_expirados | --confirmar opcional | Sin 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.
# 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)
| Fichero | Qué es |
|---|---|
| Dockerfile.paquete | Imagen 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.sh | Instalar, 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.bat | Windows: 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.Dockerfile | Compila iptables estático (nf_tables) para los sistemas sin internet que no lo traen. |
| paquete/docker-compose.yml, Caddyfile, Caddyfile.propio, Caddyfile.prueba | Servicios 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.txt | Licencia MIT: software libre y gratuito. |
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ón | Lectura | Operador | Administrador |
|---|---|---|---|
| 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.
| Elemento | Descripción |
|---|---|
| Correo electrónico obligatorio | Correo 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 obligatorio | Al 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 Entrar | Abre el Inicio. Mensajes: «Credenciales incorrectas» o «Esta empresa está desactivada…». |
| Enlace Panel de operador | Lleva a /superadmin/login. |
La sesión dura JWT_EXPIRE_MINUTES (480 min por defecto). Menú superior:
| Opción | Visible para | Lleva a |
|---|---|---|
| Inicio | Todos | Resumen (abajo) |
| Expediciones | Todos | 7.2 |
| Bandeja de revisión | Todos | 7.5 |
| Integraciones ERP | Todos | 7.7 |
| Fuentes de datos | Administrador | 7.6 |
| Certificados | Todos | 7.8 |
| Historial | Administrador | 7.10 |
| Usuarios | Administrador | 7.9 |
| Cerrar sesión | Todos | Borra 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».
| Elemento | Descripción |
|---|---|
| Indicadores | Pendientes 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ón | Certificado 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 expediciones | Los 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.
| Elemento | Comportamiento |
|---|---|
| Buscar opcional | Cuadro 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 fecha | Botó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 opcional | Panel 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 marcados | Casillas 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 activas | Sobre la tabla, una ficha por filtro aplicado («frutas», «Transporte: Este mes», «Firmadas»…). Su ✕ quita solo ese filtro. Limpiar filtros los quita todos. |
| Ordenar | Pulsa 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 desplegable | Se cierra al pulsar fuera, con Esc o al abrir el otro. |
| Exportar a Excel | Administrador 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.
| Columna | Contenido |
|---|---|
| Referencia | Referencia externa (nº de albarán del ERP). |
| ERP | Origen: generico, a3erp, sigrid, sap, dynamics365, odoo, sage. |
| Matrícula | Matrícula del vehículo (tractora). |
| Fecha transporte / Hora | Fecha (DD/MM/AAAA) y hora peninsular del transporte, en columnas separadas. |
| Estado | En tránsito, Entregado o Anulado. |
| URL pública | activa o inactiva (anulada, desactivada o más de 7 días tras el fin del servicio). |
| Firmado | «AdES» si se firmó; «—» si no. |
| Escaneos | Número de consultas registradas (visor público y descargas de la otra parte). |
| Ver | Abre 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).
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.
| Campo | Descripción |
|---|---|
| Fichero PDF obligatorio | PDF 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 obligatorio | Nº de albarán/factura, hasta 200 caracteres. No se puede repetir en la empresa (mismo ERP). |
| Matrícula del vehículo obligatorio | 1234BCD, M1234AB o R1234BCD; con país distinto de ES, alfanumérica de 2 a 12. |
| Matrícula del remolque opcional | Obligatoria en la práctica en conjuntos articulados (Art. 6.g). |
| País de las matrículas ES | Dos casillas (vehículo y remolque), código de dos letras. Distinto de ES solo en cabotaje. |
| Fecha y hora del transporte obligatorio | Hora peninsular. |
| Finalidad contractual casilla | Si se marca, se firma con AdES; exige un certificado activo y vigente. |
| Botón Crear expedición | Emite y abre el detalle. |
MADeCa redacta el PDF con todos los datos del Art. 6. Es el mismo formulario que usa la bandeja de revisión.
| Bloque | Campo | Reglas |
|---|---|---|
| Referencia externa obligatorio | Hasta 200 caracteres, única en la empresa. | |
| Cargador contractual (6.a) | Nombre / razón social obligatorio | Hasta 300 caracteres. |
| NIF/CIF obligatorio | NIF, NIE o CIF con dígito de control correcto. | |
| Domicilio obligatorio | Hasta 500 caracteres. | |
| Transportista efectivo (6.b) | Nombre / razón social obligatorio | |
| NIF/CIF obligatorio | Con dígito de control. | |
| Destinatario | Nombre, NIF/CIF, Domicilio opcional | No lo exige el Art. 6. Solo se imprime si se indican nombre y NIF. |
| Origen y destino (6.c) | Lugar de origen obligatorio | Hasta 500 caracteres. |
| Lugar de destino obligatorio | Hasta 500 caracteres. | |
| Mercancía (6.d) | Naturaleza obligatorio | Hasta 500 caracteres. |
| Peso bruto (kg) | Mayor que 0; admite coma decimal. Obligatorio salvo que se indique la magnitud alternativa. | |
| Magnitud alternativa | Solo si el peso exacto no es determinable por la forma de carga. | |
| Bultos opcional | Entero ≥ 0. | |
| ADR — nº ONU opcional | Si se indica, también la denominación. | |
| ADR — denominación opcional | Si se indica, también el nº ONU. | |
| Vehículo y fecha (6.e–g) | Matrícula del vehículo obligatorio | Como en el camino 1. |
| Matrícula del remolque opcional | ||
| País de las matrículas ES | Cabotaje. | |
| Autorización especial de circulación opcional | Solo si el vehículo circula amparado por una (6.e). Hasta 100 caracteres. | |
| Fecha y hora del transporte obligatorio | Hora peninsular. | |
| 6.h | Observaciones opcional | Hasta 2000 caracteres. |
| Finalidad contractual casilla | Firma AdES. |
| Campo | Descripción |
|---|---|
| Ficheros PDF obligatorio | Varios PDF propios a la vez (camino 1). |
| Fichero de metadatos obligatorio | CSV (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
| Elemento | Descripción |
|---|---|
| Estado / URL pública / Firma | Estado de la expedición, si la URL del QR está activa y si va firmada con AdES. |
| URL pública | La que contiene el QR (/inspect/{id}). |
| Ver PDF público | Abre el PDF como lo verá el agente (registra un acceso). |
| Descargar PDF para el conductor | PDF vigente, con sus modificaciones (Apartado Séptimo). |
| Descargar QR | PNG con el QR (fichero independiente permitido por el Segundo.3). |
| Marcar como entregado | Solo 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 parte | Enlace privado /descarga/{token} para el cargador o transportista que no emite; válido durante el plazo de conservación. No publicarlo. |
| Texto de servicio finalizado | Fecha y hora del fin del servicio y recordatorio del plazo de 7 días. |
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.
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:
| Campo | Descripción |
|---|---|
| Motivo de la modificación obligatorio | De 3 a 1000 caracteres. Se imprime en el PDF. |
| Dato 1 obligatorio, Dato 2 y Dato 3 opcionales | Desplegable: 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 DeCA | Añ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. |
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.
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
| Elemento | Descripción |
|---|---|
| Aviso superior | Recuerda 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 documentos | Operador 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ñas | Pendientes, 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. |
| Columnas | Fecha, 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). |
| Elemento | Comportamiento |
|---|---|
| Buscar opcional | Busca 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ígenes | Desplegable con los orígenes que tienen borradores, con el nombre de la fuente de datos. |
| Fecha Cualquier fecha | Mismo 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 apagado | Interruptor: muestra solo los borradores con algún aviso. |
| Ocultar entregados apagado | Interruptor que aparece solo en Emitidos: quita los borradores cuya expedición ya está entregada. |
| Ordenar | Cabeceras Recibido (por defecto, más recientes primero), Documento, Origen y Datos (primero los que tienen más avisos). |
| Fichas activas | Como en Expediciones: ✕ quita ese filtro; Limpiar filtros los quita todos. |
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ón | Comportamiento |
|---|---|
| Emitir los completos | Pide 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. |
| ✕ Descartar | Pide confirmar; los descarta y borra sus documentos originales. |
| Cancelar / Quitar selección | Vuelve atrás sin hacer nada. |
| Elemento | Descripción |
|---|---|
| Cabecera | Vuelta a la bandeja y cuántos pendientes quedan. |
| Aviso de posible duplicado | Si ya hay una expedición con la misma referencia, con su fecha, estado y enlace. |
| Aviso de responsabilidad | Recuerda 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 rojo | Obligatorio 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 escribir | Al 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 partes | Al 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 original | A 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 datos | El de 7.3, precargado, por secciones (cargador, transportista, destinatario, origen y destino, mercancía, vehículo y fecha, otros). Corrige lo necesario. |
| Emitir el DeCA | Si 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 siguiente | Igual, 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 siguiente | Lo pasa a «descartado» y borra el original. |
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.
| Columna / botón | Descripción |
|---|---|
| Nombre | Enlace a la edición. |
| Tipo | Tipo de fuente. |
| Estado | Activa o Pausada, y cada cuántos minutos se lee. |
| Última lectura / Hora | Fecha y hora de la última pasada. |
| Resultado | «N nuevo(s) en la bandeja (M leído(s))» o el error en rojo. |
| Probar | Comprueba credenciales y acceso sin traer nada. |
| Leer ahora | Ejecuta una pasada inmediata. |
| Pausar / Activar | Detiene o reanuda la lectura periódica. |
| ✕ | Elimina la fuente. Sus borradores siguen en la bandeja. |
Nombre de esta fuente obligatorio (hasta 150) y Leer cada (minutos) 15 (de 5 a 1440).
| Tipo | Campos | Funcionamiento |
|---|---|---|
| SharePoint / OneDrive | Id 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 Drive | JSON 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. |
| Dropbox | App 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 servidor | Subcarpeta (opcional). | Solo instalaciones propias con FUENTES_CARPETA_BASE. Cada empresa solo ve <base>/<id_empresa>. |
| Business Central | Id 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 One | Direcció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). |
| Holded | Clave 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.
FUENTES_PERMITIR_RED_PRIVADA=true.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)
| Elemento | Descripción |
|---|---|
| Nombre descriptivo obligatorio | P. ej. «a3ERP producción». Hasta 150 caracteres. |
| ERP de origen | Genérico / integración a medida, a3ERP, Sigrid, SAP, Microsoft Dynamics 365, Odoo, Sage. Informativo. |
| Generar API key | Solo 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. |
| Tabla | Nombre, ERP, Prefijo (inicio de la clave), Estado (activa/revocada), Último uso y Hora. |
| Revocar | Solo administrador. Deja de funcionar al instante. |
7.8 Certificados de firma
| Elemento | Descripción |
|---|---|
| Nombre descriptivo obligatorio | P. ej. «Sello de empresa 2026». |
| Fichero .p12/.pfx obligatorio | Certificado con su clave privada. |
| Contraseña del certificado obligatorio | Se comprueba al subirlo; se guarda cifrada. |
| Subir y validar | Solo administrador. Error si la contraseña o el fichero no son válidos. El fichero se guarda cifrado en disco. |
| Tabla | Nombre, Titular (sujeto del certificado), Caduca, Estado (activo o desactivado, y «caducado» si ya pasó la fecha). |
| Buscar opcional | Contiene el texto en el nombre o en el titular. |
| Caducidad Todos | Vigentes (incluye los que no indican fecha) / Caducan en 30 días / Caducados. |
| Ocultar desactivados desmarcada | Muestra solo los activos. Quitar filtros vuelve a verlos todos. |
| Desactivar | Deja 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
| Elemento | Descripción |
|---|---|
| Correo electrónico obligatorio | Único dentro de la empresa. |
| Contraseña inicial obligatorio | Hasta 72 bytes. |
| Rol Operador | Operador, Administrador o Lectura (ver 6). |
| Crear usuario | Alta inmediata. |
| Tabla | Correo, Rol (desplegable + Cambiar; tu propio rol no se puede cambiar), Estado, Alta. |
| Buscar opcional | Contiene el texto en el correo. |
| Rol (filtro) Todos | Solo los usuarios de ese rol. |
| Ocultar desactivados desmarcada | Muestra solo los activos. Quitar filtros vuelve a verlos todos. |
| Desactivar / Activar | Un 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.
| Elemento | Comportamiento |
|---|---|
| Periodo Mensual | Diario, 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 Transporte | Qué 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 expediciones | Total, 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ón | Barras 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. |
| Desglose | Destinatarios, 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ón | Recibidos, 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 activas | Cada filtro aplicado (también el tramo) con su ✕; Quitar filtros deja solo el periodo. |
| Registros | Pestañas Expediciones y Bandeja con los registros que cumplen todo lo anterior, en páginas de 50, con enlace a cada uno. |
| Exportar a Excel | Libro .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. |
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.
| Pantalla | Elementos |
|---|---|
| Empresas → Dar de alta | Nombre / razón social, NIF/CIF (con dígito de control, único), Correo del administrador inicial, Contraseña inicial; botón Crear empresa. |
| Empresas existentes | Nombre, 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 empresa | Alta 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ón | En la barra superior. |
9. Visor público y descarga de la otra parte
| Dirección | Quién | Comportamiento |
|---|---|---|
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 ruta | Parámetros | Respuesta |
|---|---|---|
| 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}/finalizar | query 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/borradores | referencia_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/documento | archivo (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.
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.ini | Descripción |
|---|---|
| [madeca] url obligatorio | Dirección https de MADeCa (http solo hacia localhost para pruebas). |
| MADECA_API_KEY (variable de entorno) obligatorio | Clave de API. Solo como último recurso en [madeca] api_key. |
| [carpetas] rutas obligatorio | Carpetas separadas por punto y coma (admite \\NAS\...). |
| [carpetas] mover_procesados_a opcional | Mueve cada documento enviado a esa carpeta. |
| [carpetas] intervalo_segundos 120 | Mínimo 30. |
| [ocr] tesseract_ruta opcional | Ruta de tesseract.exe. Sin Tesseract, los escaneos llegan sin datos y con aviso. |
| [estado] fichero / registro | Ficheros 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ámetro | Por defecto | Descripción |
|---|---|---|
| APP_ENV | development | Fuera 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_MINUTES | 480 | Duració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/0 | Conexiones (el compose las fija). |
| STORAGE_BACKEND | local | local o s3 (con S3_ENDPOINT_URL, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY). |
| STORAGE_LOCAL_PATH / CERTS_LOCAL_PATH | ./storage/pdfs / ./certs | Carpetas de PDF y certificados. |
| RETENTION_DAYS | 365 | Conservación mínima (no bajar de 365) y validez del enlace de la otra parte. |
| PUBLIC_URL_DEACTIVATION_DAYS | 7 | Dí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_RUTA | vacío | Ruta de Tesseract si no está en el PATH. |
| OCR_LIMITE_SEGUNDOS | 60 | Tiempo máximo de lectura por página. Si se supera, el documento llega a la bandeja con el aviso de revisarlo a mano. |
| OCR_SIMULTANEOS | 2 | Lecturas a la vez por servicio; el resto espera su turno. |
| ZONA_HORARIA | Europe/Madrid | Hora 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_IPS | 127.0.0.1 | IP 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_CLAVE | vacío | Azure AI Document Intelligence (región UE). Solo para empresas que lo autoricen. |
| DOCUMENTO_ORIGEN_MAX_BYTES | 20971520 | Tamaño máximo de un documento de origen (20 MB). |
| FUENTES_PERMITIR_RED_PRIVADA | false | Solo instalaciones propias: permite fuentes en redes privadas. |
| FUENTES_CARPETA_BASE | vacío | Solo instalaciones propias: activa la fuente «Carpeta del servidor». |
| CONECTORES_CICLO_SEGUNDOS | 60 | Cada cuánto el servicio de conectores comprueba qué fuentes toca leer (mínimo 15). |
| SMTP_HOST opcional | vacío | Servidor de correo para los avisos diarios. Vacío = avisos por correo desactivados. |
| SMTP_PUERTO | 587 | 587 con STARTTLS, 465 con SSL. |
| SMTP_USUARIO / SMTP_CLAVE | vacío | Credenciales del buzón que envía. Solo en el .env. |
| SMTP_REMITENTE | SMTP_USUARIO | Dirección «De» de los avisos. |
| SMTP_SEGURIDAD | starttls | starttls, ssl o ninguna (solo en red interna). |
| AVISOS_CORREO_HORA | 8 | Hora 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
| Estado | URL pública | Modificable | Enlace otra parte |
|---|---|---|---|
| en_transito | Activa | Sí | Activo |
| entregado | Activa hasta 7 días después | No | Activo hasta 1 año desde la emisión |
| anulado | Inactiva al momento | No | Activo hasta 1 año desde la emisión |
16. Resolución de problemas
| Problema | Causa | Solució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án | Zona 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 / 403 | Clave 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 correo | Sin 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 documento | PDF 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 cuadran | Se muestran en hora peninsular. | Las fechas sin zona que envíe un sistema se interpretan como hora peninsular en el PDF generado. |
17. Aviso legal
- La lectura automática de documentos (texto y OCR) puede equivocarse o no encontrar datos; por eso pasa siempre por revisión humana.
- En el camino 1 MADeCa no comprueba que el PDF del ERP contenga todos los datos del art. 6; solo que no sea un escaneo.
- La detección de escaneos es una heurística: no cubre todos los casos posibles.
- Las correspondencias de campos de SAP Business One, Holded, a3ERP y Sigrid deben verificarse con la instalación real del cliente antes de usarlas.
- El uso de Azure AI Document Intelligence implica un subencargado del tratamiento (art. 28.2 RGPD) y requiere la autorización de la empresa y el contrato correspondiente.
- La interoperabilidad eFTI (Reglamento UE 2020/1056) no está implementada en esta versión.
- Las referencias normativas se comprobaron el 09/10/2026; pueden cambiar.
- Software proporcionado «tal cual», sin garantías.