# Quickstart: a primeira fatura a partir de código

> Edição Markdown de https://api.fiz.co/docs/quickstart?lang=pt. English: https://api.fiz.co/docs/quickstart.md. Índice: https://api.fiz.co/llms.txt

Cinco pedidos levam-no de uma chave API a uma fatura em rascunho que pode abrir em PDF, com o seu próprio código ou com um agente de programação. Nada chega à Autoridade Tributária até ao último passo, que é opcional.

## 1. Obter uma chave API

Entre na FIZ e abra [Definições → Integrações](https://app.fiz.co/settings/integrations). 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
```

> A chave atua sobre a sua empresa real. Não existe sandbox fiscal: os rascunhos são a superfície de teste, e só o passo de emissão (secção 5) comunica algo à Autoridade Tributária (AT).

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

> As faturas recorrentes (`/invoices/scheduled`) emitem sozinhas depois de criadas ou retomadas. Pagamentos, anulações e notas de crédito são fiscais da mesma forma. A referência da API documenta cada um.

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

- [Abrir no Claude ↗](https://claude.ai/new?q=I'm%20integrating%20FIZ%2C%20a%20certified%20invoicing%20API%20for%20Portugal%20(https%3A%2F%2Fapi.fiz.co).%0ARead%20https%3A%2F%2Fapi.fiz.co%2Fllms.txt%20first%20and%20follow%20its%20links%20before%20writing%20any%20code.%0AMy%20API%20key%20is%20in%20the%20FIZ_API_KEY%20environment%20variable.%20Never%20print%20it%2C%20log%20it%20or%20ask%20me%20to%20paste%20it.%0AStart%20with%20GET%20https%3A%2F%2Fapi.fiz.co%2Fcompany%20to%20verify%20the%20key%20and%20the%20company's%20readiness.%0ADrafts%20are%20safe%20to%20create%2C%20change%20and%20delete.%20Do%20not%20call%20%2Fissue%2C%20%2Fpay%2C%20%2Fcancel%20or%20credit-note%20endpoints%20unless%20I%20explicitly%20ask%3A%20they%20are%20fiscal%20and%20irreversible.%0ATask%3A%20%3Cdescribe%20what%20to%20build%3E)
- [Abrir no ChatGPT ↗](https://chatgpt.com/?q=I'm%20integrating%20FIZ%2C%20a%20certified%20invoicing%20API%20for%20Portugal%20(https%3A%2F%2Fapi.fiz.co).%0ARead%20https%3A%2F%2Fapi.fiz.co%2Fllms.txt%20first%20and%20follow%20its%20links%20before%20writing%20any%20code.%0AMy%20API%20key%20is%20in%20the%20FIZ_API_KEY%20environment%20variable.%20Never%20print%20it%2C%20log%20it%20or%20ask%20me%20to%20paste%20it.%0AStart%20with%20GET%20https%3A%2F%2Fapi.fiz.co%2Fcompany%20to%20verify%20the%20key%20and%20the%20company's%20readiness.%0ADrafts%20are%20safe%20to%20create%2C%20change%20and%20delete.%20Do%20not%20call%20%2Fissue%2C%20%2Fpay%2C%20%2Fcancel%20or%20credit-note%20endpoints%20unless%20I%20explicitly%20ask%3A%20they%20are%20fiscal%20and%20irreversible.%0ATask%3A%20%3Cdescribe%20what%20to%20build%3E)

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](https://api.fiz.co/docs/mcp.md).

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

-   **Skill**: a [skill fiz-invoicing](https://github.com/FIZ-co/fiz-invoicing-skill), 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](https://api.fiz.co/llms.txt) indexa as versões Markdown de todas as páginas; o documento OpenAPI está em [/-json](https://api.fiz.co/-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](https://api.fiz.co/docs/apps.md).