Guia de integração

Experimentar a API com um token demo

Podes pedir um token sk_demo_ sem uma conta nem o registo de uma organização. Dura 24 horas a partir da emissão e funciona apenas a partir do IP público que o pediu. Mudar de rede ou de IP exige outro token.

Utiliza apenas dados fictícios. Todas as páginas do PDF apresentam SEM VALIDADE junto do logótipo e uma marca diagonal DEMO. Estes documentos não são válidos para transportar mercadorias nem para uso administrativo.

1. Pedir o token

Envia um objeto JSON vazio para este endpoint público. Não é necessário um cabeçalho Bearer. A resposta 201 contém token e expires_at; a data de expiração é expressa em UTC.

Podes incluir document_locale ao solicitar o token: es, ca, gl, ca-valencia, eu, en, pt-pt ou fr. Por exemplo, {"document_locale":"en"} gera os seus PDF em inglês. Sem este campo, utiliza-se es. A resposta inclui o idioma escolhido; pede um novo token para o alterar.

Código
curl 'https://deca.sertecpesage.com/api/v1/demo/tokens' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{}'

Código
{
  "token": "sk_demo_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "expires_at": "2026-10-07T11:00:00Z",
  "document_locale": "es"
}

2. Emitir um documento de exemplo

Guarda este JSON como document.json. A demonstração utiliza as mesmas rotas e campos do contrato habitual e valida os dados do transporte. Os nomes, moradas e referências do exemplo são fictícios.

Código
{
  "reference": "DEMO-001",
  "transport_date": "2026-10-06",
  "shipper": {
    "name": "Empresa de ejemplo, S. L.",
    "tax_country": "ES",
    "tax_id": "B12345674",
    "address": {
      "street": "Calle de Ejemplo, 1",
      "postal_code": "08040",
      "city": "Barcelona",
      "country": "ES"
    }
  },
  "carrier": {
    "name": "Transportes de ejemplo, S. L.",
    "tax_country": "ES",
    "tax_id": "B87654323"
  },
  "origin": {
    "place": "Almacén de ejemplo",
    "city": "Barcelona",
    "country": "ES"
  },
  "destination": {
    "place": "Centro de ejemplo",
    "city": "Zaragoza",
    "country": "ES"
  },
  "goods": {
    "description": "Mercancía de demostración",
    "weight_kg": "1850.000"
  },
  "vehicle": {
    "country": "ES",
    "registration": "4827 MNL"
  },
  "metadata": {
    "example": true
  }
}

Envia o pedido a partir do mesmo IP e substitui YOUR_DEMO_TOKEN pelo token recebido:

Código
curl 'https://deca.sertecpesage.com/api/v1/documents' \
  --request POST \
  --header 'Authorization: Bearer YOUR_DEMO_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data @document.json

A resposta contém uuid, url, qr, pdf_download_url, normalized_data, metadata, rectifies_uuid e document_locale, como na API habitual. A demo acrescenta expires_at, qr_url e pdf_url. Guarda o UUID e utiliza os URL recebidos.

Apenas na demo é também devolvido demo: true; o PDF utiliza o document_locale escolhido ao solicitar o token, com es por predefinição. qr_url é um alias de url e pdf_url de pdf_download_url.

3. Consultar o documento e abrir o PDF

Podes listar, consultar, retificar e eliminar documentos com as operações da referência da API. Os pedidos Bearer continuam a exigir o mesmo token e IP. Para consultar o documento:

Código
curl 'https://deca.sertecpesage.com/api/v1/documents/DOCUMENT_UUID' \
  --header 'Authorization: Bearer YOUR_DEMO_TOKEN' \
  --header 'Accept: application/json'

O QR abre o PDF diretamente no navegador através de /demo/d/{uuid}?k=..., sem Bearer. O documento e as suas ligações expiram com a sessão demo; criar ou retificar um documento não prolonga a duração do token.

Um token demo expirado ou enviado de outro IP devolve 401. Um QR demo expirado devolve 404. Se a demo estiver desativada, devolve 503 DEMO_UNAVAILABLE. O primeiro acesso ao QR ou uma retificação impedem a eliminação do documento; mantêm-se as confirmações de eliminação do contrato habitual.

Expiração, limites e privacidade

A demo utiliza armazenamento temporário próprio, separado dos utilizadores, organizações e documentos reais. Os seus dados e PDF não têm as garantias de encriptação nem os prazos de conservação do arquivo real. Não envies dados pessoais, segredos nem documentos de transportes reais.

O token, os seus documentos e as suas ligações expiram 24 horas após a emissão do token; o armazenamento ativo é limpo periodicamente. As cópias de Hostinger dos últimos sete dias e as cópias manuais anteriores à eliminação podem conservar dados demo até serem retiradas. A expiração não implica a eliminação irreversível de todas as cópias.

A demo aceita corpos até 32 KiB e dez documentos por sessão. A emissão de tokens permite três por minuto e dez por hora a partir do mesmo IP; a criação de documentos permite cinco por minuto e vinte por hora a partir do mesmo IP. Os limites partilhados por rede, região e carga global podem aplicar-se mais cedo. Estes valores correspondem à configuração predefinida.

A emissão de tokens, os pedidos, os documentos e as transferências têm limites para evitar abusos. Também se aplicam controlos por IP, rede, região e carga global; os limites partilhados podem impedir um pedido mesmo antes de o teu token atingir o seu próprio limite. Ao receber 429, espera os segundos indicados em Retry-After.

O controlo por região não consulta qualquer serviço de geolocalização de IP. Só utiliza CF-IPCountry quando o pedido chega de um proxy verificado incluído em DEMO_TRUSTED_GEO_PROXIES, que deve substituir os cabeçalhos da Cloudflare. De outras origens, esses cabeçalhos são ignorados e todos os pedidos partilham o bucket regional unverified; não são atribuídos a um país verificado.

Protege o token e o segredo k das ligações; não os publiques nem os incluas nos registos. Para uma integração permanente, pede acesso à SERTEC PESAGE. Os ambientes sk_test_ e sk_live_ mantêm as suas próprias regras e dados.