SMS-MT API HTTP GET

Versão: 3.00 Última Atualização: 31/05/2018


Índice

  1. Introdução
  2. Enviando mensagens via SMS (Envia SMS)
  3. Obtendo o saldo de créditos em conta
  4. Consultando envios realizados em um determinado período
  5. Enviando mensagens via SMS (SMS Follow)
  6. Obtendo o status de mensagens enviadas

1. Introdução

Seguindo a documentação presente nesta página, você irá conseguir integrar o seu sistema com o Gateway SMS do PitchWink! Para começar de pé direito, sugerimos que você leia os requerimentos, as notas importantes (onde comunicamos novidades e mudanças futuras) e as descrições de cada método. Desta forma, você irá ganhar tempo e conhecer a solução como um todo. Em caso de dúvida, estamos aqui para ajudá-lo! Acesse sua conta, crie um ticket de suporte e entre em contato conosco. Divirta-se integrando!

1.1. Requerimentos

É necessário ter acesso a “Credencial” e “Token” da sua conta para realizar a integração. Estes dados podem ser encontrados no menu de “Configurações”, opção “Dados de Integração”. Sugerimos que você também aproveite para adicionar o “Remetente do SMS”, o mesmo irá ajudar seus destinatários a saberem quem é o remetente das mensagens enviadas a eles.

1.2. Notas importantes

Esta é a versão atual da documentação. A mesma é similar a versão anterior com excessão do acréscimo do parâmetro Token.


2. Enviando mensagens via SMS (Envia SMS)

O EnviaSMS é o método que permite o envio de mensagens via SMS através do nosso Gateway. Mensagens com até 160 caracteres podem ser enviadas para qualquer país que o PitchWink possui cobertura. Caso deseje obter o ID da mensagem para saber o status de envio, utilize ao invés deste método, o método SMSFollow.

2.1. Parâmetros do EnviaSMS

Parâmetro Requerido? Formato Descrição
CREDENCIAL Sim A(40) Credencial da sua conta no PitchWink
TOKEN Sim A(6) Chave de acesso ao Gateway
PRINCIPAL_USER Não A(50) ou “” Controle interno do cliente
AUX_USER Não A(20) O valor atribuído a este parâmetro pode ser utilizado como referência em filtros, facilitando a identificação de mensagens específicas em relatórios criados por você a partir da plataforma
MOBILE Sim A(15) Número celular do destinatário em formato internacional. Exemplo para o Brasil: 5521999999999
SEND_PROJECT Não A(1) Se usa o remetente na mensagem. Possíveis opções:
S = SIM
N= NÃO
Y= YES
N= NO
MESSAGE Sim A(160) Conteúdo da mensagem a ser enviada via SMS.

2.2. Retornos do EnviaSMS

Código de Retorno Tipo Descrição
000 Sucesso Mensagem enviada com sucesso
X01 ou X02 Erro Um ou mais parâmetros com erro
001 Erro Credencial inválida
005 Erro MOBILE com formato inválido
007 Erro SEND_PROJECT com formato inválido
008 Erro MESSAGE ou MESSAGE + NOME_PROJETO com mais de 160 posições ou SMS concatenado com mais de 1000 posições
009 Erro Créditos insuficientes em conta
010 Erro Gateway SMS da conta bloqueado
012 Erro MOBILE correto, porém com crítica
013 Erro Conteúdo da mensagem inválido ou vazio
015 Erro País de destino sem cobertura
016 Erro MOBILE com código de área inválido
018 Erro MOBILE se encontra em lista negra
019 Erro TOKEN inválido
022 Erro Conta atingiu o limite de envio do dia

2.3. Chamada (HTTP ou HTTPS)

http://www.pw-api.com/sms/v_3_00/smspush/enviasms.aspx?Credencial=asasasasasasa&Token=8C971d&Principal_User=FF&Aux_User=F1&Mobile=552194797025&Send_Project=S&Message=testesmspushFF
Testando o exemplo acima no browser será retornado o código 001, pois a CREDENCIAL não existe. Favor substituir o conteúdo dos parâmetros, incluindo a CREDENCIAL da sua conta para obter o resultado desejado.

2.4. Exemplos do EnviaSMS

