Credenciales y seguridad
Esta guía describe los tokens sk_test_ y sk_live_. La demostración pública utiliza sk_demo_, caduca en 24 horas y tiene límites y almacenamiento temporal propios.
Utilizar el token
Soporte de SERTEC PESAGE proporciona el token al dar de alta tu integración.
Inclúyelo en todas las peticiones a /api/v1:
Código
Utiliza HTTPS y envía el token exclusivamente en esta cabecera.
El token es opaco: no necesitas decodificarlo ni generar un JWT.
Los tokens sk_test_ acceden al entorno de desarrollo y los tokens sk_live_
al de producción. La ruta de la API es la misma; los documentos de ambos
entornos están separados.
Código
IP autorizadas
Si el token tiene una lista de IP autorizadas, las peticiones deben proceder de
las IP públicas de salida dadas de alta por soporte. Un token válido enviado
desde una IP no autorizada recibe 403. Si la lista está vacía, se permite el
acceso desde cualquier IP.
Esta restricción añade protección frente al uso del token desde terceros equipos;
también es necesario proteger el token y los servidores autorizados.
No se puede dar de alta una IP mediante la API ni autorizarla enviando cabeceras
como X-Forwarded-For. Para añadir o cambiar una IP, contacta con soporte de
SERTEC PESAGE. Si tu proveedor cambia la IP de salida, solicita su actualización.
Proteger las credenciales
- Guarda el token en un gestor de secretos o en la configuración protegida del servidor.
- Realiza las llamadas desde tu servidor; evita exponer el token en páginas web, JavaScript del navegador o aplicaciones distribuidas a terceros.
- No incluyas el token en URLs, repositorios, registros, capturas o tickets de soporte.
- Utiliza una credencial independiente para cada integración.
- Si sospechas una filtración, solicita a soporte la revocación y un token nuevo.
La URL de descarga por QR contiene otro secreto. Utiliza el enlace recibido tal como se entrega y evita publicarlo o guardarlo en registros. Esa descarga utiliza el secreto del enlace, sin la cabecera Bearer ni la restricción de IP de la API.
Límites y reintentos
Cada token admite 60 peticiones por minuto. La descarga por QR admite
30 peticiones por minuto para la misma IP y documento. Al recibir 429,
espera los segundos indicados en Retry-After antes de reintentar.
Los cuerpos de las peticiones no pueden superar 128 KiB. Envía JSON con
Content-Type: application/json; un formato distinto devuelve 415 y un JSON
malformado devuelve 400.
Una referencia identifica una versión y es única dentro de la organización y el entorno. Repetir una creación con la misma referencia y los mismos datos devuelve el documento original durante 24 horas. Sin referencia, cada petición de creación emite un documento nuevo.
Solo puedes consultar y descargar mediante Bearer los documentos emitidos por esa credencial en las últimas 24 horas. La descarga por QR conserva su acceso durante la conservación del PDF, después de ese plazo y tras rotar o revocar el token. Un documento eliminado no se puede descargar por ninguna de esas vías.
El despliegue debe ejecutar el planificador de Laravel. La tarea horaria
documents:prune-recent-keys elimina las claves de acceso reciente vencidas;
la API aplica el límite de 24 horas aunque esa limpieza todavía no se haya
ejecutado.
Cuenta del portal y recuperación
El código de recuperación pertenece a una cuenta del portal; no es un token API ni se envía en la cabecera Bearer. El alta, incluida la creación de administradores adicionales, requiere configurar la primera passkey, imprimir o descargar el código y volver a introducirlo antes de crear la cuenta. DeCA no vuelve a mostrar el código guardado.
Si falla la passkey, se ofrece un modal para introducir el código. En el login sigue siendo obligatoria la contraseña correcta; el código sustituye a la passkey y abre las mismas claves del archivo cifrado. Las operaciones que piden contraseña actual siguen exigiéndola. Cancelar devuelve al formulario anterior y no ejecuta la operación.
El código puede confirmar cualquier operación que solicite una passkey, incluidas su regeneración y la eliminación de passkeys. Si se usa una passkey para borrar otra, debe ser distinta de la eliminada; cada usuario conserva siempre al menos una. En Seguridad, el código anterior sigue activo hasta imprimir o descargar y reintroducir correctamente el nuevo; entonces se invalida, junto con sus confirmaciones pendientes.
Guarda el código fuera del sistema, en un lugar privado, separado de la contraseña. No lo incluyas en llamadas a la API, registros ni mensajes a soporte. Perder las credenciales capaces de abrir las claves puede impedir recuperar el archivo.
Conservación y copias privadas
Los PDF se conservan un año y los datos estructurados cifrados cuatro años, contando desde la emisión o la fecha de transporte si es posterior. El acceso con Bearer sigue limitado a 24 horas. El enlace QR permite acceder al PDF durante su conservación, sin exigir una cuenta; la rotación o revocación del token no lo desactiva por sí sola. Una vez retirado el PDF, el antiguo QR deja de permitir su descarga.
Mientras se conservan los datos, una persona autorizada puede desbloquear el archivo desde el portal y generar una copia privada del PDF. Esa copia se genera de nuevo: no recupera los bytes del fichero original eliminado, no se guarda como nuevo PDF permanente y no reactiva el enlace QR vencido. Se conservan el idioma y el logo de la emisión cuando están incluidos en los datos originales.
El cifrado no implica que el servidor nunca maneje claves: la verificación del código de recuperación y la generación de una copia privada utilizan material de clave transitorio. No se persisten el código en texto ni la clave de datos recibida para regenerar.
Las copias de Hostinger se conservan 7 días. Además, pueden realizarse copias manuales del proyecto en ZIP y de la base de datos en SQL: guárdalas fuera del acceso público, protegidas y con acceso restringido. El almacén privado de claves temporales para las últimas 24 horas está separado del proyecto y de la base de datos, y debe quedar fuera de esos ZIP y SQL. Tras restaurar, ejecuta la purga según los plazos de conservación e invalida las sesiones y los accesos temporales antes de reabrir el servicio. Las copias no conceden un plazo ilimitado de conservación.
Resolver problemas de acceso
| Respuesta | Comprobación |
|---|---|
401 | El token falta, es incorrecto o ha sido revocado. Revisa la cabecera y contacta con soporte si necesitas sustituirlo. |
403 | Comprueba la IP pública de salida y solicita a soporte su autorización. También puede indicar una operación no permitida. |
Al contactar con soporte, facilita la hora de la petición, la IP pública de salida, el método, la ruta y el código de error. No envíes el token ni el enlace secreto del QR.
Datos del transporte y alcance
Para transporte interior de mercancías por carretera en España, la Orden FOM/2861/2012 exige nombre, NIF y domicilio del cargador contractual; nombre y NIF del transportista que efectivamente realiza el transporte; lugares de carga y descarga; naturaleza y peso de la mercancía, u otra magnitud si el peso es difícil de determinar; fecha del transporte, matrículas del vehículo y remolque, y autorización especial de circulación cuando sea necesaria.
origin.place y destination.place pueden identificar una instalación por nombre o
por dirección. Junto con city y country deben identificar claramente el lugar real;
street y postal_code son opcionales y aportan precisión. La identidad completa de
la empresa destinataria no es un dato mínimo obligatorio de esta orden.
carrier.address es opcional; si se envía, debe contener todos los campos de Address.
Indica la fecha real, datos correctos de la mercancía y el remolque cuando exista.
Los operadores deben asegurar conservación y disponibilidad durante al menos un año, incluido el acceso de otros intervinientes. Generar el PDF no implica certificación eFTI ni sustituye CMR internacional, ADR, documentos de traslado de residuos o subproductos animales. Este documento de control administrativo no exige con carácter general una firma electrónica; otros usos contractuales pueden requerir una firma adecuada.
Los requisitos electrónicos se recogen en la Resolución de 5 de junio de 2026: PDF de hasta 5 MB con metadatos de creación y modificación y acceso directo HTTPS con TLS 1.2 o posterior. Utilizar la API no sustituye las obligaciones operativas de los intervinientes.
El borrado lógico solo se permite durante 2 horas, antes de entregar o utilizar el
documento. El primer acceso correcto al enlace QR bloquea también el borrado con
409 DOCUMENT_ALREADY_ACCESSED. Ese acceso no prueba por sí solo la realización del
transporte. Las rectificaciones requieren reenviar todos los datos y, si se informa,
una referencia nueva; el PDF original y su QR se conservan.
Los ocho idiomas traducen los títulos y etiquetas del PDF, no los nombres, direcciones,
observaciones ni otros datos enviados por la integración. Los textos impresos admiten
caracteres latinos, griegos y cirílicos compatibles con las fuentes; emoji, CJK y
escrituras de derecha a izquierda devuelven 422 UNSUPPORTED_CHARACTERS en el campo
afectado. metadata conserva Unicode arbitrario y no se imprime.
Las URL de documentos utilizan la URL pública HTTPS configurada por el operador del
servicio. Si esa configuración no es válida, la emisión responde
503 SERVICE_UNAVAILABLE y no persiste un documento parcial.
Los NIF españoles especiales K, L y M se validan por formato; DNI, NIE y NIF de entidades conservan la comprobación del carácter de control. Validar un identificador no acredita existencia ni alta censal.