Bem-vindo à documentação da API SMS da MOBSIM!

Com ela você pode enviar SMS para todas as operadoras brasileiras, em todo o território nacional, e receber status de entrega e respostas dos usuários (MO) de forma automatizada.

Visão Geral ¶

A API da MOBSIM segue o formato REST. Todo envio é feito por uma única chamada:

POST https://mobsim-api.com.br/sms

Em cada chamada você envia de 1 a 1.000 mensagens em um JSON. A API valida cada mensagem individualmente e devolve, também em JSON, o resultado de cada uma.

Resumo do fluxo:

1. Sua aplicação envia a requisição com a chave de acesso no header Authorization.

2. A API valida a requisição como um todo (autenticação, quantidade de mensagens, groupId, saldo e limite mensal). Se alguma dessas validações falhar, nenhuma mensagem é enviada e a resposta traz o erro no campo header.

3. Se a requisição for aceita, cada mensagem é validada separadamente. As mensagens válidas são enviadas, e as inválidas são recusadas sem impedir o envio das demais. O resultado de cada mensagem vem no campo messages.

4. Depois do envio, a MOBSIM pode chamar a sua aplicação com os status de entrega e as respostas dos usuários (veja Callbacks da API).

Autenticação ¶

Todas as requisições à API SMS devem incluir uma chave de acesso gerada no momento da criação da conta no sistema da MOBSIM. Consulte a Equipe de Suporte da MOBSIM ou o seu Gerente Comercial para obter suas credenciais (suporte@mobsim.com.br).

A chave de acesso deve ser enviada no header Authorization, precedida de Basic, exatamente como foi fornecida:

Authorization: Basic <SUA_CHAVE_DE_ACESSO>

Erros de autenticação retornam HTTP 401 e recusam a requisição inteira:

Headers ¶

Todas as requisições devem incluir, além do cabeçalho de autenticação, os seguintes headers:

Content-Type: application/json
Accept: application/json

Se o Content-Type não for application/json, a requisição é recusada (veja Respostas Fora do Padrão).

Requisição ¶

Estrutura ¶

A requisição é um objeto JSON com uma lista de mensagens. É possível enviar uma mensagem diferente para cada número ou a mesma mensagem para vários números.

{
    "groupId": "90f93d5c-6ad1-44af",
    "groupMsg": "",
    "messages": [
        {
            "id": "90f93d5c-6ad1-44af",
            "to": "11988776655",
            "msg": "Mensagem da MOBSIM 1",
            "code": "MeuID_20-05-2018_1",
            "key1": "41177319923"
        },
        {
            "id": "90f93d5c-6ad1-77af",
            "to": "11988776644",
            "msg": "Mensagem da MOBSIM 2",
            "code": "MeuID_20-05-2018_2",
            "key1": "41177319923"
        }
    ]
}

Campos ¶

* Cada mensagem precisa ter texto: ou o seu próprio msg, ou o groupMsg da requisição.

Erros de validação ¶

Há dois níveis de erro:

• Erros da requisição: recusam a chamada inteira, retornam HTTP 400 ou HTTP 401 e trazem o código no campo header. Nenhuma mensagem é enviada.

• Erros da mensagem: recusam só aquela mensagem. A chamada é aceita com HTTP 200, as demais mensagens são enviadas normalmente e o código da mensagem recusada vem no item correspondente de messages.

Importante: Todas as mensagens precisam ter o campo to. Uma mensagem sem to faz a requisição inteira falhar (veja Respostas Fora do Padrão).

Identificadores ¶

• ID (Identificador Único de SMS)

O id é obrigatório. Ele fica vinculado ao número enviado dentro do sistema da MOBSIM e é usado para vincular os status dos SMS, as respostas dos usuários (MO) e para proteger contra envios duplicados.

É proibido usar um id que já tenha sido usado, seja na mesma requisição ou em uma requisição anterior. Recomendamos usar GUID para gerar IDs únicos. Mensagens com id duplicado recebem o detailCode 005, e as demais mensagens da chamada são enviadas normalmente.

• GroupID (Identificador da Requisição)

O groupId é opcional. Ele serve para identificar e agrupar requisições.

É proibido usar um groupId que já tenha sido usado. Recomendamos usar GUID. Se o groupId estiver duplicado, a requisição inteira é recusada com o detailCode 009. Se tiver mais de 100 caracteres, é recusada com o detailCode 008.

