Verificação de saldo via API antes do lançamento em massa de pedidos

Por que consultar o saldo antes de iniciar a fila

O lançamento em massa de pedidos sem uma verificação atualizada de saldo resulta em recusas parciais: os primeiros pedidos são criados e os seguintes recebem erro de saldo insuficiente. A situação mais difícil de resolver ocorre no envio paralelo, com serviços diferentes e vários processos operando na mesma conta.

Para o lançamento, não importa o volume total de recargas nem o saldo contábil no painel. É necessário o valor que o serviço permite debitar no momento da criação de um novo pedido. O dinheiro referente a pedidos ativos pode já estar em reserva, mesmo que o débito final ainda não tenha sido refletido no histórico de operações.

Compare o orçamento da fila com o campo de saldo disponível, e não com o valor total na conta.

Como é a resposta do método de saldo

Os nomes dos campos são definidos pela documentação de cada plataforma, mas um contrato conveniente do método de saldo geralmente retorna total, available, reserved, currency e updated_at. Abaixo há um exemplo de estrutura que pode servir de referência na integração. Não é uma resposta universal para todos os serviços, mas um exemplo de esquema de dados compreensível.

A requisição pode ser assim:

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

Resposta:

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

Neste exemplo, total são todos os fundos da conta, available é o dinheiro para novos pedidos e reserved é o valor referente a operações criadas anteriormente. A verificação confere: 125.80 menos 41.30 é igual a 84.50. O campo currency define a unidade de cálculo, e updated_at ajuda a entender o quão recentes são os dados.

Como interpretar available e reserved

O campo available é usado para decidir sobre o lançamento. Se a fila custa 80.00 e available é 84.50, os fundos são suficientes apenas se a API não adicionar uma taxa separada ou recalcular o preço no momento da criação do pedido. O campo reserved não é somado ao saldo disponível: esse valor já está ocupado.

reserved pode incluir o custo de pedidos com status processing, pending ou review — o conjunto exato depende das regras da plataforma. Às vezes a reserva é liberada após cancelamento, execução parcial ou verificação manual. Por isso, calculá-la por conta própria com base na lista de pedidos só serve como conferência adicional.

• total serve para conferir com o histórico de recargas e débitos;
• available serve para liberar uma nova fila para lançamento;
• reserved mostra quanto já está bloqueado para operações ativas;
• currency não pode ser ignorada, mesmo ao operar com uma única conta;
• updated_at é útil para o log e para diagnosticar uma resposta desatualizada.

Uma resposta apenas com o campo balance é mais simples de processar, mas tem uma desvantagem: não é possível saber se esse dinheiro está disponível imediatamente ou se parte do valor já está retida para outros pedidos.

Verifique o formato dos valores na documentação da API

No exemplo, os valores são passados como strings: "84.50", e não como o número 84.5. Esse formato preserva o valor exato retornado pelo serviço. Se a API usa strings com ponto decimal, não convém convertê-las imediatamente em números de ponto flutuante e fazer comparações com float.

Por exemplo, seu cálculo pode resultar em 84.499999 em vez dos 84.50 esperados. No limite do orçamento, isso pode liberar a fila por engano ou, ao contrário, interrompê-la. Para operações com valores decimais em string, use um tipo de dado decimal que suporte a precisão de casas fracionárias fixas.

Outro contrato comum são as unidades mínimas inteiras. Nesse caso, a resposta pode conter "available_minor": 8450 e "currency": "USD", e o preço do pedido, "price_minor": 1250. Dentro dessa API, 8450 significa 84.50, se as regras da moeda previrem duas casas fracionárias. Só se pode dividir o valor por 100 quando isso estiver explicitamente indicado na documentação.

Não misture moedas e formatos de preço

Antes de calcular a fila, compare a currency do saldo com a moeda do método de preço ou da resposta na criação do pedido. Se o saldo retorna uma moeda e o catálogo de serviços outra, não é possível usar os números diretamente. É necessário um cálculo fornecido pela própria plataforma ou um método de conversão separado e confirmado.

A conversão prévia do seu lado é conveniente para planejamento, mas tem uma desvantagem: o serviço pode aplicar outra taxa de câmbio, comissão ou regra de arredondamento no momento do débito. É mais confiável enviar o pedido com parâmetros para os quais a API retorna o custo final na moeda do saldo, ou obter o cálculo do preço imediatamente antes da criação.

