Você está acessando a área Zenvia Desenvolvedores » Métodos da API

Recebimento de SMS único – HTTP

admin — Wed, 17 Oct 2012 19:38:00 +0000

Descrição

A plataforma Zenvia envia ao sistema do cliente um SMS recebido de um celular (esta funcionalidade é utilizada, por exemplo, para enquetes, SAC, pesquisas, confirmações de visita etc).
Para receber um SMS em seu sistema, é necessário configurar uma URL de notificação na plataforma Zenvia.
Caso haja indisponibilidade em seu sistema, nossa plataforma efetua re-tentativas de envio do SMS recebido.
Para mais detalhes, acesse a seção “Como receber SMS em seu sistema”.
[HTTP]

[ZENVIA] ←→ [SISTEMA CLIENTE]

Parâmetros de entrada
Parâmetro	Obrigatório	Formato	Descrição
Id	Sim	String (50)	Identificador do SMS recebido na plataforma Zenvia.
From	Sim	código de país + código de área + número (até 15 dígitos)	Número do celular remetente.
To	Sim	String (10)	Nùmero especial (shortcode) para o qual o SMS foi enviado (ex; 28595).
Msg	Sim	String (150)	Conteúdo do SMS recebido.
Date	Sim	dd/mm/aaaa hh:mm:ss	Data e hora de recebimento do SMS na plataforma Zenvia.
Account	Sim	String (20)	Alias da conta do cliente no qual o SMS foi recebido.

The post Recebimento de SMS único – HTTP appeared first on Você está acessando a área Zenvia Desenvolvedores.

Listar novos SMS recebidos – HTTP

admin — Wed, 17 Oct 2012 19:22:02 +0000

Descrição

Listar, em uma única chamada, os SMS recebidos ainda não consultados.
Um SMS recebido só pode ser consultado uma única vez, de forma que se um SMS é retornado nesta consulta, significa que seu sistema ainda não havia listado esse SMS recebido.
O retorno é composto por linhas em formato texto: a primeira informa se foram ou não encontrados novos SMS recebidos; as demais, em formato string CSV, correspondem a novo cada SMS recebido.
Importante: deve haver um intervalo mínimo de 5 minutos entre cada chamada efetuada à plataforma Zenvia.
[HTTP]

[SISTEMA CLIENTE] ←→[ZENVIA]

Parâmetros de entrada
Parâmetro	Obrigatório	Formato	Descrição
Account	Sim	String (20)	Nome da conta utilizada pelo cliente
Code	Sim	String (20)	Senha de integração da conta.
Dispatch	Sim	Nome da operação (listReceived)	Deve conter o valor listReceived, indicando a leitura de novos SMS recebidos.

Retorno da consulta
Retorno	Descrição
300 – Received messages found	Novos SMS recebidos listados nas linhas seguintes.
301 – No received messages found	Nenhum novo SMS recebido encontrado.
Erros gerais
900 – Authentication error	Erro de autenticação. Verifique os parâmetros “account” e “code”.
990 – account limit reached	O limite de consultas de sua conta à API foi atingido. Contate nosso suporte para verificação/liberação.
998 – Wrong operation requested	Operação de chamada inexistente. Verifique o parâmetro “dispatch” conforme tabela acima.
999 – Unknown error	Erro desconhecido. Por favor, contate nosso suporte.

Retorno CSV de cada linha correspondente a um SMS recebido
Parâmetro	Obrigatório	Formato	Descrição
Id	Sim	String (50)	Identificador do SMS recebido na plataforma Zenvia.
Date	Sim	dd/mm/aaaa hh:mm:ss	Data e hora de recebimento do SMS na plataforma Zenvia.
From	Sim	código de país + código de área + número (até 15 dígitos)	Número do celular remetente.
Msg	Sim	String(150)	Conteúdo do SMS recebido.

Exemplo de linhas retornadas

300 – Received messages found
id0001; 01/01/2012 15:00:00; Mensagem recebida 2
id0002; 01/12/2011 16:00:00; Mensagem recebida 1

The post Listar novos SMS recebidos – HTTP appeared first on Você está acessando a área Zenvia Desenvolvedores.

