Conceitos-chave e dicas

Autenticação

Em todas as chamadas, devem ser identificadas sua conta e senha de integração que enviamos por e-mail. Caso haja erro na autenticação, o respectivo código de erro será retornado.

Nome Obrigatório Formato Descrição
account Sim string (20) Nome de usuário para autenticação
code Sim string (20) Senha para autenticação

 

Parâmetro Id

Ao enviar um SMS, recomendamos que você utilize o parâmetro Id. Ele serve como um identificador único de sua mensagem em nossa plataforma e pode ser utilizado para consulta de status ou mesmo para proteção contra envios duplicados. Veja detalhes a seguir:

 

Controle dos status das mensagens

Por meio do Id, nossa plataforma poderá enviar ao seu sistema o status de envio de um SMS.

envio-status-sms

Com o Id, também seu sistema pode consultar o status de envio:

consulta-status-sms

 

Proteção contra envios duplicados

Caso ocorra alguma falha em seu sistema de envio e o Id seja duplicado em um mesmo dia, nossa plataforma evitará que a mensagem seja enviada novamente.

 

Controle das mensagens trafegadas

Você pode utilizar o Id para identificar cada mensagem tanto em seu sistema quanto em nossa plataforma, facilitando o cruzamento de informações, caso seja necessário para auditoria ou para depuração de erros.

 

Formato e codificação dos campos

Fique atento à formatação e codificação dos diferentes tipos de campos utilizados nas chamadas:

Tipos de Campo Detalhes
string As variáveis devem ser URL Encoded, especialmente quando se trata do conteúdo da mensagem.
Data e hora dd/mm/aaaa hh:mm:ss
Celular Código de país + código de área + número.
Exemplo: 555199887766.
Mensagem string alfanumérica com um limite de 160 caracteres.

 

Tratamento do retorno das chamadas

A cada chamada de integração, diversos códigos de retorno serão retornados. Recomendamos que você utilize em seu código-fonte uma estrutura do tipo switch/case para tratamento desses retornos. Exemplo:

$retorno = substring($retornoIntegracao, 0, 3)
  switch ($retorno) {
    case 000:
    /*mensagem enviada com sucesso*/
    break;
    case 080:
    /*mensagem com Id repetido*/
    break;
    default:
    /*retorno não identificado*/
    break
}

 

Status do SMS

Os SMS enviados possuem o seguinte fluxo de status:

fluxo-de-envio-do-sms

Status Detalhes

zenvia-icon
Salvo para envio – SMS agendado na plataforma Zenvia para envio em data e hora futura (ainda não enviado à operadora).
operadora
SMS entregue com sucesso à operadora de destino.
sms-entregue
Recebido
Operadora confirma o recebimento pelo celular de destino.
sms-nao-entregue
Não recebido
Operadora confirma o não recebimento pelo celular de destino.
sms-sem-info-entrega
Sem informação
Operadora não retornou informação sobre o envio.
sms-nao-enviado
Não enviado à operadora – SMS registrado na plataforma Zenvia, porém bloqueado por nossas ferramentas de inteligência de envio.
Fora do plano de numeração Celular destinatário é inválido (número não existe).
Blacklist O celular destinatário do SMS foi encontrado em uma lista de bloqueio da conta.
Limpeza preditiva O celular destinatário foi bloqueado por nosso exclusivo algoritmo de limpeza preditiva de base (para mais informações, consulte nossa equipe).
Cancelado SMS com envio cancelado pelo usuário ou pelo sistema de integração.

Observação: no sistema de relatórios, você encontrará diferentes nomes que representam esses status do fluxo.