API vasitəsilə faktura yaratmaq

Idempotency-Key ilə POST /invoices, ƏDV faizlə, həmçinin siyahı, storno və ödənilmiş kimi qeyd etmə.

6 addımda ilk fakturanız

Buyer obyekti və lines-da ən azı bir element ilə POST /v1/invoices göndərin.
Idempotency-Key başlığını əlavə edin — məcburidir, hər məntiqi əməliyyat üçün bir açar.
vat_rate-i faiz kimi (21), unit_price-ı isə VERGİSİZ vahid qiymət kimi göndərin.
201 cavabı id, number, series, net/vat/gross cəmlərini və göndərdiyiniz metadatanı daşıyır.
Sənədi GET /v1/invoices/{id}/pdf ilə, UBL XML-i GET /v1/invoices/{id}/xml ilə yükləyin.

Bütün son nöqtələr

Metod	Son nöqtə	Əhatə	Idempotency-Key	Sorğu / dəqiqə
POST	/invoices Faktura və ya proforma yaradır	invoices:write	tələb olunur	30
GET	/invoices Fakturaları siyahılayır (kursorla səhifələmə)	invoices:read	—	120
POST	/invoices/preview-totals Heç nə yaratmadan cəmləri hesablayır	invoices:read	—	120
GET	/invoices/{invoice_id} Bir fakturanı gətirir	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Fakturanın PDF-ini yükləyir	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Bu fakturanı ləğv edən kredit qeydini yaradır	invoices:write	tələb olunur	30
POST	/invoices/{invoice_id}/payments Fakturanı ödənilmiş kimi qeyd edir	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Fakturanı ödənilməmiş kimi qeyd edir	invoices:write	—	30

4invoices API nədir

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

bash
# Kursorla səhifələmə: has_more false olana qədər next_cursor-ı izləyin.
curl -sS "https://api.4invoices.net/v1/invoices?limit=50&status=issued&issued_from=2026-07-01" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → {"object":"list","data":[...],"has_more":true,"next_cursor":"inv_01J..."}

curl -sS "https://api.4invoices.net/v1/invoices?limit=50&cursor=inv_01J..." \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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

# Storno öz FİSKAL nömrəsini alır; orijinal nömrə heç vaxt təkrar istifadə olunmur.

bash
# Ödənilmiş kimi qeyd et
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Geri al
curl -sS -X DELETE https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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

Xətalar

Status	Növ	Kod
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Ümumi səhvlər

Siyahı kursorla işləyir: has_more false olana qədər next_cursor-ı izləyin. Filtrlərə status, document_kind, buyer_tax_id, issued_from, issued_to və q daxildir.
Storno POST /v1/invoices/{id}/storno-dur və öz fiskal nömrəsini alır — orijinal nömrə heç vaxt təkrar istifadə olunmur.
Proforma (document_kind proforma) fiskal nömrə istifadə etmir və milli elektron qaimə sisteminə təqdim oluna bilməz.
metadata oxumalarda geri qaytarılır: sifariş id-nizi orada saxlayın, ayrıca uyğunluq cədvəlinə ehtiyac qalmır.
POST /v1/invoices/preview-totals eyni hesablamanı yan təsirsiz aparır — cəmləri öz səbətinizdə göstərmək üçün əlverişlidir.

İnkişafçılar üçün suallar və cavablar

Bir fakturada neçə sətir ola bilər?

1-dən 400-ə qədər. description 1024 simvolla məhdudlaşır, quantity isə mütləq müsbət olmalıdır.

Timeout-dan sonra eyni sorğunu yenidən göndərsəm nə olar?

Eyni Idempotency-Key ilə orijinal fakturanı və Idempotency-Replayed: true başlığını alırsınız. İkinci sənəd yaranmır.

Fakturanı necə ödənilmiş kimi qeyd edirəm?

POST /v1/invoices/{id}/payments onu ödənilmiş kimi qeyd edir, eyni yolda DELETE isə geri alır. Hər ikisi invoices:write əhatəsi tələb edir.

Həmçinin bax