Se o método de preço responde "price": "12.345", e o saldo armazena valores com duas casas, verifique a regra de arredondamento. Não arredonde automaticamente para baixo: o débito real pode ser maior. Para liberar a fila, use exatamente o valor que a API chama de custo final do pedido.

Calcule o orçamento da fila antes da primeira requisição

Antes do lançamento, reúna todos os pedidos e calcule o custo considerando o volume, o serviço escolhido, a região, as opções adicionais e a comissão, caso ela seja passada separadamente. Não compare available com o preço base da interface: na API, o total pode depender dos parâmetros de cada pedido.

Suponha que a fila tenha três pedidos. A API de cálculo de preço retornou para eles 18.40, 27.15 e 31.60 na mesma moeda indicada em balance.currency. O orçamento é 77.15. Se balance.available é 84.50, após o lançamento planejado restam 7.35. Se available é 76.90, não é possível lançar a fila inteira.

1. Obtenha os preços conforme os parâmetros reais de cada pedido.
2. Some os custos finais, sem alterar o formato nem a moeda.
3. Compare o orçamento com available de uma resposta de saldo recente.
4. Com saldo suficiente, registre o valor como reserva local de lançamento.
5. Após criar cada pedido, reduza a reserva local pelo custo confirmado.

A margem reduz o risco de recusa por débito adicional, mas tem uma desvantagem: parte dos fundos disponíveis ficará sem uso, embora a fila pudesse ser executada por completo.

Faça uma segunda verificação imediatamente antes do envio

O saldo obtido durante a preparação da campanha perde a validade rapidamente. Entre o cálculo e o lançamento, outro operador, uma automação ou um pedido ativo podem alterar available e reserved. Uma nova requisição é necessária após a formação da fila e imediatamente antes do primeiro pedido.

O esquema de trabalho tem duas etapas: primeiro obter os preços e estimar o orçamento, depois consultar o balance novamente. Se o valor de available diminuiu e ficou abaixo do valor calculado, a fila não é enviada por inteiro. Entre a verificação final e o lançamento, não se devem realizar outros débitos na mesma conta.

Uma única requisição para todo o lançamento reduz a carga na API, mas tem a desvantagem de que o saldo disponível pode mudar enquanto uma fila longa ainda está sendo processada.

Como lançar a fila com saldo insuficiente

Se available é menor que o orçamento, não envie todas as requisições na esperança de que algumas passem. Divida a fila em pacotes cujo custo caiba no limite disponível. No exemplo com saldo de 76.90, é possível enviar os dois primeiros pedidos por 45.55 e então parar: o terceiro, por 31.60, exige nova verificação.

Defina explicitamente a ordem dos pedidos no agrupamento. É possível enviar primeiro os pedidos prioritários ou formar pacotes com custo semelhante. Cada opção tem uma desvantagem: a ordem por prioridade adia os itens menos importantes, e a ordenação por preço pode alterar o plano original da campanha.

• Forme um pacote com valor não superior ao available atual.
• Crie os pedidos do pacote e guarde seus identificadores.
• Aguarde as respostas ou verifique os status das operações após timeouts.
• Faça uma pausa, se os limites da API ou as regras do serviço exigirem.
• Consulte o balance novamente antes do próximo pacote.

Após cada pacote, oriente-se pela nova resposta da API, e não apenas pela dedução local a partir do saldo anterior. O cálculo local é útil para controle, mas não enxerga estornos, débitos externos e recálculo de reservas.

Proteja o orçamento no envio paralelo

No processamento sequencial, basta reduzir o limite local após a confirmação do pedido. No modelo paralelo, dois workers podem ver available 84.50 ao mesmo tempo e cada um planejar um gasto de 60.00. As duas decisões parecem aceitáveis isoladamente, mas juntas ultrapassam o saldo disponível.

Para proteção, é necessário um contador compartilhado de reserva local ou uma fila cujo acesso seja atômico. Antes do envio, o worker tenta ocupar o valor do pedido nesse contador. Se o limite livre não for suficiente, o pedido fica aguardando nova verificação de saldo.

