4invoices inkişafçı API-si

• 4invoices ictimai API-si giriş və çıxışda JSON ilə HTTPS üzərində REST-dir.
• Bir istehsal hostu: https://api.4invoices.net/v1. Ayrıca sınaq (sandbox) hostu yoxdur.
• OpenAPI 3.1 spesifikasiyası ictimaidir və açar tələb etmir — onu birbaşa Postman-a və ya müştəri generatoruna idxal edin.
• Hər cavab X-Request-Id başlığı daşıyır; dəstək istədiyiniz zaman onu qeyd edin.
• Hər fiskal yazı idempotentdir: timeout-dan sonra təkrar cəhd heç vaxt ikinci sənəd yaratmır.

• Milli elektron qaimə sistemi ilə bütün dövr API üzərindən (Rumıniyada: ANAF e-Factura): ilkin yoxlama, təqdimat, izləmə, imzalanmış cavab və gələn qutu. Heç bir rumın rəqibi bunu təqdim etmir.
• SmartBill-in milli elektron qaimə sisteminə (Rumıniyada ANAF) təqdimat üçün son nöqtəsi yoxdur — göndərmə yalnız interfeysdə hesab parametridir — və faktura siyahısı üçün son nöqtəsi də yoxdur.
• Oblio müştəri və məhsulları yalnız sənəd yaratmanın yan təsiri kimi yarada bilir, birinci dərəcəli resurs kimi yox.
• Təqdim etmədən UBL XML generasiyası (Rumıniya üçün CIUS-RO): qanuni sənədi milli sistemə toxunmadan fayl kimi alırsınız.
• Fiskal yazılarda idempotentlik: timeout-dan sonra təkrar cəhd ikinci faktura yaratmır və ikinci nömrəni xərcləmir.
• Təchizatçı fakturalarının proqramla oxuna bilən gələn qutusu — avtomatik uzlaşdırmanın əsası.

1. Panelinizdə Fakturalaşdırma → Parametrlər → API girişi bölməsində kredensial yaradın və client_secret-i kopyalayın — o yalnız bir dəfə göstərilir.
2. Şirkət profilini tamamlayın və ən azı bir fiscale növ seriyanı aktivləşdirin; əks halda yaradılma issuer_profile_incomplete və ya no_series_configured qaytarır.
3. Kredensialı tokenə dəyişdirin: grant_type client_credentials ilə POST /v1/auth/token. Token bir saat etibarlıdır — onu keşdə saxlayın, hər sorğu üçün yenisini almayın.
4. Fakturanı yaradın: Idempotency-Key başlığı ilə POST /v1/invoices və vat_rate faiz kimi (21, 0,21 yox).
5. POST /v1/invoices/{id}/efactura/validate ilə ilkin yoxlamanı edin (Rumıniya üçün CIUS-RO), sonra POST /v1/invoices/{id}/efactura/submit ilə milli elektron qaimə sisteminə göndərin.
6. accepted və ya rejected olana qədər GET /v1/efactura/submissions/{id} ilə vəziyyəti izləyin.

bash
# 1 — token (1 saat, keşdə saxlayın)
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 — fakturanı yaradın (Idempotency-Key MƏCBURİDİR)
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'

javascript
const BASE = "https://api.4invoices.net/v1";

const token = await fetch(`${BASE}/auth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "client_credentials",
    client_id: process.env.FOURINVOICES_CLIENT_ID,
    client_secret: process.env.FOURINVOICES_CLIENT_SECRET,
  }),
}).then((r) => r.json()).then((d) => d.access_token);

const invoice = await fetch(`${BASE}/invoices`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${orderId}-invoice`,
  },
  body: JSON.stringify({
    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 }],
    currency: "RON",
    metadata: { order_id: String(orderId) },
  }),
}).then((r) => r.json());

console.log(invoice.number, invoice.totals); // "FCT-000123" { net, vat, gross }

python
import os, uuid, requests

BASE = "https://api.4invoices.net/v1"

token = requests.post(f"{BASE}/auth/token", json={
    "grant_type": "client_credentials",
    "client_id": os.environ["FOURINVOICES_CLIENT_ID"],
    "client_secret": os.environ["FOURINVOICES_CLIENT_SECRET"],
}, timeout=30).json()["access_token"]

