Credencials i seguretat
Esta guia descriu els tokens sk_test_ i sk_live_. La demostració pública utilitza sk_demo_, caduca al cap de 24 hores i té límits i emmagatzematge temporal propis.
Utilitzar el token
El suport de SERTEC PESAGE proporciona el token. Inclou-lo a totes les peticions a /api/v1:
Codi
Utilitza HTTPS, amb TLS 1.2 o posterior, i envia el token només en esta capçalera. És opac: no el descodifiquis ni generis un JWT. sk_test_ selecciona desenvolupament i sk_live_ producció, amb les mateixes rutes i documents separats.
Codi
IP autoritzades
Si el token té una llista d'IP autoritzades, les peticions han de procedir d'una d'estes IP públiques de eixida. Un token vàlid des d'una IP no autoritzada rep 403. Una llista buida permet qualsevol IP. Esta restricció complementa la protecció del token i dels servidors autoritzats.
L'API no permet donar d'alta IP. Enviar X-Forwarded-For no autoritza cap adreça. Contacta amb suport abans de canviar una IP de eixida.
Protegir les credencials
- Desa els tokens en un gestor de secrets o a la configuració protegida del servidor.
- Fes les crides des del servidor; no exposis el token en pàgines web, JavaScript del navegador o aplicacions distribuïdes a tercers.
- No incloguis tokens en URL, repositoris, registres, captures ni tiquets de suport.
- Utilitza una credencial independent per a cada integració.
- Si sospites una filtració, sol·licita la revocació i un token nou.
La URL del QR conté un altre secret. Utilitza l'enllaç retornat sense modificar-lo i no el publiquis ni registris. L'accés per QR utilitza este secret, sense Bearer ni les restriccions d'IP de l'API.
Límits i reintents
Cada token admet 60 peticions per minut. La descàrrega per QR admet 30 peticions per minut per a la mateixa IP i document. Si reps 429, espera els segons de Retry-After.
El cos de la petició té un màxim de 128 KiB. Envia JSON amb Content-Type: application/json; un altre format retorna 415 i un JSON malformat, 400.
Les referències identifiquen versions i són úniques dins de l'organització i l'entorn. Repetir una creació amb la mateixa referència i les mateixes dades retorna el document original durant 24 hores. Sense referència, cada creació emet un document nou. Les rectificacions exigeixen tornar a enviar totes les dades i, si s'informa, una referència nova. L'original i el seu QR es conserven.
Les consultes i descàrregues amb Bearer es limiten als documents emesos per esta credencial en les últimes 24 hores. El QR continua funcionant durant la conservació del PDF, després del termini i de rotar o revocar el token. Els documents eliminats no es poden descarregar. L'esborrament lògic només es permet dins de 2 hores, abans de lliurar o utilitzar el document; el primer accés vàlid per QR també el bloqueja amb 409 DOCUMENT_ALREADY_ACCESSED. L'accés per QR no demostra per si sol que s'haja fet el transport.
El desplegament ha d'executar el planificador de Laravel. La tasca horària documents:prune-recent-keys elimina les claus d'accés recent vençudes; l'API aplica les 24 hores encara que la neteja no s'haja executat.
Compte del portal i recuperació
El codi de recuperació pertany a un compte del portal; no és un token API ni s'envia a la capçalera Bearer. L'alta, inclosos els administradors addicionals, exigeix configurar la primera passkey, imprimir o descarregar el codi i tornar-lo a introduir abans de crear el compte. DeCA no torna a mostrar el codi guardat.
Si falla la passkey, un modal permet introduir el codi. L'inici de sessió continua exigint la contrasenya correcta; el codi substitueix la passkey i obre les mateixes claus de l'arxiu xifrat. Les operacions que demanen la contrasenya actual continuen exigint-la. Cancel·lar torna al formulari anterior sense executar l'operació.
El codi pot confirmar qualsevol operació que demane una passkey, incloses la seua regeneració i l'eliminació de passkeys. Si es fa servir una passkey per esborrar-ne una altra, ha de ser diferent de l'eliminada; cada usuari en conserva sempre almenys una. A Seguretat, el codi anterior continua actiu fins a imprimir o descarregar i tornar a introduir correctament el nou; aleshores s'invalida, juntament amb les confirmacions pendents.
Guarda el codi fora del sistema, en un lloc privat i separat de la contrasenya. No l'incloguis en crides a l'API, registres ni missatges a suport. Perdre les credencials que obren les claus pot impedir recuperar l'arxiu.
Conservació i còpies privades
Els PDF es conserven un any i les dades estructurades xifrades quatre anys, des de l'emissió o la data de transport si és posterior. L'accés amb Bearer continua limitat a 24 hores. El QR permet accedir al PDF sense compte durant la conservació del PDF; rotar o revocar el token no el desactiva per si sol. Un cop retirat el PDF, l'antic QR ja no en permet la descàrrega.
Mentre es conserven les dades, una persona autoritzada pot desbloquejar l'arxiu al portal i generar una còpia privada del PDF. És una nova generació: no recupera els bytes del fitxer original eliminat, no es desa com a nou PDF permanent i no reactiva el QR vençut. Es mantenen l'idioma i el logo de l'emissió quan consten a les dades originals.
El xifrat no implica que el servidor no gestioni mai claus: la verificació del codi de recuperació i la generació d'una còpia privada utilitzen material de clau transitori. No es persisteixen el codi en text ni la clau de dades rebuda per regenerar.
Les còpies de Hostinger es conserven 7 dies. També es poden fer còpies manuals del projecte en ZIP i de la base de dades en SQL: guarda-les fora de l'accés públic, protegides i amb accés restringit. El magatzem privat de claus temporals de les últimes 24 hores està separat del projecte i de la base de dades, i ha de quedar fora d'estos ZIP i SQL. Després de restaurar, executa la purga segons els terminis de conservació i invalida les sessions i els accessos temporals abans de reobrir el servei. Les còpies no concedeixen conservació il·limitada.
Dades del transport i abast
Per al transport interior de mercaderies per carretera a Espanya, l'Ordre FOM/2861/2012 exigeix nom, NIF i domicili del carregador contractual; nom i NIF del transportista efectiu; llocs de càrrega i descàrrega; naturalesa i pes de la mercaderia, o una magnitud alternativa si és difícil determinar el pes; data del transport, matrícules del vehicle i del remolc i l'autorització especial de circulació quan calgui.
origin.place i destination.place poden identificar una instal·lació pel nom o l'adreça. Amb city i country, han d'identificar clarament el lloc real; street i postal_code opcionals aporten precisió. Esta ordre no exigeix la identificació completa del destinatari. carrier.address és opcional; si s'envia, ha de contenir tots els camps d'Address. Informa la data real, les dades correctes de la mercaderia i el remolc quan existeixi.
Els operadors han de garantir-ne la conservació i disponibilitat durant almenys un any, inclòs l'accés dels altres intervinents. Generar el PDF no implica certificació eFTI ni substitueix el CMR internacional, ADR, documents de trasllat de residus o subproductes animals. Este document de control administratiu no exigeix amb caràcter general una signatura electrònica; altres usos contractuals poden requerir una signatura adequada.
Resoldre problemes d'accés
| Resposta | Comprovació |
|---|---|
401 | Token absent, incorrecte o revocat. Revisa la capçalera i contacta amb suport per substituir-lo. |
403 | Comprova la IP pública de eixida i demana'n l'autorització. També pot indicar una operació no permesa. |
Quan contactis amb suport, facilita l'hora, la IP pública de eixida, el mètode, la ruta i el codi d'error. No enviïs mai el token ni l'enllaç secret del QR.
Requisits electrònics: Resolució de 5 de juny de 2026. El PDF electrònic té un màxim de 5 MB, metadades de creació i modificació i accés directe HTTPS. Utilitzar l'API no substitueix les obligacions operatives dels intervinents.
Els vuit idiomes tradueixen els títols i les etiquetes del PDF, no els noms, les adreces, les observacions ni altres dades enviades per la integració. Els textos impresos admeten caràcters llatins, grecs i ciríl·lics compatibles amb les fonts; emoji, CJK i escriptures de dreta a esquerra retornen 422 UNSUPPORTED_CHARACTERS al camp afectat. metadata conserva Unicode arbitrari i no s'imprimeix.
Les URL dels documents utilitzen la URL pública HTTPS configurada per l'operador del servici. Si no és vàlida, es retorna 503 SERVICE_UNAVAILABLE; una emissió fallida no persisteix un document parcial.
Els NIF espanyols especials K, L i M es validen pel format; DNI, NIE i NIF d'entitats mantenen la comprovació del caràcter de control. Validar un identificador no acredita existència ni alta censal.