Conta autorizada
Entre no painel com o acesso fornecido pelo administrador. Não há cadastro público livre.
01 · PREPARAÇÃO
O que você precisa
Chave de envio
Em Chaves, crie uma chave com permissão de envio. A senha do painel e uma chave somente de celular não servem para esta integração.
Android conectado
Configure o app no aparelho dedicado, com chip ativo, permissões de SMS e acesso à internet. Use uma chave de celular separada e mantenha o app em execução.
Antes de testar de verdade
Os exemplos abaixo são ilustrativos. Troque o destinatário por um número autorizado e confirme as condições de envio da sua operadora. Esta página não executa requisições nem envia SMS.
02 · PRIMEIRO ENVIO
Uma requisição para entrar na fila
Faça a chamada no backend da sua aplicação. Guarde a chave em uma variável de ambiente ou gerenciador de segredos, nunca no JavaScript público do seu site.
POST
/v1/messagesRequer chave de enviocURL · exemplo ilustrativo
curl --request POST 'https://sms.rapp.dev.br/v1/messages' \
--header "Authorization: Bearer $GATEWAY_SMS_KEY" \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: pedido-exemplo-0001' \
--data '{
"recipient": "+15555550123",
"body": "Sua mensagem de exemplo."
}'Defina GATEWAY_SMS_KEY no ambiente seguro do seu backend. O telefone do exemplo não deve ser usado como destinatário real.
Resposta de aceitação
HTTP 202 · application/json
{ "id": "identificador-da-mensagem", "status": "queued" }Guarde o id e a chave de idempotência. A mensagem pode ser aceita mesmo com o aparelho offline: ela aguarda na fila. Consulte o histórico para saber o resultado.
03 · REFERÊNCIA
Campos e autenticação
URL base: https://sms.rapp.dev.br. Use HTTPS e o cabeçalho Authorization: Bearer SUA_CHAVE em todas as chamadas abaixo.
| Campo | Formato | Como preencher |
|---|---|---|
recipient | String · obrigatório | Telefone internacional: + seguido de 8 a 15 dígitos. No Brasil, inclua 55, DDD e número, sem espaços ou pontuação. |
body | String · obrigatório | De 1 a 500 caracteres, não apenas espaços. O limite da API não garante que o texto caiba em um único SMS. |
Atenção ao tamanho do SMS
O Android envia um único segmento, sem divisão automática. Em geral, são até 160 caracteres GSM-7 ou 70 Unicode; alguns caracteres GSM-7 consomem duas posições. Textos maiores podem falhar mesmo aceitos pela API. Prefira mensagens curtas e valide a codificação antes de enviar.
04 · CONFIABILIDADE
Evite enviar a mesma mensagem duas vezes
O cabeçalho Idempotency-Key é obrigatório: de 8 a 128 caracteres, usando letras, números, ponto, underline ou hífen.
- Uma operação, uma chave. Guarde a chave junto ao registro do envio.
- Mesma chave e mesmo conteúdo: retorna a mensagem existente e seu estado atual, sem criar outra.
- Mesma chave e conteúdo diferente: retorna HTTP 409.
- Nova mensagem: gere uma nova chave, mesmo que o texto seja igual.
Timeout não significa falha no envio.
Consulte o histórico antes de repetir. Se precisar repetir a mesma requisição, preserve a chave e o conteúdo. Não gere uma chave nova para tentar “destravar” um envio claimed ou uncertain.
05 · ACOMPANHAMENTO
Consulte o resultado
GET
/v1/messagesRequer chave de enviocURL · últimas 100 mensagens
curl 'https://sms.rapp.dev.br/v1/messages' \
--header "Authorization: Bearer $GATEWAY_SMS_KEY"A resposta contém messages, com até 100 mensagens mais recentes da empresa, e lastSeen, o último contato do aparelho em milissegundos Unix ou null. Localize o id salvo no envio. Esta rota não oferece paginação ou consulta por ID.
Evite consultar em loop contínuo. Faça consultas espaçadas e trate respostas de erro com espera progressiva. O dispositivo pode levar até 25 segundos para perceber uma mensagem nova durante o long polling.
06 · ESTADOS
Da fila ao resultado
| Estado | O que significa |
|---|---|
queued | Na fila, aguardando retirada pelo aparelho. |
claimed | O aparelho retirou a mensagem. O resultado ainda não voltou; não há redistribuição automática. |
sent | O Android reportou envio. Não é confirmação de entrega ao destinatário. |
delivered | Entrega confirmada pelo relatório da rede, quando disponível. |
failed | Falha reportada pelo aparelho. Confira o detalhe no histórico. |
uncertain | Não foi possível confirmar o resultado. Avalie antes de reenviar. |
expired | A mensagem ficou na fila por mais de 24 horas e não será retirada. |
07 · DIAGNÓSTICO
Se algo não funcionar
Erros da API retornam JSON no formato {"error":"descrição"}.
Confira telefone, texto e Idempotency-Key. Corrija os campos antes de repetir.
Verifique o Bearer token, a revogação e a permissão de envio da chave. Não use a senha do painel.
A chave já foi usada com outro conteúdo. Confira a operação original antes de criar outra.
O envio é limitado a 60 requisições por minuto por empresa. Aguarde a janela seguinte e reduza a frequência.
Espere e consulte o histórico. Preserve a idempotência e não reenvie com uma chave nova por causa do erro.
A mensagem ficou na fila. O que verificar?
Confira a conexão do Android, a chave de celular, a internet, as permissões de SMS, o chip e as restrições de bateria. O painel mostra o último contato do aparelho. Não crie outra mensagem apenas porque a primeira ainda não saiu.
Posso integrar direto pelo navegador?
Não exponha a chave em páginas, aplicativos distribuídos ou repositórios. Encaminhe a operação pelo seu backend, que guarda a credencial e controla quem pode enviar.
PRONTO PARA INTEGRAR
Documentação aberta.
Seus dados protegidos.
Esta página é pública e não lê sua sessão, mensagens ou chaves. A API, o painel e as funções administrativas continuam exigindo autenticação e as permissões correspondentes.
Use SMS apenas para destinatários autorizados. Não registre chaves, texto das mensagens ou números completos em logs públicos. Entrega e disponibilidade dependem do aparelho e da operadora.
Entrar no painel