Financeiro
Consulte saldo, tarifas vigentes e extrato de movimentações.
Visão Geral
A API Financeira permite consultar o saldo da aplicação, listar tarifas vigentes e acessar o extrato completo de movimentações.
Base URL: /api/external/financeiro
Autenticação: X-Api-Key + X-Api-Secret
O saldo é verificado automaticamente antes de cada envio de mensagem. Se insuficiente, a API retorna HTTP 402 (Payment Required).
Consultar Saldo
GET
/api/external/financeiro/saldo
curl https://api.avizuai.com.br/api/external/financeiro/saldo \
-H "X-Api-Key: sua-api-key" \
-H "X-Api-Secret: seu-api-secret"
Resposta:
{
"saldo": "150.50",
"moeda": "BRL"
}
Listar Tarifas
GET
/api/external/financeiro/tarifas
Retorna as tarifas vigentes da aplicação:
[
{
"id": 1,
"categoria": "MENSAGENS",
"subtipo": "ENVIADA",
"subtipoDescricao": "Mensagem Enviada",
"valor": "0.50",
"unidade": "POR_MENSAGEM",
"unidadeDescricao": "Por Mensagem",
"moeda": "BRL",
"descricao": "Tarifa para mensagens enviadas",
"ativo": true
},
{
"id": 2,
"categoria": "MENSAGENS",
"subtipo": "RECEBIDA",
"subtipoDescricao": "Mensagem Recebida",
"valor": "0.00",
"unidade": "POR_MENSAGEM",
"unidadeDescricao": "Por Mensagem",
"moeda": "BRL",
"descricao": "Tarifa para mensagens recebidas",
"ativo": true
}
]
Extrato de Movimentações
GET
/api/external/financeiro/extrato
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
page | integer | Opcional | Página (default: 0) |
size | integer | Opcional | Itens por página (default: 20, máx: 100) |
Exemplo de item no extrato:
{
"id": 1,
"tipo": "DEBIT",
"valor": "0.50",
"saldoAnterior": "151.00",
"saldoPosterior": "150.50",
"descricao": "Tarifa de mensagem enviada",
"referenciaTipo": "MENSAGEM",
"referenciaId": 42,
"custoTwilioUsd": "0.005000",
"cotacaoUsdBrl": "5.20",
"custoTwilioBrl": "0.026000",
"criadoEm": "2024-04-10T15:30:00"
}
A resposta segue o formato paginado Spring Data com campos:
content, totalElements, totalPages, number, size.Como Funciona a Tarifação
- Antes do envio: verificação de saldo — se insuficiente, retorna HTTP 402
- Após envio: débito automático (tarifa da aplicação + custo Twilio convertido de USD para BRL)
- Callback de status: atualização do custo real informado pelo Twilio
- Estorno: disponível via painel admin, protegido contra estorno duplo
Atenção: Créditos são adicionados apenas via painel administrativo. A cotação USD→BRL é atualizada automaticamente a cada 5 minutos via AwesomeAPI.