Autenticação

Guia de Integração do Aplicativo Móvel

A API usa autenticação por token Bearer. Há dois tipos de chave de API: uma Chave de API de Usuário (nenhum dispositivo Android necessário) e um Token por Dispositivo (vinculado a um telefone Android registrado).

Tipos de Token

Escolha o tipo de token que corresponde à sua integração de marketing por SMS gratuito:

Chave de API de Usuário - para acesso direto à API (sem telefone)

Nenhum dispositivo necessário

A forma mais simples de integrar. Gere uma chave de API pessoal na página Configurações do painel web e use-a para enfileirar SMS, mensagens de WhatsApp e campanhas por meio de qualquer cliente HTTP. Nenhum dispositivo Android ou cartão SIM é necessário quando as mensagens são enviadas por provedores de SMS conectados ou créditos.

Faça login no painel web e vá para Configurações.
Role até a seção Chave de API e clique em Gerar Chave.
Copie a chave e use-a no cabeçalho Authorization: Bearer das suas requisições.

Você pode regenerar sua chave a qualquer momento em Configurações > Chave de API. A chave antiga é invalidada imediatamente, portanto atualize todas as integrações antes de regenerar.

Token por Dispositivo - para o aplicativo Android

Dispositivo Android necessário

Cada telefone Android registrado na seção Dispositivos recebe seu próprio token. Esse token é usado pelo aplicativo Android para consultar a fila de mensagens, reportar o status de entrega e sincronizar a caixa de entrada. Ele é vinculado a um dispositivo e a um cartão SIM específicos.

Vá para Dispositivos > Adicionar Dispositivo no painel web.
Escaneie o código QR com o aplicativo Android. O app chama claim_device e o token é armazenado automaticamente.
O app usa Authorization: Bearer {token} em todas as requisições subsequentes.

Envio do Token

Cabeçalho Authorization (preferido)

HTTP

Authorization: Bearer YOUR-API-KEY

Cabeçalho X-API-Token

HTTP

X-API-Token: YOUR-API-KEY

Parâmetro de consulta ?token= (alternativa, útil quando os cabeçalhos são removidos por proxies)

URL

https://api.rcszilla.com/?endpoint=queue_sms&token=YOUR-API-KEY

Os tokens são armazenados e comparados em maiúsculas. A API normaliza seu token automaticamente.

Token Legado

Versões mais antigas usavam um único mobile_app_token compartilhado por usuário, armazenado nas configurações. Isso ainda funciona por compatibilidade retroativa, mas a Chave de API de Usuário ou os tokens por dispositivo são fortemente recomendados.

Nota de migração: Se o seu app foi criado antes da adição do suporte a múltiplos dispositivos, ele pode estar usando o token único legado. Para migrar, abra a página Dispositivos no painel web, gere um token por dispositivo e atualize a configuração do app.

Ciclo de Vida do Token de Dispositivo

O administrador abre Dispositivos > Adicionar Dispositivo no painel web e um token de registro de uso único (código QR) é gerado.
O app escaneia o QR e chama claim_device com esse token.
O servidor cria o registro do dispositivo. O mesmo token passa a ser o token de API por dispositivo permanente.
O app armazena o token com segurança (recomenda-se o EncryptedSharedPreferences do Android).
Todas as requisições subsequentes usam Authorization: Bearer {token}.
O administrador pode regenerar o token a qualquer momento na página Dispositivos. O token antigo é invalidado imediatamente.