A API Assertiva SMS permite enviar mensagens de texto para números de celular e acompanhar automaticamente o status de entrega e as respostas dos destinatários.
Por meio da API, é possível:
Enviar até 1.000 SMS por requisição;
Consultar o status de uma mensagem;
Receber atualizações por meio de webhook;
Receber respostas dos destinatários;
Identificar cada envio por um valor de referência;
Escolher diferentes tipos de rota de envio.
A API utiliza o padrão REST e recebe requisições no formato JSON.
1. URL base
A URL base da API é:
https://api.assertivasolucoes.com.br/sms
O endpoint principal de envio é:
https://api.assertivasolucoes.com.br/sms/v3/send
A documentação completa está disponível na https://integracao.assertivasolucoes.com.br/v3/portal
2. Autenticação
Para utilizar a API SMS, é necessário gerar um token temporário de acesso utilizando as credenciais da aplicação.
São necessários:
Client ID;
Secret.
A geração do token utiliza o fluxo OAuth 2.0 client_credentials.
2.1 Endpoint para geração do token
Método: POST
URL:
https://api.assertivasolucoes.com.br/oauth2/v3/token
2.2 Configuração da requisição
Configure a requisição com:
Authorization: Basic Auth;
Username: Client ID;
Password: Secret;
Content-Type:
application/x-www-form-urlencoded;Parâmetro:
grant_type=client_credentials.
Exemplo do corpo:
grant_type=client_credentials
2.3 Resposta do token
A resposta contém o token que deverá ser utilizado no envio dos SMS:
{ "access_token": "SEU_TOKEN_DE_ACESSO", "token_type": "bearer", "expires_in": 60, "scope": "ALL" }
O campo expires_in informa o tempo de validade do token em segundos. A aplicação deve considerar o valor retornado pelo serviço como referência para renovação do token.
2.4 Cabeçalho das requisições
Após gerar o token, envie-o no cabeçalho:
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Também é recomendado utilizar:
Content-Type: application/json
Nunca exponha o Client ID, o Secret ou o token em aplicações front-end, repositórios públicos ou logs.
3. Envio de SMS
3.1 Endpoint
Método: POST
URL:
https://api.assertivasolucoes.com.br/sms/v3/send
O endpoint recebe uma lista de mensagens e permite configurar o recebimento de status e respostas dos destinatários.
3.2 Estrutura da requisição
Campo | Obrigatório | Descrição |
| Sim | Define se a aplicação deseja receber os status dos SMS. |
| Sim | Define se a aplicação deseja receber as respostas dos destinatários. |
| Condicional | URL que receberá os status quando |
| Condicional | URL que receberá as respostas quando |
| Não | Define o tipo de rota de envio. |
| Sim | Lista de mensagens que serão enviadas. |
3.3 Tipos de rota
O campo route_type aceita os seguintes valores:
Código | Tipo | Utilização |
| Exclusivo | Ideal para campanhas que precisam acompanhar as respostas. |
| Básico | Ideal para campanhas que não precisam acompanhar respostas. |
| Bet | Ideal para campanhas sem necessidade de acompanhamento de respostas e sem necessidade de envio rápido. |
Quando o campo não é informado, a documentação indica que será utilizada a rota Exclusivo.
3.4 Estrutura de cada SMS
Cada item do campo arraySms deve conter:
Campo | Obrigatório | Descrição |
| Sim | Número de destino com 11 dígitos, incluindo o DDD. |
| Sim | Texto da mensagem, limitado a 600 caracteres. |
| Não | Valor livre utilizado como referência no sistema integrado. |
O número deve ser informado somente com dígitos, no formato:
11912345678
A mensagem pode conter até 600 caracteres. A documentação informa que:
Até 160 caracteres correspondem a 1 SMS;
Após 160 caracteres, a cobrança considera blocos de 152 caracteres.
3.5 Exemplo de requisição
POST https://api.assertivasolucoes.com.br/sms/v3/send
{ "can_receive_status": true, "can_receive_answer": true, "webhook_status_url": "https://suaempresa.com.br/webhooks/sms/status", "webhook_answer_url": "https://suaempresa.com.br/webhooks/sms/resposta", "route_type": 1, "arraySms": [ { "number": "11912345678", "message": "Olá! Esta é uma mensagem de teste.", "filter_value": "pedido-12345" } ] }
3.6 Limite de envio
O campo arraySms pode conter até 1.000 mensagens por requisição.
Antes do envio, valide:
Se a lista não está vazia;
Se não ultrapassa o limite permitido;
Se todas as mensagens possuem número;
Se todas as mensagens possuem conteúdo;
Se os números estão no formato correto;
Se as mensagens possuem até 600 caracteres.
3.7 Resposta do envio
A API retorna uma lista com os identificadores das mensagens enviadas.
Exemplo:
[ { "id_sms": "ID_DA_MENSAGEM", "number": "11912345678", "filter_value": "pedido-12345" } ]
O campo id_sms deve ser armazenado pela aplicação. Ele será utilizado para consultar o status e a resposta de cada SMS.
4. Recebimento de status por webhook
A API permite receber automaticamente as atualizações de entrega por meio de uma URL de callback.
Para ativar esse recurso:
Defina
can_receive_statuscomotrue;Informe a URL no campo
webhook_status_url;Certifique-se de que a URL aceite requisições
POST.
4.1 Estrutura do status recebido
O webhook de status pode receber os seguintes campos:
Campo | Descrição |
| Identificador da mensagem. |
| Número para o qual o SMS foi enviado. |
| Valor de referência enviado na requisição. |
| Código numérico do status. |
| Descrição detalhada do status. |
Exemplo:
{ "id_sms": "ID_DA_MENSAGEM", "number": "11912345678", "filter_value": "pedido-12345", "status": 1, "status_detail": "Mensagem entregue no celular" }
4.2 Boas práticas para o webhook
O endpoint de callback deve:
Utilizar HTTPS;
Aceitar o método
POST;Validar o formato do JSON recebido;
Armazenar o
id_sms;Atualizar o status da mensagem de forma idempotente;
Responder rapidamente à API;
Evitar processar o mesmo evento mais de uma vez;
Registrar falhas para posterior reprocessamento.
5. Recebimento de respostas
Também é possível receber respostas enviadas pelos destinatários.
Para ativar o recurso:
Defina
can_receive_answercomotrue;Informe uma URL no campo
webhook_answer_url;Certifique-se de que a URL aceite requisições
POST.
5.1 Estrutura da resposta recebida
Campo | Descrição |
| Identificador do SMS original. |
| Número que enviou a resposta. |
| Valor de referência informado no envio. |
| Texto enviado pelo destinatário. |
Exemplo:
{ "id_sms": "ID_DA_MENSAGEM", "number": "11912345678", "filter_value": "pedido-12345", "reply": "SIM" }
A aplicação pode utilizar o campo filter_value para relacionar a resposta ao pedido, cliente ou processo correspondente.
6. Consulta de status
A API disponibiliza um endpoint para consultar o status de um SMS já enviado.
Método: GET
Endpoint documentado:
/v3/status
URL base:
https://api.assertivasolucoes.com.br/sms/v3/status
A consulta utiliza o identificador id_sms da mensagem enviada.
A especificação disponibilizada descreve o parâmetro id_sms como identificador da mensagem. Confirme na documentação oficial o formato final da URL utilizado pelo ambiente, pois o arquivo de especificação apresenta o parâmetro associado ao endpoint sem explicitá-lo no caminho.
A resposta segue o modelo:
{ "id_sms": "ID_DA_MENSAGEM", "number": "11912345678", "filter_value": "pedido-12345", "status": 1, "status_detail": "Mensagem entregue no celular" }
7. Consulta de respostas
Também é possível consultar a resposta de um SMS utilizando seu identificador.
Método: GET
Endpoint documentado:
/v3/answer
URL base:
https://api.assertivasolucoes.com.br/sms/v3/answer
A consulta utiliza o id_sms da mensagem.
A resposta segue o modelo:
{ "id_sms": "ID_DA_MENSAGEM", "number": "11912345678", "filter_value": "pedido-12345", "reply": "SIM" }
Quando a mensagem ainda não recebeu uma resposta, a API poderá informar que nenhuma resposta foi encontrada.
8. Tabela de status
Código | Status | Detalhamento | Descrição |
| Enviado | Com confirmação | A operadora confirmou a chegada do SMS ao dispositivo do destinatário. |
| Enviado | Sem confirmação | A operadora não confirmou a chegada do SMS. O aparelho pode estar desligado ou fora de área. |
| Não enviado | Blacklist | O número está cadastrado em uma lista de bloqueio. |
| Não enviado | Com erro | Ocorreu uma falha no processo de envio. |
| Não enviado | Não me ligue | O número está cadastrado no serviço “Não me ligue” do Procon-SP. |
| Não enviado | Inválido | O número informado é inválido. |
| Andamento | Enviando | O SMS está em processo de envio. |
| Não enviado | Cancelado | O envio foi cancelado automaticamente por ausência de saldo. |
| Não enviado | Link inválido | O envio foi bloqueado devido à utilização de um link não validado previamente. |
9. Detalhamento dos status
Entre os detalhamentos que podem ser retornados estão:
Mensagem entregue no celular;
Mensagem enviada para a operadora;
Mensagem recusada pela operadora;
Celular fora da área de cobertura;
Mensagem bloqueada por conteúdo proibido ou possível fraude;
Finalizadas as tentativas de entrega;
Bloqueado por lista de bloqueio;
Erro de processamento;
Bloqueado por “Não me ligue” do Procon;
Número do destinatário incorreto ou incompleto;
Enviando SMS;
Mensagem cancelada pelo sistema ou pelo usuário;
Bloqueado por link não validado previamente.
10. Tratamento de erros
A API pode retornar os seguintes erros:
Código | Significado | Tratamento recomendado |
| Parâmetros inválidos. | Validar o corpo, os números, as mensagens e os campos obrigatórios. |
| Não autenticado. | Gerar ou enviar um token válido. |
| Acesso não autorizado. | Confirmar a permissão para realizar envios de SMS. |
| Erro interno. | Tentar novamente e registrar a ocorrência para análise. |
10.1 Mensagens relacionadas ao código 400
Entre os possíveis problemas estão:
arraySmsnão informado;Lista de SMS vazia;
Mais de 1.000 SMS na mesma requisição;
can_receive_statusnão informado;can_receive_answernão informado;URL de webhook não informada quando necessária;
Mensagens não informadas;
Números não informados;
Mensagens com mais de 600 caracteres;
Parâmetros inválidos.
10.2 Problemas de autenticação
Em caso de erro 401:
Confirme se o token foi gerado corretamente;
Verifique se o cabeçalho utiliza o formato
Bearer;Confira se o token não expirou;
Gere um novo token;
Valide se a aplicação possui permissão para utilizar a API SMS.
10.3 Problemas de permissão
O código 403 pode indicar:
Chave de acesso não informada;
A empresa não possui permissão para envio de SMS;
A aplicação não possui acesso ao produto.
11. Fluxo recomendado de integração
Criar ou obter as credenciais de acesso.
Gerar o token OAuth 2.0.
Configurar os endpoints de webhook, se necessário.
Validar os números e o conteúdo das mensagens.
Enviar a lista de SMS.
Armazenar cada
id_sms.Acompanhar os status por webhook ou consulta.
Processar as respostas dos destinatários.
Atualizar o status no sistema interno.
Implementar retentativas apenas para falhas temporárias.
12. Boas práticas
Armazene o
id_smsde cada mensagem enviada.Utilize o
filter_valuepara relacionar o SMS a um pedido ou processo interno.Não envie mensagens duplicadas sem validar o resultado da requisição anterior.
Valide se o número possui 11 dígitos e contém DDD.
Limite o texto a 600 caracteres.
Evite incluir dados sensíveis no conteúdo da mensagem.
Utilize HTTPS nos webhooks.
Responda rapidamente às notificações recebidas.
Implemente idempotência no processamento de status e respostas.
Registre o histórico de envio e entrega.
Não armazene tokens em logs.
Proteja as URLs de webhook e os dados recebidos.
Trate respostas de indisponibilidade e erro com retentativas controladas.
Consulte a documentação oficial para validar alterações de endpoint ou regras de rota.
13. Resumo dos endpoints
Funcionalidade | Método | Endpoint |
Gerar token |
|
|
Enviar SMS |
|
|
Consultar status do SMS |
|
|
Consultar resposta do SMS |
|
|
14. Documentação e suporte
Para consultar os modelos completos de requisição, respostas e regras de utilização, acesse a https://integracao.assertivasolucoes.com.br/v3/portal
Em caso de dúvidas ou dificuldades de integração, entre em contato com a Central da Assertiva:
0800 878 1179;
(11) 3197-0719;