Serviço responsável pelo envio de mensagens por SMS. Esta documentação tem como objetivo instruir sobre a utilização da mesma, demonstrando como configurar e realizar o envio de mensagens.
Esta documentação tem como objetivo instruir sobre a utilização da mesma, demonstrando como realizar o envio de mensagens.
Documentação de Uso da API de SMS.
Para utilizar os Micro Serviços Code7, é necessário um Login/ Senha fornecido pela equipa de TI. Ao realizar a validação de Login, em caso de positivo o mesmo gera um token de acesso, os login são de uso restrito e podem ser usados para todos os Micro Serviços na qual ele tem acesso.
Todas as requisições POST - Json para o API devem conter o campo de token no primeiro campo do JSON (com exceção dos métodos de Login/ Consulta Token). Todas as requisições GET - Json para o API devem conter o campo de token na URL de solicitação (com exceção dos métodos de Login/ Consulta Token).
O token de acesso tem validade de no máximo 6 horas, após este periodo, deve-se logar novamente para gerar um novo Token.
POST - https://apisms.code7.com/Messaging/Login
Exemplo de JSON de Login, substitua as informações abaixo por suas credenciais.
{
"login": "code7.xyz",
"password": "12345678"
}
Método genérico de envio de mensagens para SMS. Todos os envios estarão atrelados a uma campanha. Estes envios serão realizados pelo método Send.
Método utilizado para enviar mensagens de SMS.
POST - https://apisms.code7.com/Messaging/Send
Para envios em massa, utilizar somente até no máximo 1000 registros por POST, para Lotes maiores, quebrar o lote de envio em duas ou mais postagens de 1000 conforme a quantidade que deseja enviar.
| Campo | Tipo | Descrição | Parâmetro | Obrigatório |
|---|---|---|---|---|
| token | string | Token de retorno obtido após o Login na Api. | Json | |
| codCampaign | integer | Código da campanha relacionado ao envio das mensagens. | Json | |
| ID | string | Id de envio de mensagem enviado para identificação, caso não será enviado, será gerado um id randômico. | Json | |
| Telephone | string | Número do telefone que receberá a mensagem. | Json | |
| Message | string | Texto da mensagem simples. | Json |
Campo 'Telephone'
Deve ser informado o número completo do telefone, portanto é necessário informar o DDI + Número de província caso exista (DDD) + Telefone.
Exemplo de Json de Envio para SMS, substitua as informações abaixo de token pelo token obtido no Login.
[
{
"token": "token",
"codCampaign": "1",
"Telephone": "5511980125654",
"Message": "Envio Teste"
}
]
Método de Consulta do Status dos SMS.
Para cada SMS enviado é possível consultar o status da mensagen, se deu sucesso ou erro ao enviar.
POST - https://apiwp02.code7.com/Consultas/Status/
Utilizar somente até no máximo 1000 registros por POST, para Lotes maiores, quebrar o lote de consulta em duas ou mais postagens de 1000 conforme a quantidade que deseja consultar.
| Campo | Tipo | Descrição | Parâmetro | Obrigatório |
|---|---|---|---|---|
| Token | string | Token de retorno obtido após o Login na Api. | Json | |
| IdCampanha | string | ID da Campanha consultada. | Json | |
| TipoRetorno | integer | Flag de definição do tipo de retorno dos status. | Json | |
| URLCallBack | string | URL para efetuarmos o post de retorno do json dos status | Json | |
| EmailCallBack | string | E-Mail para efetuarmos o post de retorno do json dos status | Json | |
| ListaIDsEnvio | string | Identificador do Envio. | Json |
Dependendo do tipo de retorno informado, disponibilizaremos o JSon em um canal diferente seguindo a lista abaixo:
| ID | Tipo | Descrição |
|---|---|---|
| 1 | HTTP | Retornaremos o JSon na mesma requisição. |
| 2 | Post URL | Faremos o post do JSon em uma URL informada no parametro URLCallBack |
| 3 | Enviaremos o JSon no E-Mail informado no parametro EmailCallBack |
Os status somente ficam disponíveis para consulta no período de 90 dias.
Lista de possíveis Status retornados:
| Status | Status Message | Descrição |
|---|---|---|
| 00 | Received | SMS Recebido e em processamento |
| 02 | Sent | SMS Enviado para o destinatário |
| 03 | Delivered | SMS Entregue no celular do destinatário |
| 04 | Not Received | SMS não entregue - Possível falha no envio |
| 05 | Blocked | SMS bloqueado |
| 08 | Blocked | SMS bloqueado |
| 09 | Blocked | SMS bloqueado |
Exemplo de Json, substitua as informações abaixo de token pelo token obtido no Login.
{
"token": "token",
"IdCampanha": "2564",
"TipoRetorno": "1",
"URLCallBack": "",
"EmailCallBack": "",
"ListaIDsEnvio": [
{
"IdEnvio": "123456"
},
{
"IdEnvio": "1234567"
},
{
"IdEnvio": "1234568"
}
]
}
[
{
"id": "123456",
"codCampaign": "2564",
"Telephone": "55119574852136",
"Date": "2021-07-22 08:00:25",
"status": "03",
"statusDetail": "Delivered",
"type": "SMSStatus",
},
{
"id": "1234567",
"codCampaign": "2564",
"Telephone": "5511963294856",
"Date": "2021-07-22 08:01:12",
"status": "04",
"statusDetail": "Not Received",
"type": "SMSStatus",
},
{
"id": "1234568",
"codCampaign": "2564",
"Telephone": "5511996548123",
"Date": "2021-07-22 08:01:21",
"status": "02",
"statusDetail": "Sent",
"type": "SMSStatus",
}
]
Método de Consulta das respostas dos SMS.
É possível consultar as respostas de uma determinada campanha dentro de um período.
POST - https://apiwp02.code7.com/Consultas/Resposta/
A consulta somente será possível dentro do período de 90 dias.
| Campo | Tipo | Descrição | Parâmetro | Obrigatório |
|---|---|---|---|---|
| Token | string | Token de retorno obtido após o Login na Api. | Json | |
| IdCampanha | string | ID da Campanha consultada. | Json | |
| TipoRetorno | integer | Flag de definição do tipo de retorno das respostas. | Json | |
| URLCallBack | string | URL para efetuarmos o post de retorno do json das respostas | Json | |
| EmailCallBack | string | E-Mail para efetuarmos o post de retorno do json das respostas | Json | |
| dataInicio | string | Data de início do período da consulta. | Json | |
| dataFinal | string | Data final do período da consulta. | Json |
Dependendo do tipo de retorno informado, disponibilizaremos o JSon em um canal diferente seguindo a lista abaixo:
| ID | Tipo | Descrição |
|---|---|---|
| 1 | HTTP | Retornaremos o JSon na mesma requisição. |
| 2 | Post URL | Faremos o post do JSon em uma URL informada no parametro URLCallBack |
| 3 | Enviaremos o JSon no E-Mail informado no parametro EmailCallBack |
Exemplo de Json, substitua as informações abaixo de token pelo token obtido no Login.
{
"token": "token",
"IdCampanha": "2564",
"TipoRetorno": "1",
"URLCallBack": "",
"EmailCallBack": "",
"dataInicio": "2021-08-24 16:00",
"dataFinal": "2021-08-24 16:30"
}
[
{
"IdCampanha": "2564",
"Telefone": "55119574852136",
"DataRecebimento": "2021-08-24 16:15:25",
"Mensagem": "OK",
"DataDisparo": "2021-08-24 16:00:25"
},
{
"IdCampanha": "2564",
"Telefone": "5511986452485",
"DataRecebimento": "2021-08-24 16:15:25",
"Mensagem": "Quero Acordo",
"DataDisparo": "2021-08-24 16:00:25"
},
{
"IdCampanha": "2564",
"Telefone": "55119574852136",
"DataRecebimento": "2021-08-24 16:15:25",
"Mensagem": "1",
"DataDisparo": "2021-08-24 16:00:25"
}
]
As atualizações são enviadas através de Webhook.
Após criar o hook e enviar sua URL de Webhook as funcionalidades de callback estão ativas.
Para identificar o retorno da mensagem, é necessário criar um webhook em um endereço configurado, assim o mesmo irá enviar o retorno da mensagem quando um evento acontece através de um JSon.
| Campo | Tipo | Descrição |
|---|---|---|
| id | string | ID único de identificação. |
| codCampaign | string | cod. da campanha atrelada à mensagem enviada. |
| Telephone | string | Número do Telefone enviado. |
| Date | string | Data do evento. |
| message | string | Mensagem respondida pelo número enviado/ url de Media respondida pelo número. |
| type | string | Tipo da mensagem envida. |
Exemplo de Json de resposta SMS.
{
'id': '3AA05321A799714AADE8',
'codCampaign': '1',
'Telephone': '551199999999',
'Date': '2018-05-17 19:38:26',
'message': 'Teste',
'type': 'SMSText'
}
Para identificar o retorno do status, é necessário criar um webhook em um endereço configurado, assim o mesmo iria enviar o retorno da mensagem quando um evento acontece através de um JSon.
| Campo | Tipo | Descrição |
|---|---|---|
| id | string | ID único de identificação. |
| codCampaign | string | cod. da campanha atrelada à mensagem enviada. |
| Telephone | string | Número do Telefone enviado. |
| Date | string | Data do evento. |
| status | string | Status de envio. |
| type | string | Tipo do status envida. |
Exemplo de Json de status para SMS.
{
'id': '3AA05321A799714AADE8',
'codCampaign': '1',
'Telephone': '551199999999',
'Date': '2018-05-17 19:38:26',
'status': 'delivered',
'type': 'SMSStatus'
}
Uma listagem de erros que podem ser retornados da API.
Ao realizar um POST com um JSON valido na API, o retorno será 200 contendo o Json de retorno do POST no Body. Em caso de Json inválido, a API vai retornar Status 400 (Bad Resquest) e no Body informar qual o possível erro do JSon, segue abaixo lista de erros e orientações para o mesmo.
| Cod.Erro | Erro | Orientação |
|---|---|---|
| 1 | Invalid transference format | Json fora do formato especificado na documentação, verifique o exemplo. |
| 2 | Login not found | Login não encontrado, verifiquei o Login informado ou entre em contato com a Code7. |
| 3 | Invalid password | Password invalido, verifiquei o Login informado ou entre em contato com a Code7. |
| 4 | Invalid Token | Token informado é invalido ou já foi renovado, informe o token atual ou refaça o Login. |
| 5 | Expired Token | Token informado expirou e é necessário nova validação no Login. |
| 6 | Enter the Token field | Informe o Token obtido no Login dentro da assinatura Json. |
| 7 | Please report a valid campaign | Campanha atual informada não existe, verifique. |
| 8 | Please report a valid date | Campanha atual informada não existe, verifique. |
| 10 | Please report a valid Id | ID no formato invalido. |
| 11 | Description of (Lote) already registered. | Descrição do lote informado não esta registrado (Erro disponível somente para API MAIL). |
| 12 | Description of (html_pach) already registered. | Descrição do template informado não esta registrado (Erro disponível somente para API MAIL). |
| 13 | Please report a valid namespace | Namespace informada não existe, verifique. (Erro disponível somente para API MENSAGERIA - WHATSAPP). |
| 14 | Number of fields reported differently than expected for codNamespace | Numero de fields informado, esta diferente do numero esperado pelo Namespace. |
| 16 | Please report a valid IdMedia | IdMedia invalido ou não cadastrado no Upload. |
| 17 | Please report a valid NEW campaign | Nova campanha informada não existe, verifique. |
| 18 | Informed campaign does not belong to a Whatsapp campaign | Campanha atual informada não pertence a uma campanha Whatsapp, somente é possível transferir entre campanhas de Whatsapp. |
| 19 | NEW Campaign reported does not belong to a Whatsapp campaign | Nova Campanha informada não pertence a uma campanha Whatsapp, somente é possível transferir entre campanhas de Whatsapp. |
| 20 | NEW Campaign with no registered callback url | Nova campanha não tem Url de callback cadastrada. |
| 21 | Information not found on the number reported for transfer. | Número de telefone informada não existe para a campanha atual.. |
| 22 | Campaign download canceled due to error in new campaign webhook. | Não foi possível concluir a transferência devido a problemas no webhook ao receber o histórico. |
| 24 | Invalid destination | Destino de operação e Chat não informado (Erro disponível somente para envio de CHAT sem Whatsapp). |
| 25 | Destination without registered URL | Destino de operação e Chat não cadastrado (Erro disponível somente para envio de CHAT sem Whatsapp). |