Credenciais e seguridade
Esta guía describe os tokens sk_test_ e sk_live_. A demostración pública utiliza sk_demo_, caduca en 24 horas e ten límites e almacenamento temporal propios.
Usar o token
O soporte de SERTEC PESAGE proporciona o token. Inclúeo en todas as peticións a /api/v1:
Código
Usa HTTPS, con TLS 1.2 ou posterior, e envía o token só nesta cabeceira. É opaco: non o descodifiques nin xeres un JWT. sk_test_ selecciona desenvolvemento e sk_live_ produción, coas mesmas rutas e documentos separados.
Código
IP autorizadas
Se o token ten unha lista de IP autorizadas, as peticións deben proceder dunha desas IP públicas de saída. Un token válido desde unha IP non autorizada recibe 403. Unha lista baleira permite calquera IP. A restrición complementa a protección do token e dos servidores autorizados.
A API non permite dar de alta IP. Enviar X-Forwarded-For non autoriza unha dirección. Contacta con soporte antes de cambiar unha IP de saída.
Protexer as credenciais
- Garda os tokens nun xestor de segredos ou na configuración protexida do servidor.
- Fai as chamadas desde o servidor; non expoñas o token en páxinas web, JavaScript do navegador ou aplicacións distribuídas a terceiros.
- Non inclúas tokens en URL, repositorios, rexistros, capturas nin incidencias de soporte.
- Usa unha credencial independente para cada integración.
- Se sospeitas unha filtración, solicita a revogación e un token novo.
A URL do QR contén outro segredo. Usa a ligazón devolta sen modificala e non a publiques nin rexistres. O acceso por QR usa ese segredo, sen Bearer nin as restricións de IP da API.
Límites e reintentos
Cada token admite 60 peticións por minuto. A descarga por QR admite 30 peticións por minuto para a mesma IP e documento. Se recibes 429, agarda os segundos de Retry-After.
O corpo da petición ten un máximo de 128 KiB. Envía JSON con Content-Type: application/json; outro formato devolve 415 e un JSON mal formado, 400.
As referencias identifican versións e son únicas dentro da organización e do contorno. Repetir unha creación coa mesma referencia e cos mesmos datos devolve o documento orixinal durante 24 horas. Sen referencia, cada creación emite un documento novo. As rectificacións esixen volver enviar todos os datos e, se se indica, unha referencia nova. O orixinal e o seu QR consérvanse.
As consultas e descargas con Bearer limítanse aos documentos emitidos por esa credencial nas últimas 24 horas. O QR segue funcionando durante a conservación do PDF, despois do prazo e de rotar ou revogar o token. Os documentos eliminados non se poden descargar. O borrado lóxico só se permite dentro de 2 horas, antes de entregar ou usar o documento; o primeiro acceso válido por QR tamén o bloquea con 409 DOCUMENT_ALREADY_ACCESSED. O acceso por QR non demostra por si só que se realizase o transporte.
O despregamento debe executar o planificador de Laravel. A tarefa horaria documents:prune-recent-keys elimina as claves de acceso recente caducadas; a API aplica as 24 horas aínda que a limpeza non se executase.
Conta do portal e recuperación
O código de recuperación pertence a unha conta do portal; non é un token API nin se envía na cabeceira Bearer. A alta, incluídos os administradores adicionais, esixe configurar a primeira passkey, imprimir ou descargar o código e introducilo de novo antes de crear a conta. DeCA non volve mostrar o código gardado.
Se falla a passkey, un modal permite introducir o código. O inicio de sesión segue esixindo o contrasinal correcto; o código substitúe a passkey e abre as mesmas claves do arquivo cifrado. As operacións que piden o contrasinal actual seguen esixíndoo. Cancelar volve ao formulario anterior sen executar a operación.
O código pode confirmar calquera operación que solicite unha passkey, incluídas a súa rexeneración e a eliminación de passkeys. Se se emprega unha passkey para eliminar outra, debe ser distinta da eliminada; cada usuario conserva sempre polo menos unha. En Seguridade, o código anterior segue activo ata imprimir ou descargar e introducir correctamente o novo; entón invalídase, xunto coas confirmacións pendentes.
Garda o código fóra do sistema, nun lugar privado e separado do contrasinal. Non o inclúas en chamadas á API, rexistros nin mensaxes a soporte. Perder as credenciais que abren as claves pode impedir recuperar o arquivo.
Conservación e copias privadas
Os PDF consérvanse un ano e os datos estruturados cifrados catro anos, desde a emisión ou a data do transporte se é posterior. O acceso con Bearer segue limitado a 24 horas. O QR permite acceder ao PDF sen conta durante a conservación do PDF; rotar ou revogar o token non o desactiva por si só. Cando se retira o PDF, o antigo QR xa non permite descargalo.
Mentres se conservan os datos, unha persoa autorizada pode desbloquear o arquivo no portal e xerar unha copia privada do PDF. Xérase de novo: non recupera os bytes do ficheiro orixinal eliminado, non se garda como novo PDF permanente nin reactiva o QR vencido. Mantéñense o idioma e o logo da emisión cando figuran nos datos orixinais.
O cifrado non implica que o servidor nunca manexe claves: a verificación do código de recuperación e a xeración dunha copia privada empregan material de clave transitorio. Non se persisten o código en texto nin a clave de datos recibida para rexenerar.
As copias de Hostinger consérvanse 7 días. Tamén poden facerse copias manuais do proxecto en ZIP e da base de datos en SQL: gárdaas fóra do acceso público, protexidas e con acceso restrinxido. O almacén privado de claves temporais das últimas 24 horas está separado do proxecto e da base de datos, e debe quedar fóra deses ZIP e SQL. Tras restaurar, executa a purga segundo os prazos de conservación e invalida as sesións e os accesos temporais antes de reabrir o servizo. As copias non conceden conservación ilimitada.
Datos do transporte e alcance
Para o transporte interior de mercadorías por estrada en España, a Orde FOM/2861/2012 esixe nome, NIF e domicilio do cargador contractual; nome e NIF do transportista efectivo; lugares de carga e descarga; natureza e peso da mercadoría, ou outra magnitude se é difícil determinar o peso; data de transporte, matrículas do vehículo e do remolque e a autorización especial de circulación cando corresponda.
origin.place e destination.place poden identificar unha instalación polo nome ou o enderezo. Con city e country, deben identificar claramente o lugar real; street e postal_code opcionais achegan precisión. Esta orde non esixe a identificación completa do destinatario. carrier.address é opcional; se se envía, debe conter todos os campos de Address. Indica a data real, os datos correctos da mercadoría e o remolque cando exista.
Os operadores deben garantir a conservación e dispoñibilidade durante polo menos un ano, incluído o acceso dos demais intervenientes. Xerar o PDF non implica certificación eFTI nin substitúe o CMR internacional, ADR, documentos de traslado de residuos ou subprodutos animais. Este documento de control administrativo non esixe con carácter xeral unha sinatura electrónica; outros usos contractuais poden requirir unha sinatura axeitada.
Resolver problemas de acceso
| Resposta | Comprobación |
|---|---|
401 | Token ausente, incorrecto ou revogado. Revisa a cabeceira e contacta con soporte para substituílo. |
403 | Comproba a IP pública de saída e solicita a autorización. Tamén pode indicar unha operación non permitida. |
Ao contactar con soporte, facilita a hora, a IP pública de saída, o método, a ruta e o código de erro. Non envíes nunca o token nin a ligazón secreta do QR.
Requisitos electrónicos: Resolución do 5 de xuño de 2026. O PDF electrónico ten un máximo de 5 MB, metadatos de creación e modificación e acceso directo HTTPS. Usar a API non substitúe as obrigas operativas dos intervenientes.
Os oito idiomas traducen os títulos e etiquetas do PDF, non os nomes, enderezos, observacións nin outros datos enviados pola integración. Os textos impresos admiten caracteres latinos, gregos e cirílicos compatibles coas fontes; emoji, CJK e escrituras de dereita a esquerda devolven 422 UNSUPPORTED_CHARACTERS no campo afectado. metadata conserva Unicode arbitrario e non se imprime.
As URL dos documentos usan a URL pública HTTPS configurada polo operador do servizo. Se non é válida, devólvese 503 SERVICE_UNAVAILABLE; unha emisión fallida non persiste un documento parcial.
Os NIF españois especiais K, L e M valídanse polo formato; DNI, NIE e NIF de entidades manteñen a comprobación do carácter de control. Validar un identificador non acredita existencia nin alta censal.