Integration guide

Try the API with a demo token

You can request an sk_demo_ token without an account or a registered organisation. It lasts 24 hours from issuance and works only from the public IP that requested it. Changing network or IP requires another token.

Use fictitious data only. Every PDF page displays NOT VALID beside the logo and a diagonal DEMO watermark. These documents are not valid for transporting goods or for administrative use.

1. Request the token

Send an empty JSON object to this public endpoint. No Bearer header is required. The 201 response contains token and expires_at; the expiry time is expressed in UTC.

Include document_locale when requesting the token: es, ca, gl, ca-valencia, eu, en, pt-pt or fr. For example, {"document_locale":"en"} generates its PDFs in English. Without this field, es is used. The response includes the selected language; request a new token to change it.

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

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

2. Issue a sample document

Save this JSON as document.json. The demonstration uses the same routes and fields as the standard contract and validates transport data. The names, addresses and references in this example are fictitious.

Code
{
  "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
  }
}

Send the request from the same IP, replacing YOUR_DEMO_TOKEN with the token you received:

Code
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

The response contains uuid, url, qr, pdf_download_url, normalized_data, metadata, rectifies_uuid and document_locale, as in the standard API. The demo adds expires_at, qr_url and pdf_url. Save the UUID and use the returned URLs.

Only the demo also returns demo: true; its PDF uses the document_locale selected when requesting the token, defaulting to es. qr_url is an alias of url, and pdf_url an alias of pdf_download_url.

3. Retrieve the document and open the PDF

You can list, retrieve, rectify and delete documents using the operations in the API reference. Bearer requests still require the same token and IP. To retrieve the document:

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

The QR opens the PDF directly in the browser through /demo/d/{uuid}?k=..., without Bearer authentication. The document and its links expire with the demo session; creating or rectifying a document does not extend the token’s lifetime.

An expired demo token or one sent from a different IP returns 401. An expired demo QR returns 404. When the demo is disabled, it returns 503 DEMO_UNAVAILABLE. The first QR access or a rectification prevents deletion; the standard contract’s deletion confirmations still apply.

Expiry, limits and privacy

The demo uses its own temporary storage, separate from real users, organisations and documents. Its data and PDFs do not have the encryption guarantees or retention periods of the real archive. Do not send personal data, secrets or documents for real transports.

The token, its documents and its links expire 24 hours after token issuance; active storage is purged periodically. Hostinger backups from the last seven days and manual copies made before deletion may retain demo data until those copies are retired. Expiry does not mean irreversible removal of every copy.

The demo accepts bodies up to 32 KiB and ten documents per session. Token issuance allows three per minute and ten per hour from the same IP; document creation allows five per minute and twenty per hour from the same IP. Shared network, region and global load limits may apply earlier. These figures describe the default configuration.

Token issuance, requests, documents and downloads are limited to prevent abuse. Controls also apply by IP, network, region and global load; shared limits may block a request even before your token reaches its own limit. On 429, wait for the number of seconds in Retry-After.

Region controls do not call an IP geolocation service. They use CF-IPCountry only when the request comes from a verified proxy listed in DEMO_TRUSTED_GEO_PROXIES, which must overwrite Cloudflare headers. From other sources, these headers are ignored and all requests share the unverified regional bucket; they are not assigned to a verified country.

Protect the token and the links’ k secret; do not publish or log them. For a permanent integration, request access from SERTEC PESAGE. The sk_test_ and sk_live_ environments retain their own rules and data.