Receber Notificação

Como funciona

  1. A Gerencianet envia (via POST) uma notificação para a URL de notificação cadastrada em sua conta;
  2. Seu sistema recebe a requisição e nos envia um xml contendo seu token e o identificador da notificação;
  3. 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.

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <integracao>
  3. <notificacao>notificacao_teste</notificacao>
  4. </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:

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <integracao>
  3. <status>2</status>
  4. <resposta>
  5. <transacao>12323</transacao>
  6. <identificador>43210</identificador>
  7. <status>selecionado</status>
  8. <codigoStatus>3</codigoStatus>
  9. <assinatura>
  10. <identificador>98765</identificador>
  11. <numeroOcorrencia>3</numeroOcorrencia>
  12. </assinatura>
  13. <historico>
  14. <log>
  15. <acao>Cobrança aguardando pagamento</acao>
  16. <data>2014-03-20T09:57:01</data>
  17. <status>aguardando</status>
  18. <codigoStatus>1</codigoStatus>
  19. </log>
  20. <log>
  21. <acao>Cliente selecionou pagamento via boleto</acao>
  22. <data>2014-03-25T12:57:03</data>
  23. <status>selecionado</status>
  24. <codigoStatus>3</codigoStatus>
  25. </log>
  26. </historico>
  27. </resposta>
  28. </integracao>

Resposta em caso de erro

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <integracao>
  3. <status>1</status>
  4. <erros>
  5. <codigo>10043</codigo>
  6. <erro>Token de notificação não encontrado</erro>
  7. </erros>
  8. </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:
  • aguardando (para transações ainda não pagas)
  • pago (para transações que já foram pagas)
  • recusado (para transações com cartão de crédito recusado)
  • visualizado (para transações em que o cliente já abriu a tela de pagamento mas ainda não o efetuou)
  • selecionado (para transações que estão aguardando a confirmação do pagamento)
  • cancelado (para transações que foram canceladas)
  • arquivado (para transações que foram pagas e arquivadas)
  • vencido (para transações que ultrapassaram a data de vencimento e ainda não foram pagas)
codigoStatus Demonstra código referente ao status atual da transação. Os códigos podem ser:
  • 1 (aguardando)
  • 2 (visitado)
  • 3 (selecionado)
  • 4 (vencido)
  • 5 (pago)
  • 6 (recusado)
  • 7 (arquivado)
  • 8 (cancelado)
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
  1. // Recebendo a notificação da Gerencianet
  2. $postNotificacao = $_POST["notificacao"];
  3.  
  4.  
  5. // Consultando os detalhes da notificação
  6. $url = "https://go.gerencianet.com.br/api/notificacao/xml";
  7. $token = "token";
  8.  
  9. $xml = "<?xml version='1.0' encoding='utf-8'?>
  10. <integracao>
  11. <notificacao>".$postNotificacao."</notificacao>
  12. </integracao>";
  13.  
  14. $xml = str_replace(array("\n", "\r", "\t"), '', $xml);
  15.  
  16. $ch = curl_init();
  17. curl_setopt($ch, CURLOPT_URL, $url);
  18. curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  19. curl_setopt($ch, CURLOPT_MAXREDIRS, 2);
  20. curl_setopt($ch, CURLOPT_AUTOREFERER, true);
  21. $data = array("token" => $token, "dados" => $xml);
  22.  
  23. curl_setopt($ch, CURLOPT_POST, true);
  24.  
  25. curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
  26. curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 30);
  27. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  28. $response = curl_exec($ch);
  29.  
  30. curl_close($ch);
  31.  
  32. echo "<xmp>".$response."</xmp>";