VB.NetPHPJSPDelphi 7.0
v_st_HTTPGET = "https://www.pw-api.com/sms/v_3_00/smspush/enviasms.aspx"
v_st_Parametros = "?" & _
"CREDENCIAL=" & Server.UrlEncode("XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX") & _
"&TOKEN=" & Server.UrlEncode("123456") & _
"&PRINCIPAL_USER=" & Server.UrlEncode("MP") & _
"&AUX_USER=" & Server.UrlEncode("USUÁRIOAUX") & _
"&MOBILE=" & Server.UrlEncode("5521999999999") & _
"&SEND_PROJECT=" & Server.UrlEncode("S") & _
"&MESSAGE=" & Server.UrlEncode("Mensagem de Teste")
' Montagem da URL de chamada
v_st_HTTPGET &= v_st_Parametros
Dim v_obj_Request As System.Net.HttpWebRequest = _
DirectCast(System.Net.WebRequest.Create(v_st_HTTPGET), _
System.Net.HttpWebRequest)
Dim v_st_Cod_Retorno As String
Dim v_obj_Response As System.Net.WebResponse = _
v_obj_Request.GetResponse()
If Not IsNothing(v_obj_Response) Then
Dim v_obj_IOStream As New _
System.IO.StreamReader(v_obj_Response.GetResponseStream())
v_st_Cod_Retorno = v_obj_IOStream.ReadToEnd()
v_obj_IOStream.Close()
' Retorna o v_st_Cod_Retorno no formato: 999
If v_st_Cod_Retorno.Equals("000") Then
' Mensagem enviada ao MobiPronto com sucesso
Else
' Tratar o resultado de acordo com a tabela
' de Códigos de Retorno do MobiPronto
End If
Else
' Algum erro na chamada HTTP GET
End If
<?php
        $credencial= URLEncode("XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"); //**Credencial da Conta 40 caracteres
        $token= URLEncode("123456"); //**Token da Conta 6 caracteres
        $principal = URLEncode("aaa");  //* SEU CODIGO PARA CONTROLE, não colocar e-mail
        $auxuser = URLEncode("AUX_USER"); //* SEU CODIGO PARA CONTROLE, não colocar e-mail
        $mobile= URLEncode("55XXNNNNNNNN"); //* Numero do telefone  FORMATO: PAÍS+DDD(DOIS DÍGITOS)+NÚMERO
        $sendproj = URLEncode("N"); //* S = Envia o SenderId antes da mensagem , N = Não envia o SenderId
        $msg="Teste para PHP."; // Mensagem
        $msg=mb_convert_encoding($msg, "UTF-8"); // Converte a mensagem para não ocorrer erros com caracteres semi-gráficos
        $msg = URLEncode($msg); 
        $response =fopen("https://www.pw-api.com/sms/v_3_00/smspush/enviasms.aspx?CREDENCIAL=".$credencial."& TOKEN=".$token."&PRINCIPAL_USER=".$principal."&AUX_USER=".$auxuser."&MOBILE=".$mobile."&SEND_PROJECT=".$sendproj."&MESSAGE=".$msg,"r");
        $status_code= fgets($response,4);
            echo "Codigo retornando do fopen=";
            echo $status_code;
        ?>
