Integração de API SMS

Guia de integração com API de SMS Comtele

INTRODUÇÃO

ANTES DE COMEÇAR

A API Comtele funciona nos padrões REST, podendo então conter métodos GET, POST, PUT e DELETE.

O QUE É REST?

Um conjunto de operações bem definidas que se aplicam a todos os recursos de informação: HTTP em si define um pequeno conjunto de operações, as mais importantes são POST, GET, PUT e DELETE. Com frequência estas operações são combinadas com operações CRUD para a persistência de dados, onde POST não se encaixa exatamente neste esquema.
http://pt.wikipedia.org/wiki/REST

CHAVE DE INTERAÇÃO DA API

Para ter acesso a sua chave de utilização da API é necessário acessar a plataforma de envio através do endereço https://sms.comtele.com.br, aceitar os termos e condições de uso e localizar a chave na tela inicial do sistema no menu “Informações de Desenvolvedor”

EXEMPLOS DE INTEGRAÇÃO

REPOSITÓRIO NO GITHUB

Veja todos os projetos em nosso repositório no GitHub

TEM UM PROJETO E QUER COMPARTILHAR
COM NOSSA COMUNIDADE DEV ?

Clique aqui

FLUXOS DA API

ENVIO DE MENSAGENS

SUA APLICAÇÃO
COMTELE
TELEFONE

O MESMO FLUXO É APLICADO PARA OS SEGUINTES MÉTODOS:

ENVIO DE MENSAGEM

Utilizado para enviar mensagem para os destinatários especificados.

URL: https://sms.comtele.com.br/api/{sua_chave}/sendmessage?sender={remetente}&receivers={destinatarios}&content={conteudo}
MÉTODO: HTTPS - POST

PARÂMETROS:
destinatários. Tamanho máximo de 32 caracteres.
receivers: Destinatários que receberam a mensagem, pode ser separado por vírgula. Obrigatóriamente deve possuir o formato DDD+Número
content: Conteúdo da mensagem que será enviada. Tamanho máximo de 2048 caracteres.

AGENDAMENTO DE MENSAGEM

Agendar mensagem para enviar aos destinatários na data especificada.

URL: https://sms.comtele.com.br/api/{sua_chave}/schedulemessage?sender={remetente}&receivers={destinatarios}&content={conteudo}&date={data_envio}
MÉTODO: HTTPS - POST

PARÂMETROS:
sender: Remetente do envio das mensagens, será utilizado apenas para organização de relatórios, o conteúdo deste parâmetro não será mostrado aos destinatários. Tamanho máximo de 32 caracteres.
receivers: Destinatários que receberam a mensagem, pode ser separado por vírgula. Obrigatóriamente deve possuir o formato DDD+Número.
content: Conteúdo da mensagem que será enviada. Tamanho máximo de 2048 caracteres.
date: Data em que a mensagem será enviada aos destinatários. Padrão: yyyy-MM-dd HH:mm:ss.

ENVIO DE MENSAGEM CONTEXTUAL

Enviar mensagem com regra de contexto para os destinatários especificados, possibilitando interação com o destinatário de acordo com determinadas respostas. A regra de contexto deve ser previamente cadastrada no painel https://sms.comtele.com.br para ser utilizada via API.

URL: https://sms.comtele.com.br/api/[sua_chave]/sendmessage?sender=[remetente]&receivers=[destinatarios]&content=[conteudo]&namecontextrule=[nome_da_regra]
MÉTODO: HTTPS - POST

PARÂMETROS:
sender: Remetente do envio das mensagens, será utilizado apenas para organização de relatórios, o conteúdo deste parâmetro não será mostrado aos destinatários. Tamanho máximo de 32 caracteres.
receivers: Destinatários que receberam a mensagem, pode ser separado por vírgula. Obrigatóriamente deve possuir o formato DDD+Número.
content: Conteúdo da mensagem que será enviada. Tamanho máximo de 2048 caracteres.
namecontextrule: Nome da regra de contexto préviamente cadastrada no painel que deseja usar.

AGENDAMENTO DE MENSAGEM CONTEXTUAL

Agendar mensagem com regra de contexto para enviar aos destinatários na data especificada.

URL: https://sms.comtele.com.br/api/[sua_chave]/schedulemessage?sender=[remetente]&receivers=[destinatarios]&content=[conteudo]&date=[data_envio]&namecontextrule=[nome_da_regra]
MÉTODO: HTTPS - POST

PARÂMETROS:
sender: Remetente do envio das mensagens, será utilizado apenas para organização de relatórios, o conteúdo deste parâmetro não será mostrado aos destinatários. Tamanho máximo de 32 caracteres.
receivers: Destinatários que receberam a mensagem, pode ser separado por vírgula. Obrigatóriamente deve possuir o formato DDD+Número.
content: Conteúdo da mensagem que será enviada. Tamanho máximo de 2048 caracteres.
date: Data em que a mensagem será enviada aos destinatários. Padrão: yyyy-MM-dd HH:mm:ss.
namecontextrule: Nome da regra de contexto préviamente cadastrada no painel que deseja usar.