Cancelamento de SMS agendado – HTTP

admin — Wed, 17 Oct 2012 18:57:03 +0000

Descrição

Cancelar o envio de um SMS agendado para data e hora futura.
Para realizar a consulta, é necessário que tenha sido utilizado o identificador (Id) no momento do envio.
O retorno é composto por linhas em formato texto correspondentes a cada Id enviado como parâmetro.
Importante: o cancelamento de um SMS só pode ser feito até sua data de agendamento. Após, o SMS terá sido enviado à operadora e não poderá ser cancelado.
HTTP]

[SISTEMA CLIENTE] ←→[ZENVIA]

Parâmetros enviados ao sistema do cliente
Parâmetro	Obrigatório	Formato	Descrição
Account	Sim	String (20)	Nome da conta utilizada pelo cliente
Code	Sim	String (20)	Senha de integração da conta.
Dispatch	Sim	Nome da operação(cancel)	Deve conter o valor cancel, indicando o cancelamento de envio de um SMS.
Id	Sim	String (50)	Identificador único do SMS a ser cancelado.

Retorno da chamada
Retorno	Descrição
Sucesso no cancelamento
002 – Message succesfully canceled	Mensagem cancelada com sucesso.
SMS não cancelado
131- Message already sent, can’t be canceled	SMS já enviado à operadora de destino.
132 – Message already canceled	SMS já cancelado anteriormente.
Erros na consulta
021 – ‘id’ field is mandatory	Campo Id é obrigatório.
180 – Message Id not found	Não foi encontrado SMS com o Id fornecido como parâmetro.
190 – Unknown error	Erro desconhecido. Por favor, contate nosso suporte.
Erros gerais
900 – Authentication error	Erro de autenticação. Verifique os parâmetros “account” e “code”.
990 – Acount limit reached	O limite de consultas de sua conta à API foi atingido. Contate nosso suporte para verificação/liberação.
998 – Wrong operation requested	Operação de chamada inexistente. Verifique o parâmetro “dispatch” conforme tabela acima.
999 – Unknown error	Erro desconhecido. Por favor, contate nosso suporte.

The post Cancelamento de SMS agendado – HTTP appeared first on Você está acessando a área Zenvia Desenvolvedores.

Recebimento de status de SMS – HTTP

admin — Wed, 17 Oct 2012 18:34:05 +0000

Descrição

A plataforma Zenvia envia ao sistema do cliente o status e a identificação do SMS correspondente.
Para receber uma notificação de status, é necessário que tenha sido utilizado o identificador (Id) no momento do envio. É possível enviar status intermediários ou finais.
Para receber o status, é necessário configurar uma URL de notificação na plataforma Zenvia.
Caso haja indisponibilidade em seu sistema, nossa plataforma efetua re-tentativas de envio do status do SMS.
Para mais detalhes, acesse a seção “Como enviar SMS de seu sistema”.
[HTTP]

[ZENVIA] ←→ [SISTEMA CLIENTE]

Parâmetros enviados ao sistema do cliente
Parâmetro	Obrigatório	Formato	Descrição
Id	Sim	String (50)	Identificador único do SMS definido no momento do envio.
Status	Sim	String (100)	Status do SMS conforme tabela a seguir.

Status do SMS
Retorno	Descrição
SMS agendado na plataforma Zenvia para envio em data e hora futura (ainda não enviado à operadora).
100 – Message queued	SMS aguardando envio.
SMS entregue com sucesso na operadora de destino.
110 – Message sent to operator	Ainda aguardando informações detalhadas da operadora.
111 – Message reception unavailable	Sem informação – operadora não retornou informações detalhadas sobre o SMS.
120 – Message received by mobile	Recebido – operadora confirma o recebimento pelo celular de destino.
140 – Mobile number not covered	Não recebido – operadora confirma o não recebimento do SMS pelo celular de destino
150 – Message expired in operator
160 – Operator network error
161 – Message rejected by operator
162 – Message cancelled or blocked by operator
170 – Bad message
171 – Bad number
SMS não enviado à operadora – SMS registrado na plataforma Zenvia, porém bloqueado por nossas ferramentas de inteligência de envio.
130 – Message blocked	Celular destinatário inválido (número não existe).
131 – Message blocked by predictive cleansing	Celular destinatário bloqueado por nosso exclusivo algoritmo de limpeza preditiva de base (para mais informações, consulte nossa equipe).
Erros gerais
999 – unknown error	Erro desconhecido. Por favor, contate nosso suporte.

