Emitir faturas pela API

POST /invoices com Idempotency-Key, IVA em percentagem, mais listagem, nota de crédito e marcar como paga.

A primeira fatura em 6 passos

Envie POST /v1/invoices com um objeto buyer e pelo menos uma entrada em lines.
Adicione o cabeçalho Idempotency-Key — é obrigatório, uma chave por operação lógica.
Envie vat_rate em percentagem (21) e unit_price como preço unitário LÍQUIDO.
A resposta 201 inclui id, number, series, os totais líquido/IVA/bruto e os metadata que enviou.
Obtenha o documento com GET /v1/invoices/{id}/pdf ou o XML UBL com GET /v1/invoices/{id}/xml.

Todos os endpoints

Método	Endpoint	Scope	Idempotency-Key	Pedidos / minuto
POST	/invoices Emitir uma fatura ou proforma	invoices:write	obrigatório	30
GET	/invoices Listar faturas (paginação por cursor)	invoices:read	—	120
POST	/invoices/preview-totals Calcular totais sem criar nada	invoices:read	—	120
GET	/invoices/{invoice_id} Obter uma fatura	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Descarregar o PDF da fatura	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Emitir uma nota de crédito que anula esta fatura	invoices:write	obrigatório	30
POST	/invoices/{invoice_id}/payments Marcar a fatura como paga	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Marcar a fatura como não paga	invoices:write	—	30

O que é a API 4invoices

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
# Paginação por cursor: siga next_cursor até has_more ser false.
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'

# A nota de crédito recebe o SEU PRÓPRIO número fiscal; o número do original nunca é reutilizado.

bash
# Marcar como paga
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Anular
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

Erros

Estado	Tipo	Código
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Erros frequentes

A listagem é paginada por cursor: siga next_cursor até has_more ser false. Os filtros incluem status, document_kind, buyer_tax_id, issued_from, issued_to e q.
Uma anulação (storno) é POST /v1/invoices/{id}/storno e recebe o seu próprio número fiscal — o número original nunca é reutilizado.
Uma fatura pró-forma (document_kind proforma) não consome nenhum número fiscal e não pode ser submetida no sistema nacional de faturação eletrónica.
metadata é devolvido nas leituras: coloque aí o id da sua encomenda e deixa de precisar de uma tabela de correspondência separada.
POST /v1/invoices/preview-totals executa o mesmo cálculo sem efeitos secundários — prático para mostrar os totais no seu próprio carrinho.

Perguntas e respostas para desenvolvedores

Quantas linhas pode ter uma fatura?

Entre 1 e 400. description está limitado a 1024 caracteres e quantity tem de ser estritamente positivo.

O que acontece se reenviar o mesmo pedido após um timeout?

Com a mesma Idempotency-Key recebe a fatura original, mais um cabeçalho Idempotency-Replayed: true. Não é emitido nenhum segundo documento.

Como marco uma fatura como paga?

POST /v1/invoices/{id}/payments marca-a como paga e DELETE no mesmo caminho anula a marcação. Ambos exigem o scope invoices:write.

Ver também