← Ana sayfa

API Dokümantasyonu

Kurumsal plan hesapları, ana sayfadaki API erişimi bölümünden anahtar oluşturabilir. Her başarılı istek 1 kredi harcar.

Kimlik doğrulama

Her istekte anahtarınızı X-API-Key başlığında gönderin. Anahtar gp_live_ ile başlar. Anahtarı asla tarayıcı/mobil uygulama gibi herkese açık koda koymayın; yalnızca sunucu tarafında kullanın.

POST /api/v1/classify

AlanTürAçıklama
querymetin (3–500 karakter)Ürün tanımı (malzeme, kullanım amacı, teknik özellik ne kadar netse sonuç o kadar isabetli)
deeptrue/false (varsayılan false)true: resmî Fasıl Notları ile çapraz kontrol de yapılır (daha yavaş, ~5 sn ek)
curl -X POST https://www.gumrukpusulasi.com/api/v1/classify \
  -H "X-API-Key: gp_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"query": "18V şarjlı darbeli matkap", "deep": true}'

Örnek yanıt:

{
  "gtip_code": "8467.21.10.00.00",
  "section": "XVI - Makinalar ve mekanik cihazlar ...",
  "vat_rate": "%20 KDV",
  "analysis": "GYK 1 ve 6 uyarınca ...",
  "details": { "customs_duty": "...", "required_documents": ["..."], "risk_notes": "...", "alternative_codes": ["..."],
    "gyk_steps": [ { "rule": "GYK 1", "aciklama": "Eşya 84.67 pozisyonunun metnine göre sınıflandırıldı." } ],
    "second_opinion": { "engine": "Claude", "code": "8467.21.10.00.00", "confidence": "Yüksek", "note": "...", "agree": true } },
  "confidence": "Yüksek",
  "verification": "exact",
  "evidence": [ { "gtip": "8467.21.10.00.00", "aciklama": "Her tür matkaplar ..." } ],
  "notes_check": { "verdict": "uyumlu", "explanation": "...", "note": "..." },
  "clarifying_questions": [],
  "remaining_credits": 41,
  "disclaimer": "Ön değerlendirmedir; resmî beyan yerine geçmez, gümrük müşavirinin onayı gerekir."
}
AlanAnlamı
confidenceYüksek / Orta / Düşük. "Düşük" ise sonucu beyan için kullanmayın.
verificationexact: kod resmî tarife cetvelinde birebir var · partial: kısmen · none: cetvelde yok · n/a: cetvel verisi yüklü değil
notes_check.verdictuyumlu / şüpheli / uyumsuz (yalnızca deep=true)
clarifying_questionsSonucu netleştirecek sorular; varsa sorguyu bu bilgilerle zenginleştirip tekrar gönderin.
details.gyk_stepsUygulanan Genel Yorum Kurallarının adım adım listesi (rule, aciklama).
details.second_opinionYalnızca Gemini'nin güveni Yüksek olmadığında doldurulur: bağımsız bir ikinci yapay zekâ motorunun (Claude) aynı ürün için verdiği sonuç ve iki motorun aynı pozisyonda (ilk 6 hane) uyuşup uyuşmadığı (agree).

GET /api/v1/credits

curl https://www.gumrukpusulasi.com/api/v1/credits -H "X-API-Key: gp_live_XXXXXXXX"
→ {"credits": 41}

Hata kodları

401Anahtar eksik/geçersiz/iptal edilmiş
402Yeterli kredi yok
403Hesap API kullanımına uygun değil (askıda veya Kurumsal plan değil)
422Geçersiz istek gövdesi
429Dakikada en fazla 30 istek
503Analiz servisi yoğun; kredinizden düşülmez; birkaç saniye sonra tekrar deneyin

Python örneği

import requests
r = requests.post("https://www.gumrukpusulasi.com/api/v1/classify",
                  headers={"X-API-Key": "gp_live_XXXXXXXX"},
                  json={"query": "pamuklu erkek tişört", "deep": False}, timeout=60)
r.raise_for_status()
print(r.json()["gtip_code"], r.json()["confidence"])

Sonuçlar yapay zekâ destekli ön değerlendirmedir; resmî beyan, Bağlayıcı Tarife Bilgisi (BTB) veya hukuki görüş yerine geçmez. Beyan öncesinde gümrük müşavirinin onayı gerekir.