Receber Notificação
Como funciona
- A Gerencianet envia (via POST) uma notificação para a URL de notificação cadastrada em sua conta;
- Seu sistema recebe a requisição e nos envia um xml contendo seu token e o identificador da notificação;
- A Gerencianet retorna todas as informações sobre as mudanças no status da transação, assim vocẽ poderá atualizar o status do pagamento em seu sistema (liberar ou bloquear serviços, autorizar a entrega de produtos, etc).
Utilize esta integração para automatizar seu processo de análise de transações. A Gerencianet notificará seu sistema sempre que for identificada uma alteração de status em qualquer uma de suas cobranças.
Cadastrando uma URL de Notificação
Para começar a receber notificações, você deve cadastrar uma URL em sua conta Gerencianet. A API de pagamentos da Gerencianet enviará notificações referentes aos seus pagamentos para esta URL via POST. Para cadastrar a URL, acesse o menu Desenvolvedor e, em seguida Notificações.
Observação: As notificações são enviadas a cada duas horas. Se neste intervalo de tempo nenhuma de suas transações tiver o status alterado, nenhuma notificação será enviada.
A página cadastrada deve ser preparada para receber o código que será enviado pela Gerencianet, como será explicado a seguir.
Recebendo uma notificação
Sempre que uma cobrança sofrer uma alteração de status, um POST será disparado para a URL cadastrada contendo um identificador de notificação.
Por segurança, as informações da transação serão enviadas somente quando seu sistema consultá-las utilizando o código recebido.
Veja abaixo um exemplo de notificação enviada pela Gerencianet:
POST http://seu_dominio.com.br/notificacao HTTP/1.1
Content-Type: multipart/form-data; charset=utf-8
notificacao=codigo_da_notificacao
Perceba que enviamos apenas um parâmetro nesta primeira etapa:
Parâmetro | Descrição |
---|---|
notificacao | Identificador da notificação. Este código é único e deve ser utilizado apenas para consultar as informações de status da transação. |
Consultando uma notificação
Para que seu sistema receba as informações da notificação, é necessário consultá-las fazendo uma requisição à nossa API, enviando o identificador de notificação recebido anteriormente e seu token de integração Gerencianet.
POST https://go.gerencianet.com.br/api/notificacao/xml HTTP/1.1
Content-Type: multipart/form-data; charset=utf-8
token=token_de_integracao
dados=seu_xml
Exemplo dos dados em formato XML
A seguir você encontra um exemplo de como seu XML deve ser construído para consultar a notificação.
- <?xml version="1.0" encoding="utf-8"?>
- <integracao>
- <notificacao>notificacao_teste</notificacao>
- </integracao>
Token de integração
O token de integração é uma espécie de senha. Ele é solicitado em todas as requisições da api de pagamentos.
Não divulgue seu token de integração. Caso isto aconteça, a Gerencianet recomenda que você gere um novo.
Para gerar um token de integração acesse sua conta Gerencianet e clique em Desenvolvedor e, em seguida Token de integração.
Resposta em caso de sucesso
Se os dados enviados estiverem corretos, a Gerencianet retornará as alterações de status para a notificação consultada:
- <?xml version="1.0" encoding="utf-8"?>
- <integracao>
- <status>2</status>
- <resposta>
- <transacao>12323</transacao>
- <identificador>43210</identificador>
- <status>selecionado</status>
- <codigoStatus>3</codigoStatus>
- <assinatura>
- <identificador>98765</identificador>
- <numeroOcorrencia>3</numeroOcorrencia>
- </assinatura>
- <historico>
- <log>
- <acao>Cobrança aguardando pagamento</acao>
- <data>2014-03-20T09:57:01</data>
- <status>aguardando</status>
- <codigoStatus>1</codigoStatus>
- </log>
- <log>
- <acao>Cliente selecionou pagamento via boleto</acao>
- <data>2014-03-25T12:57:03</data>
- <status>selecionado</status>
- <codigoStatus>3</codigoStatus>
- </log>
- </historico>
- </resposta>
- </integracao>
Resposta em caso de erro
- <?xml version="1.0" encoding="utf-8"?>
- <integracao>
- <status>1</status>
- <erros>
- <codigo>10043</codigo>
- <erro>Token de notificação não encontrado</erro>
- </erros>
- </integracao>
Descrição dos parâmetros de notificação
A tabela abaixo detalha os parâmetros retornados nos XMLs de sucesso e de erro:
Tag | Descrição |
---|---|
status | Código de status do processamento da requisição. Pode ser 1 ou 2. Caso seja 1 indica que ocorreu algum erro. Caso for 2 o processamento foi realizado com sucesso. |
resposta | Engloba toda resposta da requisição. |
transacao | Número da transação à qual as notificações correspondem. |
identificador | Número da transação, em seu sistema, à qual as notificações correspondem. Este parâmetro só será enviado se você o informou no momento de gerar a transação. |
status | Demonstra o status atual da transação. Os status podem ser:
|
codigoStatus | Demonstra código referente ao status atual da transação. Os códigos podem ser:
|
pagamento | Demonstra a forma de pagamento selecionada pelo cliente. Esta tag existirá somente se a cobrança tiver o status "pago". Os valores possíveis para esta tag são: boleto e cartão de crédito |
codigoPagamento | Código da forma de pagamento selecionada pelo cliente. Esta tag existirá somente se a cobrança tiver o status "pago". Os valores possíveis para esta tag são: 1 (boleto) e 2 (cartão de crédito) |
assinatura | Tag que engloba os dados de assinaturas geradas através do web-service de assinaturas ou do checkout transparente de assinaturas |
identificador | Identificador da assinatura gerada. O identificador será o mesmo para todas as cobraças geradas à partir da mesma assinatura. |
numeroOcorrencia | Número da ocorrência da assinatura. Este número identifica a cobrança corrente, ou seja, a última cobrança gerada a partir da assinatura. |
historico | Engloba o log de mudanças do status da transacao. Ordenado da data mais antiga para a mais atual. |
log | Uma ocorrência de modificação do status da transacao. |
acao | Descrição da ação que efetuou a alteração de status. |
data | Data da realização da alteração de status da transação no formato:
YYYY-MM-DDThh:mm:ss
formato oficial do W3C |
status | Simboliza o status da transacao quando foi realizada a alteração de status. |
codigoStatus | Código do status da transação quando foi realizada a mudança (mesma sequência listada na tag resposta > codigoStatus). |
pagamento | Demonstra a forma de pagamento selecionada pelo cliente. Esta tag existirá somente o status for igual a "pago". Os valores possíveis para esta tag são: boleto e cartão de crédito |
codigoPagamento | Código da forma de pagamento selecionada pelo cliente. Esta tag existirá somente o status for igual a "pago". Os valores possíveis para esta tag são: 1 (boleto) e 2 (cartão de crédito) |
erros | Em caso de status 1, os dados dos erros serão englobados por esta tag. |
codigo | Código que simboliza o erro gerado. |
erro | Descrição do erro ocorrido ao realiza a requisição. |
Ambiente de testes
Para realizar testes de notificações, acesse o menu Desenvolvedor -> Notificações em sua conta Gerencianet. Após cadastrar sua URL clique em testar.
A Gerencianet enviará uma notificação de teste para sua URL. Você poderá consultar os detalhes desta notificação conforme descrito aqui.
Observação: Os dados retornados ao se consultar a notificação de teste são fictícios.
Exemplos
Via Curl
- // Recebendo a notificação da Gerencianet
- $postNotificacao = $_POST["notificacao"];
- // Consultando os detalhes da notificação
- $url = "https://go.gerencianet.com.br/api/notificacao/xml";
- $token = "token";
- $xml = "<?xml version='1.0' encoding='utf-8'?>
- <integracao>
- <notificacao>".$postNotificacao."</notificacao>
- </integracao>";
- $xml = str_replace(array("\n", "\r", "\t"), '', $xml);
- $ch = curl_init();
- curl_setopt($ch, CURLOPT_URL, $url);
- curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
- curl_setopt($ch, CURLOPT_MAXREDIRS, 2);
- curl_setopt($ch, CURLOPT_AUTOREFERER, true);
- $data = array("token" => $token, "dados" => $xml);
- curl_setopt($ch, CURLOPT_POST, true);
- curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
- curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 30);
- curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
- $response = curl_exec($ch);
- curl_close($ch);
- echo "<xmp>".$response."</xmp>";
Via Guzzle
- // Recebendo a notificação da Gerencianet
- $postNotificacao = $_POST["notificacao"];
- // Consultando os detalhes da notificação
- $url = "https://go.gerencianet.com.br/api/notificacao/xml";
- $token = "token";
- $xml = "<?xml version='1.0' encoding='utf-8'?>
- <integracao>
- <notificacao>".$postNotificacao."</notificacao>
- </integracao>";
- $xml = str_replace(array("\n", "\r", "\t"), '', $xml);
- Guzzle\Http\StaticClient::mount();
- $client = new \Guzzle\Http\Client($url);
- $request = $client->post('', null, array("token" => $token, "dados" => $xml));
- $response = $request->send();
- echo "<xmp>".$response."</xmp>";
- // Recebendo a notificação da Gerencianet
- String postNotificacao = request.getParameter("notificacao")
- // Consultando os detalhes da notificação
- String url = "https://go.gerencianet.com.br/api/notificacao";
- String token = "token";
- String xml = "<?xml version='1.0' encoding='utf-8'?>"
- + "<integracao>"
- + "<notificacao>" + postNotificacao + "</notificacao>"
- + "</integracao>";
- HttpClient client = new DefaultHttpClient();
- HttpPost post = new HttpPost(url);
- post.setHeader("User-Agent", HttpHeaders.USER_AGENT);
- List<NameValuePair> urlParameters;
- urlParameters = new ArrayList<>();
- urlParameters.add(new BasicNameValuePair("token", token));
- urlParameters.add(new BasicNameValuePair("dados", xml));
- post.setEntity(new UrlEncodedFormEntity(urlParameters));
- HttpResponse response = client.execute(post);
- System.out.println("Response Code : " + response.getStatusLine().getStatusCode());
- BufferedReader rd = new BufferedReader(
- new InputStreamReader(response.getEntity().getContent()));
- StringBuilder result = new StringBuilder();
- String line = "";
- while ((line = rd.readLine()) != null) {
- result.append(line);
- }
- System.out.println(result.toString());
- // Recebendo a notificação da Gerencianet
- String postNotificacao = Request.Form("notificacao").ToString()
- // Consultando os detalhes da notificação
- String url = "http://go.gerencianet.com.br/api/notificacao";
- String token = "token";
- String xml = "<?xml version='1.0' encoding='utf-8'?>" +
- "<integracao>" +
- "<notificacao>" + postNotificacao + "</notificacao>" +
- "</integracao>";
- WebClient client = new WebClient();
- NameValueCollection postData = new NameValueCollection() { { "token", token }, { "dados", xml } };
- byte[] response = client.UploadValues(url, postData);
- Console.WriteLine("Output: " + System.Text.Encoding.Default.GetString(response));
- import requests
- # Recebendo a notificação da Gerencianet
- # Obs.: Considerando que se esteja usando o Python Flask
- post_notificacao = request.form['notificacao']
- # Consultando os detalhes da notificação
- url = "http://go.gerencianet.com.br/api/notificacao/xml"
- token = "token"
- params = ("<?xml version='1.0' encoding='utf-8'?>" +
- "<integracao>" +
- "<notificacao>" + post_notificacao + "</notificacao>" +
- "</integracao>")
- response = requests.post(url = url, data = { 'token': token, 'dados': params })
- print response.text
- require 'httparty'
- # Recebendo a notificação da Gerencianet
- post_notificacao = params[:notificacao]
- # Consultando os detalhes da notificação
- url = "http://go.gerencianet.com.br/api/notificacao/xml"
- token = "token"
- xml = "<?xml version='1.0' encoding='utf-8'?>
- <integracao>
- <notificacao>#{post_notificacao}</notificacao>
- </integracao>"
- HTTParty.post(url, body: { token: token, dados: xml }, headers: { "User-Agent" => request.user_agent }).body
Histórico de requisições
Acompanhe o histórico de requisições realizadas à API de pagamentos em sua conta. O histórico de requisições é ideal para identificar erros durante a etapa de implementação da integração.