Visão geral de faturas

Esta seção documenta operações relacionadas a faturas (invoices): listagem, visualização e ações (pagar, fechar, cancelar e desfazer pagamento).

Conceitos e campos importantes

invoiceDateTime

Identificador (chave) da fatura. No sistema ele costuma ser gerado no formato YYYYMMDDHHmmss (ex.: 20260110194738) e é usado como parâmetro de rota.

Situação (situationId)

Em alto nível, as situações mais comuns são:

Valor	Significado	Observações
1	Pendente / em aberto	Pode ter regras adicionais para clientes “pós pago” (ver abaixo).
2	Paga	Normalmente tem transactionId e paymentDateTime preenchidos.
3	Cancelada	Pode exigir senha do usuário e motivo no cancelamento/undo.

“Aberta” (opened)

Em algumas respostas a API inclui o campo calculado opened:

• 1 quando, pela regra interna, a fatura ainda é considerada “aberta” (com base em closingDateTime)
• 0 caso contrário

Isso afeta somente clientes pós pago ao tentar pagar/fechar faturas.

Tolerância e multa (penalty)

Na visualização completa de fatura, a API pode ajustar o valor sugerido a pagar (amountReceived) considerando:

• Dias de tolerância (toleranceDays): estende a data efetiva para comparação de vencimento.
• Multa (penalty e penaltyType): aplicada somente quando situationId = 1 e a fatura está vencida após tolerância.
  • Se penaltyType = 2, a multa é percentual sobre amount.

Envelope de resposta

As respostas seguem o envelope padrão:

• Sucesso: { "response": "success", "data": <payload> }
• Erro: { "response": "error", "data": { "msg": "...", "code": "..." } }

Para 401/403, veja Autorização.