The post Recebimento de status de SMS – HTTP appeared first on Você está acessando a área Zenvia Desenvolvedores.

Consultado de status de múltiplos SMS – HTTP

admin — Wed, 17 Oct 2012 18:18:49 +0000

Descrição

Consultar, em uma única chamada, status de vários SMS registrados na plataforma.
Para realizar a consulta, é necessário que tenha sido utilizado o identificador (ID) no momento do envio.
O retorno é composto por linhas em formato texto correspondentes a cada ID enviado como parâmetro.
Importante: a consulta a um SMS fica disponível por até 24 horas após seu envio. Após esse período, será retornado “180 – message ID not found”.
[HTTP]

[SISTEMA CLIENTE] ←→[ZENVIA]

Parâmetros de entrada
Parâmetro	Obrigatório	Formato	Descrição
Account	Sim	String (20)	Nome da conta utilizada pelo cliente.
Code	Sim	String (20)	Senha de integração da conta.
Dispatch	Sim	Nome da operação(checkMultiple)	Deve conter o valor checkMultiple, indicando a consulta de status de diversos SMS.
IdList	Sim	String csv	Lista de identificadores (IDs) separados por ponto-e-vírgula. Exemplo: id0012;id0013;id0014

Retorno de cada linha consultada
Retorno	Descrição
SMS agendado na plataforma Zenvia para envio em data e hora futura (ainda não enviado à operadora).
100 – Message queued	SMS aguardando envio.
SMS entregue com sucesso na operadora de destino.
110 – Message sent to operator	Ainda aguardando informações detalhadas da operadora.
111 – Message reception unavailable	Sem informação – operadora não retornou informações detalhadas sobre o SMS.
120 – Message received by mobile	Recebido – operadora confirma o recebimento pelo celular de destino.
140 – Mobile number not covered	Não recebido – operadora confirma o não recebimento do SMS pelo celular de destino
150 – Message expired in operator
160 – Operator network error
161 – Message rejected by operator
162 – Message cancelled or blocked by operator
170 – Bad message
171 – Bad number
SMS não enviado à operadora – SMS registrado na plataforma Zenvia, porém bloqueado por nossas ferramentas de inteligência de envio.
130 – Message blocked	Celular destinatário inválido (número não existe).
131 – Message blocked by predictive cleansing	Celular destinatário bloqueado por nosso exclusivo algoritmo de limpeza preditiva de base (para mais informações, consulte nossa equipe).
Erros na consulta
180 – Message ID not found	Não foi encontrado SMS com o ID fornecido como parâmetro.
190 – Unknown error	Erro desconhecido. Por favor, contate nosso suporte.
Erros gerais
900 – Authentication error	Erro de autenticação. Verifique os parâmetros “account” e “code”.
990 – account limit reached	O limite de consultas de sua conta à API foi atingido. Contate nosso suporte para verificação/liberação.
998 – Wrong operation requested	Operação de chamada inexistente. Verifique o parâmetro “dispatch” conforme tabela acima.
999 – Unknown error	Erro desconhecido. Por favor, contate nosso suporte.

The post Consultado de status de múltiplos SMS – HTTP appeared first on Você está acessando a área Zenvia Desenvolvedores.

Consulta de status de SMS único – HTTP

admin — Wed, 17 Oct 2012 18:12:04 +0000

Descrição

Consultar status de um SMS registrado na plataforma. Para realizar a consulta, é necessário que tenha sido utilizado o Identificador (Id) no momento do envio.
O retorno é uma linha de texto contendo o resultado da operação.
Importante: a consulta a um SMS fica disponível por até 24 horas após seu envio. Após esse período, será retornado “180 – message Id not found”.
[HTTP]