• Code e Key (Identificadores Próprios)

Os campos code, key1, key2 e key3 são opcionais e podem ser preenchidos com códigos, IDs, chaves e outras informações para controle interno. Eles são devolvidos nos callbacks de status e de respostas (MO) (veja Callbacks da API).

O limite é de 100 caracteres por campo. Se ultrapassado, só a mensagem afetada é recusada, com o detailCode 010, 011, 012 ou 013.

• groupMsg (Mensagem Padrão)

O groupMsg replica a mesma mensagem para todos os números da lista. Mensagens que vierem com o msg vazio usam o texto do groupMsg. Se as duas forem preenchidas, vale o msg da mensagem.

Números de Telefone ¶

Formato aceito ¶

Envie o número no formato DDD + número (ex.: 11988776655). O DDI (55) e o nono dígito (9) são opcionais, pois o sistema da MOBSIM os inclui automaticamente.

O número pode vir com máscara: espaços, parênteses, hífens, + e zeros à esquerda são ignorados. Por exemplo, (11) 98877-6655, +55 11 98877-6655 e 011988776655 são tratados como 5511988776655.

A resposta devolve no campo to o número já normalizado, com 13 dígitos (55 + DDD + 9 + número).

Números recusados ¶

Somente celulares brasileiros são aceitos. São recusados com o detailCode 002:

• números que, depois da normalização, não tenham 13 dígitos;

• números com DDI diferente de 55;

• telefones fixos;

• números com falsos DDDs, ou seja, DDDs que não existem no Brasil: 10, 20, 23, 25, 26, 29, 30, 36, 39, 40, 50, 52, 56, 57, 58, 59, 60, 70, 72, 76, 78, 80 e 90;

• números em que todos os dígitos depois do DDD e do nono dígito são iguais (ex.: 11999999999).

Importante: Os números recusados com o detailCode 002 não são tarifados.

Mensagens ¶

Limite de caracteres ¶

O padrão SMS (“Short Message Service”) suporta até 160 caracteres. Mensagens acima desse limite são recusadas com o detailCode 003.

O limite é verificado depois da limpeza de caracteres e já com o texto de opt-out, quando houver (veja abaixo).

Mensagens concatenadas (até 480 caracteres) ¶

É possível enviar SMS com até 480 caracteres. Para isso é necessário solicitar uma configuração específica na sua conta. Consulte a Equipe de Suporte da MOBSIM ou o seu Gerente Comercial (suporte@mobsim.com.br).

Cada parte da mensagem contém até 152 caracteres, pois há uma reserva de 8 caracteres para identificar as partes que compõem a mensagem. Essa identificação é necessária para que os aparelhos exibam as partes como uma única mensagem.

Como o particionamento é feito no último espaço (as palavras não são cortadas), uma parte pode ter menos de 152 caracteres.

A requisição é idêntica à de mensagens curtas. Basta enviar o texto longo no campo msg.

Importante: Cada parte da mensagem é tarifada como 1 SMS.

Caracteres aceitos ¶

O texto da mensagem passa por uma limpeza automática antes do envio:

• Mantidos: letras sem acento (A–Z, a–z), números (0–9), espaço e os símbolos $ @ _ ! " # % & ' ( ) * + , - . / : ; < = > ?

• Trocados pela letra sem acento: á à â ã ä å, é è ê, í ì, ó ò ô õ ö, ú ù ü, ç e ñ, em maiúsculas e minúsculas (ex.: “Promoção” vira “Promocao”).

