Paraşüt’ten geçiş
Aynı işi yapan iki API’nin farkları, entegrasyonu yazarken değil okurken görülsün diye.
Ad eşlemesi — önce buraya bakın
En pahalı yanlış anlama adlardadır, çünkü kod derlenir ve yanlış tabloyu okur.
| Aradığınız şey | YouSoft kaynağı |
|---|---|
| Müşteri / tedarikçi kartı (cari) | /v1/contacts |
| Carinin hareket dökümü (ekstre) | /v1/contacts/{id}/ledger |
| Kasa / banka hesabı | /v1/accounts — cari DEĞİL |
| Kasa / banka hareketleri | /v1/accounts/{id}/transactions |
| Satış faturası ve taslakları | /v1/invoices (taslağı status: draft ayırır) |
| Gelen (alış) e-faturalar | /v1/inbox-invoices |
| e-SMM / e-Müstahsil | /v1/receipts |
| e-İrsaliye | /v1/despatches |
| Alıcının e-fatura posta kutusu sorgusu | /v1/e-invoice-inboxes/{tax_number} |
contacts ile accounts ayrımı burada keskindir: “hesap” sözcüğü YouSoft’ta kasa ve banka demektir, carinin bakiyesi demek değildir. Cari bakiyesini contacts kaynağından, hareketlerini ledger’dan okursunuz.
İlişkiler satır içi gelir — included[] yok
JSON:API alışkanlığıyla yanıtın kökünde bir included[] dizisi arayıp tip+id ile birleştirme yapmayın: burada genişletme satır içidir. ?include=contact istediğinizde cari, faturanın kendi contact alanına yazılır. Derinlik 1’dir; noktalı ad 400 alır.
Eşleşen cari kartı yoksa contact anahtarı hiç gelmez (null da değil) — belge satırı cari kartına FK ile değil VKN/TCKN ile bağlanır ve kartı açılmamış alıcıya da fatura kesilir. Ayrıntısı sorgu sözleşmesinde.
Sayfalama: numara değil imleç, tavan 25 değil 100
page= yoktur; sayfa meta.next_cursor ile ilerler ve page_size tavanı 100’dür (varsayılan 25). Toplam kayıt sayısı (total) yayımlanmaz — ilerleme çubuğu kuran istemciler bunu baştan bilsin.
Kimlik: OAuth token değil, istek imzası
Jeton uç noktası, yenileme jetonu ve süre yönetimi yoktur. Her istek anahtar + zaman damgası + HMAC-SHA256 imzasıyla gider; imza gövdeyi ve ham sorgu dizesini kapsar. Geçişte en sık kaybedilen yer burasıdır: test vektörünü ilk gün koşturun.
password grant’ının karşılığı yoktur ve olmayacaktır: kullanıcının panel parolasını üçüncü tarafa verdiren bir akış, parolayı üçüncü tarafın log ve yedeklerine taşır. Yetki, kullanıcının parolasından değil, firma sahibinin ürettiği anahtarın kapsamlarından gelir. client_credentials de v1’de yoktur — gerekçesi başlangıç rehberinde.
Gönderim asenkrondur
POST /v1/invoices/{id}/send 202 döner ve bu, belgenin GİB’e ulaştığı anlamına gelmez: uç, taslağı gönderilebilir olduğunu doğrular ve kuyruğa alır. İlerlemeyi GET /v1/invoices/{id} ile status alanından izleyin (draft → sending → sent, ya da failed); ham GİB/NES durumu status_detail’dedir. Yanıtı senkron sanan bir istemci, faturayı gönderilmemiş sayıp yeniden dener.