• A fila sequencial é mais fácil de controlar, mas inicia mais devagar.
• O envio paralelo reduz o tempo de lançamento, mas exige bloqueio do orçamento compartilhado.
• A reserva local reduz conflitos, mas pode travar após uma falha de um worker.
• A reserva do lado da API é mais confiável, mas não está disponível em todas as plataformas.

Se o processo terminou antes de receber a resposta, a reserva local não pode ser considerada imediatamente como gasta ou livre. Primeiro verifique se o pedido foi criado, pelo seu identificador externo ou pelo método de busca de operações.

Use a reserva da API, se ela existir

Algumas APIs permitem criar uma reserva para um conjunto de operações ou realizar o pedido em duas etapas: cálculo, bloqueio do valor, confirmação. Nesse esquema, a janela entre a verificação e o débito em que outro processo pode consumir os fundos da conta é menor.

Se esse método existir, guarde o identificador da reserva, seu valor, a moeda, o prazo de validade e o status. Depois, passe esse identificador na criação dos pedidos, se o contrato da API exigir. Ao final da fila, confira a parte não utilizada e o fato de o bloqueio ter sido removido.

A reserva da API não resolve todos os problemas: ela pode ter prazo curto, não cobrir comissões ou ser liberada após um erro de confirmação. A reserva local é mais simples de implementar, mas tem a desvantagem de não proteger contra gastos criados fora do seu aplicativo.

Separe o erro de saldo do saldo zero

Uma resposta com código de erro, um timeout ou um limite de requisições não significam que available é zero. Não insira automaticamente o último valor conhecido se um lançamento grande depende dele. Se não for possível obter um saldo atualizado, a fila deve ser pausada.

Trate separadamente a recusa na criação do pedido. Ela pode estar relacionada a saldo insuficiente, mas também a um identificador de serviço incorreto, volume inválido, restrição de canal ou repetição de uma operação. Guarde o código e o texto do erro junto com o identificador externo do pedido.

• Em erro de autorização, atualize o acesso e só então repita a requisição.
• Em limite de requisições, aguarde conforme as regras da API.
• Em timeout na criação, primeiro verifique se a operação realmente apareceu.
• Em erro de saldo insuficiente, interrompa o pacote e consulte o balance novamente.

Não crie duplicatas após um timeout

Um timeout significa que seu cliente não recebeu a resposta, e não que o servidor não processou a requisição. Reenviar sem verificar pode criar um segundo pedido e ocupar o dinheiro novamente. Isso é especialmente perigoso em uma fila em que o reenvio automático está configurado para várias tentativas.

Passe um identificador externo exclusivo do pedido, se a API suportar o campo client_order_id, external_id ou idempotency_key. Guarde-o antes de enviar a requisição. Após um timeout, encontre a operação por esse valor ou consulte o status pelo identificador obtido anteriormente.

O reenvio sem verificação é mais rápido, mas tem uma desvantagem direta: podem ocorrer pedidos duplicados, reserva em dobro e divergências entre o seu cálculo de orçamento e os débitos reais.

O que guardar no log de lançamento

O log ajuda a reconstruir o andamento de uma operação em massa e a explicar por que um determinado pacote parou. Para cada lançamento, guarde o horário das duas verificações, total, available, reserved, currency, o orçamento calculado, o tamanho da reserva local e a lista de identificadores externos dos pedidos.

Para cada tentativa de criação, registre o custo, o código de resposta, o identificador técnico da operação e o status final. Segredos não entram no log: tokens de autorização, chaves de API, cabeçalhos completos de requisição e dados pessoais devem ser mascarados ou excluídos antes da gravação.

O log completo é conveniente para depuração, mas tem uma desvantagem: sem filtragem, dados de acesso e informações de clientes podem acabar no armazenamento.

Teste o esquema em uma fila pequena

Antes de um lançamento grande, execute um cenário curto: obtenha o balance, consulte os preços finais, crie um pacote limitado, consulte o balance novamente e compare a mudança esperada de available e reserved com a resposta real. Assim é possível perceber quando o serviço reserva o valor e quando o debita definitivamente.

Um pacote de teste não garante o mesmo comportamento sob carga alta: limites, processos paralelos ou restrições de um serviço específico podem entrar em ação. Por isso, na fila em massa, continue dividindo o lançamento em pacotes, verificando o saldo disponível entre eles e analisando cada recusa separadamente.