Guía de integración

Probar a API cun token demo

Podes solicitar un token sk_demo_ sen conta nin alta dunha organización. Dura 24 horas desde a súa emisión e só funciona desde a IP pública que o solicitou. Cambiar de rede ou de IP require solicitar outro token.

Utiliza unicamente datos ficticios. Cada páxina do PDF mostra SEN VALIDEZ xunto ao logo e unha marca diagonal DEMO. Estes documentos non serven para transportar mercadorías nin como documentos administrativos válidos.

1. Solicitar o token

Envía un obxecto JSON baleiro a este endpoint público. Non precisa unha cabeceira Bearer. A resposta 201 contén token e expires_at; a data de caducidade exprésase en UTC.

Podes incluír document_locale ao solicitar o token: es, ca, gl, ca-valencia, eu, en, pt-pt ou fr. Por exemplo, {"document_locale":"en"} xera os seus PDF en inglés. Sen este campo utilízase es. A resposta inclúe o idioma escollido; para cambialo solicita un novo token.

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 un documento de exemplo

Garda este JSON como document.json. A demostración utiliza as mesmas rutas e campos do contrato habitual e valida os datos do transporte. Os nomes, enderezos e referencias do exemplo son ficticios.

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
  }
}

Envía a petición desde a mesma IP, substituíndo YOUR_DEMO_TOKEN polo token recibido:

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én uuid, url, qr, pdf_download_url, normalized_data, metadata, rectifies_uuid e document_locale, igual que a API habitual. Na demo engade expires_at, qr_url e pdf_url. Garda o UUID e utiliza as URL recibidas.

Só na demo se devolve tamén demo: true; o PDF utiliza o document_locale escollido ao solicitar o token, por defecto es. qr_url é un alias de url e pdf_url de pdf_download_url.

3. Consultar e abrir o PDF

Podes listar, consultar, rectificar e eliminar documentos coas operacións da referencia da API. As chamadas Bearer seguen esixindo o mesmo token e a mesma 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 directamente no navegador mediante /demo/d/{uuid}?k=..., sen Bearer. Tanto o documento como as súas ligazóns caducan coa sesión demo; crear ou rectificar un documento non amplía a duración do token.

Un token demo caducado ou enviado desde outra IP devolve 401. Un QR demo caducado devolve 404. Se a demo está desactivada, devolve 503 DEMO_UNAVAILABLE. O primeiro acceso ao QR ou unha rectificación impiden eliminar o documento; mantéñense as confirmacións de borrado do contrato habitual.

Caducidade, límites e privacidade

A demo ten almacenamento temporal propio, separado dos usuarios, organizacións e documentos reais. Os seus datos e PDF non teñen as garantías de cifrado nin os prazos de conservación do arquivo real. Non envíes datos persoais, segredos nin documentos de transportes reais.

O token, os seus documentos e as súas ligazóns caducan ás 24 horas desde a emisión do token; o borrado do almacenamento activo execútase periodicamente. As copias de Hostinger dos últimos sete días e as copias manuais anteriores ao borrado poden conservar datos demo ata que se retiren. A caducidade non implica unha eliminación irreversible de todas as copias.

A demo admite corpos de ata 32 KiB e dez documentos por sesión. A emisión de tokens admite tres por minuto e dez por hora desde unha mesma IP; a creación, cinco por minuto e vinte por hora desde unha mesma IP. Os límites compartidos por rede, rexión e carga global poden aplicarse antes. Estas cifras corresponden á configuración predeterminada.

Hai límites de emisión, peticións, documentos e descargas para evitar abusos. Tamén se aplican controis por IP, rede, rexión e carga global; os límites compartidos poden impedir unha petición aínda que o teu token non os alcanzase. Ante 429, agarda os segundos indicados en Retry-After.

O control por rexión non chama a ningún servizo de xeolocalización de IP. Só utiliza CF-IPCountry cando a petición chega desde un proxy verificado incluído en DEMO_TRUSTED_GEO_PROXIES, que debe sobrescribir as cabeceiras de Cloudflare. Desde outras orixes, esas cabeceiras ignóranse e todas as peticións comparten o bucket rexional unverified; non se atribúen a un país comprobado.

Protexe o token e o segredo k das ligazóns; non os publiques nin os inclúas nos rexistros. Para unha integración permanente, solicita acceso a SERTEC PESAGE. Os contornos sk_test_ e sk_live_ manteñen as súas propias regras e datos.