Documentation

L’API — votre première requête en cinq minutes.

REST, JSON, une seule clé. Chaque point de terminaison ci-dessous est actif et les exemples montrent la forme réelle de la réponse.

Par quelles étapes passe un appel ?l’ordre réel dans src/app.ts

Les étapes s’exécutent dans cet ordre : une requête dont l’identité ne peut être résolue ne touche jamais au quota, et une requête à court de quota n’atteint jamais la validation. Il n’y a pas de résultat partiel — une tâche de 100 postes dont il reste 40 est entièrement rejetée ; renvoyer un demi-résultat comme s’il était complet serait le pire.

1 · Obtenir une clé

Connectez-vous au tableau de bord et générez-la depuis l’écran API Anahtarları générez-la. La clé brute est affichée une seule fois ; la base de données ne conserve que le hachage SHA-256, et en cas de perte, une nouvelle est générée.

Générer une clé administrateur requiert des droits d’administrateur. Une nouvelle clé ne peut pas être générée avec une clé API — afin qu’une seule clé divulguée ne se transforme pas en un nombre infini de clés permanentes.

2 · Authentification

Envoyez la clé avec l’un des deux en-têtes.

HTTPEn-tête de requête

x-api-key: gtin_live_XXXXXXXXXXXX
— ou —
Authorization: Bearer gtin_live_XXXXXXXXXXXX

Une requête sans clé renvoie 401. Les requêtes depuis le tableau de bord utilisent le cookie de session ; aucune clé n’est nécessaire.

3 · Numéro unique

Comment un numéro est-il résolu ?en une seule requête

Le champ issuer dans la réponse porte ce préfixe. Attention : le préfixe n’est pas le pays d’origine ; il indique qui a émis le numéro.

Comment trouve-t-on le chiffre de contrôle ?GS1 mod-10

Ce calcul sur la page n’a pas été écrit à la main ; il a été produit avec la même règle qu’utilise le produit. C’est pourquoi, pour un numéro invalide, nous ne disons pas seulement « invalide » mais indiquons aussi le le chiffre attendu.

GET/v1/gtins/{gtin}

{
  "input": "4006381333931",
  "compact": "4006381333931",
  "valid": true,
  "type": "GTIN-13",
  "gtin14": "04006381333931",
  "checkDigit": "1",
  "expectedCheckDigit": "1",
  "issues": [],
  "issuer": {
    "prefix": "400-440",
    "issuer": "GS1 Germany",
    "countryCode": "DE",
    "kind": "company"
  },
  "product": null
}

Champ	Quoi
`valid`	Si le chiffre de contrôle respecte la règle GS1 mod-10.
`type`	`GTIN-8`, `GTIN-12`, `GTIN-13`, `GTIN-14`.
`gtin14`	L’équivalent à 14 chiffres — utilisez-le pour la mise en correspondance.
`expectedCheckDigit`	Le chiffre qu’il devrait être s’il est invalide.
`issues`	Codes de problème ; un tableau vide si valide.
`issuer`	L’organisation GS1 qui a émis le numéro, le pays et le préfixe. Pour un préfixe non attribué, `null`.
`product`	Depuis votre propre catalogue : nom, marque, catégorie, image. S’il n’est pas dans votre catalogue, `null`.

4 · Validation par lot

Une liste JSON ou un corps CSV brut. Jusqu’à 10 000 numéros par tâche.

POST/v1/batches

Content-Type: application/json

{ "gtins": ["4006381333931", "8690504045618"] }

— ou un corps CSV (text/csv) : la colonne GTIN est détectée automatiquement —

Point de terminaison	Ce qu’il fait
`POST /v1/batches`	Démarre la tâche, `202` et renvoie un identifiant de tâche.
`GET /v1/batches`	Liste les tâches récentes.
`GET /v1/batches/{id}`	Statut et progression.
`GET /v1/batches/{id}/results`	Résultats ; `offset` ve `limit` paginé.
`GET /v1/batches/{id}/result.csv`	Télécharge le tout en CSV.

Résultats persistant — ils survivent même à un redémarrage du service. Conservés 60 minutes.

5 · Votre propre catalogue

Les champs que vous téléversez sont renvoyés dans product à chaque requête. Téléverser un catalogue n’est pas décompté du quota.

CSVColonnes attendues

gtin,urun_adi,marka,kategori,gorsel_url
4006381333931,STABILO BOSS Fosforlu Kalem,STABILO,Kırtasiye,https://...
8690504045618,Çikolatalı Gofret 36 g,Örnek Marka,Gıda,

Colonne	Obligatoire	Note
`gtin`	oui	Tout format GTIN ; normalisé à 14 chiffres.
`urun_adi`	non	300 caractères au maximum.
`marka`	non
`kategori`	non	Texte libre.
`gorsel_url`	non	Seul `https` est accepté.

6 · Utilisation et quota

GET/v1/usage

{ "requests": 128, "items": 4210 }

GET /v1/usage/daily donne la ventilation quotidienne. Une requête diffère d’un poste : un lot de 100 numéros est 1 requête mais 100 postes ; la facturation se fait au poste.

Codes de réponse

Six codes. Tous arrivent avec une clé error dans le corps ; aucun ne renvoie silencieusement un résultat vide.

Quel code, quand ?un numéro invalide est aussi 200

Le point qui prête à confusion : un numéro invalide n’est pas une erreur. L’appel réussit, la réponse indique valid: false. 400 n’est renvoyé que lorsqu’un numéro est totalement illisible.

Lisez votre quota dans la réponse

Inutile de demander ; chaque réponse porte votre quota restant. Vous n’avez pas à apprendre l’épuisement du quota via un 402.

En-têtes renvoyés à chaque réponsepour éviter toute coupure surprise

7 · Limites et erreurs

Code	Quand	Que faire
`400`	Le corps ou le CSV n’a pas pu être lu.	Vérifiez les noms de champs et le format.
`401`	Clé manquante, erronée ou révoquée.	Générez une nouvelle clé depuis le tableau de bord.
`403`	Droits insuffisants (p. ex. un membre ne peut pas générer de clés).	Des droits d’administrateur sont requis.
`413`	Le lot a dépassé 10 000 postes.	Divisez la liste.
`429`	Limite par minute de requêtes ou de postes dépassée.	`retry-after` attendez la durée indiquée dans l’en-tête.
`kota_doldu`	Votre quota mensuel de postes est épuisé.	Passez à un forfait supérieur ou attendez le début de la période.
`503`	Trop de lots ouverts en même temps.	Réessayez sous peu.

Les en-têtes de réponse portent votre quota restant : x-ratelimit-remaining, x-item-ratelimit-remaining.

Obtenez votre clé

Connectez-vous au tableau de bord et générez-la depuis l’écran Clés API. Si vous n’avez pas de compte, votre administrateur d’organisation en ouvre un.

Se connecter au tableau de bord