API quick start

The Gümrük AI REST API speaks JSON over HTTPS. All endpoints sit under https://api.gumruk.ai.

Authentication

Every API call needs a Bearer access token from /auth/login.

``bash curl -X POST "https://api.gumruk.ai/auth/login" \ -H "Content-Type: application/json" \ -d '{ "email": "you@firm.com", "password": "**********", "tenant_id": "default" }' ``

Response:

``json { "access_token": "eyJ…", "refresh_token": "eyJ…", "expires_at": 1735000000000, "user": { "user_id": "u_…", "email": "you@firm.com", "tenant_id": "default", "role": "owner" } } ``

access_token is short-lived (1 hour). Refresh with /auth/refresh.

HS code (GTİP) search

``bash curl -X POST "https://api.gumruk.ai/gtip/search" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${TOKEN}" \ -d '{ "query": "polyethylene granules, white, food-contact, import", "tenant_id": "default" }' ``

Tax calculation

``bash curl -X POST "https://api.gumruk.ai/taxes/calculate" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${TOKEN}" \ -d '{ "gtip": "3902.30.00.00.11", "origin_country": "DE", "cif_value": 100000, "currency": "TRY", "quantity": 1000, "quantity_unit": "kg" }' ``

Pre-check on a case

``bash curl -X POST "https://api.gumruk.ai/cases/precheck" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${TOKEN}" \ -d '{ "case_id": "case_abc", "documents": [ { "kind": "proforma", "url": "https://...signed-url..." } ] }' ``

Rate limits

Rate limits depend on your plan; the current plan catalog is shown on the pricing page. When exceeded the API returns 429 Too Many Requests with a Retry-After header.

OpenAPI

The complete schema lives under /docs/api (Swagger / ReDoc embed).