Savrsoft API — geliştirici dokümantasyonu

Kimlik doğrulama

Tüm API istekleri, bearer token olarak bir API anahtarı kullanır. Uygulamada Geliştirici → API anahtarları altından bir tane oluşturun. Anahtarlar salt okunur veya okuma/yazma.

curl https://savrsoft.com/api/v1/events \
  -H "Authorization: Bearer savr_live_your_key_here"

Temel URL: https://savrsoft.com/api/v1 · Tüm yanıtlar JSON formatındadır. Hatalar { "error": "…" } şeklinde 4xx/5xx durum koduyla döner.

Durum kodları

Kod	Ne zaman alırsınız
`200`	Başarılı okuma.
`201`	Başarıyla oluşturuldu. Gövde `{ "id": 42 }` — kaydın geri kalanına ihtiyacınız varsa kaydı getirin.
`400`	Gerekli bir alan eksik, örneğin `{ "error": "name is required" }`, ya da bir sayfalama imleci okunamadı.
`401`	API anahtarı yok, hatalı biçimlendirilmiş ya da iptal edilmiş bir anahtar.
`403`	Salt okunur bir anahtar yazma işlemi için kullanıldı. Aşağıdan okuma/yazma yetkili bir anahtar oluşturun: Geliştirici → API anahtarları.
`404`	Kayıt mevcut değil ya da başka bir organizasyona ait — bu iki durum kasıtlı olarak birbirinden ayırt edilemez. Tanınmayan bir yol veya yöntem için de aynı yanıt döner.

Bu API'nin Kapsamı

API yalnızca okuma ve oluşturmaişlemlerine izin verir. Herhangi bir DELETE, PUT veya PATCH uç noktası bulunmaz — bu yöntemlerden biriyle yapılan istek, tanınmayan herhangi bir yolla aynı şekilde 404 Bilinmeyen uç noktadöndürür. Silme ve düzenleme işlemleri uygulama üzerinden yapılır, böylece bir entegrasyon bir cateringcinin kayıtlarını yok edemez. Oluşturmanın ötesinde yazma erişimine ihtiyaç duyarsanız, ne inşa ettiğinizi bize anlatın.

Sayfalama

Her liste uç noktası sayfalanır. Geçirin: limit (varsayılan 100, maksimum 500) ve takip edin: next_cursor ta ki has_more durumu false:

{
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "eyJuYW1lIjoiQWNtZSIsImlkIjo0Mn0"
}

Sonraki sayfayı almak için imleci aynen geri gönderin. Onu opak bir değer olarak ele alın — kodlama değişebilir:

curl "https://savrsoft.com/api/v1/clients?limit=100&cursor=eyJuYW1lIjoiQWNtZSIsImlkIjo0Mn0" \
  -H "Authorization: Bearer savr_live_your_key_here"

Sayfalama, bir ofsete değil, aldığınız son satıra bağlıdır; bu sayede siz sayfalar arasında ilerlerken oluşturulan veya silinen satırlar bir kaydı atlamanıza ya da tekrar görmenize neden olmaz. Bir cursor süresiz olarak geçerliliğini korur.

Parametre	Davranış
`limit`	1–500. Boş, sıfır, negatif veya sayısal olmayan değerlerde varsayılan olarak 100 kullanılır; 500'ün üzerindeki değerler 500 ile sınırlandırılır.
`cursor`	`next_cursor` önceki sayfadan. İlk sayfa için bu alanı boş bırakın. Okunamayan bir cursor — bozuk ya da farklı bir endpoint'e ait olan — `400 Invalid cursor` döndürür, baştan sessizce yeniden başlamaz.

Sıralama: /events ve /invoices önce en yeniler; /recipes ve /clients isme göre sıralanır, isimlerin tekrarlandığı durumlarda id'ye göre eşitlik bozularak sayfalamanın kararlı kalması sağlanır.

Endpoint'ler

GET/v1/me

Kuruluşunuz (id, ad, para birimi).

GET/v1/events

Etkinlikleri en yeniden en eskiye listeler. Sayfalanmıştır — yukarıdaki Sayfalama bölümüne bakın.

GET/v1/events/{id}

Yemekleriyle birlikte tek bir etkinlik.

POST/v1/events · okuma/yazma izni gerektirir

Bir etkinlik oluşturun. Gövde:

{ "name": "Acme holiday party", "event_date": "2026-12-18",
  "guests": 120, "price_per_head": 55, "event_type": "corporate" }

GET/v1/recipes · GET/v1/recipes/{id}

Tarifleri listeleyin (alerjenler ve diyet etiketleriyle) veya malzemeleriyle birlikte tek bir tarifi görüntüleyin. Liste sayfalanır ve isme göre sıralanır.

GET/v1/clients · POST/v1/clients

Müşterileri listeleyin (isme göre sayfalanmış) veya yeni bir müşteri oluşturun. Oluşturma gövdesi: { "name": "...", "email": "...", "phone": "...", "company": "..." }

GET/v1/invoices · GET/v1/invoices/{id}

Hesaplanmış toplamlarıyla faturaları en yeniden en eskiye listeleyin veya kalem detaylarıyla tek bir faturayı görüntüleyin. Liste sayfalanır.

Webhook'lar

Şu adresten bir uç nokta kaydedin: Geliştirici → Webhook'lar. Etkinlikler gerçekleştiğinde bir JSON POST yükü gönderiyoruz:

{
  "id": "evt_abc123",
  "type": "event.inquiry",
  "created_at": "2026-07-17T18:20:00.000Z",
  "data": { "id": 42, "name": "Corporate lunch — Dana Ruiz", ... }
}

Etkinlik türleri

Tür	Ne zaman tetiklenir
`event.created`	Bir etkinlik oluşturulduğunda
`event.inquiry`	Yeni bir online catering talebi geldiğinde
`invoice.sent`	Bir fatura gönderildi olarak işaretlendiğinde
`invoice.paid`	Bir fatura ödendi olarak işaretlendiğinde
`proposal.approved`	Bir müşteri teklifi onayladığında
`client.created`	Bir müşteri oluşturulduğunda

İmzaları doğrulama

Her teslimat bir x-savrsoft-signature başlığı içerir: ham istek gövdesinin, webhook imzalama anahtarınızla anahtarlanmış HMAC-SHA256 karması. Aynısını hesaplayıp karşılaştırın:

// Node.js
const crypto = require('crypto');
const sig = crypto.createHmac('sha256', SIGNING_SECRET)
  .update(rawBody).digest('hex');
if (sig !== req.headers['x-savrsoft-signature']) reject();

Gizlilik · Güvenlik · Şartlar · Sorularınız mı var? savrsoft.com · Catering entegrasyonlarını dakikalar içinde oluşturun.