Credenciais e segurança
Este guia descreve os tokens sk_test_ e sk_live_. A demonstração pública utiliza sk_demo_, expira em 24 horas e tem limites e armazenamento temporário próprios.
Utilizar o token
O suporte da SERTEC PESAGE fornece o token. Inclua-o em todos os pedidos a /api/v1:
Código
Utilize HTTPS, com TLS 1.2 ou posterior, e envie o token apenas neste cabeçalho. É opaco: não o descodifique nem gere um JWT. sk_test_ seleciona desenvolvimento e sk_live_ produção, com as mesmas rotas e documentos separados.
Código
IP autorizados
Se o token tiver uma lista de IP autorizados, os pedidos devem provir de um desses IP públicos de saída. Um token válido de um IP não autorizado recebe 403. Uma lista vazia permite qualquer IP. A restrição complementa a proteção do token e dos servidores autorizados.
A API não permite registar IP. Enviar X-Forwarded-For não autoriza um endereço. Contacte o suporte antes de alterar um IP de saída.
Proteger as credenciais
- Guarde tokens num gestor de segredos ou na configuração protegida do servidor.
- Faça chamadas a partir do servidor; não exponha o token em páginas web, JavaScript do navegador ou aplicações distribuídas a terceiros.
- Não inclua tokens em URL, repositórios, registos, capturas nem pedidos de suporte.
- Utilize uma credencial independente por integração.
- Se suspeitar de uma fuga, peça a revogação e um novo token.
A URL do QR contém outro segredo. Utilize a ligação devolvida sem a modificar e não a publique nem registe. O acesso por QR utiliza esse segredo, sem Bearer nem as restrições de IP da API.
Limites e novas tentativas
Cada token admite 60 pedidos por minuto. A descarga por QR admite 30 pedidos por minuto para o mesmo IP e documento. Se receber 429, aguarde os segundos de Retry-After.
O corpo do pedido tem um máximo de 128 KiB. Envie JSON com Content-Type: application/json; outro formato devolve 415 e JSON malformado, 400.
As referências identificam versões e são únicas na organização e no ambiente. Repetir uma criação com a mesma referência e os mesmos dados devolve o documento original durante 24 horas. Sem referência, cada criação emite um documento novo. As retificações exigem o reenvio de todos os dados e, se indicada, uma nova referência. O original e o seu QR são conservados.
As consultas e descargas com Bearer limitam-se aos documentos emitidos por essa credencial nas últimas 24 horas. O QR continua a funcionar durante a conservação do PDF, após o prazo e após rodar ou revogar o token. Documentos eliminados não podem ser descarregados. A eliminação lógica só é permitida no prazo de 2 horas, antes de entregar ou utilizar o documento; o primeiro acesso válido por QR também a bloqueia com 409 DOCUMENT_ALREADY_ACCESSED. O acesso por QR não prova, por si só, que o transporte se realizou.
O deployment deve executar o agendador do Laravel. A tarefa horária documents:prune-recent-keys elimina as chaves de acesso recente expiradas; a API aplica as 24 horas mesmo que a limpeza não tenha sido executada.
Conta do portal e recuperação
O código de recuperação pertence a uma conta do portal; não é um token API nem é enviado no cabeçalho Bearer. O registo, incluindo administradores adicionais, exige configurar a primeira passkey, imprimir ou descarregar o código e introduzi-lo novamente antes de criar a conta. A DeCA não volta a mostrar o código guardado.
Se a passkey falhar, um modal permite introduzir o código. O início de sessão continua a exigir a palavra-passe correta; o código substitui a passkey e abre as mesmas chaves do arquivo cifrado. As operações que pedem a palavra-passe atual continuam a exigi-la. Cancelar volta ao formulário anterior sem executar a operação.
O código pode confirmar qualquer operação que solicite uma passkey, incluindo a sua própria regeneração e a eliminação de passkeys. Se for usada uma passkey para eliminar outra, tem de ser diferente da eliminada; cada utilizador mantém sempre pelo menos uma. Em Segurança, o código anterior continua ativo até imprimir ou descarregar e introduzir corretamente o novo; depois é invalidado, juntamente com as confirmações pendentes.
Guarde o código fora do sistema, num local privado separado da palavra-passe. Não o inclua em chamadas à API, registos nem mensagens de suporte. Perder as credenciais que abrem as chaves pode impedir recuperar o arquivo.
Conservação e cópias privadas
Os PDF são conservados durante um ano e os dados estruturados cifrados durante quatro anos, a partir da emissão ou da data de transporte se posterior. O acesso com Bearer continua limitado a 24 horas. O QR permite acesso ao PDF sem conta durante a conservação do PDF; rodar ou revogar o token não o desativa por si só. Depois de retirar o PDF, o antigo QR já não permite descarregá-lo.
Enquanto os dados forem conservados, uma pessoa autorizada pode desbloquear o arquivo no portal e gerar uma cópia privada do PDF. É uma nova geração: não recupera os bytes do ficheiro original eliminado, não é guardada como novo PDF permanente e não reativa o QR expirado. O idioma e o logótipo da emissão são mantidos quando constam dos dados originais.
A cifragem não significa que o servidor nunca trate chaves: a verificação do código de recuperação e a geração de uma cópia privada utilizam material de chave transitório. Não são persistidos o código em texto simples nem a chave de dados recebida para regenerar.
As cópias de Hostinger são conservadas durante 7 dias. Também podem ser feitas cópias manuais do projeto em ZIP e da base de dados em SQL: guarde-as fora do acesso público, protegidas e com acesso restrito. O armazenamento privado de chaves temporárias das últimas 24 horas está separado do projeto e da base de dados e deve ficar fora dessas cópias ZIP e SQL. Após restaurar, execute a limpeza de acordo com os prazos de conservação e invalide as sessões e os acessos temporários antes de reabrir o serviço. As cópias não concedem conservação ilimitada.
Dados do transporte e âmbito
Para o transporte interno de mercadorias por estrada em Espanha, a Ordem FOM/2861/2012 exige nome, NIF e morada do carregador contratual; nome e NIF do transportador efetivo; locais de carga e descarga; natureza e peso da mercadoria, ou outra grandeza se o peso for difícil de determinar; data do transporte, matrículas do veículo e do reboque e autorização especial de circulação quando necessária.
origin.place e destination.place podem identificar uma instalação pelo nome ou morada. Com city e country, devem identificar claramente o local real; os campos opcionais street e postal_code acrescentam precisão. A ordem não exige a identidade completa do destinatário. carrier.address é opcional; se fornecido, deve incluir todos os campos de Address. Indique a data real, dados corretos da mercadoria e o reboque quando exista.
Os operadores devem garantir conservação e disponibilidade durante pelo menos um ano, incluindo o acesso pelos restantes intervenientes. Gerar o PDF não implica certificação eFTI nem substitui CMR internacional, ADR, documentos de transferência de resíduos ou subprodutos animais. Este documento de controlo administrativo não exige, em geral, assinatura eletrónica; outros usos contratuais podem exigir uma assinatura adequada.
Resolver problemas de acesso
| Resposta | Verificação |
|---|---|
401 | Token ausente, incorreto ou revogado. Verifique o cabeçalho e contacte o suporte para o substituir. |
403 | Verifique o IP público de saída e peça autorização. Pode também indicar uma operação não permitida. |
Ao contactar o suporte, indique a hora, o IP público de saída, o método, a rota e o código de erro. Nunca envie o token nem a ligação secreta do QR.
Requisitos eletrónicos: Resolução de 5 de junho de 2026. O PDF eletrónico tem um máximo de 5 MB, metadados de criação e modificação e acesso direto HTTPS. Utilizar a API não substitui as obrigações operacionais dos intervenientes.
Os oito idiomas traduzem os títulos e etiquetas do PDF, não os nomes, moradas, observações nem outros dados enviados pela integração. Os textos impressos admitem carateres latinos, gregos e cirílicos compatíveis com as fontes; emoji, CJK e escritas da direita para a esquerda devolvem 422 UNSUPPORTED_CHARACTERS no campo afetado. metadata conserva Unicode arbitrário e não é impressa.
As URL dos documentos utilizam a URL pública HTTPS configurada pelo operador do serviço. Se for inválida, é devolvido 503 SERVICE_UNAVAILABLE; uma emissão falhada não persiste um documento parcial.
Os NIF espanhóis especiais K, L e M são validados pelo formato; DNI, NIE e NIF de entidades mantêm a verificação do caráter de controlo. Validar um identificador não comprova existência nem registo fiscal.