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.

A API da MOBSIM suporta o formato REST:

A sua programação ou o seu sistema deve realizar uma requisição para a URL https://mobsim-api.com.br/sms, enviando os parâmetros por meio de POST. O retorno para cada requisição será um JSON cujo formato é detalhado ao longo desta documentação.

Autenticação ¶

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

A chave de acesso deve ser fornecida conforme o exemplo a seguir:

Basic Y29udGE6c2VuaGEEGXTPcyozWmaIKc6D

Importante: Caso haja erro na autenticação, será retornado o status code 02 e o detail code 017.

Header ¶

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

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

Identificadores de SMS ¶

• ID (Identificador Único de SMS)

É obrigatório a utilização do parâmetro ID como um identificador único de SMS. O ID está vinculado ao número enviado dentro do sistema da MOBSIM e será utilizado para vincular os status dos SMS, as respostas dos usuários (MO) e proteção contra envios duplicados.

Restringimos em 100 caracteres o limite do id. Se o limite for ultrapassado, será retornado o status code 02 e o detail code 006.

Importante: É proibida a utilização de um ID que já tenha sido utilizado uma vez, por isso recomendamos utilizar GUID para gerar IDs únicos. Se o ID estiver duplicado será retornado o status code 02 e o detail code 005.

• GroupID (Identificador de Chamadas)

A utilização do parâmetro GroupID para identificação de requisições é opcional. Ele serve para identificar e agrupar várias requisições distintas.

Restringimos em 100 caracteres o limite do groupId. Se o limite for ultrapassado, será retornado o status code 02 e o detail code 009.

Importante: É proibida a utilização de um GroupID que já tenha sido usado uma vez, por isso recomendamos utilizar GUID para gerar GroupIDs únicos. Se o GroupID estiver duplicado será retornado o status code 02 e o detail code 008.

• CODE e KEY (Identificador Próprio)

Os parâmetros Code e Key são campos extras que podem ser preenchidos com códigos, IDs, chaves e outras informações diversas para controle interno. Esses parâmetros são disponibilizados nos callbacks de retornos de status e respostas (MO) de forma automatizada (veja “Métodos da API” no final da documentação).

Ao todo são quatro parâmetros: Code, Key1, Key2 e Key3.

Restringimos em 100 caracteres o limite desses parâmetros. Se o limite for ultrapassado, será retornado o status code 02 e o(s) detail code 010, 011, 012 e 013.

Restrições ¶

• 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.

• Limite de Números por Requisição

Restringimos que cada requisição tenha, no máximo, 500 números. Se o limite for ultrapassado, será retornado o status code 02 e o detail code 015.

• ID

Restringimos o uso de id duplicados, isto é, que já tenham sido utilizados via API uma primeira vez.

Caso o sistema detecte mensagens com id duplicados, a chamada será aceita, porém todas as mensagens duplicadas apresentarão o código status code 02 e o detail code 005 (vide tabela de códigos abaixo).

• GroupID

Restringimos o uso de GroupID duplicados, isto é, que já tenham sido utilizados via API uma primeira vez.

Caso o sistema detecte requisições com GroupID duplicado, será apresentado o código status code 02 e o detail code 008 (vide tabela de códigos abaixo).

• Caractere Excedido

Restringimos em 100 caracteres o limite dos parâmetros: ID, GroupID, Code, Key1, Key2 e Key3. Caso esse limite seja ultrapassado, o erro 400 Bad Request será apresentado e a requisição será rejeitada.

Formatação dos Números ¶

• Número Válido

Para que um número seja considerado válido, ele precisa seguir a seguinte estrutura: “DDD” + “NÚMERO”. (Ex: 1198980202). É opcional a inclusão do DDI (“55”) e Nono Dígito (“9”), pois o sistema da MOBSIM inclui essas informações automaticamente.

• Números Inválidos

Qualquer estrutura de número que não siga a recomendação anterior, será apresentado o código status code 02 e o detail code 002 (vide tabela de códigos abaixo).

Importante: Os números inválidos que receberem o código detail code 002 não serão tarifados.

Estrutura das Mensagens ¶

• Limite de 160 caracteres por mensagem

O padrão SMS (“Short Message Service”) suporta até 160 caracteres. Se alguma mensagem ultrapassar esse limite será apresentado o código status code 02 e o detail code 003 (vide tabela de códigos abaixo).

• Mensagens Concatenadas – até 480 caracteres

É possível enviar SMS com mais de 160 caracteres, para tanto será necessário solicitar uma configuração específica em sua subconta no sistema da MOBSIM. Consulte a Equipe de Suporte da MOBSIM ou o seu Gerente Comercial (contato@mobsim.com.br).

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

Além disso, como o particionamento das mensagens será realizado no último caractere de espaço, ou seja, palavras não serão truncadas, a mensagem pode ser particionada com menos de 152 caracteres.

Para esse tipo de envio a requisição será idêntica a requisição de envio de mensagens curtas. Basta enviar o texto da mensagem longa no parâmetro msg com mais de 160 caracteres.

Importante: Lembrando que cada parte do SMS será tarifado 1 SMS adicional.

Tabela de Códigos ¶

As requisições à API da MOBSIM retornarão dois tipos de código. O statusCode e o detailCode. A seguir, veja a lista de códigos fornecidos pela API:

statusCode ¶

detailCode ¶

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:

Status do SMS ¶

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

Content-Type: application/json

{
  "groupId": "90f93d5c-6ad1-454af-90f93d5c",
  "groupMsg": "",
  "messages": [
    {
      "id": "90f93d5c-6ad1-44af-90f93d5c",
      "to": "11988776655",
      "msg": "Mensagem da MOBSIM 1"
    },
    {
      "id": "90f93d5c-6ad1-77af-90f93d5c",
      "to": "11988776644",
      "msg": "Mensagem da MOBSIM 2"
    },
    {
      "id": "90f93d5c-6ad1-55af-90f93d5c",
      "to": "11988776633",
      "msg": "Mensagem da MOBSIM 3"
    }
  ]
}

Content-Type: application/json

{
  "StatusCode": 200,
  "Headers": {
    "Content-Type": "application/json",
    "Access-Control-Allow-Origin": "*"
  },
  "Body": "\"{\\\"header\\\":null,\\\"messages\\\":[{\\\"to\\\":\\\"5511988776655\\\",\\\"statusCode\\\":\\\"01\\\",\\\"statusDescription\\\":\\\"Ok\\\",\\\"detailCode\\\":\\\"001\\\",\\\"detailDescription\\\":\\\"Enviado\\\"}]}\"",
  "IsBase64Encoded": false
}

        {
           "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
        }