Versão: 3.00 Última Atualização: 16/12/2015
Índice
- Introdução
- Enviando mensagens via SMS
- Consultando o status das mensagens
- Obtendo o saldo de créditos em conta
- Consultando envios realizados em um determinado período
- Calculando o nº de caracteres em UTF-8 e UTF-16
- Exemplos em PHP
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 da mensagens enviadas a eles.
1.2. URL do Web Service
http://pw-api.com/sms/v_3_00/service.asmx
1.3. Notas importantes
1 A partir da próxima versão, os seguintes métodos estarão obsoletos:
- MPG_SendSimple_SMS
- MPG_Send_Long_SMS
- MPG_Send_SMS
- MPG_SendandFollowUp_SMS
Utilize o novo método MPG_Send_LMS que contempla todas as funcionalidades dos métodos citados acima.
2. Enviando mensagens via SMS
O MPG_Send_LMS é 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.
2.1. Parâmetros do MPG_Send_LMS
Parâmetro | Requerido? | Formato | Descrição |
---|---|---|---|
CREDENCIAL | Sim | A(40) | Credencial da sua conta no PitchWink |
TOKEN | Sim | A(6) | Código de acesso ao Gateway |
PRINCIPAL_USER | Sim | A(50) ou “” | Controle interno do cliente |
AUX_USER | Sim | 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: +55(21)999999999 |
MESSAGE | Sim | A(160) | Conteúdo da mensagem a ser enviada via SMS. |
2.2. Retornos do MPG_Send_LMS
Código de Retorno | Tipo | Descrição |
---|---|---|
000:ID | Sucesso | Mensagem enviada com sucesso. Onde o ID é o identificador único da mensagem no PitchWink |
001 | Erro | Credencial inválida |
005 | Erro | MOBILE 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 sem cobertura ou não aceita mensagens concatenadas (SMS Longo) |
016 | Erro | MOBILE com código de área inválido |
017 | Erro | Operadora não autorizada para esta credencial |
018 | Erro | MOBILE se encontra em lista negra |
019 | Erro | Token inválido |
022 | Erro | Conta atingiu o limite de envio do dia |
800 a 899 | Erro | Falha no Gateway |
900 | Erro | Erro de autenticação ou limite de segurança excedido |
901 a 999 | Erro | Erro no acesso as operadoras |
3. Consultando o status das mensagens
Utilizando a URL Callback é possível obter o status atual das mensagens. Clique aqui para visualizar.
4. Obtendo o saldo de créditos em conta
O método MPG_Credits serve para consultar o número de créditos disponíveis em sua conta.
4.1. Parâmetros do MPG_Credits
Parâmetro | Requerido? | Formato | Descrição |
---|---|---|---|
CREDENCIAL | Sim | A(40) | Credencial da sua conta no PitchWink |
TOKEN | Sim | A(6) | Código de acesso ao Gateway |
STATUS | Sim | A(3) | Caso preenchido vêm com o código de erro |
4.2. Retornos do MPG_Credits
Código de Retorno | Tipo | Descrição |
---|---|---|
N. 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. Em caso de erro, o retorno será -1 e no campo STATUS, irá conter um dos erros abaixo. |
001 | Erro | Credencial inválida |
019 | Erro | Token inválido |
022 | Erro | Conta atingiu o limite de envio do dia |
800 a 899 | Erro | Falha no Gateway |
900 | Erro | Erro de autenticação ou limite de segurança excedido |
5. Consultando envios realizados em um determinado período
O método MPG_Query01 é utilizado para consultar as mensagens de texto SMS enviadas através da sua conta em um determinado intervalo de tempo.
5.1. Parâmetros do MPG_Query01
Parâmetro | Requerido? | Formato | Descrição |
---|---|---|---|
CREDENCIAL | Sim | A(40) | Credencial da sua conta no PitchWink |
TOKEN | Sim | A(6) | Código de acesso ao Gateway |
START_DATE | Sim | A(10) | Data inicial da consulta. Ex: 14/07/2017 |
END_DATE | Sim | A(10) | Data final da consulta. Ex: 15/07/2017 |
AUX_USER | Sim | 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: +55(21)999999999 |
STATUS_CODE | Sim | N | 0 – SMS enviado com erro de crítica 1 – SMS enviado com sucesso 2 – Ambos |
5.2. Retornos do MPG_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 |
001 | Erro | Credencial inválida |
002 | Erro | Data inicial inválida |
003 | Erro | Data final inválida |
005 | Erro | Mobile com formato inválido |
019 | Erro | Token inválido |
022 | Erro | Conta atingiu o limite de envio do dia |
890 | Erro | Falha no método MPG_Query, favor entrar em contato com o suporte |
6. Calculando o nº de caracteres em UTF-8 e UTF-16
O método MPG_Calculate_Message_Length_UTF8_or_UTF16 é utilizado para calcular o número de caracteres (UTF-8 ou UTF-16) presentes no conteúdo da mensagem.
6.1. Parâmetros do MPG_Calculate_Message_Length_UTF8_or_UTF16
Parâmetro | Requerido? | Formato | Descrição |
---|---|---|---|
CREDENCIAL | Sim | A(40) | Credencial da sua conta no PitchWink |
TOKEN | Sim | A(6) | Código de acesso ao Gateway |
MESSAGE | Sim | A | Conteúdo da mensagem no qual o cálculo será feito |
6.2. Retornos do MPG_Calculate_Message_Length_UTF8_or_UTF16
Código de Retorno | Tipo | Descrição |
---|---|---|
N. DE CARACTERES | Sucesso | Número de caracteres UTF-8 ou UTF-16 encontrados na MESSAGE. Note que, caso exista algum caracter UTF-16 no conteúdo, todos os outros caracteres serão contados como 16-bit (2 bytes) |
-1 | Erro | Credencial inválida |
-2 | Erro | Token inválido |
-9 | Erro | Erro interno, favor entrar em contato com o suporte |
Exemplo em PHP
<?php /** * * @author Gilson Santos * */ class PitchWink { // /** * Protegidas * @var $params = vai receber valores em ARRAY com os parametros que serão utilizados nas chamadas. * os valores serão como o modelo abaixo: * array( * "MPG_Credits" => array('Credencial', 'Token'), * "MPG_Send_LMS" => array('Credencial', 'Token', 'Principal_User', 'Aux_User', 'Mobile', 'Message') * "<Nome_Chamada_1>" => array('<Campo_Chamada_1>') * ) * @var $wsdl = url do WSDL. Valor Inicial: NULL * @var $client = Variavel utilizada para realizar as chamadas. Valor inicial: NULL * @var $error = valor do error qdo ocorre. Valor Inicial: NULL * @var $result = resultado da chamada. Valor inicial: NULL * * @var $options = opcoes do WSDL. Valor Inicial * array( 'soap_version'=>SOAP_1_2, 'exceptions'=>true, 'trace'=>1, 'cache_wsdl'=>WSDL_CACHE_NONE ); * @var $rtWsdl = recebe os resultados das chamadas. Array padrão. * @var $callsArr = sao os campos ordenados que cada funcao precisa para ser executada * */ protected $params = array(); //vai receber todos os paramentos protected $wsdl = NULL; // vai receber protected $error = null; protected $client = null; // protected $result = NULL; // public $rtWsdl = array(); // protected $options = array( 'soap_version'=>SOAP_1_2, 'exceptions'=>true, 'trace'=>1, 'cache_wsdl'=>WSDL_CACHE_NONE ); // protected $callsArr = array( "MPG_Credits" => array('Credencial', 'Token'), "MPG_Send_LMS" => array('Credencial', 'Token', 'Principal_User', 'Aux_User', 'Mobile', 'Message'), "MPG_Query01" => array('Credencial', 'Token', 'Start_Date', 'End_Date', 'Aux_User', 'Mobile', 'Status_Code', 'Status'), "MPG_Calculate_Message_Length_UTF8_or_UTF16" => array('Credencial', 'Token', 'Message') ); //] /* ** vai executar a funcao run() * Funcao run() é será chamada e irá executar o que o usuário desejar. * run () tem os mesmos parametros da __construct para chamar * */ public function __construct($wsdl, $credencial, $token, $func = NULL, $mobile = NULL, $message = NULL, $user = NULL, $aux_user = NULL, $start_date = NULL, $end_date = NULL, $status_code = NULL, $status = NULL, $suxResult = "Result") { $this->run($wsdl, $credencial, $token, $func, $mobile, $message, $user, $aux_user, $start_date, $end_date, $status_code, $status, $suxResult); } /** * * @param unknown $wsdl = url wsdl * @param unknown $credencial = credencial mobi pronto * @param unknown $token = token mobi pronto * @param string/array $func = string/array * @param unknown $mobile = numero para envio formato +55(xx)9xxxxxxxx. se nao for definido para relatorio, vai trazer todos os registros * @param unknown $message = mensagem com até 160 caracteres * @param unknown $user = Principal_User * @param unknown $aux_user = definicao do PitchWink * ******* relatorio ******* * @param unknown $start_date = para definicao de relatorio, data inicial * @param unknown $end_date = para definicao de relatorio, data final * @param unknown $status_code = para definicao de relatorio, valor padrao para exibir todos os retornos * @param unknown $status = valor padrao vazio * @param string $suxResult = */ public function run($wsdl, $credencial, $token, $func = NULL, $mobile = NULL, $message = NULL, $user = NULL, $aux_user = NULL, $start_date = NULL, $end_date = NULL, $status_code = NULL, $status = NULL, $suxResult = "Result") { // $this->wsdl = $wsdl; // if (!is_null($credencial)) $this->params['Credencial'] = $credencial; if (!is_null($token)) $this->params['Token'] = $token; if (!is_null($user)) $this->params['Principal_User'] = $user; if (!is_null($aux_user)) $this->params['Aux_User'] = $aux_user; if (!is_null($aux_user)) $this->params['Start_Date'] = $start_date; if (!is_null($aux_user)) $this->params['End_Date'] = $end_date; if (!is_null($aux_user)) $this->params['Status_Code'] = $status_code; if (!is_null($aux_user)) $this->params['Status'] = $status; // try{ $this->client = new SoapClient( $this->wsdl, $this->options); }catch (Exception $e){ $logText = $e->getMessage(); $l = new logs($this->nomeArquivo, $logText, $this->localArquivo, true); } // $this->arMerge(array('Mobile'=>$mobile, 'Message'=>$message)); // $this->exCalls($func); // } // /** * Envia o SMS para o número desejado * * @param string $mobile = numero para qual deseja. Exemplo +55(99)999999999 * @param string $message = texto * @param string $call = */ public function enviarSms($mobile, $message, $call = "MPG_Send_LMS"){ $this->arMerge(array('Mobile'=>$mobile, 'Message'=>$message)); //envia o sms e retorna o resultado $this->getCall($call, $this->permParansArr($call)); return $this->loadResult($call); // } /** * Mostra o saldo disponível * * @param string $call = "MPG_Credits" foi definida como padrao */ public function mostraSaldo($call = "MPG_Credits"){ $this->getCall($call, $this->permParansArr($call)); return $this->loadResult($call); } /** * * @param string $sDt = dd/mm/aaaa * @param string $eDt = dd/mm/aaaa * @param integer $stCod = 0, 1, 2 * @param string $call = "MPG_Query01" */ public function relatorio($sDt, $eDt, $stCod = 2, $call = "MPG_Query01"){ $this->arMerge(array( 'Start_Date' => $sDt, 'End_Date'=> $eDt, 'Status_Code' => $stCod )); // //print_r($this->paramsPerm($this->params, $this->permParansArr($call)));exit; // $this->getCall($call, $this->permParansArr($call)); return $this->loadResult($call); } /** * executa as chamadas de acordo com o solicitado * $func pode ser de duas formas * 1: $func = "MPG_Credits"; * 2: $func = array("MPG_Credtis") * * @param string/array $func */ public function exCalls($func){ $arrCall = $this->permParansArr(); // if(!is_array($func)){ if(!is_null($func) && array_key_exists($func, $arrCall)){ $this->getCall($func, $arrCall[$func]); }else{ //executa todas as chamadas caso nao seja definida uma chamada específica $this->allCalls($arrCall); // } }else{ if(is_array($func)){ foreach($func as $k=>$v){ if(array_key_exists($v, $arrCall)){ $this->getCall($v, $arrCall[$v]); } } } } } /** * verifica o tamanho da mensagem é o permitido */ private function tamMsg(){ if(strlen(trim($this->params['Message']))<=160){ return true; } // return false; } /** * Junta os valores em array em $this->params * * @param unknown $aMg */ private function arMerge($aMg){ $this->params = array_merge($this->params, $aMg); } /** * executa a chamada especifica de acordo com os campos permitidos * @param unknown $call * @param unknown $paramPerm */ private function getCall($call, $paramPerm){ try{ $this->result = $this->client->$call( $this->paramsPerm($this->params, $paramPerm) ); $this->rtWsdl[$call] = $this->loadResult($call); }catch (Exception $e){ $this->error = $e->getMessage(); } } /** * executa todas as chamadas. Call precisar ser array * @param unknown $call */ private function allCalls($call){ if(is_array($call)){ foreach ($call as $calling=>$param){ if(is_array($param)) $this->getCall($calling, $param); } } } private function setError($e) { $this->error = $e; } private function getError() { return $this->translateError ( $this->getErrorCode () ); } private function getErrorCode() { return $this->error; } protected function translateError($e) { $arr = array ( '0' => 'Sucesso-Mensagem enviada com sucesso', '1' => 'Erro ' . $e . ' - Credencial inválida', '5' => 'Erro ' . $e . ' - MOBILE com formato inválido', '8' => 'Erro ' . $e . ' - MESSAGE ou MESSAGE + NOME_PROJETO com mais de 160 posições. SMS concatenado com mais de 1000 posições', '9' => 'Erro ' . $e . ' - Créditos insuficientes em conta', '10' => 'Erro ' . $e . ' - Gateway SMS da conta bloqueado', '12' => 'Erro ' . $e . ' - MOBILE correto, porém com crítica', '13' => 'Erro ' . $e . ' - Conteúdo da mensagem inválido ou vazio', '15' => 'Erro ' . $e . ' - País sem cobertura ou não aceita mensagens concatenadas (SMS Longo)', '16' => 'Erro ' . $e . ' - MOBILE com código de área inválido', '17' => 'Erro ' . $e . ' - Operadora não autorizada para esta credencial', '18' => 'Erro ' . $e . ' - MOBILE se encontra em lista negra', '19' => 'Erro ' . $e . ' - Token inválido', '900' => 'Erro ' . $e . ' - Erro de autenticação ou limite de segurança excedido' ); if (isset ( $arr [$e] )) return $arr [$e]; /* * 800 a 899 Erro Falha no Gateway * 900 Erro * 901 a 999 Erro Erro no acesso as operadoras */ if ($e >= 800 && $e <= 899) return 'Erro ' . $e . ' - Falha no Gateway'; if ($e >= 900 && $e <= 999) return 'Erro ' . $e . ' - Erro no acesso as operadoras'; return $e; } /** * busca os campos que são permitidos na chamada especifica. Se não for definido, chama os campos válidos de todas as chamadas * * @param unknown $call = a chamada especifica * @return string[]|string[][] = retorno em array */ protected function permParansArr($call = NULL){ if(!is_null($call) && array_key_exists($call, $this->callsArr)){ return $this->callsArr[$call]; } //caso não seja definido ou encontrado call, todas as chamadas serão executadas return $this->callsArr; } /** * retorna apenas os campos permitidos para executar a funcao * * @param array $params = array de parametros * @param array $perm = array de campos permitidos * @param boolean $all = false padrao | se true, retorna todos os campos * */ function paramsPerm($params, $perm, $all = false){//$perm campos permitidos $retParams = array(); if(!$all){ // caso $all seja false, será feita uma verificação em $params e recolhe apenas os parametros permitidos if(is_array($perm)){ //se for array, continua foreach($perm as $k=>$v){// if(array_key_exists($v, $params)){ switch ($v){ case "Start_Date": case "End_Date": if(preg_match("/\//", $params[$v])){ $params[$v] = preg_replace("/\//", '-', $params[$v]); } default: $retParams[$v]=&$params[$v]; } } } }else{ if(in_array($perm, $params)){ $retParams = &$params[$perm]; } } }else{ $retParams = &$params; } // return $retParams; // retorno // } // /** * Retorna o resultado da chamada. * Para MPG_Query01, o retorno está como Objeto. * * @param unknown $call = chamada * @param string $suxResult = sufixo do RetornoXML */ function loadResult($call, $suxResult = "Result"){ $r = "{$call}{$suxResult}"; try{ $rt = $this->result->$r; if($call == "MPG_Query01"){ return $rt->any; } return $rt; }catch (Exception $e){ $this->error = $e->getMessage(); } } } //para fins de logs //defina a variável $localArquivo, dê a permissão de criacao, leitura e escrita, que o arquivo será criado automaticamente. class logs{ // /** * * @var $ofl = variavel de controle da leitura e escrita do arquivo * @var $nomeArquivo = nome do arquivo que vai escrever * @var $localArquivo = local do arquivo. não é necessario colocar "/" no final da pasta * @var $fileWt = forma como o arquivo vai escrever. Por padrao o valor "a"( que se arquivo não existir, ele cria ) * a pasta definida em $localArquivo */ protected $oFl; protected $nomeArquivo = "log"; protected $localArquivo = "log"; protected $extensao = "txt"; protected $fileWt = "a"; // /** * @param unknown $log = valor do que que será escrito no arquivo * @param boolean $tempoAtual = true | false (padrao), se verdeiro exibe o tempo da execução */ function __construct($log, $tempoAtual = false){ $this->escreve($log, $tempoAtual);// } /** * escreve o arquivo de log * * @param unknown $log = conteudo do arquivo de log * @param string $tempoAtual = true | false * */ public function escreve($log,$tempoAtual = false){ // if(strlen(trim($log))>0 && !is_null($log)){ $this->oFile("{$this->nomeArquivo}.{$this->extensao}", $this->localArquivo); if($tempoAtual){//caso queira que exiba o tempo do log $log = date('d/m/Y H:i:s') . "{$log}\r\n"; } $this->oWrite($log); $this->oClose(); /** log completo */ } // } // // /** * Manipula o arquivo aberto */ protected function oFile(){ // if(!is_null($this->localArquivo) && trim($localArquivo)!='' && is_dir($this->localArquivo)){ // se o local não foi $path_file = "{$this->localArquivo}/{$this->nomeArquivo}"; //determina o local e nome do log }else{ $path_file = $this->nomeArquivo; } // $this->oFl = fopen($path_file, $this->fileWt); // } // /** * Com * @param string $str = conteudo do arquivo */ protected function oWrite($str){ fwrite($this->oFl, $str); } // /** * fecha a conexao com o arquivo */ protected function oClose(){ fclose($this->oFl); } // } /** * @author Gilson Santos * exemplos para executar as chamadas */ // $wsdl = 'http://pw-api.com/sms/v_3_00/service.asmx?wsdl'; /* * caso queira executar apenas uma chamadas específicas * $func = "MPG_Credits"; * ou * $func = array( "MPG_Send_LMS", "MPG_Credits"); */ $func = array( "MPG_Credits"); // // $credencial = '442XXXAD3C80XXXRTUE5D867C59C2AEDB7XXXXXX'; // sua credencial $token = 'b4033a'; // o token $user = '27999017915'; //o codigo principal user $aux_user = ''; // auxiliar user $mobile = "+55(21)988889999"; // insira o número de telefone que vai receber o sms $message = "Mensagem teste Mobi Pronto via PHP!"; //mensagem que você quer enviar. $start_date = "20/10/2015"; // $end_date = "01/11/2015"; // $status_code = 2; $status = ""; /* * exemplo 1 * chame a classe com as variaveis nesta ordem ou com as variaveis necessarias apenas. Ex.: $mb = new PitchWink($wsdl, $credencial, $token) */ $mb = new PitchWink($wsdl, $credencial, $token, $func, $mobile, $message, $user, $aux_user, $start_date, $end_date, $status_code, $status); // //os retornos da execucao da chamada está na variavel $rtWsdl. ex.: $mb->$rtWsdl['<chamada>'] echo "Creditos restantes: {$mb->rtWsdl['MPG_Credits']}"; echo "<br>/***/<br>"; /* * exemplo 2 * invocando chamadas */ //caso queira trocar o número do telefone $mobile = "+55(21)977778888"; /* * para executar as chamadas abaixo, é necessário chamar sempre a classe antes. Após, voce tem a possibilidade de invocar as funcoes abaixo. */ echo $mb->enviarSms($mobile, "nova msg PitchWink") . "<br><br>/*******************/<br><br>"; // envia o sms para o destinatario echo $mb->mostraSaldo() . "<br><br>/*******************/<br><br>"; //mostra o saldo // /** * caso queria chamar o relatorio a qualquer momento, basta colocar a chamada abaixo */ echo $mb->relatorio($start_date, $end_date, $status_code); // //echo print_r($mb->rtWsdl, true); ?>
Exemplo em PHP no SourceForge
Desenvolvido por Renato Liibke. Os arquivos se encontram no SourceForge através de http://sourceforge.net/projects/nusoap/files/