Quickstart: a primeira fatura a partir de código

1. Obter uma chave API

Entre na FIZ e abra Definições → Integrações. Crie uma chave API: pertence a uma empresa e só emite para essa empresa. Copie-a uma vez; a FIZ guarda apenas um hash.

Coloque-a no ambiente como FIZ_API_KEY e carregue-a na shell antes de executar o que quer que seja. Todos os exemplos abaixo, e a skill FIZ para agentes de programação, leem essa variável, por isso nunca cola a chave numa conversa, num prompt ou num repositório. Um terminal novo precisa de repetir o carregamento.

# .env (never commit it; add it to .gitignore)
FIZ_API_KEY=fiz_api_...

# A shell does not read .env by itself. Run this in the terminal you use for
# the snippets; a coding agent started from that terminal inherits the key.
set -a; source .env; set +a

2. Verificar a ligação

O primeiro pedido diz-lhe se a chave funciona e se a empresa pode emitir.

curl https://api.fiz.co/company \
  --header "x-api-key: $FIZ_API_KEY"

A resposta traz id, name, taxpayerNumber, cae e readiness. Se readiness.ready for false, reasons[].code diz o que falta (AT_CREDENTIALS_REQUIRED, AT_SYNC_REQUIRED, SERIES_REQUIRED) e actionUrl é a página na FIZ que o resolve. Pode criar rascunhos mesmo sem estar pronta.

Um 401 significa chave em falta ou revogada. Anote o valor de cae: um rascunho precisa de um dos códigos de atividade da empresa.

3. Criar um cliente e um artigo

Uma fatura referencia um cliente e um ou mais artigos do catálogo pelo id. Crie um de cada e guarde os valores de id devolvidos. O cabeçalho Idempotency-Key torna a repetição segura: a mesma chave devolve a primeira resposta em vez de criar um segundo registo.

curl --request POST https://api.fiz.co/customers \
  --header "x-api-key: $FIZ_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: quickstart-customer-1' \
  --data '{"name":"Example customer","country":"PT"}'

curl --request POST https://api.fiz.co/items \
  --header "x-api-key: $FIZ_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: quickstart-item-1' \
  --data '{"name":"Example service","type":"SERVICE","unitPrice":10,"vatRate":"NORMAL"}'

Envie apenas campos documentados: a validação é estrita e um campo desconhecido é um 400. vatRate e qualquer código de isenção são uma decisão fiscal da empresa; a categoria do exemplo não é aconselhamento fiscal.

4. Criar um rascunho e vê-lo

Guarde isto como draft.json, substituindo os dois ids pelos que acabou de receber e cae por um valor da resposta da sua empresa. A referência ao artigo é items[].id.

{
  "type": "INVOICE",
  "cae": "62010",
  "customerId": "aaaaaaaaaaaaaaaaaaaaaaaa",
  "items": [
    {
      "id": "bbbbbbbbbbbbbbbbbbbbbbbb",
      "quantity": 1
    }
  ]
}

curl --request POST https://api.fiz.co/invoices \
  --header "x-api-key: $FIZ_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: quickstart-draft-1' \
  --data @draft.json

A resposta é o rascunho, com o seu id, status e updatedAt. Leia-o de volta e confirme totais, IVA e o bloco do cliente no PDF antes de qualquer ato fiscal. O endpoint do PDF devolve um link de descarga, não o ficheiro: obtenha o url da resposta.

curl https://api.fiz.co/invoices/$INVOICE_ID \
  --header "x-api-key: $FIZ_API_KEY"

# The PDF endpoint answers { id, name, url }: download the url (jq extracts it).
PDF_URL=$(curl -s https://api.fiz.co/invoices/$INVOICE_ID/pdf \
  --header "x-api-key: $FIZ_API_KEY" | jq -r .url)
curl -L "$PDF_URL" --output draft.pdf

Um rascunho pode ser alterado com PATCH /invoices/{id} e removido com DELETE /invoices/{id}. Crie tantos quantos precisar.

5. Emitir (fiscal, irreversível)

Emitir atribui o número e o ATCUD e comunica o documento à AT. Não pode ser desfeito; um erro corrige-se com uma nota de crédito. Faça a primeira emissão à mão, depois de ler o PDF, e só quando readiness.ready for true.

# Once per issue attempt. Store it next to the invoice id; a retry must reuse it.
ISSUE_KEY=$(uuidgen)

# Fiscal and irreversible. expectedUpdatedAt is the draft's updatedAt from GET /invoices/{id}.
# Safe to re-run after a lost response: the same ISSUE_KEY returns the recorded result.
curl --request POST https://api.fiz.co/invoices/$INVOICE_ID/issue \
  --header "x-api-key: $FIZ_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $ISSUE_KEY" \
  --data '{ "expectedUpdatedAt": "2026-09-15T10:20:30.000Z" }'

Envie o updatedAt atual do rascunho como expectedUpdatedAt: se o rascunho tiver mudado entretanto, o pedido é recusado em vez de emitir uma versão desatualizada. Gere a Idempotency-Key uma vez por emissão e guarde-a junto do id da fatura; após uma resposta perdida, repita com essa mesma chave e o servidor devolve o resultado registado em vez de emitir duas vezes. Uma chave nova é uma nova tentativa.

6. Construir com um agente de programação

Dê este prompt ao seu agente. Aponta-o para a documentação em Markdown escrita para agentes, fixa a convenção da chave e mantém os atos fiscais atrás do seu pedido explícito.

I'm integrating FIZ, a certified invoicing API for Portugal (https://api.fiz.co).
Read https://api.fiz.co/llms.txt first and follow its links before writing any code.
My API key is in the FIZ_API_KEY environment variable. Never print it, log it or ask me to paste it.
Start with GET https://api.fiz.co/company to verify the key and the company's readiness.
Drafts are safe to create, change and delete. Do not call /issue, /pay, /cancel or credit-note endpoints unless I explicitly ask: they are fiscal and irreversible.
Task: <describe what to build>

Num projeto que continua a evoluir, acrescente uma linha ao CLAUDE.md, AGENTS.md ou .cursorrules para que cada sessão comece no sítio certo:

FIZ invoicing API: read https://api.fiz.co/llms.txt before touching the integration.
The API key is in FIZ_API_KEY; never print it. Drafts are safe; never call /issue, /pay, /cancel or credit notes unless asked.

Outras entradas

Claude Code: ligue o servidor MCP da FIZ e o assistente lê e prepara documentos por si, com OAuth em vez de chave. Detalhes na página MCP.

claude mcp add --transport http fiz https://api.fiz.co/mcp

• Skill: a skill fiz-invoicing, open-source, acrescenta as regras de IVA portuguesas e um auxiliar curl ao Claude Code e a outros runtimes de Agent Skills.
• Documentação para agentes: o llms.txt indexa as versões Markdown de todas as páginas; o documento OpenAPI está em /-json.
• Vai faturar em nome dos seus clientes? Isso é uma aplicação OAuth, não uma chave API: siga Criar uma aplicação com a FIZ.