Dokumentation

Die API — Ihre erste Anfrage in fünf Minuten.

REST, JSON, ein einziger Schlüssel. Jeder Endpunkt unten ist live und die Beispiele zeigen die echte Antwortform.

Welche Prüfstufen durchläuft ein Aufruf?die echte Reihenfolge in src/app.ts

Die Prüfstufen laufen in dieser Reihenfolge: eine Anfrage, deren Identität nicht aufgelöst werden kann, berührt das Kontingent nie, und eine Anfrage mit zu wenig Kontingent erreicht die Validierung nie. Es gibt kein Teilergebnis — ein Auftrag mit 100 Positionen, bei dem noch 40 übrig sind, wird vollständig abgelehnt; ein halbes Ergebnis als vollständig auszugeben, wäre das Schlimmste.

1 · Schlüssel holen

Melden Sie sich im Dashboard an und erzeugen Sie ihn im Bildschirm API Anahtarları erzeugen. Der Rohschlüssel wird nur einmal angezeigt; die Datenbank speichert nur den SHA-256-Hash, geht er verloren, wird ein neuer erzeugt.

Einen Schlüssel zu erzeugen Administrator- erfordert Administratorrechte. Mit einem API-Schlüssel lässt sich kein neuer erzeugen — damit ein einziger geleakter Schlüssel nicht zu unendlich vielen dauerhaften Schlüsseln wird.

2 · Authentifizierung

Senden Sie den Schlüssel mit einem von zwei Headern.

HTTPRequest-Header

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

Eine Anfrage ohne Schlüssel gibt 401. zurück. Anfragen aus dem Dashboard nutzen das Sitzungs- Cookie; kein Schlüssel nötig.

3 · Einzelne Nummer

Wie wird eine Nummer aufgelöst?in einer einzigen Anfrage

Das Feld issuer in der Antwort trägt dieses Präfix. Achtung: das Präfix ist nicht das Ursprungsland ; es zeigt, wer die Nummer vergeben hat.

Wie wird die Prüfziffer ermittelt?GS1 mod-10

Diese Berechnung auf der Seite wurde nicht von Hand geschrieben; sie entstand mit derselben Regel die das Produkt verwendet. Deshalb sagen wir bei einer ungültigen Nummer nicht nur „ungültig“, sondern nennen auch die die richtige Ziffer.

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
}

Feld	Was
`valid`	Ob die Prüfziffer der GS1-mod-10-Regel entspricht.
`type`	`GTIN-8`, `GTIN-12`, `GTIN-13`, `GTIN-14`.
`gtin14`	Das 14-stellige Äquivalent — nutzen Sie dies zum Abgleich.
`expectedCheckDigit`	Die Ziffer, die es sein müsste, wenn ungültig.
`issues`	Problemcodes; ein leeres Array, wenn gültig.
`issuer`	Die GS1-Organisation, die die Nummer vergeben hat, Land und Präfix. Bei einem nicht zugeteilten Präfix `null`.
`product`	Aus Ihrem eigenen Katalog: Name, Marke, Kategorie, Bild. Ist es nicht im Katalog, `null`.

4 · Stapelvalidierung

Eine JSON-Liste oder ein roher CSV-Body. Bis zu 10.000 Nummern pro Auftrag.

POST/v1/batches

Content-Type: application/json

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

— oder ein CSV-Body (text/csv): die GTIN-Spalte wird automatisch erkannt —

Endpunkt	Was es tut
`POST /v1/batches`	Startet den Auftrag, `202` und gibt eine Auftrags-ID zurück.
`GET /v1/batches`	Listet die letzten Aufträge auf.
`GET /v1/batches/{id}`	Status und Fortschritt.
`GET /v1/batches/{id}/results`	Ergebnisse; `offset` ve `limit` seitenweise.
`GET /v1/batches/{id}/result.csv`	Lädt alles als CSV herunter.

Ergebnisse dauerhaft — sie überstehen sogar einen Dienstneustart. 60 Minuten aufbewahrt.

5 · Ihr eigener Katalog

Die von Ihnen hochgeladenen Felder werden in jeder Abfrage in product zurückgegeben. Einen Katalog hochzuladen wird nicht vom Kontingent abgezogen.

CSVErwartete Spalten

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,

Spalte	Pflicht	Hinweis
`gtin`	ja	Jedes GTIN-Format; wird auf 14 Stellen normalisiert.
`urun_adi`	nein	Höchstens 300 Zeichen.
`marka`	nein
`kategori`	nein	Freitext.
`gorsel_url`	nein	Nur `https` wird akzeptiert.

6 · Nutzung und Kontingent

GET/v1/usage

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

GET /v1/usage/daily liefert die tägliche Aufschlüsselung. Eine Anfrage unterscheidet sich von einer Position: ein Stapel mit 100 Nummern ist 1 Anfrage, aber 100 Positionen; abgerechnet wird pro Position.

Antwortcodes

Sechs Codes. Alle kommen mit einem error im Body; keiner gibt stillschweigend ein leeres Ergebnis zurück.

Welcher Code, wann?eine ungültige Nummer ist ebenfalls 200

Der verwirrende Punkt: eine ungültige Nummer ist kein Fehler. Der Aufruf gelingt, die Antwort sagt valid: false. 400 kommt nur zurück, wenn eine Nummer gar nicht gelesen werden kann.

Lesen Sie Ihr Kontingent aus der Antwort

Kein Nachfragen nötig; jede Antwort trägt Ihr Restkontingent. Sie müssen nicht erst über ein 402 erfahren, dass das Kontingent aufgebraucht ist.

Header, die bei jeder Antwort zurückkommendamit es keine überraschenden Abbrüche gibt

7 · Grenzen und Fehler

Code	Wann	Was tun
`400`	Body oder CSV konnte nicht gelesen werden.	Feldnamen und Format prüfen.
`401`	Schlüssel fehlt, falsch oder widerrufen.	Erzeugen Sie einen neuen Schlüssel im Dashboard.
`403`	Unzureichende Rechte (z. B. ein Mitglied kann keine Schlüssel erzeugen).	Administratorrechte erforderlich.
`413`	Stapel überschritt 10.000 Positionen.	Teilen Sie die Liste.
`429`	Minutenlimit für Anfragen oder Positionen überschritten.	`retry-after` warten Sie so lange, wie der Header angibt.
`kota_doldu`	Ihr monatliches Positionskontingent ist aufgebraucht.	Paket upgraden oder auf den Periodenbeginn warten.
`503`	Zu viele offene Stapel gleichzeitig.	Versuchen Sie es in Kürze erneut.

Die Antwort-Header tragen Ihr Restkontingent: x-ratelimit-remaining, x-item-ratelimit-remaining.

Holen Sie sich Ihren Schlüssel

Melden Sie sich im Dashboard an und erzeugen Sie ihn im Bildschirm API-Schlüssel. Ohne Konto legt Ihr Organisationsadministrator eines an.

Zum Dashboard anmelden