Fatura

External Commerce API V1 fatura erişimi read-only'dir.

Fatura oluşturma, provider'a gönderme veya iptal External Commerce API V1 write contract'ına dahil değildir.

Endpointler

GET/invoicesFaturaları listele

GET/invoices/{invoice}Fatura detayı

GET/orders/{order}/invoiceSipariş faturalarını oku

Invoices API ne işe yarar?

BYNovax siparişlerine bağlı fatura kayıtlarını dış sistemden okumak için kullanılır.

External Commerce API V1 içerisinde invoice işlemleri read-only'dir.

Gerekli scope

Invoice read endpointleri orders:read scope kullanır.

Endpointler

Endpoint	Amaç
GET /invoices	Tenant kapsamındaki faturaları listele
GET /invoices/{invoice}	Tek fatura kaydını oku
GET /orders/{order}/invoice	Belirli siparişe bağlı faturaları oku

Authority zinciri

Invoice erişimi doğrudan istemcinin gönderdiği store_id üzerinden yapılmaz. Credential store kapsamı belirlenir, ardından yalnızca o store'a ait order kayıtları ve bu order'lara bağlı connect_invoices kayıtları erişilebilir olur.

Credential → Store → Orders → connect_invoices

Neden invoice alanları provider'a göre değişebilir?

Fatura payload'ı connect_invoices authority'sinden gelir ve provider-specific alanlar içerebilir. Bu nedenle entegrasyonunuz yalnızca ihtiyaç duyduğu alanları okumalı ve ek alanları tolere etmelidir.

Response içerisine commerce_order_no gibi sipariş eşleme bilgisi eklenebilir; internal store authority alanları dış response'a taşınmaz.

Order invoice endpointi

GET /orders/{order}/invoice belirli sipariş için invoice listesini döndürür. Response order_id, order_no ve invoices koleksiyonunu içerir; meta.count kayıt sayısını gösterebilir.

Write işlemleri neden yok?

Fatura oluşturma External Commerce API V1 write contract'ına dahil değildir.
Faturayı provider'a gönderme dahil değildir.
Fatura iptal işlemi dahil değildir.

Muhasebe entegrasyon senaryosu

1. Siparişi orders API ile ERP'ye alın.
2. BYNovax order ID eşlemesini saklayın.
3. GET /orders/{order}/invoice çağırın.
4. invoices boşsa daha sonra tekrar kontrol edin.
5. Fatura oluştuysa provider payload'ını muhasebe
   sisteminizin ihtiyaç duyduğu alanlara map edin.

Çalıştığını nasıl doğrularım?

orders:read scope var.
Invoice endpointleri 200 dönüyor.
Başka tenant'a ait order faturaları görünmüyor.
Boş invoices dizisi hata olarak değerlendirilmemeli.
Provider'a özel bilinmeyen alanlar parser'ı bozmuyor.

Invoice ve invoice_address farkı

invoice_address bir adres snapshot contractıdır; invoice endpointleri connect_invoices authority'sindeki fatura kayıtlarını temsil eder.

Kaynak	Anlam
orders[].invoice_address	Siparişin fatura adresi
GET /orders/{order}/invoice	Siparişe bağlı fatura kayıtları
GET /invoices	Tenant kapsamındaki invoice kayıtları
GET /invoices/{invoice}	Tek invoice kaydı

Muhasebe reconciliation kuralları

ERP order ID eşlemesini invoice kaydından önce oluşturmalıdır.
Bir sipariş için invoices dizisinin boş olması teknik hata olmak zorunda değildir; fatura henüz oluşmamış olabilir.
Provider-specific bilinmeyen invoice alanlarını parser'ın bozulmasına neden olmayacak şekilde tolere edin.
External Commerce API V1 invoice contractı read-only'dir.
Fatura oluşturma, gönderme veya iptal endpointi varmış gibi entegrasyon geliştirmeyin.