Geliştirici API Dokümantasyonu

1. Genel bilgiler

• Kök adres: https://getnexell.com/api/v1 — yalnızca HTTPS.
• İstek ve yanıt gövdeleri JSON'dur (Content-Type: application/json, UTF-8). Tek istisna, dosya baytları döndüren /disa-aktar ucudur.
• Gönderdiğiniz metin, dosya ve tablolar yalnızca istek işlenirken sunucu belleğinde tutulur; diske, veritabanına ya da günlüklere yazılmaz ve hiçbir yapay zekâ ya da dış servise gönderilmez. Sonucu saklamak sizin tarafınızdadır.
• Motor kural tabanlıdır: aynı girdi her zaman aynı sonucu verir. Anlaşılmayan bir istek uygulanmış gibi yapılmaz; yanıtta anlasilmayan listesinde döner.

2. Kimlik doğrulama

Hesabım sayfasındaki API anahtarları bölümünden bir anahtar üretin. Anahtarın tamamı yalnızca üretildiği anda bir kez gösterilir; sunucuda yalnızca özeti saklanır. Her istekte Authorization başlığıyla gönderin:

Authorization: Bearer nxl_live_ANAHTARINIZ

Alternatif olarak X-API-Key: nxl_live_ANAHTARINIZ başlığı da kabul edilir. Anahtarınızı istemci tarafı koda (tarayıcı, mobil uygulama) gömmeyin; sızdığını düşünüyorsanız Hesabım sayfasından iptal edip yenisini üretin. Anahtarla yapılan işler, anahtarın sahibi olan hesabın kotasından düşer; ekip üyelerinde ekibin ortak havuzundan.

Anahtar yalnızca bu belgedeki işlem uçlarında (/api/v1/cevir, /api/v1/komut, /api/v1/disa-aktar) geçer. Hesap, ödeme, ekip ve anahtar yönetimi yalnızca Hesabım sayfasındaki oturumla yapılır; bu uçlara anahtarla gelen istek 403 OTURUM_GEREKLI alır. Anahtar üretmek için e-posta adresinizin doğrulanmış olması gerekir. Şifreniz değiştiğinde ya da sıfırlandığında hesabın bütün anahtarları silinir; askıya alınan hesabın anahtarı çalışmaz.

3. Tablo biçimi

Uçların aldığı ve döndürdüğü tablo nesnesi, sütun tanımlarından ve satırlardan oluşur:

{
  "columns": [
    { "key": "ad",    "label": "Ad Soyad / Firma" },
    { "key": "tutar", "label": "Tutar", "numeric": true },
    { "key": "il",    "label": "İl" }
  ],
  "rows": [
    { "ad": "Ahmet Yılmaz", "tutar": "1500", "il": "İstanbul" },
    { "ad": "Mehmet Demir", "tutar": "2400", "il": "Ankara" }
  ]
}

• Hücre değerleri metin olarak gelir; numeric: true olan sütunlar Excel'e sayı olarak yazılır. Satırlarda columns'ta görünmeyen anahtarlar (ör. boş alanlar, _issues ile işaretlenen şüpheli değerler) bulunabilir.
• Komutların eklediği formüller, toplam satırı, koşullu biçimler, doğrulamalar, grafik, PivotTable ve yazdırma ayarı tablo nesnesinin ek alanlarında taşınır. Bir sonraki /komut ya da /disa-aktar isteğine tabloyu aldığınız gibi gönderin ki bunlar kaybolmasın.

4. Tabloya çevirme

POST /api/v1/cevir

Metni ya da tek bir dosyayı tabloya çevirir; isterseniz aynı istekte yazılı bir isteği de uygular.

Metinle

{
  "parcalar": [
    { "ad": "whatsapp.txt", "metin": "Ahmet Yılmaz 0532 111 22 33 İstanbul 1.500 TL\nMehmet Demir 0544 999 88 77 Ankara 2.400 TL" }
  ],
  "istek": "tutarlara %20 KDV ekle"
}

Dosyayla

{
  "dosya": "UEsDBBQABgAIAAAAIQ...",
  "ad": "siparisler.xlsx",
  "istek": "sadece İstanbul'dakileri al"
}