headers = {
    "Authorization": f"Bearer {token}",
    # Hər MƏNTİQİ əməliyyat üçün bir açar — təkrar cəhddə ondan istifadə edin, heç vaxt yenidən yaratmayın.
    "Idempotency-Key": f"order-{order_id}-invoice",
}

invoice = requests.post(f"{BASE}/invoices", headers=headers, json={
    "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}],   # faiz, 0,21 yox
    "currency": "RON",
}, timeout=60).json()

print(invoice["number"], invoice["totals"])

• Axın client_credentials-dır: client_id + client_secret-i Bearer access_token ilə əvəz edirsiniz.
• Token 3600 saniyədə bitir. Hər çağırışda deyil, bitməzdən əvvəl yeniləyin — POST /auth/token öz IP üzrə limitinə malikdir.
• client_secret yalnız hash kimi saxlanılır və bərpa edilə bilməz. İtirsəniz, yeni kredensial yaradın və köhnəni ləğv edin.
• Yalnız server-server. CORS heç bir brauzer mənbəyinə icazə vermir: səhifənin JavaScript-indən secret ziyarətçiyə sızardı.
• Əhatələr kredensial üzrə verilir. Hər sistem üçün ayrıca kredensial yaradın və hər birinə lazım olan minimum əhatəni verin.

Fakturalaşdırma → Parametrlər → API girişi

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"}

javascript
// Tokeni keşdə saxlayın; hər sorğu üçün yeni yaratmayın.
let cached = { token: "", expiresAt: 0 };

async function getToken() {
  if (cached.token && Date.now() < cached.expiresAt - 60_000) return cached.token;

  const res = await fetch("https://api.4invoices.net/v1/auth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: process.env.FOURINVOICES_CLIENT_ID,
      client_secret: process.env.FOURINVOICES_CLIENT_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`token ${res.status}`);

  const data = await res.json();
  cached = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return cached.token;
}

• vat_rate FAİZDİR: 21 o deməkdir ki, 21%.
• (0, 1] aralığındakı dəyərlər rədd edilir — 0,19 kəsrdir, 1 isə 1% və ya 100% arasında qeyri-müəyyəndir.
• 0 etibarlıdır və azad (exempt) və ya reverse charge deməkdir; hüquqi qeydi notes-a yazın.
• Satıcı ƏDV ödəyicisi olduqda unit_price VERGİSİZ (NET) vahid qiymətdir.
• Öhdəliyə girməzdən əvvəl cəmlər lazımdır? POST /v1/invoices/preview-totals fiskal nömrə istifadə etmədən eyni hesablamanı aparır.

• Idempotency-Key başlığı POST /invoices, POST /invoices/{id}/storno və POST /invoices/{id}/efactura/submit üçün MƏCBURİDİR.
• Açarlar 24 saat yadda saxlanılır. Eyni açarın eyni body ilə təkrarı orijinal nəticəni qaytarır və Idempotency-Replayed: true qoyur.
• Eyni açar fərqli body ilə 409 idempotency_key_reuse qaytarır — artıq verilmiş fiskal sənəd heç vaxt üzərinə yazılmır.
• Hər MƏNTİQİ əməliyyat üçün bir açar, HTTP cəhdi üçün yox: order-10457-invoice, hər təkrarda yeni UUID yox.
• Səbəb texniki yox, hüquqidir: istifadə olunmuş fiskal nömrə və milli elektron qaimə sisteminə təqdim edilmiş faktura geri alına bilməz.

bash
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",
      "address": "Str. Fabricii 12",
      "city": "Cluj-Napoca",
      "county": "Cluj",
      "country": "RO",
      "email": "[email protected]"
    },
    "lines": [
      { "description": "Abonament SaaS, iulie", "quantity": 1, "unit_price": 400, "vat_rate": 21, "unit": "buc" },
      { "description": "Implementare", "quantity": 6, "unit_price": 250, "vat_rate": 21, "unit": "ora" }
    ],
    "currency": "RON",
    "document_kind": "factura",
    "due_date": "2026-08-15",
    "metadata": { "order_id": "10457" }
  }'

25 endpoints · https://api.4invoices.net/v1/openapi.json