Via Guzzle
  1. // Recebendo a notificação da Gerencianet
  2. $postNotificacao = $_POST["notificacao"];
  3.  
  4.  
  5. // Consultando os detalhes da notificação
  6. $url = "https://go.gerencianet.com.br/api/notificacao/xml";
  7. $token = "token";
  8.  
  9. $xml = "<?xml version='1.0' encoding='utf-8'?>
  10. <integracao>
  11. <notificacao>".$postNotificacao."</notificacao>
  12. </integracao>";
  13.  
  14. $xml = str_replace(array("\n", "\r", "\t"), '', $xml);
  15.  
  16. Guzzle\Http\StaticClient::mount();
  17. $client = new \Guzzle\Http\Client($url);
  18. $request = $client->post('', null, array("token" => $token, "dados" => $xml));
  19. $response = $request->send();
  20.  
  21. echo "<xmp>".$response."</xmp>";
  1. // Recebendo a notificação da Gerencianet
  2. String postNotificacao = request.getParameter("notificacao")
  3.  
  4.  
  5. // Consultando os detalhes da notificação
  6. String url = "https://go.gerencianet.com.br/api/notificacao";
  7. String token = "token";
  8.  
  9. String xml = "<?xml version='1.0' encoding='utf-8'?>"
  10. + "<integracao>"
  11. + "<notificacao>" + postNotificacao + "</notificacao>"
  12. + "</integracao>";
  13.  
  14. HttpClient client = new DefaultHttpClient();
  15. HttpPost post = new HttpPost(url);
  16.  
  17. post.setHeader("User-Agent", HttpHeaders.USER_AGENT);
  18.  
  19. List<NameValuePair> urlParameters;
  20. urlParameters = new ArrayList<>();
  21. urlParameters.add(new BasicNameValuePair("token", token));
  22. urlParameters.add(new BasicNameValuePair("dados", xml));
  23.  
  24. post.setEntity(new UrlEncodedFormEntity(urlParameters));
  25.  
  26. HttpResponse response = client.execute(post);
  27. System.out.println("Response Code : " + response.getStatusLine().getStatusCode());
  28.  
  29. BufferedReader rd = new BufferedReader(
  30. new InputStreamReader(response.getEntity().getContent()));
  31.  
  32. StringBuilder result = new StringBuilder();
  33. String line = "";
  34. while ((line = rd.readLine()) != null) {
  35. result.append(line);
  36. }
  37.  
  38. System.out.println(result.toString());
  1. // Recebendo a notificação da Gerencianet
  2. String postNotificacao = Request.Form("notificacao").ToString()
  3.  
  4.  
  5. // Consultando os detalhes da notificação
  6. String url = "http://go.gerencianet.com.br/api/notificacao";
  7. String token = "token";
  8. String xml = "<?xml version='1.0' encoding='utf-8'?>" +
  9. "<integracao>" +
  10. "<notificacao>" + postNotificacao + "</notificacao>" +
  11. "</integracao>";
  12.  
  13. WebClient client = new WebClient();
  14. NameValueCollection postData = new NameValueCollection() { { "token", token }, { "dados", xml } };
  15. byte[] response = client.UploadValues(url, postData);
  16.  
  17. Console.WriteLine("Output: " + System.Text.Encoding.Default.GetString(response));
  1. import requests
  2.  
  3. # Recebendo a notificação da Gerencianet
  4. # Obs.: Considerando que se esteja usando o Python Flask
  5. post_notificacao = request.form['notificacao']
  6.  
  7.  
  8. # Consultando os detalhes da notificação
  9. url = "http://go.gerencianet.com.br/api/notificacao/xml"
  10. token = "token"
  11.  
  12. params = ("<?xml version='1.0' encoding='utf-8'?>" +
  13. "<integracao>" +
  14. "<notificacao>" + post_notificacao + "</notificacao>" +
  15. "</integracao>")
  16.  
  17. response = requests.post(url = url, data = { 'token': token, 'dados': params })
  18. print response.text
  1. require 'httparty'
  2.  
  3. # Recebendo a notificação da Gerencianet
  4. post_notificacao = params[:notificacao]
  5.  
  6.  
  7. # Consultando os detalhes da notificação
  8. url = "http://go.gerencianet.com.br/api/notificacao/xml"
  9. token = "token"
  10. xml = "<?xml version='1.0' encoding='utf-8'?>
  11. <integracao>
  12. <notificacao>#{post_notificacao}</notificacao>
  13. </integracao>"
  14.  
  15. 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.