Parametreler

• parcalar (dizi): { ad, metin } nesneleri, en çok 200 parça. Birden çok parça tek tabloda birleştirilir. Tek bir metin için kısaca "metin": "..." da gönderebilirsiniz.
• dosya (string) ve ad (string): parcalar yerine, base64 ile kodlanmış tek bir dosya ve uzantısıyla birlikte adı (data: önekli base64 da kabul edilir). Okunan biçimler: xlsx, xlsm, xls, xlsb, ods, csv, tsv, txt, prn, json, xml, html, docx, odt, rtf, pdf ve görseller (JPG, PNG, WebP, BMP, GIF, TIFF). Görseller ve taranmış PDF sayfaları sunucuda OCR ile (Türkçe + İngilizce) okunur; OCR'lanan dosya en çok 25 MB olabilir ve taranmış PDF'lerde en çok ilk 50 sayfa okunur.
• istek (string, isteğe bağlı, en çok 2.000 karakter): tabloya uygulanacak yazılı istek, Türkçe ya da İngilizce (ör. "tutara göre büyükten küçüğe sırala"). Birden çok isteği noktalı virgülle ayırabilirsiniz.

İstek gövdesi en çok 32 MB olabilir. Base64 kodlama dosyayı yaklaşık üçte bir büyüttüğü için bu uçla tek seferde gönderilebilecek dosya, planınızın dosya sınırı daha yüksek olsa da yaklaşık 24 MB'tır. Büyük tabloları Content-Encoding: gzip ile sıkıştırılmış gövdeyle gönderebilirsiniz; Accept-Encoding: gzip gönderirseniz büyük yanıtlar da sıkıştırılmış gelir.

Yanıt

{
  "tablo": {
    "columns": [
      { "key": "ad", "label": "Ad Soyad / Firma", "numeric": false },
      { "key": "telefon", "label": "Telefon", "numeric": false },
      { "key": "tutar", "label": "Tutar", "numeric": true },
      { "key": "paraBirimi", "label": "Para Birimi", "numeric": false },
      { "key": "il", "label": "İl", "numeric": false }
    ],
    "rows": [
      { "ad": "Ahmet Yılmaz", "telefon": "0532 111 22 33", "tutar": "1800", "paraBirimi": "TRY", "il": "İstanbul" },
      { "ad": "Mehmet Demir", "telefon": "0544 999 88 77", "tutar": "2880", "paraBirimi": "TRY", "il": "Ankara" }
    ]
  },
  "uygulanan": ["Tutar değerlerine %20 eklendi (2 satır)"],
  "anlasilmayan": [],
  "bilgiler": [],
  "yorumlanan": [],
  "oneriler": [],
  "kota": {
    "plan": "pro",
    "donem": "2026-09",
    "satir": { "kullanilan": 1242, "kota": 50000, "kalan": 48758, "ek": 0 },
    "sayfa": { "kullanilan": 12, "kota": 500, "kalan": 488, "ek": 0 },
    "tabloSiniri": 50000,
    "dosyaSiniriMB": 50,
    "koltuk": 1
  }
}

• uygulanan: yapılan her işlemin açıklaması. anlasilmayan: uygulanamayan istek parçaları (tablo onlar yüzünden değişmez).
• bilgiler: tabloyu değiştirmeyen soruların cevapları (ör. "toplam tutar ne kadar?").
• yorumlanan ve oneriler: motorun bir isteği nasıl yorumladığı ve anlaşılmayan istekler için yakın öneriler (varsa).
• Dosya OCR ile okunduysa yanıtta ayrıca kaynaklar alanı bulunur: [{ ad, tur, boyut, ocr: { sayfa, guven } }].
• Çıkan satır sayısı aylık satır kotanızdan, OCR ile okunan her sayfa sayfa kotanızdan düşer.

5. Tabloyu işleme

POST /api/v1/komut

Elinizdeki bir tabloya yazılı istek uygular: süzme, sıralama, sütun bölme ve birleştirme, formül sütunu, toplam satırı, gruplama ve özet tablo, koşullu biçim, veri doğrulama, grafik ve daha fazlası.