• Removidos sem aviso: qualquer outro caractere, como quebras de linha, tabulações, emojis, [, ], {, }, \, |, ~, ^, `, €, º, ª e letras com outros acentos (ë, ï, î, û).

Recomendamos revisar o texto antes do envio para que a remoção de caracteres não altere o sentido da mensagem.

Opt-out ¶

Se a sua conta estiver configurada com opt-out, o texto (Envie PARE p/Sair) (20 caracteres, incluindo o espaço inicial) é adicionado ao fim de cada mensagem.

Esse texto conta no limite de caracteres. Na prática, o limite disponível para o seu texto passa a ser de 140 caracteres (ou 460, em contas com mensagens concatenadas).

Saldo e Limite Mensal ¶

Contas pré-pagas: saldo (detailCode 014) ¶

A verificação de saldo vale somente para contas pré-pagas. O saldo disponível precisa ser maior ou igual à quantidade de mensagens da requisição. Caso contrário, a requisição inteira é recusada com HTTP 400 e o detailCode 014, e nenhuma mensagem é enviada.

Somente as mensagens enviadas (detailCode 001) são debitadas do saldo. Mensagens concatenadas debitam uma unidade por parte.

Contas pós-pagas não têm verificação de saldo. Elas podem ter um limite mensal, descrito a seguir.

Contas pós-pagas: limite mensal (detailCode 021) ¶

Contas pós-pagas podem ter um limite mensal de envios configurado pela MOBSIM. O limite considera o total de SMS debitados da conta no mês corrente (horário de Brasília), somando os envios pela API e pelas campanhas.

Uma equipe da MOBSIM acompanha os limites e pode, por decisão própria, ampliá-los gradativamente conforme o volume de cada cliente.

Quando o total enviado no mês atinge o limite, as requisições seguintes são recusadas com HTTP 400 e o detailCode 021 até o início do mês seguinte ou até que o limite seja ampliado. A requisição que ultrapassa o limite ainda é aceita e enviada. O bloqueio passa a valer a partir da próxima.

Alertas por E-mail ¶

Quando a conta tem limite mensal, a MOBSIM envia alertas por E-mail aos usuários ativos vinculados à conta e à equipe MOBSIM:

O E-mail informa o limite mensal, o total usado no mês e a quantidade ainda disponível. Se uma única requisição levar o total de menos de 80% direto para 100% ou mais, só o alerta de 100% é enviado.

Os alertas são enviados sempre que o total do mês atinge 80% ou 100% do limite vigente. Se o limite for ampliado depois de um alerta, novos alertas são enviados quando a conta atingir 80% ou 100% do novo limite. Se, no momento da ampliação, o total já estiver acima de 80% do novo limite, só o alerta de 100% será enviado. Assim, a mesma conta pode receber mais de um alerta de cada tipo no mesmo mês.

Resposta ¶

Formato ¶

A resposta tem dois campos:

• header: preenchido apenas quando a requisição inteira é recusada. Nesse caso, messages vem null.

• messages: preenchido quando a requisição é aceita, com o resultado de cada mensagem, na mesma ordem do envio. Nesse caso, header vem null.

Cada resultado traz statusCode, statusDescription, detailCode e detailDescription (veja Tabela de Códigos). Os itens de messages também trazem o número normalizado em to.

O detailCode 001 indica que a mensagem foi aceita pela MOBSIM para envio. O status de entrega no celular é informado depois, pelo callback de status.

Decodificação da resposta ¶

Importante: O corpo da resposta é uma string JSON que contém o JSON do resultado. Ou seja, o resultado vem codificado duas vezes, e a sua aplicação precisa decodificá-lo duas vezes.

Corpo recebido:

"{\"header\":null,\"messages\":[{\"to\":\"5511988776655\",\"statusCode\":\"01\",\"statusDescription\":\"Ok\",\"detailCode\":\"001\",\"detailDescription\":\"Enviado\"}]}"

Resultado depois da segunda decodificação:

{
    "header": null,
    "messages": [
        {
            "to": "5511988776655",
            "statusCode": "01",
            "statusDescription": "Ok",
            "detailCode": "001",
            "detailDescription": "Enviado"
        }
    ]
}

Exemplos de decodificação:

// JavaScript
const resultado = JSON.parse(JSON.parse(corpo));

# Python
resultado = json.loads(json.loads(corpo))

// C# (Newtonsoft.Json)
var json = JsonConvert.DeserializeObject<string>(corpo);
var resultado = JsonConvert.DeserializeObject<Resposta>(json);

Códigos HTTP ¶

Respostas Fora do Padrão ¶

Nos casos abaixo, a resposta não segue o formato com header e messages. O corpo é apenas uma mensagem de texto, ou vem vazio:

Em caso de erro 500, entre em contato com a Equipe de Suporte da MOBSIM antes de reenviar, informando o horário e o groupId da requisição, se houver.

Tabela de Códigos ¶

As respostas da API da MOBSIM trazem dois tipos de código: o statusCode e o detailCode.

statusCode ¶

detailCode ¶

Se todos os números de uma requisição forem inválidos, a requisição é aceita (HTTP 200) e cada mensagem recebe o detailCode 002. O detailCode 016 só é usado quando a lista messages está vazia.

Tabela de Status ¶

Abaixo está a relação dos status que os números enviados para as operadoras apresentam. Estes status são fornecidos exclusivamente pelas operadoras e repassados pela MOBSIM no callback de status:

Limites de Uso ¶

• Requisições Simultâneas

Solicitamos que sejam feitas, no máximo, 10 requisições simultâneas (threads) para a aplicação da MOBSIM com um espaçamento de 10 segundos por requisição.

• Velocidade e Capacidade de Envio

É possível gerar até 25 threads de 1.000 números ao mesmo tempo, gerando uma performance de até 25.000 envios por requisição.

Recomendamos que haja um espaçamento de 15 segundos a cada lote de 25 threads de 1.000 números, ou seja, 100.000 SMS/minuto.

Chamadas individuais, com apenas 1 número por requisição, recomendamos que sejam feitas até 1.500 threads por minuto.

• Tempo de Resposta da Requisição

O tempo de resposta de cada requisição varia conforme o fluxo de mensagens trafegadas pela MOBSIM. Datas especiais, comemorativas ou horários de pico costumam ter um tempo maior de processamento das requisições.

Embora o tempo médio possa variar entre 5 e 30 segundos, há casos em que o tempo de resposta ultrapassa o tempo default de 60 segundos para time-out.

Ou seja, o seu sistema precisa estar preparado para aguardar o nosso tempo de resposta. Solicitamos que seja configurado um time-out de até 300 segundos (5 minutos) para retorno de cada requisição.

Content-Type: application/json
Authorization: Basic <SUA_CHAVE_DE_ACESSO>
Accept: application/json

{
  "groupId": "90f93d5c-6ad1-454af-90f93d5c",
  "groupMsg": "Hello, world!",
  "messages": [
    {
      "id": "90f93d5c-6ad1-44af-90f93d5c",
      "to": "11988776655",
      "msg": "Mensagem da MOBSIM 1",
      "code": "Hello, world!",
      "key1": "Hello, world!",
      "key2": "Hello, world!",
      "key3": "Hello, world!"
    }
  ]
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "groupId": {
      "type": "string",
      "description": "Identificador único da requisição. Até 100 caracteres."
    },
    "groupMsg": {
      "type": "string",
      "description": "Mensagem padrão, usada nas mensagens que vierem sem `msg`."
    },
    "messages": {
      "type": "array",
      "description": "De 1 a 1.000 mensagens."
    }
  },
  "required": [
    "messages"
  ]
}

Content-Type: application/json

"{\"header\":null,\"messages\":[{\"to\":\"5511988776655\",\"statusCode\":\"01\",\"statusDescription\":\"Ok\",\"detailCode\":\"001\",\"detailDescription\":\"Enviado\"},{\"to\":\"5511933334444\",\"statusCode\":\"02\",\"statusDescription\":\"Falha\",\"detailCode\":\"002\",\"detailDescription\":\"Não enviado\"},{\"to\":\"5511988776633\",\"statusCode\":\"01\",\"statusDescription\":\"Ok\",\"detailCode\":\"001\",\"detailDescription\":\"Enviado\"}]}"

Content-Type: application/json

"{\"header\":{\"statusCode\":\"02\",\"statusDescription\":\"Falha\",\"detailCode\":\"015\",\"detailDescription\":\"Não enviado\"},\"messages\":null}"

Content-Type: application/json

"{\"header\":{\"statusCode\":\"02\",\"statusDescription\":\"Falha\",\"detailCode\":\"017\",\"detailDescription\":\"Não enviado\"},\"messages\":null}"

{
    "id": "90f93d5c-6ad1-55af",
    "number": "5511988776633",
    "status": "Entregue",
    "code": null,
    "key1": null,
    "key2": null,
    "key3": null
}

{
    "id": "90f93d5c-6ad1-55af",
    "number": "5511988776633",
    "message": "Resposta do Usuário",
    "date": "2022-04-05 10:27:28",
    "code": null,
    "key1": null,
    "key2": null,
    "key3": null
}