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

Die Antwort trennt mathematische Prüfung und Produktquellenstatus.

GET/api/v1/gtins/{gtin}

{
  "valid": true,
  "status": "UNVERIFIED",
  "type": "GTIN-13",
  "gtin14": "04006381333931",
  "checkDigit": "1",
  "expectedCheckDigit": "1",
  "product": null
}

Externe Zuordnungsfelder werden ohne Lizenzfreigabe nicht ausgegeben. UNVERIFIED bedeutet: mathematisch gültig, aber ohne Treffer in einer Produktquelle.

4 · Stapelvalidierung

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

POST/api/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 /api/v1/batches`	Startet den Auftrag, `202` und gibt eine Auftrags-ID zurück.
`GET /api/v1/batches`	Listet die letzten Aufträge auf.
`GET /api/v1/batches/{id}`	Status und Fortschritt.
`GET /api/v1/batches/{id}/results`	Ergebnisse; `offset` und `limit` seitenweise.
`GET /api/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/api/v1/usage

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

GET /api/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 wird nur zurückgegeben, wenn die Anfrage nicht dem API-Schema entspricht.

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