Dokümantasyon

4invoices dokümantasyonu iki katmandan oluşur: kod yazmadan kullandığınız panel ve kendi sisteminizin fatura kestiği, belgeyi ulusal e-fatura sürecinden geçirdiği genel API (Romanya'da: ANAF e-Factura). Bu sayfa ikinci katmanın giriş noktasıdır.

Tam API dokümantasyonunu aç →

Neleri otomatikleştirebilirsiniz

Genel API fatura ve proforma kesimini, iade faturalarını, ticaret sicili kontrolüyle müşterileri (Romanya'da: ANAF sicili), numaralandırma serilerini ve ulusal e-fatura sürecinin tamamını (Romanya'da: e-Factura) kapsar: CIUS-RO ön kontrolü, SPV'ye gönderim, durum takibi, imzalı yanıt ve tedarikçilerden gelen faturaların kutusu.

https://api.4invoices.net/v1 · 25 endpoints · OpenAPI şeması (anahtar gerekmez)

invoices:read · invoices:write · clients:read · clients:write · efactura:read · efactura:submit

Kimlik doğrulama

İlk çağrıdan önceFaturalama → Ayarlar → API erişimi
bash
curl -sS -X POST https://api.4invoices.net/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cli_XXXXXXXXXXXX",
    "client_secret": "sec_XXXXXXXXXXXXXXXXXXXX"
  }'

# → {"access_token":"eyJ...","token_type":"Bearer","expires_in":3600,
#    "scope":"invoices:read invoices:write efactura:submit"}
Yalnızca sunucudan sunucuya. API'yi tarayıcı JavaScript'inden asla çağırmayın: client_secret ziyaretçiye ulaşır ve CORS zaten her origin'i engeller.

6 adımda ilk fatura

  1. Panelde Faturalama → Ayarlar → API erişimi bölümünden bir kimlik bilgisi oluşturun ve client_secret değerini kopyalayın — yalnızca bir kez gösterilir.
  2. Firma profilini tamamlayın ve fiscale türünde en az bir seri etkinleştirin; aksi hâlde kesim issuer_profile_incomplete veya no_series_configured döner.
  3. Kimlik bilgisini token ile değişin: grant_type client_credentials ile POST /v1/auth/token. Token bir saat geçerlidir — önbelleğe alın, her istek için yenisini almayın.
  4. Faturayı kesin: Idempotency-Key başlığı ve yüzde olarak vat_rate (21, 0.21 değil) ile POST /v1/invoices.
  5. Ön kontrolü (Romanya'da: CIUS-RO) POST /v1/invoices/{id}/efactura/validate ile çalıştırın, ardından POST /v1/invoices/{id}/efactura/submit ile ulusal e-fatura sistemine (Romanya'da: ANAF) gönderin.
  6. Durumu GET /v1/efactura/submissions/{id} ile accepted veya rejected olana kadar izleyin.
bash
# 1 — token (1 saat, önbelleğe al)
ACCESS_TOKEN=$(curl -sS -X POST https://api.4invoices.net/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"cli_XXX","client_secret":"sec_XXX"}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["access_token"])')

# 2 — faturayı kes (Idempotency-Key ZORUNLUDUR)
curl -sS -X POST https://api.4invoices.net/v1/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-10457-invoice' \
  -d '{"buyer":{"name":"Exemplu Comert SRL","tax_id":"RO12345678","county":"Cluj","city":"Cluj-Napoca","country":"RO"},
       "lines":[{"description":"Abonament SaaS","quantity":1,"unit_price":400,"vat_rate":21}]}'

# 3 — preflight CIUS-RO, then send to ANAF
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/efactura/validate \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/efactura/submit \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: efactura-inv_01J7ABC-1'

Konuya göre kılavuzlar

Her konunun kendi sayfası var: ilgili uç noktalar, örnekler ve hatalar.

Tam API dokümantasyonunu aç →