Documentação

A documentação da 4invoices tem duas camadas: o painel, que usa sem escrever código, e a API pública, através da qual o seu sistema emite faturas e leva o documento através do circuito nacional de faturação eletrónica (na Roménia, e-Factura da ANAF). Esta página é a entrada para a segunda camada.

Abrir a documentação completa da API →

O que pode automatizar

A API pública cobre a emissão de faturas e proformas, notas de crédito, clientes com consulta ao registo empresarial (na Roménia, registo da ANAF), séries de numeração e todo o circuito nacional de faturação eletrónica (na Roménia, e-Factura): pré-validação CIUS-RO, submissão ao SPV, acompanhamento do estado, resposta assinada e a caixa de faturas recebidas de fornecedores.

https://api.4invoices.net/v1 · 25 endpoints · Especificação OpenAPI (sem chave)

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

Autenticação

Antes da primeira chamadaFaturação → Definições → Acesso à 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"}
Apenas servidor a servidor. Nunca chame a API a partir de JavaScript de browser: o client_secret chegaria ao visitante e o CORS bloqueia qualquer origem de todo o modo.

A primeira fatura em 6 passos

  1. Gere uma credencial no painel, em Faturação → Definições → Acesso à API, e copie o client_secret — é mostrado uma única vez.
  2. Complete o perfil da empresa e ative pelo menos uma série do tipo fiscale, caso contrário a emissão devolve issuer_profile_incomplete ou no_series_configured.
  3. Troque a credencial por um token: POST /v1/auth/token com grant_type client_credentials. O token dura uma hora — guarde-o em cache, não peça um por cada pedido.
  4. Emita a fatura: POST /v1/invoices com o cabeçalho Idempotency-Key e vat_rate em percentagem (21, não 0.21).
  5. Para o mercado romeno, execute a pré-validação CIUS-RO com POST /v1/invoices/{id}/efactura/validate e envie à ANAF com POST /v1/invoices/{id}/efactura/submit.
  6. Acompanhe o estado com GET /v1/efactura/submissions/{id} até chegar a accepted ou rejected.
bash
# 1 — token (1 hora, guardar em 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 — emitir a fatura (Idempotency-Key é OBRIGATÓRIO)
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'

Guias por tema

Cada tema tem a sua página, com os endpoints, exemplos e erros respetivos.

Abrir a documentação completa da API →