# Emitir facturas e notas de crédito

Emita uma factura manual numa conta de serviço fora de um ciclo de facturação, corrija o valor com uma nota de crédito ou de débito e acompanhe os eventos invoice.issued e invoice.adjusted.


## O que vai construir

A maior parte das facturas nasce dos ciclos de facturação, que valorizam as leituras aceites segundo o tarifário. Há cobranças sem leitura associada: uma taxa de religação, um selo danificado, um serviço pontual. Neste guia emite uma dessas facturas à mão numa conta existente e depois corrige-a com uma nota de crédito. Uma factura manual recebe número da mesma série sem falhas das facturas dos ciclos, é lançada no razão e paga-se da mesma maneira, por isso nenhum processo a jusante precisa de a tratar à parte.

## Pré-requisitos

- Uma sandbox, cujos dados de exemplo incluem contas activas e os tarifários que as valorizam.
- Uma chave de API de teste em `$API_KEY` com `invoices:write` (emitir e corrigir), `invoices:read` e `business:accounts:read`. A capacidade de facturação tem de estar activa na empresa; caso contrário a API responde `403` com `code: "CAPABILITY_INACTIVE"`.
- Opcional: `gotactl` com sessão iniciada na mesma sandbox, para acompanhar os eventos.

## 1. Escolher uma conta

```bash
curl -sS "$BUSINESS_API/accounts?status=active&limit=1" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: `data[0].id` começa por `act_` e `data[0].status` vale `active`. Use esse `id` como `account_id` a seguir.

## 2. Emitir a factura manual

São obrigatórios `account_id` e pelo menos uma entrada em `lines`. Cada linha precisa de `description`, de uma `quantity` superior a zero e de um `unit_price_cents` de pelo menos `1`. Os preços estão na moeda do tarifário activo da conta. Com `taxable: true` numa linha, cobra-se IVA sobre ela à taxa desse tarifário. `customer_id` é opcional, mas quando o envia o cliente tem de ser o titular da conta. Sem `due_date`, a factura vence no fim do prazo de pagamento da política de facturação, ou ao fim de 30 dias se a política não definir nenhum.

```bash
curl -sS -X POST "$BUSINESS_API/invoices/manual" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: reconnection-act_2pN4wF6gLr2ZtB9uKe4WqP7hYc3-2026-11" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"act_2pN4wF6gLr2ZtB9uKe4WqP7hYc3","lines":[{"description":"Religação após suspensão","quantity":1,"unit_price_cents":150000,"taxable":false}]}'
```

```json
{
  "id": "inv_2pP8kM3xVt6RbN1qZw4HcY9fLd5",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "invoice_number": "INV-000214",
  "customer_id": "cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7",
  "account_id": "act_2pN4wF6gLr2ZtB9uKe4WqP7hYc3",
  "tariff_version_id": "trf_2nX6bT1rQp8LwK3vYm5ZcJ7sHd4",
  "subtotal_cents": 150000,
  "sanitation_cents": 0,
  "tax_cents": 0,
  "total_cents": 150000,
  "balance_cents": 150000,
  "amount_due_cents": 150000,
  "currency": "MZN",
  "status": "open",
  "payment_terms_days": 30,
  "issued_at": "2026-11-19T10:02:41Z",
  "due_date": "2026-12-19T10:02:41Z",
  "line_items": [
    {
      "id": "inv_2pP8kM3xVt6RbN1qZw4HcY9fLd5-1",
      "invoice_id": "inv_2pP8kM3xVt6RbN1qZw4HcY9fLd5",
      "description": "Religação após suspensão",
      "quantity": 1,
      "unit_price_cents": 150000,
      "total_cents": 150000,
      "line_type": "charge_component",
      "component_kind": "fixed",
      "taxable": false
    }
  ]
}
```

✓ Checkpoint: `201` com `status: "open"`, um `invoice_number` da série de facturas e `amount_due_cents` igual a `total_cents`. Se a conta tiver crédito por usar, é aplicado de imediato e `balance_cents` vem mais baixo.

## 3. Emitir uma nota de crédito

Uma nota de crédito reduz o saldo; uma nota de débito aumenta o saldo e o total. São obrigatórios `type` (`credit_note` ou `debit_note`), um `amount_cents` positivo e `reason`. Só uma nota de débito pode levar `category` `late_fee` ou `interest`; por omissão, todas as notas ficam com `general`.

```bash
curl -sS -X POST "$BUSINESS_API/invoices/inv_2pP8kM3xVt6RbN1qZw4HcY9fLd5/adjust" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: cn-inv_2pP8kM3xVt6RbN1qZw4HcY9fLd5-1" \
  -H "Content-Type: application/json" \
  -d '{"type":"credit_note","amount_cents":50000,"reason":"Religação feita no próprio dia do pagamento"}'
```

✓ Checkpoint: `200` com a factura actualizada: `balance_cents` passa a `100000` e `status` continua `open`. Um crédito que leve o saldo a zero marca a factura como `paid`. Um crédito maior do que o saldo apenas o leva a zero; o evento `invoice.adjusted` indica a parte não aplicada em `credit_excess_minor`. Facturas anuladas ou abatidas recusam notas, e uma factura paga só aceita créditos; cada um destes casos devolve `400`.

## Testar

Antes do passo 2, abra um terminal à parte e ponha um receptor à escuta:

```bash
gotactl webhooks listen --events invoice.issued,invoice.adjusted --forward-to http://localhost:3000/hooks
```

Cada passo escreve uma linha com `--> invoice.issued` ou `--> invoice.adjusted` e o código de estado do seu endpoint. No painel, abra a factura em **Facturas**; a acção **Nota de crédito ou débito** emite a mesma nota, e todas as notas aparecem em **Notas de crédito e débito**. `GET $BUSINESS_API/invoices/{id}/pdf?locale=pt-MZ` gera o PDF da factura.

## Próximos passos

- [Cobrar a factura em aberto](/docs/guides/receive-payments)
- [Verificar a assinatura dos eventos de facturas](/docs/webhooks/verify)
- [Todas as operações de facturas na referência da Business API](/docs/api/business)

