Документация

Документацията на 4invoices има два слоя: панелът, който ползвате без да пишете код, и публичното API, чрез което вашата система издава фактури и придвижва документа през националната система за електронно фактуриране (в Румъния – e-Factura на ANAF). Тази страница е входът към втория слой.

Отворете пълната API документация →

Какво можете да автоматизирате

Публичното API покрива издаване на фактури и проформи, сторно, клиенти с проверка в търговския регистър (в Румъния – регистърът на ANAF), серии за номериране и целия национален път на електронното фактуриране (в Румъния – e-Factura): CIUS-RO проверка, подаване в SPV, следене на статуса, подписан отговор и входящата кутия с фактури от доставчици.

https://api.4invoices.net/v1 · 25 endpoints · OpenAPI спецификация (без ключ)

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

Автентикация

Преди първата заявкаФактуриране → Настройки → 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"}
Само сървър-към-сървър. Никога не извиквайте API от браузърен JavaScript: client_secret ще стигне до посетителя, а CORS блокира всеки източник.

Първата фактура в 6 стъпки

  1. Генерирайте идентификационни данни в панела, в Фактуриране → Настройки → API достъп, и копирайте client_secret — показва се само веднъж.
  2. Попълнете профила на фирмата и активирайте поне една серия от тип fiscale, иначе издаването връща issuer_profile_incomplete или no_series_configured.
  3. Разменете идентификационните данни за токен: POST /v1/auth/token с grant_type client_credentials. Токенът е валиден един час — кеширайте го, не вземайте нов за всяка заявка.
  4. Издайте фактурата: POST /v1/invoices със заглавка Idempotency-Key и vat_rate като процент (21, не 0.21).
  5. Направете предварителната проверка (в Румъния CIUS-RO) с POST /v1/invoices/{id}/efactura/validate и изпратете фактурата към националната система за е-фактуриране (в Румъния ANAF) с POST /v1/invoices/{id}/efactura/submit.
  6. Следете състоянието с GET /v1/efactura/submissions/{id}, докато стигне accepted или rejected.
bash
# 1 — токен (1 час, кеширайте го)
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 — издаване на фактурата (Idempotency-Key е ЗАДЪЛЖИТЕЛЕН)
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'

Ръководства по тема

Всяка тема има собствена страница със съответните endpoint-и, примери и грешки.

Отворете пълната API документация →