[SISTEMA CLIENTE] ←→[ZENVIA]

Parâmetros de entrada
Parâmetro	Obrigatório	Formato	Descrição
Account	Sim	String (20)	Nome da conta utilizada pelo cliente.
Code	Sim	String (20)	Senha de integração da conta.
Dispatch	Sim	Nome da operação(check)	Deve conter o valor check, indicando a consulta de status de um SMS.
Id	Sim	String (50)	Identificador único do SMS a ser consultado.

Retorno de cada linha consultada
Retorno	Descrição
SMS agendado na plataforma Zenvia para envio em data e hora futura (ainda não enviado à operadora).
100 – Message queued	SMS aguardando envio.
SMS entregue com sucesso na operadora de destino.
110 – Message sent to operator	Ainda aguardando informações detalhadas da operadora.
111 – Message reception unavailable	Sem informação – operadora não retornou informações detalhadas sobre o SMS.
120 – Message received by mobile	Recebido – operadora confirma o recebimento pelo celular de destino.
140 – Mobile number not covered	Não recebido – operadora confirma o não recebimento do SMS pelo celular de destino
150 – Message expired in operator
160 – Operator network error
161 – Message rejected by operator
162 – Message cancelled or blocked by operator
170 – Bad message
171 – Bad number
SMS não enviado à operadora – SMS registrado na plataforma Zenvia, porém bloqueado por nossas ferramentas de inteligência de envio.
130 – Message blocked	Celular destinatário inválido (número não existe).
131 – Message blocked by predictive cleansing	Celular destinatário bloqueado por nosso exclusivo algoritmo de limpeza preditiva de base (para mais informações, consulte nossa equipe).
Erros na consulta
180 – Message Id not found	Não foi encontrado SMS com o Id fornecido como parâmetro.
190 – Unknown error	Erro desconhecido. Por favor, contate nosso suporte.
Erros gerais
900 – Authentication error	Erro de autenticação. Verifique os parâmetros “account” e “code”.
990 – account limit reached	O limite de consultas de sua conta à API foi atingido. Contate nosso suporte para verificação/liberação.
998 – Wrong operation requested	Operação de chamada inexistente. Verifique o parâmetro “dispatch” conforme tabela acima.
999 – Unknown error	Erro desconhecido. Por favor, contate nosso suporte.

The post Consulta de status de SMS único – HTTP appeared first on Você está acessando a área Zenvia Desenvolvedores.

Envio múltiplo de SMS – HTTP

admin — Wed, 17 Oct 2012 17:12:30 +0000

Descrição

Enviar, em uma mesma chamada, até 10 mil SMS para múltiplos destinatários.
A lista de destinatários pode ser enviada de duas formas: como uma variável HTTP POST ou como um arquivo em um formulário HTML. Veja a seguir.

[SISTEMA CLIENTE] ←→[ZENVIA]
→ no retorno, identificar linha geral e específica de cada SMS.

Parâmetros de entrada
Parâmetro	Obrigatório	Formato	Descrição
Account	Sim	String (20)	Nome da conta utilizada pelo cliente.
Code	Sim	String (20)	Senha de integração da conta.
Dispatch	Sim	Nome da operação (sendMultiple)	Deve conter o valor sendMultiple.
Type	Sim	A, B, C, D, E	Layout do arquivo ou lista enviado no parâmetro “file” ou “list” (ver os formatos de layout no quadro a seguir).
CallbackOption	Não	0 – nenhuma resposta (padrão) 1 – envia o status final da mensagem (recomendado) 2 – envia status intermediários e final da mensagem	Opção para habilitar a notificação do status de cada SMS ao sistema do cliente, em uma URL de retorno personalizada. Obs.: para habilitar o retorno de status, é preciso utilizar layouts que contenham o parâmetro ID para cada SMS e configurar uma URL de retorno na conta utilizada.
File	Não	Arquivo csv	Arquivo em formato csv, de acordo com os layouts descritos no quadro a seguir.
List	Não	String csv	String em formato csv, de acordo com os layouts descritos no quadro a seguir.

