Documentation

The API — your first request in five minutes.

REST, JSON, a single key. Every endpoint below is live and the examples show the real response shape.

Which gates does a call pass through?the real order in src/app.ts

The gates run in this order: a request whose identity cannot be resolved never touches the quota, and a request short on quota never reaches validation. There is no partial result — a 100-item job with 40 items left is rejected entirely; handing back a half result as if it were complete would be the worst outcome.

1 · Get a key

Sign in to the dashboard and generate it from the API Anahtarları screen. The raw key is shown only once ; the database keeps only the SHA-256 digest, and if lost a new one is generated.

Generating a key admin rights are required. A new key cannot be generated with an API key — so that a single leaked key cannot turn into an endless number of permanent keys.

2 · Authentication

Send the key with one of two headers.

HTTPRequest header

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

A request without a key returns 401. Requests from the dashboard use the session cookie; no key is needed.

3 · Single number

How is a number resolved?in a single request

The issuer field in the response carries this prefix. Note: the prefix is not the country of origin ; it shows who issued the number.

How is the check digit found?GS1 mod-10

This calculation on the page was not written by hand; it was produced with the same rule the product uses. That is why, for an invalid number, we don’t just say “invalid” but also tell you the the digit it should be.

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
}

Field	What
`valid`	Whether the check digit follows the GS1 mod-10 rule.
`type`	`GTIN-8`, `GTIN-12`, `GTIN-13`, `GTIN-14`.
`gtin14`	The 14-digit equivalent — use this for matching.
`expectedCheckDigit`	The digit it should be if invalid.
`issues`	Issue codes; an empty array if valid.
`issuer`	The GS1 organization that issued the number, country and prefix. For an unassigned prefix, `null`.
`product`	From your own catalogue: name, brand, category, image. If not in your catalogue, `null`.

4 · Batch validation

A JSON list or a raw CSV body. Up to 10,000 numbers per job.

POST/v1/batches

Content-Type: application/json

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

— or a CSV body (text/csv): the GTIN column is detected automatically —

Endpoint	What it does
`POST /v1/batches`	Starts the job, `202` and returns a job id.
`GET /v1/batches`	Lists recent jobs.
`GET /v1/batches/{id}`	Status and progress.
`GET /v1/batches/{id}/results`	Results; `offset` ve `limit` paginated.
`GET /v1/batches/{id}/result.csv`	Downloads everything as CSV.

Results persistent — they survive even a service restart. Kept for 60 minutes.

5 · Your own catalogue

The fields you upload are returned in product on every query. Uploading a catalogue does not count against quota.

CSVExpected columns

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,

Column	Required	Note
`gtin`	yes	Any GTIN format; normalized to 14 digits.
`urun_adi`	no	At most 300 characters.
`marka`	no
`kategori`	no	Free text.
`gorsel_url`	no	Only `https` is accepted.

6 · Usage and quota

GET/v1/usage

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

GET /v1/usage/daily gives the daily breakdown. A request differs from an item: a 100-number batch is 1 request but 100 items; billing is per item.

Response codes

Six codes. All come with an error key in the body; none silently returns an empty result.

Which code, when?an invalid number is also 200

The confusing point: an invalid number is not an error. The call succeeds, the response says valid: false. 400 only comes back when a number can’t be read at all.

Read your quota from the response

No need to ask; every response carries your remaining allowance. You don’t have to learn the quota ran out from a 402.

Headers returned on every responseso there are no surprise cut-offs

7 · Limits and errors

Code	When	What to do
`400`	Body or CSV could not be read.	Check the field names and format.
`401`	Key missing, wrong or revoked.	Generate a new key from the dashboard.
`403`	Insufficient rights (e.g. a member cannot generate keys).	Administrator rights are required.
`413`	Batch exceeded 10,000 items.	Split the list.
`429`	Per-minute request or item limit exceeded.	`retry-after` wait as long as the header says.
`kota_doldu`	Your monthly item allowance is used up.	Upgrade the plan or wait for the period to start.
`503`	Too many open batches at once.	Try again shortly.

The response headers carry your remaining allowance: x-ratelimit-remaining, x-item-ratelimit-remaining.

Get your key

Sign in to the dashboard and generate it from the API Keys screen. If you don’t have an account, your organization admin opens one.