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_KEYcominvoices:write(emitir e corrigir),invoices:readebusiness:accounts:read. A capacidade de facturação tem de estar activa na empresa; caso contrário a API responde403comcode: "CAPABILITY_INACTIVE". - Opcional:
gotactlcom sessão iniciada na mesma sandbox, para acompanhar os eventos.
1. Escolher uma conta#
curl -sS "$BUSINESS_API/accounts?status=active&limit=1" \
-H "Authorization: Bearer $API_KEY"
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.
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}]}'
{
"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
}
]
}
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.
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"}'
Testar#
Antes do passo 2, abra um terminal à parte e ponha um receptor à escuta:
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.