Quadro: layout

Layout	Formato da linha
A	to;msg
B	to;msg;from
C	to;msg;id
D	to;msg;id;from
E	to;msg;id;from;schedule

O conjunto de linhas para envio pode ser enviado por uma lista ou por um arquivo de formulário HTML.
Os parâmetros a serem enviados em cada linha são:

Parâmetro	Obrigatório	Formato	Descrição
To	Sim	código de país + código de área + número (até 15 dígitos)	Celular de destino. Exemplo: 555199887766.
Msg	Sim	String(150)	Texto do SMS. Junto com o parâmetro “from”, deve ter no máximo 150 caracteres (140 para destinatários Nextel).
Id	Não	String(50)	Identificador único para o SMS.
From	Não	String(20)	Nome do remetente. Se não informado, utiliza-se o remetente-padrão da conta.
Schedule	Não	dd/mm/aaaa hh:mm:ss	Detalhes ou observações extras.

Exemplo de linhas no layout E

555199887766;Mensagem de teste 1;id0001; XPTO Ltda;01/01/2012 15:00:00
5511978871234;Mensagem de teste 2;id0002; XPTO Ltda;01/01/2012 15:10:00

O retorno tem a seguinte estrutura:

Linha 1: retorno da chamada
Demais linhas: um linha para cada SMS enviado

A resposta deve ser interpretada em duas partes: a primeira linha traz o retorno geral da chamada; as demais linhas trazem o retorno para cada SMS da lista enviada.

Retorno da chamada
Retorno	Descrição
Sucesso na chamada
200 – Messages sent	Requisição aceita pela API. Verifique, nas linhas seguintes, o retorno específico de cada SMS enviado.
Envio parcial
210 – Messages scheduled but account limit reached – please contact support	Durante o envio, o limite de créditos de sua conta foi atingido. Contate nosso suporte para verificação/liberação.
Erro no arquivo
240 – File empty of not sent	Arquivo vazio ou não identificado. Verifique o parâmetro "file", conforme tabela acima.
241 – File too large	Arquivo muito grande (mais de 1 Mbyte). Verifique o parâmetro "file", conforme tabela acima.
242 – File read error	Arquivo corrompido ou mal formatado. Verifique o parâmetro "file", conforme tabela acima.
Erros gerais
900 – Authentication error	Erro de autenticação. Verifique os parâmetros "account" e "code".
990 – account limit reached	O limite de créditos de sua conta foi atingido. Contate nosso suporte para verificação/liberação.
998 – Wrong operation requested	Operação de chamada inexistente. Verifique o parâmetro "dispatch", conforme tabela acima.
999 – Unknown error	Erro desconhecido. Por favor, contate nosso suporte.

Retorno de cada SMS da lista de envio
Retorno	Descrição
Envio com sucesso
000 – Message sent	SMS enviado com sucesso
Erro no envio do SMS
010 – Empty message content	Conteúdo do SMS vazio. Verifique parâmetro "msg".
011 – Message body invalid	Conteúdo do SMS inválido. Verifique o parâmetro "msg".
012 – Message content overflow	Conteúdo do SMS muito longo. Verifique se o tamanho dos parâmetros "msg" e "from" juntos não ultrapassam 150 caracteres.
013 – Incorrect or incomplete ‘to’ mobile number	Celular destinatário está incompleto ou inválido. Verifique o formato do parâmetro "to", conforme tabela acima.
014 – Empty ‘to’ mobile number	Celular destinatário vazio. Verifique o formato do parâmetro "to", conforme tabela acima.
015 – Scheduling date invalid or incorrect	Data de agendamento mal formatada. Verifique o formato do parâmetro "schedule", conforme tabela acima.
016 – ID overflow	Identificador com tamanho maior que o limite máximo. Verifique o parâmetro "id", conforme tabela acima.
080 – Message with same ID already sent	Identificador do SMS já foi utilizado nas últimas 24 horas.
Erros gerais
240 – File empty of not sent	Arquivo vazio ou não identificado. Verifique o parâmetro "file", conforme tabela acima.
241 – File too large	Arquivo muito grande (mais de 1 Mbyte). Verifique o parâmetro "file", conforme tabela acima.
242 – File read error	Arquivo corrompido ou mal formatado. Verifique o parâmetro "file", conforme tabela acima.
Erros gerais
900 – Authentication error	Erro de autenticação. Verifique os parâmetros "account" e "code".
990 – account limit reached	O limite de créditos de sua conta foi atingido. Contate nosso suporte para verificação/liberação.
998 – Wrong operation requested	Operação de chamada inexistente. Verifique o parâmetro "dispatch", conforme tabela acima.
999 – Unknown error	Erro desconhecido. Por favor, contate nosso suporte.

