Dokumentacja

Dokumentacja 4invoices ma dwie warstwy: panel, którego używasz bez pisania kodu, oraz publiczne API, przez które Twój system wystawia faktury i prowadzi dokument przez krajowy obieg e-faktur (w Rumunii: e-Factura ANAF). Ta strona jest wejściem do drugiej warstwy.

Otwórz pełną dokumentację API →

Co możesz zautomatyzować

Publiczne API obejmuje wystawianie faktur i proform, korekty, klientów ze sprawdzeniem w rejestrze przedsiębiorców (w Rumunii: rejestr ANAF), serie numeracji i cały krajowy obieg e-faktur (w Rumunii: e-Factura): walidację CIUS-RO, wysyłkę do SPV, śledzenie statusu, podpisaną odpowiedź i skrzynkę faktur od dostawców.

https://api.4invoices.net/v1 · 25 endpoints · Specyfikacja OpenAPI (bez klucza)

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

Uwierzytelnianie

Przed pierwszym wywołaniemFakturowanie → Ustawienia → Dostęp API
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"}
Wyłącznie server-to-server. Nigdy nie wywołuj API z JavaScriptu w przeglądarce: client_secret trafiłby do użytkownika, a CORS i tak blokuje każdy origin.

Pierwsza faktura w 6 krokach

  1. Wygeneruj poświadczenie w panelu, w Fakturowanie → Ustawienia → Dostęp API, i skopiuj client_secret — jest pokazywany tylko raz.
  2. Uzupełnij profil firmy i aktywuj co najmniej jedną serię typu fiscale, inaczej wystawienie zwróci issuer_profile_incomplete lub no_series_configured.
  3. Wymień poświadczenie na token: POST /v1/auth/token z grant_type client_credentials. Token żyje godzinę — buforuj go, nie pobieraj nowego przy każdym żądaniu.
  4. Wystaw fakturę: POST /v1/invoices z nagłówkiem Idempotency-Key i vat_rate jako procentem (21, nie 0.21).
  5. Uruchom walidację (CIUS-RO dla Rumunii) przez POST /v1/invoices/{id}/efactura/validate, a potem wyślij do krajowego systemu e-fakturowania (w Rumunii: ANAF) przez POST /v1/invoices/{id}/efactura/submit.
  6. Śledź stan przez GET /v1/efactura/submissions/{id}, aż osiągnie accepted lub rejected.
bash
# 1 — token (1 godzina, zapisz w cache)
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 — wystaw fakturę (Idempotency-Key jest WYMAGANY)
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'

Przewodniki tematyczne

Każdy temat ma własną stronę z odpowiednimi endpointami, przykładami i błędami.

Otwórz pełną dokumentację API →