Guide d'intégration

Essayer l’API avec un jeton demo

Vous pouvez demander un jeton sk_demo_ sans compte ni organisation enregistrée. Il dure 24 heures à partir de son émission et fonctionne uniquement depuis l’IP publique qui l’a demandé. Un changement de réseau ou d’IP nécessite un autre jeton.

Utilisez uniquement des données fictives. Chaque page du PDF affiche SANS VALIDITÉ à côté du logo et un filigrane diagonal DEMO. Ces documents ne sont valables ni pour transporter des marchandises ni pour un usage administratif.

1. Demander le jeton

Envoyez un objet JSON vide à cet endpoint public. Aucun en-tête Bearer n’est nécessaire. La réponse 201 contient token et expires_at ; la date d’expiration est exprimée en UTC.

Incluez document_locale lors de la demande du jeton : es, ca, gl, ca-valencia, eu, en, pt-pt ou fr. Par exemple, {"document_locale":"en"} génère ses PDF en anglais. Sans ce champ, es est utilisé. La réponse indique la langue choisie ; demandez un nouveau jeton pour la modifier.

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. Émettre un document d’exemple

Enregistrez ce JSON dans document.json. La démonstration utilise les mêmes routes et champs que le contrat habituel et valide les données du transport. Les noms, adresses et références de l’exemple sont fictifs.

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

Envoyez la requête depuis la même IP en remplaçant YOUR_DEMO_TOKEN par le jeton reçu :

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

La réponse contient uuid, url, qr, pdf_download_url, normalized_data, metadata, rectifies_uuid et document_locale, comme l’API habituelle. La démo ajoute expires_at, qr_url et pdf_url. Conservez le UUID et utilisez les URL reçues.

La démo renvoie également demo: true ; son PDF utilise le document_locale choisi lors de la demande du jeton, par défaut es. qr_url est un alias de url et pdf_url de pdf_download_url.

3. Consulter le document et ouvrir le PDF

Vous pouvez lister, consulter, rectifier et supprimer des documents avec les opérations de la référence API. Les appels Bearer exigent toujours le même jeton et la même IP. Pour consulter le document :

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

Le QR ouvre directement le PDF dans le navigateur via /demo/d/{uuid}?k=..., sans Bearer. Le document et ses liens expirent avec la session demo ; créer ou rectifier un document ne prolonge pas la durée du jeton.

Un jeton demo expiré ou envoyé depuis une autre IP renvoie 401. Un QR demo expiré renvoie 404. Lorsque la démo est désactivée, elle renvoie 503 DEMO_UNAVAILABLE. Le premier accès au QR ou une rectification empêche la suppression du document ; les confirmations de suppression du contrat habituel restent requises.

Expiration, limites et confidentialité

La démo utilise son propre stockage temporaire, distinct des utilisateurs, organisations et documents réels. Ses données et PDF n’ont pas les garanties de chiffrement ni les durées de conservation de l’archive réelle. N’envoyez ni données personnelles, ni secrets, ni documents de transports réels.

Le jeton, ses documents et ses liens expirent 24 heures après l’émission du jeton ; le stockage actif est purgé périodiquement. Les sauvegardes de Hostinger des sept derniers jours et les copies manuelles réalisées avant la suppression peuvent conserver des données demo jusqu’à leur retrait. L’expiration ne signifie pas la suppression irréversible de toutes les copies.

La démo accepte des corps de requête jusqu’à 32 KiB et dix documents par session. L’émission de jetons permet trois par minute et dix par heure depuis la même IP ; la création de documents permet cinq par minute et vingt par heure depuis la même IP. Les limites partagées par réseau, région et charge globale peuvent s’appliquer plus tôt. Ces valeurs correspondent à la configuration par défaut.

L’émission de jetons, les requêtes, les documents et les téléchargements sont limités pour éviter les abus. Des contrôles s’appliquent également par IP, réseau, région et charge globale ; les limites partagées peuvent bloquer une requête avant même que votre jeton ait atteint sa propre limite. En cas de 429, attendez le nombre de secondes indiqué dans Retry-After.

Le contrôle par région ne consulte aucun service de géolocalisation IP. Il utilise CF-IPCountry uniquement lorsque la requête provient d’un proxy vérifié figurant dans DEMO_TRUSTED_GEO_PROXIES, qui doit remplacer les en-têtes Cloudflare. Depuis d’autres sources, ces en-têtes sont ignorés et toutes les requêtes partagent le compartiment régional unverified ; aucun pays vérifié ne leur est attribué.

Protégez le jeton et le secret k des liens ; ne les publiez pas et ne les enregistrez pas dans les journaux. Pour une intégration permanente, demandez l’accès à SERTEC PESAGE. Les environnements sk_test_ et sk_live_ conservent leurs propres règles et données.