{
  "tablo": { "columns": [ ... ], "rows": [ ... ] },
  "komut": "İl sütununa göre grupla, tutarları topla; tutara göre büyükten küçüğe sırala"
}

Yanıt: { tablo, uygulanan, anlasilmayan, bilgiler, yorumlanan, oneriler }. Komutlar satır kotasından düşmez; ancak tablo, planınızın tek tablo sınırını aşamaz.

6. Dışa aktarma

POST /api/v1/disa-aktar

{
  "tablo": { "columns": [ ... ], "rows": [ ... ] },
  "bicim": "xlsx",
  "secenekler": { "baslik": "Eylül siparişleri", "paraBirimi": "TRY", "grafikYok": false }
}

• bicim: xlsx, csv, tsv, json ya da pdf (yazdırılabilir tablo raporu). CSV, Türkçe Excel'in doğru açması için UTF-8 BOM ve ; ayracıyla üretilir; başka ayraç için secenekler.ayrac: ",", "\t" ya da "|".
• secenekler.baslik: Excel dosyasının belge özelliklerindeki başlık. secenekler.paraBirimi: tutar sütunlarının para birimi biçimi (TRY, USD, EUR, GBP). secenekler.grafikYok: true ise tabloda grafik tanımlı değilken eklenen otomatik özet grafiği yazılmaz.
• Yanıt JSON değil, dosyanın kendisidir; Content-Disposition: attachment başlığıyla gelir. Excel dosyasında formüller canlı formül, tarihler gerçek tarih, sayılar sayı olarak yazılır; PivotTable, grafik, koşullu biçim ve doğrulamalar Excel'in kendi nesneleridir.
• Dışa aktarma satır kotasından düşmez; tablo, planınızın tek tablo sınırını aşamaz.

7. Kod örnekleri

cURL — metni çevir

curl -X POST https://getnexell.com/api/v1/cevir \
  -H "Authorization: Bearer nxl_live_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d '{
    "parcalar": [{ "ad": "liste.txt", "metin": "Ali Veli 0532 100 00 00 İzmir 500 TL" }],
    "istek": "tutarı 1000 TL altında olanları sil"
  }'

cURL — Excel olarak indir

curl -X POST https://getnexell.com/api/v1/disa-aktar \
  -H "Authorization: Bearer nxl_live_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d @istek.json \
  -o tablo.xlsx

Node.js (18+) — dosyayı çevir, işle, Excel olarak kaydet

import { readFile, writeFile } from 'node:fs/promises';

const KOK = 'https://getnexell.com/api/v1';
const BASLIK = {
  'Authorization': 'Bearer ' + process.env.NEXELL_API_KEY,
  'Content-Type': 'application/json'
};

async function istek(yol, govde) {
  const y = await fetch(KOK + yol, { method: 'POST', headers: BASLIK, body: JSON.stringify(govde) });
  if (!y.ok) {
    const h = await y.json();
    throw new Error(`${y.status} ${h.kod}: ${h.hata}`);
  }
  return y;
}

// 1) Dosyayı tabloya çevir
const dosya = (await readFile('fatura.pdf')).toString('base64');
const cevir = await (await istek('/cevir', { dosya, ad: 'fatura.pdf' })).json();

// 2) Yazılı istek uygula
const komut = await (await istek('/komut', {
  tablo: cevir.tablo,
  komut: 'tutara göre büyükten küçüğe sırala; alta toplam satırı ekle'
})).json();
console.log(komut.uygulanan, komut.anlasilmayan);

// 3) Excel olarak kaydet
const xlsx = await istek('/disa-aktar', { tablo: komut.tablo, bicim: 'xlsx' });
await writeFile('fatura.xlsx', Buffer.from(await xlsx.arrayBuffer()));
console.log('Kalan satır kotası:', cevir.kota.satir.kalan);

Python (requests)

import base64, os, requests

KOK = "https://getnexell.com/api/v1"
BASLIK = {"Authorization": "Bearer " + os.environ["NEXELL_API_KEY"]}

with open("stok.xls", "rb") as f:
    dosya = base64.b64encode(f.read()).decode()

r = requests.post(f"{KOK}/cevir", headers=BASLIK,
                  json={"dosya": dosya, "ad": "stok.xls", "istek": "tekrar eden kodları sil"})
