Identifiants et sécurité
Ce guide décrit les jetons sk_test_ et sk_live_. La démonstration publique utilise sk_demo_, expire au bout de 24 heures et dispose de ses propres limites et de son stockage temporaire.
Utiliser le jeton
Le support SERTEC PESAGE fournit le jeton. Incluez-le dans toutes les requêtes vers /api/v1 :
Code
Utilisez HTTPS, avec TLS 1.2 ou ultérieur, et envoyez le jeton uniquement dans cet en-tête. Il est opaque : ne le décodez pas et ne générez pas de JWT. sk_test_ sélectionne le développement et sk_live_ la production, avec les mêmes routes et des documents séparés.
Code
IP autorisées
Si le jeton possède une liste d'IP autorisées, les requêtes doivent provenir de l'une de ces IP publiques de sortie. Un jeton valide depuis une IP non autorisée reçoit 403. Une liste vide autorise toute IP. Cette restriction complète la protection du jeton et des serveurs autorisés.
L'API ne permet pas d'enregistrer des IP. Envoyer X-Forwarded-For n'autorise aucune adresse. Contactez le support avant de modifier une IP de sortie.
Protéger les identifiants
- Conservez les jetons dans un gestionnaire de secrets ou une configuration serveur protégée.
- Appelez depuis le serveur ; n'exposez pas le jeton dans des pages web, du JavaScript de navigateur ou des applications distribuées à des tiers.
- Excluez les jetons des URL, dépôts, journaux, captures et tickets de support.
- Utilisez un identifiant distinct par intégration.
- En cas de fuite suspectée, demandez la révocation et un nouveau jeton.
L'URL du QR contient un autre secret. Utilisez le lien renvoyé sans modification, sans le publier ni l'enregistrer. L'accès par QR utilise ce secret, sans Bearer ni restrictions d'IP de l'API.
Limites et nouvelles tentatives
Chaque jeton autorise 60 requêtes par minute. Le téléchargement par QR autorise 30 requêtes par minute pour la même IP et le même document. Sur 429, attendez le nombre de secondes indiqué dans Retry-After.
Le corps d'une requête est limité à 128 KiB. Envoyez du JSON avec Content-Type: application/json ; un autre format renvoie 415, un JSON mal formé renvoie 400.
Les références identifient des versions et sont uniques dans l'organisation et l'environnement. Répéter une création avec la même référence et les mêmes données renvoie le document original pendant 24 heures. Sans référence, chaque création émet un nouveau document. Une rectification exige de renvoyer toutes les données et, si elle est fournie, une nouvelle référence. L'original et son QR sont conservés.
Les consultations et téléchargements avec Bearer sont limités aux documents émis par cet identifiant durant les dernières 24 heures. Le QR reste accessible pendant la conservation du PDF, après ce délai et après rotation ou révocation du jeton. Les documents supprimés ne peuvent pas être téléchargés. La suppression logique n'est autorisée que dans les 2 heures, avant la remise ou l'utilisation du document ; le premier accès valide par QR la bloque également avec 409 DOCUMENT_ALREADY_ACCESSED. Un accès par QR ne prouve pas, à lui seul, que le transport a eu lieu.
Le déploiement doit exécuter le planificateur Laravel. La tâche horaire documents:prune-recent-keys supprime les clés d'accès récent expirées ; l'API applique les 24 heures même si le nettoyage n'a pas encore été exécuté.
Compte du portail et récupération
Le code de récupération appartient à un compte du portail ; ce n'est pas un jeton API et il n'est pas envoyé dans l'en-tête Bearer. L'inscription, y compris les administrateurs supplémentaires, exige de configurer la première passkey, d'imprimer ou de télécharger le code puis de le saisir à nouveau avant la création du compte. DeCA n'affiche plus le code enregistré.
Si la passkey échoue, une fenêtre modale permet de saisir le code. La connexion exige toujours le bon mot de passe ; le code remplace la passkey et ouvre les mêmes clés de l'archive chiffrée. Les opérations demandant le mot de passe actuel continuent de l'exiger. Annuler revient au formulaire précédent sans effectuer l'opération.
Le code peut confirmer toute opération demandant une passkey, y compris sa propre régénération et la suppression de passkeys. Si une passkey est utilisée pour en supprimer une autre, elle doit être différente de celle supprimée ; chaque utilisateur en conserve toujours au moins une. Dans Sécurité, le précédent code reste actif jusqu'à l'impression ou au téléchargement puis à la nouvelle saisie correcte du nouveau ; il est alors invalidé, avec ses confirmations en attente.
Conservez le code hors du système, dans un lieu privé séparé du mot de passe. Ne l'incluez pas dans les appels API, journaux ni messages au support. Perdre les identifiants capables d'ouvrir les clés peut empêcher de récupérer l'archive.
Conservation et copies privées
Les PDF sont conservés un an et les données structurées chiffrées quatre ans, à compter de l'émission ou de la date du transport si elle est postérieure. L'accès Bearer reste limité à 24 heures. Le QR permet d'accéder au PDF sans compte pendant sa conservation ; la rotation ou la révocation du jeton ne le désactive pas à elle seule. Après le retrait du PDF, l'ancien QR n'en permet plus le téléchargement.
Tant que les données sont conservées, une personne autorisée peut déverrouiller l'archive dans le portail et générer une copie privée du PDF. Elle est générée à nouveau : elle ne récupère pas les octets du fichier original supprimé, n'est pas enregistrée comme nouveau PDF permanent et ne réactive pas le QR expiré. La langue et le logo de l'émission sont conservés lorsqu'ils figurent dans les données originales.
Le chiffrement ne signifie pas que le serveur ne traite jamais de clés : la vérification du code de récupération et la génération d'une copie privée utilisent des clés de façon transitoire. Ni le code en clair ni la clé de données reçue pour régénérer ne sont conservés durablement.
Les sauvegardes Hostinger sont conservées 7 jours. Des copies manuelles du projet en ZIP et de la base de données en SQL peuvent également être réalisées : conservez-les hors de l'accès public, protégées et avec un accès restreint. Le stockage privé des clés temporaires des dernières 24 heures est séparé du projet et de la base de données et doit rester hors de ces copies ZIP et SQL. Après restauration, appliquez la purge selon les délais de conservation et invalidez les sessions et les accès temporaires avant de rouvrir le service. Les sauvegardes n'autorisent pas une conservation illimitée.
Données du transport et périmètre
Pour le transport intérieur de marchandises par route en Espagne, l'Arrêté FOM/2861/2012 exige nom, identifiant fiscal et adresse du chargeur contractuel ; nom et identifiant fiscal du transporteur effectif ; lieux de chargement et déchargement ; nature et poids des marchandises, ou une autre grandeur si le poids est difficile à déterminer ; date de transport, immatriculations du véhicule et de la remorque et autorisation spéciale de circulation si nécessaire.
origin.place et destination.place peuvent identifier un site par nom ou adresse. Avec city et country, ils doivent identifier clairement le lieu réel ; les champs facultatifs street et postal_code apportent une précision. Cet arrêté n'exige pas l'identité complète du destinataire. carrier.address est facultatif ; s'il est fourni, tous les champs d'Address sont requis. Indiquez la date réelle, les données exactes des marchandises et la remorque si elle existe.
Les opérateurs doivent garantir conservation et disponibilité pendant au moins un an, y compris l'accès des autres intervenants. La génération du PDF n'établit pas de certification eFTI et ne remplace pas CMR internationale, ADR, documents de transfert de déchets ou sous-produits animaux. Ce document de contrôle administratif n'exige généralement pas de signature électronique ; d'autres usages contractuels peuvent nécessiter une signature appropriée.
Résoudre les problèmes d'accès
| Réponse | Vérification |
|---|---|
401 | Jeton absent, incorrect ou révoqué. Vérifiez l'en-tête et contactez le support pour le remplacer. |
403 | Vérifiez l'IP publique de sortie et demandez l'autorisation. Cela peut aussi indiquer une opération interdite. |
Pour contacter le support, indiquez l'heure, l'IP publique de sortie, la méthode, la route et le code d'erreur. N'envoyez jamais le jeton ni le lien secret du QR.
Exigences électroniques : Résolution du 5 juin 2026. Le PDF électronique est limité à 5 MB, comporte des métadonnées de création et modification et offre un accès HTTPS direct. Utiliser l'API ne remplace pas les obligations opérationnelles des intervenants.
Les huit langues traduisent les titres et libellés du PDF, pas les noms, adresses, observations ni autres données transmises par l'intégration. Les textes imprimés acceptent les caractères latins, grecs et cyrilliques compatibles avec les polices ; emoji, CJK et écritures de droite à gauche renvoient 422 UNSUPPORTED_CHARACTERS pour le champ concerné. metadata conserve tout Unicode et n'est pas imprimée.
Les URL des documents utilisent l'URL HTTPS publique configurée par l'opérateur du service. Une configuration invalide renvoie 503 SERVICE_UNAVAILABLE ; une émission échouée ne conserve aucun document partiel.
Les NIF espagnols spéciaux K, L et M sont validés par format ; DNI, NIE et NIF d'entités conservent la vérification du caractère de contrôle. Valider un identifiant ne prouve ni l'existence ni l'immatriculation fiscale.