Callback bildirimi (callback_url)

Fatura oluştururken gövdede callback_url gönderirseniz, faturanın işlem durumu her değiştiğinde bu adrese POST isteği yapılır. Böylece durumu öğrenmek için sürekli GET /api/invoices/{id} çağırmanız (polling) gerekmez.

Hesap düzeyinde webhook'tan farklıdır

callback_url fatura başına tanımlanır ve yalnızca o faturanın durum değişikliklerinde tetiklenir. Hesap düzeyinde genel bildirim adresi için Webhook URL ayarı endpoint'ine bakın.

Ne zaman tetiklenir?

Aynı fatura için birden fazla bildirim gelebilir:

• Fatura iş akışının (workflow) bir adımı tamamlandığında veya hata aldığında
• Resmileştirme (GİB'e gönderim) sonuçlandığında — başarılı veya hatalı
• Arka planda çalışan durum kontrolü, faturanın resmi durumunda değişiklik tespit ettiğinde

Bu nedenle callback alıcınız idempotent olmalıdır: aynı invoice_id için tekrarlanan bildirimleri güvenle işleyebilmelidir.

İstek gövdesi (payload)

Bildirim, Content-Type: application/json gövdesiyle POST olarak gönderilir:

{
  "invoice_id": 123,
  "team_id": 45,
  "time": "2026-07-02 14:30:15",
  "hash": "b3f1c9a4e8d2..."
}

Alan	Tip	Açıklama
invoice_id	number	Durumu değişen faturanın ID'si.
team_id	number	Hesabınızın (team) ID'si.
time	string	Bildirimin oluşturulduğu an (Y-m-d H:i:s).
hash	string	Doğrulama imzası; aşağıya bakın.

Payload durum bilgisi içermez

Bildirim gövdesinde workflow_status, formal_status, ETTN veya PDF adresi bulunmaz. Bildirimi aldıktan sonra güncel veriyi almak için GET /api/invoices/{id} çağrısı yapın.

İsteğin zaman aşımı 10 saniyedir; uç noktanız bu süre içinde 2xx durum kodu döndürmelidir.

İmza doğrulama (hash)

hash alanı, isteğin gerçekten Fatura Entegratör'den geldiğini doğrulamanızı sağlar:

hash = HMAC-SHA512( invoice_id + team_id + time , API_ANAHTARINIZ )

Üç değer araya ayraç konmadan art arda eklenir (örn. 123 + 45 + 2026-07-02 14:30:15 → "123452026-07-02 14:30:15"), anahtar olarak panelden aldığınız API anahtarı kullanılır.

🐘 PHP

<?php
$payload = json_decode(file_get_contents('php://input'), true);

$expected = hash_hmac(
    'sha512',
    $payload['invoice_id'] . $payload['team_id'] . $payload['time'],
    'YOUR_API_KEY'
);

if (! hash_equals($expected, $payload['hash'])) {
    http_response_code(401);
    exit;
}

// Bildirim doğrulandı; güncel durumu çekin:
// GET https://app.faturaentegrator.com/api/invoices/{$payload['invoice_id']}
http_response_code(200);

🟢 Node.js

import crypto from 'node:crypto';

function verifyCallback(payload, apiKey) {
  const expected = crypto
    .createHmac('sha512', apiKey)
    .update(`${payload.invoice_id}${payload.team_id}${payload.time}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(payload.hash)
  );
}

// Express örneği
app.post('/fatura-callback', express.json(), async (req, res) => {
  if (!verifyCallback(req.body, process.env.FE_API_KEY)) {
    return res.sendStatus(401);
  }

  res.sendStatus(200); // Önce hızlıca yanıtlayın

  // Ardından güncel durumu çekin:
  // GET /api/invoices/{req.body.invoice_id}
});

🐍 Python

import hashlib
import hmac

def verify_callback(payload: dict, api_key: str) -> bool:
    message = f"{payload['invoice_id']}{payload['team_id']}{payload['time']}"
    expected = hmac.new(
        api_key.encode(), message.encode(), hashlib.sha512
    ).hexdigest()
    return hmac.compare_digest(expected, payload['hash'])

Önerilen akış

1. POST /api/invoices isteğinde callback_url gönderin; yanıttaki id değerini kendi sipariş/fatura kaydınızla eşleyin.
2. Callback geldiğinde hash imzasını doğrulayın ve hemen 200 dönün.
3. GET /api/invoices/{invoice_id} ile güncel kaydı çekin; workflow_status, formal_status, ettn, serial_number ve pdf_url alanlarını kendi sisteminize işleyin.
4. formal_status: failed görürseniz hata ayrıntıları için kayıttaki errors[] dizisine bakın (bkz. Hata yanıtları).

Test

Dummy Fatura entegrasyonuyla oluşturduğunuz test faturalarında da callback_url tetiklenir; canlıya geçmeden bildirimi uçtan uca doğrulayabilirsiniz.