• invoices:read
• invoices:write
• clients:read
• clients:write
• efactura:read
• efactura:submit

• Əsas fərqləndirici: milli elektron qaimə sistemi ilə bütün dövr yalnız sənəd generasiyası deyil, API vasitəsilə işləyir.
• POST /invoices/{id}/efactura/validate ilkin yoxlamanı aparır (Rumıniya üçün CIUS-RO) və milli elektron qaimə sisteminin rədd edəcəyi dəqiq sahələri qaytarır, heç nə göndərmədən.
• GET /invoices/{id}/xml təqdimat olmadan UBL XML generasiya edir (Rumıniya üçün CIUS-RO) — öz arxiviniz və ya daxili audit üçün faydalıdır.
• POST /invoices/{id}/efactura/submit onu milli elektron qaimə sisteminə təqdim edir. Geri dönməzdir: eyni fakturanın ikinci nüsxəsi sistemdən geri alına bilməz.
• Həyat dövrü normallaşdırılıb: not_sent → validating → queued → sent → processing → accepted | rejected | error. accepted qanuni olaraq ötürüldüyü deməkdir; error bizim tərəfdə nəqliyyat xətasıdır və təhlükəsiz şəkildə təkrar cəhd edilə bilər.
• GET /efactura/submissions/{id}/download milli elektron qaimə sisteminin imzalanmış cavabı ilə arxivi gətirir.
• Qəbul tərəfi də mövcuddur: POST /efactura/inbox/sync milli elektron qaimə sistemindən yeni mesajları çəkir, GET /efactura/inbox isə təchizatçılarınızın göndərdiyi faktura siyahısını verir.

bash
# CIUS-RO preflight. Sends NOTHING to ANAF.
curl -sS -X POST "https://api.4invoices.net/v1/invoices/inv_01J7ABC/efactura/validate?include_xml=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → {"invoice_id":"inv_01J7ABC","valid":false,
#    "errors":["buyer.county is required for RO buyers"],
#    "xml_base64":"PD94bWwg..."}

bash
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'

# → {"submission_id":"sub_01J7XYZ","status":"queued"}

python
import time, requests

BASE = "https://api.4invoices.net/v1"
TERMINAL = {"accepted", "rejected"}
H = {"Authorization": f"Bearer {token}"}

def wait_for_anaf(submission_id, timeout=900):
    deadline = time.time() + timeout
    delay = 15
    while time.time() < deadline:
        r = requests.get(f"{BASE}/efactura/submissions/{submission_id}", headers=H, timeout=30)
        r.raise_for_status()
        status = r.json()["status"]
        if status in TERMINAL:
            return r.json()
        # /refresh asks ANAF directly and shares the 10/min submit bucket.
        requests.post(f"{BASE}/efactura/submissions/{submission_id}/refresh", headers=H, timeout=30)
        time.sleep(delay)
        delay = min(delay * 2, 120)
    raise TimeoutError(submission_id)

• Hər 4xx və 5xx eyni zərfdən istifadə edir: { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
• type təkrar cəhd edə biləcəyinizə görə qərar verdiyiniz ümumi sinifdir («təkrar cəhd edə bilərəmmi?»), code isə öz sisteminizə xəritələdiyiniz sabit səbəbdir.
• param problemli sahənin nöqtəli yoludur, məsələn lines.0.vat_rate.
• errors[] tək sorğuda bir neçə sahədə problem olduqda görünür.
• request_id bizim tərəfdə qeyd olunur. Hər dəstək biletində qeyd edin — dəqiq sorğunu müəyyənləşdirir.
• Başqa bir müştərinin id-si üçün də 404 qaytarılır: biz heç vaxt başqasının məlumatının mövcud olduğunu təsdiq etmirik.

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Datele trimise nu sunt valide.",
    "param": "lines.0.vat_rate",
    "doc_url": "https://4invoices.net/ro/api-dezvoltatori#errors",
    "request_id": "req_8a893f2f33d4472da8d6e144",
    "errors": [
      { "param": "lines.0.vat_rate", "message": "VAT rate must be a percent (21), not a fraction", "type": "value_error" }
    ]
  }
}

