Paraşüt’ten geçiş
Paraşüt API’siyle entegrasyon yazmış geliştiriciler için kaynak adı eşlemesi ve en sık yanlış anlaşılan farklar.
Kaynak adı eşlemesi
En pahalı yanlış anlamalar adlardan çıkar: kod derlenir, çalışır ve yanlış kaynağı okur. Aradığınız şeyin YouSoft’taki karşılığı:
| Aradığınız şey | YouSoft kaynağı |
|---|---|
| Müşteri ve tedarikçi kartı (cari) | /v1/contacts (yalnız açma ve güncelleme; liste ve tek kart okuması yok) |
| Carinin hareket dökümü (ekstre) | Dış API’de yok, panelden bakılır. |
| Carinin iletişim kişileri | /v1/contacts/{id}/people (yalnız ekleme ve güncelleme) |
| Kasa ve banka hesabı | Dış API’de yok, panelden bakılır. Cari değildir. |
| Kasa ve banka hareketleri | Dış API’de yok, panelden bakılır. |
| Ürün ve hizmet kartı (stok) | /v1/products (yalnız açma ve güncelleme) |
| Stok hareketleri | /v1/stock-movements (yalnız yazma) |
| Satış faturası ve taslakları | /v1/invoices (liste, fatura no / ETTN / zarf ile arama, XML ve PDF indirme, iptal; taslağı status: draft ayırır) |
| Satış faturasına tahsilat (ödeme) işleme | Dış API’de yok, panelden bakılır. |
| Gelen (alış) e-Faturalar | /v1/inbox-invoices (liste, tek belge, XML ve PDF indirme; kabul ya da red yanıtı panelden) |
| e-Serbest Meslek Makbuzu (e-SMM) ve e-Müstahsil Makbuzu | /v1/receipts/{id} (yalnız tek makbuz okuması) |
| e-İrsaliye | /v1/despatches/{id} (yalnız tek irsaliye okuması) |
| Alıcının e-Fatura posta kutusu sorgusu | /v1/e-invoice-inboxes/{tax_number} |
Alan adları İngilizcedir ve snake_case yazılır (örneğin contact_title). Okurken tutarlar ondalık metindir ("1250.00"); ayrıntı için sorgu sözleşmesindeki veri biçimlerine bakın.
Cari adresi bir nesnedir
Cari kartının adresi tek bir address nesnesinde durur: line, neighborhood, district, city, postal_code ve country (ISO 3166-1 alpha-2, büyük harf; boşsa Türkiye). Hiçbir alanı dolu olmayan kartta address anahtarı gelmez. PATCH adresi alan alan birleştirir: göndermediğiniz alan korunur, boş dize o alanı siler.
e-Fatura ve e-Arşiv gönderimi alıcının il ve ilçesini ister. Kartı aktarırken adresi de yazın; il ya da ilçesi boş olan karta kesilen fatura gönderimde 400 validation_failed alır (details.field: contact_id).
İlişkiler satır içi gelir
JSON:API tabanlı bir istemciye alışkınsanız yanıtın kökünde included dizisi aramayın: burada genişletme satır içidir. ?include=contact istediğinizde cari kartı, faturanın kendi contact alanına yazılır. Derinlik 1’dir; noktalı ad 400 alır.
Cari kartı belirlenemeyen belgede contact anahtarı hiç gelmez (null da gelmez). Dönen kart, belge düzenlenirken seçilen karttır: belgenin cari hareketinin yazıldığı kartın kendisi. Kart seçilmemiş bir alıcıya da fatura kesilebilir. Ayrıntı için sorgu sözleşmesine bakın.
Sayfalama: sayfa numarası yok, cursor var
page parametresi yoktur; sayfa, meta.next_cursor değeri cursor olarak geri verilerek ilerler. page_size en çok 100 olabilir (varsayılan 25). Toplam kayıt sayısı (total) yayımlanmaz; ilerleme çubuğu gösteren bir istemci yazıyorsanız bunu baştan bilin. Tanınmayan sorgu parametreleri hata vermeden yok sayıldığı için sayfa numarası parametresi göndermek sessizce ilk sayfayı getirir.
Kimlik: OAuth jetonu yok, istek imzası var
Jeton ucu, yenileme jetonu ve süre yönetimi yoktur. Her istek API anahtarı, zaman damgası ve HMAC-SHA256 imzasıyla gider; imza gövdeyi ve ham sorgu dizesini kapsar. Geçişte en sık hata burada yapılır: test vektörünü ilk gün çalıştırın.
OAuth’taki password akışının karşılığı yoktur ve olmayacaktır: kullanıcının panel parolasını üçüncü tarafa verdiren bir akış, parolayı o tarafın günlüklerine ve yedeklerine taşır. Yetki, kullanıcının parolasından değil, firma sahibinin ürettiği API anahtarının kapsamlarından gelir. client_credentials akışı da v1’de yoktur; gerekçesi İmzalama sayfasında.
Fatura gönderimi asenkrondur
POST /v1/invoices/{id}/send 202 döner ve bu, belgenin GİB’e ulaştığı anlamına gelmez: uç, taslağın gönderilebilir olduğunu doğrular ve gönderim kuyruğuna alır. İlerlemeyi GET /v1/invoices/{id} ile status alanından izleyin: draft, sending, sent (ya da failed); sonrasında accepted, rejected ya da cancelled. Daraltılmamış ham durum status_detail alanındadır.
Yanıtı senkron sanan bir istemci faturayı gönderilmemiş sayıp yeniden dener. Yeniden gönderirken aynı Idempotency-Key değerini kullanın; böylece GİB’e ikinci bir gönderim olmaz.