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_ENVIADA",
"referenciaId": 42,
"tarifaCobrada": "0.50",
"custoTwilioUsd": "0.005000",
"custoTwilioBrl": "0.026000",
"custoMetaUsd": null,
"custoMetaBrl": null,
"cotacaoUsdBrl": "5.20",
"tipoConversa": null,
"criadoEm": "2024-04-10T15:30:00"
}
Campos de custo do lançamento (variam conforme o serviço tarifado):
| Campo | Descrição |
|---|---|
referenciaTipo | Origem do lançamento (valores possíveis):
|
tarifaCobrada | Valor efetivamente cobrado da aplicação por este lançamento (BRL) |
custoTwilioUsd / custoTwilioBrl | Custo do provider Twilio (USD e convertido para BRL). Preenchido quando o envio foi via Twilio. |
custoMetaUsd / custoMetaBrl | Custo do provider Meta Cloud API (USD e BRL). Preenchido quando o envio foi via Meta. |
cotacaoUsdBrl | Cotação USD→BRL aplicada na conversão |
tipoConversa | Tipo de conversa Meta (quando aplicável): UTILITY, AUTHENTICATION, MARKETING, SERVICE |
A resposta segue o formato paginado Spring Data com campos:
content, totalElements, totalPages, number, size. Campos de custo não aplicáveis ao lançamento vêm null (ex.: um débito de IA não tem custo de provider WhatsApp).Como Funciona a Tarifação
Além das mensagens WhatsApp, a plataforma tarifa outros serviços — cada um gera um lançamento no extrato com o referenciaTipo correspondente:
- Mensagens WhatsApp (provider Twilio ou Meta): tarifa da aplicação + custo do provider.
- Inteligência Artificial (auto-resposta, geração de conteúdo, advisor): tarifa por interação conforme o provider de IA (OpenAI, Claude, Groq, Ollama).
- App mobile: mensagens de chat e notificações push do aplicativo do paciente.
- Carimbo de tempo (RFC 3161): quando habilitado para integridade legal.
- Faturas de plano: créditos do plano contratado lançados quando a fatura é paga.
Fluxo de tarifação de uma mensagem:
- Antes do envio: verificação de saldo — se insuficiente, retorna HTTP 402
- Após envio: débito automático (tarifa da aplicação + custo do provider convertido de USD para BRL)
- Callback de status: atualização do custo real informado pelo provider (Twilio ou Meta)
- 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.