• Limitlər hər kredensial üçün, hər dəqiqə: oxulara 120, yazılara 30, elektron qaimə əməliyyatlarına (submit, refresh, inbox/sync) 10.
• X-RateLimit-Limit, X-RateLimit-Remaining və X-RateLimit-Reset HƏR cavabda görünür, 429 daxil olmaqla.
• 429 həmçinin saniyələrlə Retry-After daşıyır. Ona əməl edin; sıx dövrədə təkrar cəhd etməyin.
• 10/dəqiqə qrupu ona görə mövcuddur ki, Rumıniyada ANAF özü hər CIF üçün dəqiqədə təxminən bir mesaj siyahısı çağırışına icazə verir.
• /efactura/inbox/sync-i aqressiv polling yerinə cron-a qoyun.
• Daha yüksək limitlər lazımdır? Gözlənilən gündəlik həcminizlə Əlaqə bölməsi üzərindən müraciət edin.

X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset · Retry-After

http
HTTP/2 429
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1785312000
Retry-After: 17
Content-Type: application/json

{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded",
 "message":"...","doc_url":"https://4invoices.net/ro/api-dezvoltatori#errors",
 "request_id":"req_..."}}

javascript
// Retry-After-a əməl edin; 429-dan başqa 4xx-i heç vaxt təkrar cəhd etməyin.
async function call(url, init, attempt = 0) {
  const res = await fetch(url, init);
  if (res.status === 429 || res.status >= 500) {
    if (attempt >= 5) return res;
    const retryAfter = Number(res.headers.get("Retry-After")) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return call(url, init, attempt + 1);
  }
  return res;
}

// Yazının təkrar cəhdi MƏCBURƏN eyni Idempotency-Key-dən istifadə etməlidir, əks halda verirsiniz
// ikinci fiskal sənədi.

Hər mövzunun öz səhifəsi var: müvafiq son nöqtələr, nümunələr və xətalar.

• 4invoices API-də autentifikasiyaclient_id və client_secret-i yalnız server-server üçün bir saatlıq Bearer tokenə dəyişirsiniz.
• API vasitəsilə faktura yaratmaqIdempotency-Key ilə POST /invoices, ƏDV faizlə, həmçinin siyahı, storno və ödənilmiş kimi qeyd etmə.
• Müştərilər və rəsmi reyestrdə axtarıştax_id üzrə dublikatsız əlavə etmə və ya yeniləmə (upsert) və elektron qaimənin rədd edilməməsi üçün rəsmi reyestrdə (Rumıniyada: ANAF) axtarış.
• API üzərindən milli elektron qaiməİlkin yoxlama (Rumıniya üçün CIUS-RO), milli sistemə təqdimat, normallaşdırılmış status, imzalanmış cavab və təchizatçıların gələn qutusu.
• API-də nömrələmə seriyalarıfiscale növündə aktiv seriya olmadan yaradılma 409 no_series_configured qaytarır.
• Xəta kodları və xəta zərfiHər marşrutda bir forma: type, code, message, param, doc_url, request_id və errors.
• Sorğu limitləri və təkrar cəhdlərHər kredensial üçün dəqiqədə 120 oxu, 30 yazı və 10 elektron qaimə əməliyyatı, X-RateLimit-* başlıqları ilə.

• ƏDV-ni kəsr (0,19) və ya 1 kimi göndərmək. Hər ikisi rədd edilir; 19 və ya 21 göndərin.
• Hər sorğu üçün token yaratmaq. Token bir saat yaşayır; onu keşdə saxlayın, əks halda token son nöqtəsinin IP limitinə çatacaqsınız.
• Hər təkrar cəhddə yeni idempotentlik açarı yaratmaq — məhz dublikat faktura yaradan ssenari.
• Brauzer JavaScript-indən çağırmaq. CORS bütün mənbələri bloklayır və secret hər halda açıq olardı.
• İlkin yoxlama olmadan milli elektron qaimə sisteminə təqdim etmək. Yanlış göndərişi geri almaq mümkün deyil.
• /efactura/submissions/{id}/refresh-i dəqiqədə 10 dəfədən çox sorğulamaq — bu qrup submit ilə paylaşılır.
• Şirkət profili tam olmadan və aktiv fiskal seriya mövcud olmadan fakturalar yaratmaq.