API entegrasyon şartnamesi
Entegrasyon: Mağaza siparişlerinden muhasebeye
Sürüm: 1.0
Hazırlayan: Hamza Idrissi
Tarih: 5 Nisan 2029
1. Amaç
Ödemesi alınmış her web mağazası siparişini satış faturası olarak muhasebe sistemine gönderin, böylece finans ekibi siparişi yeniden yazmak zorunda kalmasın.
2. Sistemler
- Veri gönderen: Web mağazası (API v2)
- Veri alan: Muhasebe sistemi (REST API)
3. Veri akışı
1. Müşteri bir siparişin ödemesini yapar.
2. Mağaza, entegrasyon hizmetine bir webhook gönderir.
3. Hizmet siparişi faturaya dönüştürür ve muhasebe API'sini çağırır.
4. Muhasebe sistemi bir fatura numarası döndürür; hizmet bunu siparişe kaydeder.
4. Uç noktalar ve mesajlar
| Yöntem ve yol | Ne yapar | Ana alanlar | Ne döndürür |
|---|---|---|---|
| POST /invoices | Fatura oluştur | Gövde: müşteri, satırlar, vergi, toplam | Döndürür: fatura kimliği ve numarası |
| GET /customers?email= | Müşteri bul | Döndürür: müşteri kimliği veya boş | |
| POST /customers | Müşteri oluştur | Gövde: ad, e-posta, adres |
5. Alan eşleme
order.total_paid → invoice.total
order.billing_email → customer.email
order.items[].sku → line.product_code
6. Kimlik doğrulama ve güvenlik
OAuth 2.0 istemci kimlik bilgileri. Belirteçler bir saat geçerlidir. Gizli bilgiler kasada tutulur, asla kodda olmaz. Tüm çağrılar HTTPS kullanır. Webhook'lar imzalanır ve imza kontrol edilir.
Kişisel veriler yalnızca gerektiğinde gönderilir, günlüklere yazılmaz ve her iki sistemin gizlilik koşulları kapsamındadır.
7. Hatalar ve yeniden denemeler
429 ve 5xx hatalarında artan gecikmelerle en fazla 5 kez yeniden deneyin. 4xx hatalarını yeniden denemeyin; günlüğe kaydedin ve finans ekibine uyarı verin. Her faturanın benzersiz bir anahtarı vardır, böylece yeniden deneme yinelenen kayıt oluşturamaz.
8. Sınırlar ve hacimler
Muhasebe API'si dakikada 60 çağrıya izin verir. Günde 400 sipariş, kampanya günlerinde 2.000'e kadar beklenir.
9. Testler
Muhasebe test ortamını kullanın. Normal bir siparişi, indirimli bir siparişi, iadeyi, zaten var olan bir müşteriyi ve API kesintisini test edin.
10. Sahipler ve destek
Sahip: E-ticaret ekibi. Destek: Hamza Idrissi. Eskalasyon: muhasebe satıcısının destek masası.
11. Değişiklikler ve sürümleme
Taraflardan biri, uyumluluğu bozan bir değişikliği 30 gün önceden bildirir.