REQUISIÇÃO DE RELATÓRIOS

SUA APLICAÇÃO
COMTELE

O MESMO FLUXO É APLICADO PARA OS SEGUINTES MÉTODOS:

RELATÓRIO CONSOLIDADO

Relatório com os dados consolidados dos status envios de mensagens.

NOTA: Este método possui proteção anti-spam e apenas pode ser requisitado uma vez a cada 30 segundos

URL: https://sms.comtele.com.br/Api/{sua_chave}/consolidatedreport?startDate={data_inicial}&endDate={data_final}&group={true_false}
MÉTODO: HTTPS - GET

PARÂMETROS:
StartDate: Data inicial para efetuar a busca do relatório. Padrão: yyyy-MM-dd HH:mm:ss.
EndDate: Data final para efetuar a busca do relatório. Padrão: yyyy-MM-dd HH:mm:ss.
Group: Este parâmetro é opcional. Quando “true” agrupa o relatório por dia, quando “false” agrupa o relatório por mês.

PARÂMETROS RETORNADOS:
Accepted: Total de mensagens que foram aceitas para envio pelo sistema.
Date: Data em que as mensagens foram agrupadas.
Delivered: Total de mensagens que foram entregues.
Expired: Total de mensagens expiradas.
Rejected: Total de mensagens rejeitadas pelo sistema.
Reply: Total de respostas.
Total: Total geral de todos os status.
Undelivered: Total de mensagens não entregues.

RELATÓRIO DETALHADO

Relatório com informações de cada mensagem e seu status de envio.

NOTA: Este método possui proteção anti-spam e apenas pode ser requisitado uma vez a cada 30 segundos

URL: https://sms.comtele.com.br/api/{sua_chave}/detailedreport?startDate={data_inicial}&endDate={data_final}&delivered=[all_true_false]
MÉTODO: HTTPS - GET

PARÂMETROS:
StartDate: Data inicial para efetuar a busca do relatório. Padrão: yyyy-MM-dd HH:mm:ss.
EndDate: Data final para efetuar a busca do relatório. Padrão: yyyy-MM-dd HH:mm:ss.
Delivered: Este parâmetro é opcional, o valor "all" será assumido caso o parâmetro não seja informado. Quando "true" o relatório retornará apenas mensagens entregues, quando "false" o reltário retornará mensagens com algum tipo de erro. Para visualizar todas as suas mensagens, utilize o valor "all".

PARÂMETROS RETORNADOS:
Content: Conteúdo da mensagem.
DlrStatus: Detalhe do status da mensagem, nos padrões DLR.

Delivered: Mensagem entregue.
Undelivered: Mensagem não entregue.
Rejected: Requisição não passou em regras de validação.
Expired: Mensagem não entregue pois expirou o período de entrega.
Accepted: Requisição aceita, passou em regras de validação.

Receiver: Número para o qual a mensagem foi enviada.
Status: Status da mensagem simplificado.
Status: Status de sucesso ou erro da requisição, nos padrões DLR.

Processed: Requisição aceita, passou em regras de validação.
Delivered: Mensagem entregue.
Error: Requisição pode não ter passado em regras de validação ou pode ter passado e não foi entregue por ter expirado ou gerado erro no envio.

SystemMessage: Mensagem de retorno do sistema.
Sender: Remetente da mensagem que foi especificado no momento do envio.

RELATÓRIO DE RESPOSTAS

Relatório com informações das respostas enviadas pelos destinatários.

NOTA: Este método possui proteção anti-spam e apenas pode ser requisitado uma vez a cada 30 segundos

URL: https://sms.comtele.com.br/api/{sua_chave}/replyreport?startDate={data_inicial}&endDate={data_final}&sender={remetente}&unread={true_false}
MÉTODO: HTTPS - GET

PARÂMETROS:
startDate: Data inicial para efetuar a busca do relatório. Padrão: yyyy-MM-dd HH:mm:ss.
endDate: Data final para efetuar a busca do relatório. Padrão: yyyy-MM-dd HH:mm:ss.
sender: Este parâmetro é opcional. Quando informado, irá trazer apenas as respostas enviadas por um número especifico. Quando omitido, irá trazer todas as respostas, para omitir o parâmetro retire todo o conteúdo “&sender={remetente}”.
unread: Este parâmetro é opcional, o valor “false” será assumido caso o parâmetro não seja informado. Quando “true” o relatório retornará apenas mensagens não lidas, quando “false” o reltário retornara mensagens lidas. Para visualizar todas as respostas utilize o parâmetro “all”.

PARÂMETROS RETORNADOS:
ReceivedContent: Conteúdo recebido na resposta da mensagem.
SentContent: Conteúdo original da mensagem.
Sender: Número que enviou a resposta.
ReceivedDate: Data de recebimento da resposta.

