Versão: 3.00 Última Atualização: 31/05/2018
Índice
- Introdução
- Enviando mensagens via SMS (Envia SMS)
- Obtendo o saldo de créditos em conta
- Consultando envios realizados em um determinado período
- Enviando mensagens via SMS (SMS Follow)
- 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
2.4. Exemplos do EnviaSMS
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.
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
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.
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
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
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