Uma integração confiável separa catálogo, cotação vinculada ao usuário, pedido idempotente, consulta de status e cancelamento confirmado. Mantenha as chaves no servidor e verifique a titularidade em cada requisição. Respostas incertas exigem conciliação, em vez de comprar novamente ou reembolsar sem confirmação do provedor.
Separe a interface do acesso ao provedor
O navegador deve chamar sua API; seu servidor consulta o provedor SMS. Guarde credenciais em segredos do ambiente e devolva apenas os campos necessários ao usuário autenticado. Catálogo público é diferente de conta ou caixa privada. Verifique titularidade em toda operação, incluindo consulta, cancelamento e conclusão. Autenticar apenas a rota de compra não é suficiente para proteger o restante do ciclo.
Faça da cotação uma referência curta e confiável
O POST /api/v1/quotes implementado na ReceiveSMSGo cria cotação vinculada ao usuário com validade de 60 segundos. O servidor calcula USD como max(US$ 0,39, custo convertido × 2). Para comprar, o cliente envia o identificador, não um preço confiável. Se expirar, peça outra cotação. Uma oferta pode acabar entre consulta e compra; represente erros de disponibilidade de forma explícita.
Reserve uma vez e concilie compras incertas
POST /api/v1/orders exige Idempotency-Key e quoteId. Reutilizar a mesma chave na mesma operação pretendida devolve o pedido existente. Reserva da carteira e lançamento no livro de movimentações são atômicos. Se a resposta de compra for ambígua, o pedido vai para análise em vez de repetir a compra automaticamente. Idempotência protege sua fronteira; não concilia um timeout do provedor por conta própria.
- Crie uma chave por compra pretendida e preserve-a nas tentativas.
- Envie o identificador atual com o contexto autenticado.
- Concilie resultados ambíguos antes de iniciar outra compra.
Consulte o pedido sem sobrecarregar o provedor
GET /api/v1/orders/{id} retorna o pedido do usuário e pode atualizar o status do provedor. A implementação limita consultas ao provedor a uma a cada cinco segundos por pedido. Modele aguardando, recebido, concluído, cancelado, expirado e análise separadamente. Não invente prazo quando a unidade da documentação for incerta. Fechar o navegador não comprova que o pedido remoto terminou.
Confirme o cancelamento antes de alterar saldo
POST /api/v1/orders/{id} aceita cancel ou finish. O cancelamento fica bloqueado por 120 segundos após a criação; depois o servidor solicita confirmação antes de um único reembolso. Concluir exige código SMS recebido. Ações simultâneas usam transições para evitar sobreposição. Uma falha de rede não deve significar cancelamento confirmado nem autorização para creditar novamente.
Verifique callbacks e a prontidão operacional
Uma notificação recebida não é automaticamente uma fonte confiável. Após verificar a assinatura da Stripe, o registro oficial do pagamento é consultado antes de creditar o saldo. Uma notificação de status de SMS sem assinatura é apenas um sinal para consultar o status autenticado do pedido. Os eventos de teste e reais da Stripe devem corresponder ao segredo do endpoint, à conta e ao ambiente do depósito. As notificações externas precisam ser acessíveis; um redirecionamento não é prova de pagamento. As APIs da área de trabalho exigem uma sessão autenticada do site, não uma chave pública de API para desenvolvedores. Confira as operações habilitadas e a OpenAPI antes da integração.
Perguntas úteis, respostas claras
Posso colocar a chave do provedor no frontend?
Não. Guarde em segredos do servidor. O frontend deve chamar sua API com contexto do usuário autenticado.
Devo repetir uma compra com timeout usando nova chave?
Primeiro consulte e concilie o pedido original. Uma nova chave representa outra compra e pode gerar outra cobrança.
A API do painel é um produto público com chave de desenvolvedor?
Não. APIs de conta e pedido exigem sessão autenticada do site. Um produto público separado ainda não está disponível; confira operações habilitadas antes de integrar.
Fontes e leituras complementares
As fontes descrevem seus próprios serviços e podem mudar. Confira os requisitos atuais do destino antes de escolher um número.
Entenda o fluxo antes de começar.
Explore a seleção de serviços, as opções de países e o status do SMS na área de trabalho. Cotações e disponibilidade dependem do provedor; a aceitação do número e a entrega não são garantidas. Sua carteira e seus pedidos exigem login.
Abrir área de trabalho
