Docsper API

Kimlik doğrulama

Anahtarları Docsper içinde Entegrasyon sayfasından firma yöneticisi oluşturur. Her istekte Authorization: Bearer <anahtar> gönderin. dps_test_ ile başlayan anahtarlar deneme modundadır: kredi tüketmez, PDF üretmez ve yalnızca deneme sevkiyatlarını görür. Oran sınırı anahtar başına dakikada 60 istektir.

Uç noktalar

• GET /api/v1/ben — bağlantı sınaması (anahtarın firması ve modu)
• GET /api/v1/urunler — ürün kartları (?kod=, ?limit=)
• POST /api/v1/urunler — ürün kartı ekle / güncelle (ERP stok koduyla; tek kayıt ya da 200'e kadar kayitlar)
• GET /api/v1/cariler — cari kartları (?kod=, ?limit=)
• POST /api/v1/cariler — cari kartı ekle / güncelle (ERP cari koduyla)
• GET /api/v1/sevkiyatlar — son sevkiyatlar (?referansNo=, ?durum=, ?limit=)
• POST /api/v1/sevkiyatlar — sevkiyat oluştur (hazirla: true ile hazır durumuna geçir)
• GET /api/v1/sevkiyatlar/{id} — sevkiyat, denetim bulguları ve belgeler
• PUT /api/v1/sevkiyatlar/{id} — taslak sevkiyatı güncelle (hazır sevkiyat güncellenmez)
• POST /api/v1/sevkiyatlar/{id}/hazirla — taslağı hazır durumuna al
• POST /api/v1/sevkiyatlar/{id}/denetim — denetimi çalıştır
• POST /api/v1/sevkiyatlar/{id}/belgeler — belge üret
• GET /api/v1/sevkiyatlar/{id}/belgeler/{belgeId} — PDF için 5 dakikalık indirme linki

curl -X POST https://www.docsper.com/api/v1/sevkiyatlar \
  -H "Authorization: Bearer dps_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: siparis-2026-0042" \
  -d '{
    "paraBirimi": "EUR",
    "alici": { "unvan": "Bergström Textilhandel GmbH", "ulke": "Almanya", "vat": "DE811907980" },
    "urunSatirlari": [
      { "gtip": "610910000000", "aciklamaTr": "Pamuklu tişört", "aciklamaEn": "Cotton T-shirt",
        "birim": "ADET", "miktar": 500, "birimFiyat": 4.5, "birimNetAgirlikKg": 0.18, "birimBrutAgirlikKg": 0.2 }
    ],
    "sartlar": { "incoterm": "FOB", "incotermYeri": "Mersin", "tasimaSekli": "deniz" },
    "hazirla": true
  }'

ERP kodlarıyla en az veriyle sevkiyat

Ürün ve cari kartlarını ERP kodlarıyla bir kez gönderin; sonraki siparişlerde yalnızca urunKodu, miktar, fiyat ve alici.kod yeterlidir. GTİP, açıklama, ağırlık, adres ve müşteri varsayılanları karttan dolar; ürün kartında koli düzeni varsa paketler de kendiliğinden hesaplanır. Kart güncellemesinde yalnızca gönderdiğiniz dolu alanlar yazılır — Docsper'da elle tamamlanan bilgi silinmez.

# 1) Kartları bir kez gönderin (tekrar gönderirseniz güncellenir, kopya oluşmaz)
curl -X POST https://www.docsper.com/api/v1/urunler -H "Authorization: Bearer dps_live_..." -H "Content-Type: application/json" \
  -d '{ "kayitlar": [ { "kod": "TS-001", "aciklamaTr": "Pamuklu tişört", "aciklamaEn": "Cotton T-shirt", "gtip": "610910000000",
        "birimNetAgirlikKg": 0.18, "birimBrutAgirlikKg": 0.2, "ambalaj": { "koliIciAdet": 50, "uzunlukCm": 60, "genislikCm": 40, "yukseklikCm": 30 } } ] }'

curl -X POST https://www.docsper.com/api/v1/cariler -H "Authorization: Bearer dps_live_..." -H "Content-Type: application/json" \
  -d '{ "kod": "120.01.042", "unvan": "Bergström Textilhandel GmbH", "ulke": "Almanya", "vat": "DE811907980",
        "varsayilanlar": { "incoterm": "FOB", "incotermYeri": "Mersin", "tasimaSekli": "deniz", "belgeDili": "en" } }'