<%@ page import="java.net.*, java.io.*" %>
<%
String Credential = URLEncoder.encode("XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
String Token = URLEncoder.encode("123456");
String MainUser = URLEncoder.encode("SEUPROJETO"); 
String AuxUser = URLEncoder.encode("AUX1");
String Mobile = URLEncoder.encode("552199999999");
char SendProject = URLEncoder.encode("S");
String Msg = "Seu Primeiro Envio de SMS via Java usado o Gateway Mobi Pronto.";
Msg = URLEncoder.encode(Msg, "UTF-8");
String connection =
"https://www.pw-api.com/sms/v_3_00/smspush/enviasms.aspx?CREDENCIAL="+
Credential + "&TOKEN="+ Token +"&PRINCIPAL_USER="+ MainUser +"&AUX_USER="+ AuxUser +"&MOBILE="+ Mobile
+"&SEND_PROJECT="+ SendProject +"&MESSAGE="+ Msg;
URL url = new URL(connection);
InputStream input = url.openStream();
byte[] b = new byte[4];
input.read(b, 0, b.length);
String RetornoMPG = new String(b);
out.println("Retorno = " + RetornoMPG);
%>
procedure TMain.Button1Click(Sender: TObject);
var
sret: String;
begin
IdHTTP1.Host := 'mobipronto.com';
IdHTTP1.Port := 80;
Memo1.Lines.Text := IdHTTP1.Get('
https://www.pw-api.com.com/sms/v_3_00/smspush/enviasms.aspx?
CREDENCIAL=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&TOKEN=123456
&PRINCIPAL_USER=SEUPROJETO
&AUX_USER=AUX1
&MOBILE=552199999999
&SEND_PROJECT=S
&MESSAGE=Teste SMS');
end;
end.

3. Obtendo o saldo de créditos em conta

O método Credits serve para consultar o número de créditos disponíveis em sua conta.

Créditos são utilizados para enviar qualquer tipo de mensagem e podem ser adquiridos em nossa “Loja Virtual” através da plataforma.

3.1. Parâmetros do Credits

Parâmetro Requerido? Formato Descrição
CREDENCIAL Sim A(40) Credencial da sua conta no PitchWink
TOKEN Sim A(6) Chave de acesso ao Gateway

3.2. Retornos do Credits

Código de Retorno Tipo Descrição
NÚMERO DE CRÉDITOS Sucesso O número de créditos disponível em sua conta. Este retorno contém 5 casas decimais. Ex: 855357,20000
X01 ou X02 Erro Um ou mais parâmetros com erro
001 Erro Credencial inválida
019 Erro TOKEN inválido
022 Erro Conta atingiu o limite de envio do dia

3.3. Chamada (HTTP ou HTTPS)

http://www.pw-api.com/sms/v_3_00/smscredits/credits.aspx?Credencial=F4F4110B1123456D58793A74B5BC08D12266E&Token=123456
Testando o exemplo acima no browser será retornado o código 001, pois a CREDENCIAL não existe. Favor substituir o conteúdo dos parâmetros, incluindo a CREDENCIAL da sua conta para obter o resultado desejado.

4. Consultando envios realizados em um determinado período

O método Query01 é utilizado para consultar as mensagens de texto SMS enviadas através da sua conta em um determinado intervalo de tempo.

O retorno é um XML de até 1000 linhas, no qual os campos são: código auxiliar, data de envio, mobile, flag de recebimento, código de retorno e message.

4.1. Parâmetros do Query01

Parâmetro Requerido? Formato Descrição
CREDENCIAL Sim A(40) Credencial da sua conta no PitchWink
TOKEN Sim A(6) Chave de acesso ao Gateway
START_DATE Sim A(10) Formato DD/MM/YYYY
END_DATE Sim A(10) Formato DD/MM/YYYY
AUX_USER Não A(20) O valor atribuído a este parâmetro pode ser utilizado como referência em filtros, facilitando a identificação de mensagens específicas em relatórios criados por você a partir da plataforma
MOBILE Sim A(15) Número celular do destinatário em formato internacional. Exemplo para o Brasil: 5521999999999
STATUS_CODE Sim N(1) 0=Erro
1=Sucesso

4.2. Retornos do Query01

Código de Retorno Tipo Descrição
XML Sucesso XML com os resultados solicitados (máximo de 1000 linhas). Os campos incluem: código auxiliar, data de envio, mobile, flag de recebimento, código de retorno e message
X01 ou X02 Erro Um ou mais parâmetros com erro
001 Erro Credencial inválida
002 Erro START_DATE com erro
003 Erro END_DATE com erro
004 Erro AUX_USER com erro
005 Erro MOBILE com erro
006 Erro MOBILE com formato inválido
007 Erro STATUS_CODE com erro
019 Erro TOKEN inválido
022 Erro Conta atingiu o limite de envio do dia

4.3. Chamada (HTTP ou HTTPS)

http://www.pw-api.com/sms/v_3_00/query01/query01.aspx?Credencial=XXXMU10B1B8SED382FXXX793A74B5BC08D12266E&Token=123456&Start_Date=01/09/2010&End_Date=05/09/2010&Aux_User=F1&Mobile=552199999999&Status_Code=1
Testando o exemplo acima no browser será retornado o código 001, pois a CREDENCIAL não existe. Favor substituir o conteúdo dos parâmetros, incluindo a CREDENCIAL da sua conta para obter o resultado desejado.

5. Enviando mensagens via SMS (SMS Follow)

O método SMSFollow tem a mesma funcionalidade do EnviaSMS. A diferença é no retorno, onde vem também o ID da mensagem. Este ID vai ser utilizado no método Status de forma a obter o status de uma mensagem enviada.

5.1. Parâmetros do SMSFollow

Parâmetro Requerido? Formato Descrição
CREDENCIAL Sim A(40) Credencial da sua conta no PitchWink
TOKEN Sim A(6) Chave de acesso ao Gateway
PRINCIPAL_USER Não A(50) ou “” Controle interno do cliente
AUX_USER Não A(20) O valor atribuído a este parâmetro pode ser utilizado como referência em filtros, facilitando a identificação de mensagens específicas em relatórios criados por você a partir da plataforma
MOBILE Sim A(15) Número celular do destinatário em formato internacional. Exemplo para o Brasil: 5521999999999
SEND_PROJECT Não A(1) Se usa o remetente na mensagem. Possíveis opções:
S = SIM
N= NÃO
Y= YES
N= NO
MESSAGE Sim A(160) Conteúdo da mensagem a ser enviada via SMS.

5.2. Retornos do SMSFollow

Código de Retorno Tipo Descrição
000:ID Sucesso Mensagem enviada com sucesso. Onde o ID é o identificador único da mensagem no PitchWink
X01 ou X02 Erro Um ou mais parâmetros com erro
001 Erro Credencial inválida
005 Erro MOBILE com formato inválido
007 Erro SEND_PROJECT com formato inválido
008 Erro MESSAGE ou MESSAGE + NOME_PROJETO com mais de 160 posições ou SMS concatenado com mais de 1000 posições
009 Erro Número de créditos insuficiente
010 Erro Gateway SMS da conta bloqueado
012 Erro MOBILE correto, porém com crítica
013 Erro Conteúdo da mensagem inválido ou vazio
015 Erro País sem cobertura
016 Erro MOBILE com código de área inválido
018 Erro MOBILE se encontra em lista negra
019 Erro TOKEN inválido
022 Erro Conta atingiu o limite de envio do dia

5.3. Chamada (HTTP ou HTTPS)

http://www.pw-api.com/sms/v_3_00/smsfollow/smsfollow.aspx?Credencial=XXXX110B1B8723382XXXX793A74B5BC08D12266E&&Token=123456&Principal_User=FF&Aux_User=F1&Mobile=552194797025&Send_Project=S&Message=teste
Testando o exemplo acima no browser será retornado o código 001, pois a CREDENCIAL não existe. Favor substituir o conteúdo dos parâmetros, incluindo a CREDENCIAL da sua conta para obter o resultado desejado.

6. Obtendo o status de mensagens enviadas

O método Status permite obter a condição atual da mensagem.

6.1. Parâmetros do Status

Parâmetro Requerido? Formato Descrição
CREDENCIAL Sim A(40) Credencial da sua conta no PitchWink
TOKEN Sim A(6) Chave de acesso ao Gateway
ID Sim A(40) ID da mensagem que se deseja obter o status atual

6.2. Retornos do Status

Código de Retorno Tipo Descrição
200 Sucesso Mensagem entregue ao celular com recibo de confirmação do aparelho
220 Sucesso Mensagem entregue ao celular sem recibo de confirmação
300 Temporário Em processo de envio
X01 ou X02 Erro Um ou mais parâmetros com erro
020 Erro ID não encontrado
001 Erro Credencial inválida
019 Erro TOKEN inválido
022 Erro Conta atingiu o limite de envio do dia
100 Erro Mensagem não foi entregue ao celular após diversas tentativas

6.3. Chamada (HTTP ou HTTPS)

http://www.pw-api.com/sms/v_3_00/smsstatus/status.aspx?Credencial=XXXXXXXXXX7737FA5D81XX1C2BFDDBEB7F1D7584&ID=XXXXXXXXXXCCCCCCCCCCYYYYYYYYYYUUUUUUUUUU&Token=123456
Testando o exemplo acima no browser será retornado o código 001, pois a CREDENCIAL não existe. Favor substituir o conteúdo dos parâmetros, incluindo a CREDENCIAL da sua conta para obter o resultado desejado.