The post Envio múltiplo de SMS – HTTP appeared first on Você está acessando a área Zenvia Desenvolvedores.

Envio de SMS único – HTTP – WebService

admin — Tue, 16 Oct 2012 14:45:36 +0000

Descrição

Enviar uma mensagem SMS para um único celular de destino.
[HTTP | WebService]

[SISTEMA CLIENTE] ←→[ZENVIA]

Parâmetros de entrada
Parâmetro	Obrigatório	Formato	Descrição
Account	Sim	String (20)	Nome da conta utilizada pelo cliente.
Code	Sim	String (20)	Senha de integração da conta.
Dispatch	Sim	Nome da operação(send)	Deve conter o valor send, indicando o envio de um SMS.
From	Não	String (20)	Nome do remetente. Se não informado, utiliza-se o remetente-padrão da conta.
To	Sim	código de país + código de área + número (até 15 dígitos)	Celular de destino. Exemplo: 555199887766.
Msg	Sim	String (150)	Texto do SMS. Junto com o parâmetro “from”, deve ter no máximo 150 caracteres (140 para destinatários Nextel).
Schedule	Não	dd/mm/aaaa hh:mm:ss	Detalhes ou observações extras.
Id	Não	String (50)	Identificador único para o SMS.
CallbackOption	Não	0 – nenhuma resposta (padrão) 1 – envia o status final da mensagem (recomendado) 2 – envia status intermediários e final da mensagem	Opção para habilitar a notificação do status do SMS ao sistema do cliente, em uma URL de retorno personalizada. Obs.: para habilitar o retorno de status, é preciso utilizar o parâmetro ID e configurar uma URL de retorno na conta utilizada.

Retorno da chamada
Retorno	Descrição
Envio com sucesso
000 – Message sent	SMS enviado com sucesso
Erro no envio do SMS
010 – Empty message content	Conteúdo do SMS vazio. Verifique parâmetro “msg”.
012 – Message content overflow	Conteúdo do SMS muito longo. Verifique se o tamanho dos parâmetros “msg” e “from” juntos não ultrapassam 150 caracteres.
013 – Incorrect or incomplete ‘to’ mobile number	Celular destinatário está incompleto ou inválido. Verifique o formato do parâmetro “to”, conforme tabela acima.
014 – Empty ‘to’ mobile number	Celular destinatário vazio. Verifique o formato do parâmetro “to”, conforme tabela acima.
015 – Scheduling date invalid or incorrect	Data de agendamento mal formatada. Verifique o formato do parâmetro “schedule”, conforme tabela acima.
016 – ID overflow	Identificador com tamanho maior que o limite máximo. Verifique o parâmetro “id”, conforme tabela acima.
080 – Message with same ID already sent	Identificador do SMS já foi utilizado nas últimas 24 horas.
010 – Empty message content	Conteúdo do SMS vazio. Verifique parâmetro “msg”.
Erros gerais
900 – Authentication error	Erro de autenticação. Verifique os parâmetros “account” e “code”.
990 – account limit reached	O limite de créditos de sua conta foi atingido. Contate nosso suporte para verificação/liberação.
998 – Wrong operation requested	Operação de chamada inexistente. Verifique o parâmetro “dispatch”, conforme tabela acima.
999 – Unknown error	Erro desconhecido. Por favor, contate nosso suporte.

The post Envio de SMS único – HTTP – WebService appeared first on Você está acessando a área Zenvia Desenvolvedores.