if r.status_code != 200:
    hata = r.json()
    raise SystemExit(f"{r.status_code} {hata['kod']}: {hata['hata']}")
sonuc = r.json()

x = requests.post(f"{KOK}/disa-aktar", headers=BASLIK,
                  json={"tablo": sonuc["tablo"], "bicim": "xlsx"})
x.raise_for_status()
with open("stok-temiz.xlsx", "wb") as f:
    f.write(x.content)

8. Kotalar ve sınırlar

API, araçla aynı kotaları kullanır. Her /cevir yanıtındaki kota alanı güncel durumunuzu verir; null değer sınırsız demektir.

• Ücretsiz: ayda 500 satır, 10 OCR sayfası · tek tabloda en çok 500 satır · dosya en çok 5 MB
• Başlangıç: ayda 10.000 satır, 100 OCR sayfası · tek tabloda en çok 10.000 satır · dosya en çok 25 MB
• Pro: ayda 50.000 satır, 500 OCR sayfası · tek tabloda en çok 50.000 satır · dosya en çok 50 MB
• Ekip: sınırsız satır, ayda 2.000 OCR sayfası · tek tabloda en çok 200.000 satır · dosya en çok 100 MB · 5 koltuk, ortak havuz
• Ek paketler: süresi dolmaz, aylık kota bitince kullanılır — +5.000 satır ve 50 sayfa, +25.000 satır ve 250 sayfa ya da +100.000 satır ve 1.000 sayfa.

Satır kotası yalnızca tabloya çevrilen yeni satırları sayar; /komut ve /disa-aktar satır kotasından düşmez. Aylık kotalar takvim ayının başında yenilenir. Güncel değerler için Fiyatlandırma bölümüne bakın. API uçlarında hız sınırı vardır (şu an üç uç birlikte dakikada 120 istek); aşıldığında 429 döner ve Retry-After başlığı kaç saniye beklemeniz gerektiğini söyler. Bir tabloda en çok 1.000 sütun olabilir.

9. Hata kodları

Hatalar her zaman aynı biçimde döner:

{ "hata": "Aylık satır kotanız doldu.", "kod": "KOTA_SATIR", "detay": { ...kota durumu... } }

• 400 — istek hatalı: GECERSIZ_GIRDI (eksik ya da yanlış türde alan), GECERSIZ_JSON, GECERSIZ_TABLO, GECERSIZ_BICIM, ISTEK_UZUN, BOS_DOSYA; hata alanı nedenini söyler.
• 401 GIRIS_GEREKLI — API anahtarı yok, hatalı ya da iptal edilmiş.
• 402 KOTA_SATIR — aylık satır kotası ve ek paket bakiyesi bitti. detay güncel kota durumudur.
• 402 KOTA_SAYFA — aylık OCR sayfa kotası ve ek paket bakiyesi bitti.
• 413 TABLO_BUYUK — tablo planınızın tek tablo sınırını ya da istek gövdesi 32 MB'ı aşıyor.
• 413 DOSYA_BUYUK — dosya, planınızın dosya boyutu sınırını aşıyor.
• 415 GECERSIZ_TUR — gövdenin kodlaması desteklenmiyor.
• 422 OKUNAMADI — dosyada okunabilir metin bulunamadı (ör. çok bulanık fotoğraf); detay.kaynaklar dosya özetini verir.
• 429 HIZ_SINIRI — çok sık istek; Retry-After kadar bekleyip yeniden deneyin.
• 503 MESGUL — sunucunun iş kuyruğu dolu; Retry-After kadar bekleyip yeniden deneyin. 503 OCR_HAZIR_DEGIL / KOTA_HAZIR_DEGIL — ilgili hizmet geçici olarak hazır değil.
• 504 ZAMAN_ASIMI — iş süre sınırını aştı ve durduruldu (ör. çok sayfalı taranmış PDF ya da çok büyük tablo); daha küçük parçalarla yeniden deneyin.
• 500 — beklenmeyen sunucu hatası; sürerse destek@getnexell.com adresine yazın.

Kota ve boyut kontrolleri iş başlamadan yapılır: reddedilen bir istek kotanızdan düşmez.