# 2) Sipariş geldiğinde yalnızca kod, miktar ve fiyat yeterli
curl -X POST https://www.docsper.com/api/v1/sevkiyatlar -H "Authorization: Bearer dps_live_..." -H "Content-Type: application/json" \
  -d '{ "referansNo": "SIP-2026-0042", "paraBirimi": "EUR", "alici": { "kod": "120.01.042" },
        "urunSatirlari": [ { "urunKodu": "TS-001", "miktar": 500, "birimFiyat": 4.5 } ], "hazirla": true }'

Uçtan uca akış

Sipariş numaranızı referansNo olarak gönderirseniz sevkiyatı sonradan GET /api/v1/sevkiyatlar?referansNo=... ile bulabilirsiniz.

# 1) Bağlantıyı sına
curl https://www.docsper.com/api/v1/ben -H "Authorization: Bearer dps_test_..."

# 2) Sevkiyatı oluştur (yukarıdaki istek) -> yanıttaki "id" değerini saklayın
# 3) Denetimi çalıştır
curl -X POST https://www.docsper.com/api/v1/sevkiyatlar/{id}/denetim -H "Authorization: Bearer dps_live_..."

# 4) Belgeleri üret (canlı anahtar gerekir)
curl -X POST https://www.docsper.com/api/v1/sevkiyatlar/{id}/belgeler -H "Authorization: Bearer dps_live_..."

# 5) Her belge için indirme linkini al, PDF'i indir (link 5 dakika geçerlidir)
curl https://www.docsper.com/api/v1/sevkiyatlar/{id}/belgeler/{belgeId} -H "Authorization: Bearer dps_live_..."
curl -L -o fatura.pdf "<yanıttaki indirmeUrl>"

Tekrar koruması

POST isteklerinde Idempotency-Key başlığı gönderin. Aynı anahtarla 24 saat içinde gelen ikinci istek işlenmez; ilk yanıt Idempotent-Replayed: true başlığıyla aynen döner.

Webhook'lar

Olaylar: sevkiyat.olusturuldu, sevkiyat.hazirlandi, denetim.tamamlandi, belge.hazir. İşlem Docsper panelinden de API'den de yapılsa gönderilir; veri.kaynak alanı hangisi olduğunu söyler. Her istek X-Docsper-Imza: t=<unix>,v1=<hex> başlığını taşır; v1, gizli anahtarınızla <t>.<ham gövde> metninin HMAC-SHA256 özetidir.

5 saniye içinde 2xx dönün. Dönülmezse (ağ hatası, 408, 429 ya da 5xx) 2 ve 10 saniye sonra iki kez daha denenir. Aynı olay aynı id ile gelir; tekrarları bu alanla ayıklayın. Başarısız teslimleri Entegrasyon sayfasından elle yeniden gönderebilirsiniz.

{
  "id": "evt_6f1c...",
  "olay": "belge.hazir",
  "mod": "canli",
  "olusturma": "2026-10-03T09:12:44.000Z",
  "veri": {
    "sevkiyatId": "abc123",
    "referansNo": "SVK-20261003-K7QD",
    "id": "belge456",
    "tip": "ticari-fatura",
    "numara": "TF-2026-0042",
    "versiyon": 1,
    "dil": "en",
    "indirmeYolu": "/api/v1/sevkiyatlar/abc123/belgeler/belge456",
    "kaynak": "panel"
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

export function docsperImzasiGecerliMi(gizli: string, hamGovde: string, baslik: string): boolean {
  const t = Number(baslik.match(/t=(\d+)/)?.[1]);
  const v1 = baslik.match(/v1=([a-f0-9]{64})/)?.[1];
  if (!t || !v1 || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const beklenen = createHmac("sha256", gizli).update(`${t}.${hamGovde}`).digest("hex");
  return timingSafeEqual(Buffer.from(beklenen, "hex"), Buffer.from(v1, "hex"));
}

Kod yazmadan bağlama (Make, Zapier, n8n)

Docsper için hazır bir Make ya da Zapier uygulaması yoktur; bu araçların genel HTTP ve webhook modülleriyle bağlanırsınız. Docsper'a veri göndermek için HTTP modülünde yukarıdaki adresleri ve Authorization: Bearer <anahtar> başlığını kullanın. Docsper'dan olay almak için aracın verdiği webhook adresini Entegrasyon sayfasındaki adres alanına yapıştırın. ERP'nizin bu araçlara bağlanabilmesi, ERP'nin kendi dışa açık servisine bağlıdır.

Hatalar

Hata gövdesi: { "hata": { "kod": "...", "mesaj": "...", "message": "..." } }. Kodlar: anahtar_gecersiz (401), kredi_tukendi (402), api_kapali (403), bulunamadi (404), sevkiyat_hazir_degil (409), dogrulama_hatasi ve eksik_veri (422), oran_siniri (429), storage_kapali (503).