RELATÓRIO DE ENVIO CONTEXTUAL

Relatório com informações das mensagens enviadas com regra de contexto para os destinatários

NOTA: Este método possui proteção anti-spam e apenas pode ser requisitado uma vez a cada 30 segundos

URL: https://sms.comtele.com.br/api/[sua_chave]/ContextReport?startDate=[data_inicial]&endDate=[data_final]&sender=[remetente]&nameContextRule=[nome_da_regra]
MÉTODO: HTTPS - GET

PARÂMETROS:
startDate: Data inicial para efetuar a busca do relatório. Padrão: yyyy-MM-dd HH:mm:ss.
endDate: Data final para efetuar a busca do relatório. Padrão: yyyy-MM-dd HH:mm:ss.
sender: Este parâmetro é opcional. Quando informado, irá trazer apenas as respostas enviadas por um número especifico. Quando omitido, irá trazer todas as respostas, para omitir o parâmetro retire todo o conteúdo “&sender={remetente}”.
nameContextRule: Este parâmetro é opcional. Quando informado, irá trazer apenas as mensagens enviadas com uma regra de contextual especifica. Quando omitido, irá trazer todas as mensagens.

PARÂMETROS RETORNADOS:
Content: Conteúdo recebido na resposta da mensagem.
Sender: Número do remetente da mensagem.
NameContextRule: Data da mensagem.
ReceivedDate: Nome da Regra de Envio Contextual.
StatusMessage: Status da Mensagem.

RELATÓRIO DE RECARGAS

Histórico com todas a Recargas realizadas para uma conta expecífica.

URL: https://sms.comtele.com.br/api/[sua_chave]/accountbalancehistory?username=[usuario]
MÉTODO: HTTPS - GET

PARÂMETROS:
username: Login do usuário a ser consultado o histórico de recargas.

PARÂMETROS RETORNADOS:
Amount: Quantidade de créditos da transação.
Balance: Quantidade de créditos que o usuário ficou após a transação.
ExpiryDate: Validade dos créditos.
AssociadedUsername: Usuário que inseriu os créditos.

OUTROS MÉTODOS

ADICIONAR CRÉDITO PARA USUÁRIO

Utilizado para usuários de perfil conta master adicionar ou remover créditos para um determinado usuário de nível abaixo

URL: https://sms.comtele.com.br/api/{sua_chave}balance?username={usuario}&amount={quantidade}
MÉTODO: HTTPS - PUT

PARÂMETROS:
username: Login do usuário em que os créditos serão adicionados.
amount: Quantidade de créditos a serem adicionados.

OBTER SALDO DE CONTA

Utilizado para obter saldo de SMS disponível em conta.

URL: https://sms.comtele.com.br/api/{sua_chave}/balance
MÉTODO: HTTPS - GET

PARÂMETROS:
username: Login do usuário a ser consultado o histórico de recargas.

PARÂMETROS RETORNADOS:
int: Quantidade de créditos disponíveis na conta

OBTER LISTA DE USUÁRIOS

Obter lista com informações de usuários cadastrados.

URL: https://sms.comtele.com.br/api/{sua_chave}/account?username={usuario}
MÉTODO: HTTPS - GET

PARÂMETROS:
username: Este parâmetro é opcional, quando informado irá retornar o usuário especificado, quando omitido irá retornar uma lista com todos os usuários cadastrados.

PARÂMETROS RETORNADOS:
Balance: Saldo de SMS do usuário.
MultimediaBalance: Saldo de mensagens multimedia do usuário.
Connection: Data de último login do usuário.
LastBalanceHistory: Data de última recarga de crédito do usuário.
Password: Senha do usuário.
Username: Login do usuário.

ENVIO DE SMS POR ARQUIVO

CHAVE DE USUÁRIO

• Para ter acesso a sua chave de utilização é necessário acessar a plataforma de envio através do endereço https://sms.comtele.com.br, aceitar os termos e condições de uso e localizar a chave na tela inicial do sistema no menu “Informações de Desenvolvedor”

• Após isso, basta colar no local indicado

PASTA OUT

• A pasta OUT é onde será colocado os arquivos para envio

• Exemplo de Arquivo .ctlo

PASTA IN

• A pasta IN recebera as respostas

MODO DE ENVIO

• O arquivo para envio deve conter a extensão .ctlo (para envio imediato), .ctls (para envio agendado)

• Deve conter os Seguintes parâmetros (Para arquivos .ctlo)
Sender="remetente"
Receiver="destinatario (DDD)999999999 "
Content="conteudo"

• Deve conter os Seguintes parâmetros (Para arquivos .ctls)
Sender="remetente"
Receiver="destinatario (DDD)999999999 "
Content="conteudo"
Date="yyyy-MM-dd hh:mm:ss"

• Para fazer o envio, basta colar o arquivo na pasta OUT

FAÇA O DOWNLOAD

Download

Repositório GitHub