🛠️ Troubleshooting & FAQ
Seja você um desenvolvedor depurando código ou um analista financeiro operando o painel, esta seção reúne as respostas para os problemas e dúvidas mais comuns enfrentados na FastGivr Money.
🚦 Tabela de Resolução de Erros de API (Troubleshooting)
Se a API retornar um código de status HTTP de erro 4xx ou 5xx, consulte a tabela abaixo para entender a causa raiz e a solução recomendada:
| Status HTTP | Mensagem de Erro Comum | Causa Provável | Ação Recomendada |
|---|---|---|---|
400 | Invalid Request Body | Payload JSON malformado ou parâmetros incompatíveis. | Use um validador JSON e certifique-se de que os tipos de dados estão corretos (ex: amount como número, não string). |
401 | Token Expired ou Unauthorized | O seu token Bearer JWT expirou (validade rígida de 10 minutos). | Execute uma nova chamada em /access/account/get-token para renovar o token e atualize seu cache. |
403 | Forbidden Scope | O seu token de API autenticado não possui permissão para este endpoint. | Verifique se a chave de API utilizada possui o escopo necessário (ex: withdrawals.create para realizar saques). |
422 | Validation Failed | Erro em campos específicos (CPF inválido, valor de saque abaixo do mínimo). | Verifique a chave "errors" no corpo da resposta JSON para ver qual campo falhou e corrija o input. |
429 | Too Many Requests | Você excedeu o limite de requisições por minuto (Rate Limiting). | Implemente um controle de fila ou lógica de atraso (backoff) no envio de chamadas consecutivas. |
500 / 503 | Internal Server Error | Instabilidade temporária em nossos servidores ou nos bancos parceiros. | Aguarde alguns segundos e tente novamente (implemente lógica de retentativa automática no seu integrador). |
❓ Perguntas Frequentes (FAQ)
👥 Dúvidas Operacionais (Não Técnicas)
1. Por que o saldo de um boleto pago ainda não está "Disponível"?
- Resposta: Os boletos bancários levam até 1 dia útil para serem compensados e liquidados pelo banco emissor (D+1). Se o boleto foi pago no final de semana, a liquidação ocorrerá na terça-feira.
2. Posso estornar uma transação de Pix parcialmente?
- Resposta: Sim. O endpoint
/quickpay/pix/refundpermite passar o parâmetroamountpara estornar qualquer valor parcial menor ou igual ao valor original pago.
3. Como cadastrar novos colaboradores no portal?
- Resposta: Se você for o Administrador, vá em Configurações > Equipe > Convidar Membro. Insira o e-mail do colaborador e selecione o perfil de acesso adequado (Financeiro, Suporte ou Administrador).
💻 Dúvidas Técnicas (Integração)
1. Como simular pagamentos em Sandbox?
- Simulação de Pix: Em Sandbox, qualquer Pix criado muda para o status
Paidautomaticamente após 5 segundos ou clicando em "Simular Pagamento" nos logs do painel. - Simulação de Cartão: Utilize números de cartões fictícios de teste. Cartões terminados em
1111simulam sucesso, enquanto terminados em2222simulam recusa por saldo insuficiente.
2. Meu servidor não está recebendo os webhooks. O que fazer?
- Passo 1: Verifique na aba Webhooks do portal administrativo se a URL de destino está correta e respondendo com HTTP
200 OK. - Passo 2: Certifique-se de que seu servidor suporta conexões HTTPS e possui um certificado SSL válido e público (Let's Encrypt, Cloudflare, etc.). O Docusaurus e a API de testes não enviam webhooks para
http://localhostsem túnel reverso (use ferramentas como ngrok ou LocalTunnel para testes locais).