{"__v":35,"_id":"578cec81fabc870e00c40b32","category":{"project":"575aeffae12cf20e002f306c","version":"575aeffae12cf20e002f306f","_id":"57852aeb87c9280e0090394d","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-07-12T17:37:47.784Z","from_sync":false,"order":10,"slug":"notificações-1","title":"Notificações"},"parentDoc":null,"project":"575aeffae12cf20e002f306c","user":"57601a13af3e090e00108059","version":{"__v":30,"_id":"575aeffae12cf20e002f306f","project":"575aeffae12cf20e002f306c","createdAt":"2016-06-10T16:51:06.080Z","releaseDate":"2016-06-10T16:51:06.080Z","categories":["575aeffae12cf20e002f3070","575af039a083950e004487f7","575af5c7ba4ed70e000ca288","57602fe5b82256240055c657","57602ff6c811102000cef302","576030909b1a9a220067ca40","57604518b82256240055c722","5761a63d207db7170022fc14","5761b9a2b65324200072d79e","576832939f0bf4190014ffdf","576832c09f0bf4190014ffe1","576832cba151c10e004316f0","576832d5bb15f40e00a288ec","576832e107b1f30e0039c645","577680bf3cee3a0e00a000bc","577ff3b1ff48990e000c6806","5783f78c5cbce30e0074e2b7","5783f86292edb92200e6101c","5783f86dbfbba719003f0d8b","5783f8755cbce30e0074e2b8","5783f8b65cbce30e0074e2b9","5783f8bf5cbce30e0074e2ba","5783f8d8ce802f0e0087d574","578529f887c9280e0090394b","57852aeb87c9280e0090394d","57866e72b2f4060e00fa39ca","57ab6d5c39c2fd1900191879","57f39451ab0ee12000bef915","582499a0d90fa027009b259e","58c29df1258e5a1900b60478"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"2016","version_clean":"1.0.0","version":"1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-18T14:49:37.544Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Antes de prosseguir, [certifique-se](https://dev.gerencianet.com.br/docs#section-bibliotecas) que foi instalada uma de nossas bibliotecas em seu servidor.\n\nAs notificações permitem que você seja informado quando uma transação (também chamada de \"cobrança\") tiver seu status alterado. Dessa forma, você poderá identificar quando um boleto for pago, por exemplo.\n\nQuando uma transação possui uma URL de notificação cadastrada, a Gerencianet dispara um POST para esta URL a cada mudança no status da cobrança.\n\nEssa notificação possui um token específico, que será o mesmo durante todo o \"ciclo de alterações\" da transação. Por exemplo:\n\n- Foi gerada uma cobrança. Seu sistema recebe um POST da Gerencianet contendo o token de notificação <code>09027955-5e06-4ff0-a9c7-46b47b8f1b27</code> e informando o status da transação - neste caso, <code>new</code> (novo);\n\n- Essa mesma cobrança teve o método de pagamento definido, então seu status mudou para <code>waiting</code> (aguardando) e, em seguida, chega uma nova notificação em seu sistema com o mesmo token <code>09027955-5e06-4ff0-a9c7-46b47b8f1b27</code>.\n\n- Essa mesma cobrança teve o pagamento confirmado, o status muda para <code>paid</code> (pago) e novamente seu sistema recebe uma notificação ainda com o token <code>09027955-5e06-4ff0-a9c7-46b47b8f1b27</code>.\n\nUm POST vai conter apenas uma informação: um token de notificação. Ou seja, se a URL cadastrada estiver preparada para ler o token na variável <code>$_POST['notification']</code> e consultar essa informação, a resposta será todos os dados informativos sobre a alteração sofrida pela cobrança, como por exemplo, o status anterior e atual da cobrança. Para tal, você precisa cadastrar uma URL de notificação na cobrança e prepará-la para mostrar/armazenar o token de notificação.\n\nA qualquer momento que o integrador consultar esse token de notificação, irá obter as informações mais atuais da cobrança, todas ordenadas de acordo com os acontecimentos. Toda alteração em status gera uma notificação.\n\nNa aba *\"Histórico de Notificações\"* é possível acompanhar todo POST de notificação disparado pelo nosso sistema. Se o integrador consulta o token enviado, consideramos que a notificação foi realizada com sucesso. Caso não consulte, tentamos novamente.\n\nPara visualizar a tabela contendo todos os status de uma transação, acesse <a href=\"https://dev.gerencianet.com.br/docs/transacoes\" target=\"_blank\">este link</a> em nossa documentação.\n\n\n## Índice\n<hr>\n\nVá direto ao ponto ­- utilize o índice abaixo e veja diretamente o que você precisa:\n\n1. [Definindo a URL para recebimento de notificações](https://dev.gerencianet.com.br/docs/notificacoes-recebendo#section-1-definindo-a-url-para-recebimento-de-notifica-es)\n\n2. [Consultando detalhes de uma notificação](https://dev.gerencianet.com.br/docs/notificacoes-recebendo#section-2-consultando-detalhes-de-uma-notifica-o)\n\n3. [Vídeos Explicativos: Notificações](https://dev.gerencianet.com.br/docs/notificacoes-recebendo#section-3-v-deos-explicativos-notifica-es)\n\n\n<br />\n## 1. Definindo a URL para recebimento de notificações\n<hr>\n\nVocê poderá definir uma URL que receberá as notificações durante a criação da cobrança (<code>createCharge</code>) ou posteriormente (<code>updateCharge</code>).\n\nUma transação gerada por meio da API pode passar por diversas alterações de status conforme interações do pagador, do integrador ou das operadoras e instituições bancárias envolvidas. Para acompanhar essas mudanças, é necessário preparar seu sistema para receber as notificações enviadas pela Gerencianet.\n\nNo momento da definição dos parâmetros para a criação da transação você poderá <a target=\"_blank\" href=\"https://files.readme.io/Z16zb2z4SYSLhBaQk1zA_Screenshot_13.png\">definir uma URL de notificação</a>. Esta URL irá receber um *token* quando uma transação sofrer uma alteração de status. Com este *token*, sua aplicação poderá realizar uma consulta em nosso webservice para obter o status da transação.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$options = [\\n\\t'client_id' => $clientId,\\n\\t'client_secret' => $clientSecret,\\n\\t'sandbox' => true\\n],\\n\\n$metadata = array('notification_url'=>'http://sua_url_aqui');\\n\\n$body = [\\n\\t'items' => $items,\\n\\t'metadata' => $metadata\\n];\\n\\ntry {\\n\\t$api = new Gerencianet($options);\\n\\t$charge = $api->createCharge([], $body);\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Código: definir URL de notificação\"\n    }\n  ]\n}\n[/block]\nCaso você não cadastre uma URL no momento de criação da transação, poderá fazê-lo através do método de alteração de metadata, por meio do endpoint <code>PUT /charge/:id/metadata</code>.\n\nVocê deve observar que o processo de notificação é realizado em duas etapas para garantir a segurança dos dados informados:\n\n1. Na primeira, seu sistema é avisado que houve uma alteração relacionada a uma transação (o webservice envia um POST com um *token* pra você);\n\n2.  Na segunda, seu sistema consulta - passando o *token* que você recebeu como parâmetro para a Gerencianet para saber detalhes sobre essa alteração.\n\n\n<br />\n## 2. Consultando detalhes de uma notificação\n<hr>\n\nA Gerencianet considera que uma notificação foi realizada com sucesso apenas após essa consulta. Enquanto seu sistema não consultar os detalhes da notificação, ele continuará sendo notificado.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n \\nrequire __DIR__.'/../../vendor/autoload.php'; // caminho relacionado ao Composer\\n \\nuse Gerencianet\\\\Exception\\\\GerencianetException;\\nuse Gerencianet\\\\Gerencianet;\\n \\n$clientId = 'your_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod)\\n$clientSecret = 'your_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod)\\n \\n$options = [\\n  'client_id' => $clientId,\\n  'client_secret' => $clientSecret,\\n  'sandbox' => true // altere conforme o ambiente (true = desenvolvimento e false = producao)\\n];\\n \\n/*\\n* Este token será recebido em sua variável que representa os parâmetros do POST\\n* Ex.: $_POST['notification']\\n*/\\n$token = $_POST[\\\"notification\\\"];\\n \\n$params = [\\n  'token' => $token\\n];\\n \\ntry {\\n    $api = new Gerencianet($options);\\n    $chargeNotification = $api->getNotification($params, []);\\n  // Para identificar o status atual da sua transação você deverá contar o número de situações contidas no array, pois a última posição guarda sempre o último status. Veja na um modelo de respostas na seção \\\"Exemplos de respostas\\\" abaixo.\\n  \\n  // Veja abaixo como acessar o ID e a String referente ao último status da transação.\\n\\t\\t\\n\\t\\t// Conta o tamanho do array data (que armazena o resultado)\\n  \\t$i = count($chargeNotification[\\\"data\\\"]);\\n  \\t// Pega o último Object chargeStatus\\n\\t\\t$ultimoStatus = $chargeNotification[\\\"data\\\"][$i-1];\\n  \\t// Acessando o array Status\\n \\t\\t$status = $ultimoStatus[\\\"status\\\"];\\n\\t\\t// Obtendo o ID da transação\\t\\t\\n\\t\\t$charge_id = $ultimoStatus[\\\"identifiers\\\"][\\\"charge_id\\\"];\\n  \\t// Obtendo a String do status atual\\n\\t\\t$statusAtual = $status[\\\"current\\\"];\\n\\t\\t\\n  \\t// Com estas informações, você poderá consultar sua base de dados e atualizar o status da transação especifica, uma vez que você possui o \\\"charge_id\\\" e a String do STATUS\\n  \\n\\t\\techo \\\"O id da transação é: \\\".$charge_id.\\\" seu novo status é: \\\".$statusAtual;\\n \\n    //print_r($chargeNotification);\\n} catch (GerencianetException $e) {\\n    print_r($e->code);\\n    print_r($e->error);\\n    print_r($e->errorDescription);\\n} catch (Exception $e) {\\n    print_r($e->getMessage());\\n}\",\n      \"language\": \"php\",\n      \"name\": \"PHP\"\n    },\n    {\n      \"code\": \"'use strict';\\n \\nvar Gerencianet = require('gn-api-sdk-node');\\n \\nvar clientId = 'your_client_id';\\nvar clientSecret = 'your_client_secret';\\n \\nvar options = {\\n  client_id: clientId,\\n  client_secret: clientSecret,\\n  sandbox: true\\n}\\n \\n/*\\n* Este token será recebido em sua variável que representa os parâmetros do POST\\n* Ex.: req.body['notification']\\n*/\\nvar token = 'token_da_notificacao';\\n \\nvar params = {\\n  token: token\\n}\\n \\nvar gerencianet = new Gerencianet(options);\\n \\ngerencianet\\n  .getNotification(params)\\n  .then(console.log)\\n  .catch(console.log)\\n  .done();\",\n      \"language\": \"javascript\",\n      \"name\": \"NodeJS\"\n    },\n    {\n      \"code\": \"require \\\"gerencianet\\\"\\n \\noptions = {\\n  client_id: \\\"client_id\\\",\\n  client_secret: \\\"client_secret\\\",\\n  sandbox: true\\n}\\n \\n# Este token será recebido em sua variável que representa os parâmetros do POST\\n# Ex.: req.body['notification']\\n \\nparams = {\\n  token: \\\"token_da_notificacao\\\"\\n}\\n \\ngerencianet = Gerencianet.new(options)\\ngerencianet.get_notification(params: params)\",\n      \"language\": \"ruby\",\n      \"name\": \"\"\n    },\n    {\n      \"code\": \"from gerencianet import Gerencianet\\n \\noptions = {\\n    'client_id': 'client_id',\\n    'client_secret': 'client_secret',\\n    'sandbox': True\\n}\\n \\ngn = Gerencianet(options)\\n \\nparams = {\\n    'token': notification\\n}\\n \\nresponse =  gn.get_notification(params=params)\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"// supposing that this is a post route\\npublic void NotificationRoute(notification) {\\n \\tvar param = new {\\n    \\ttoken = notification\\n  \\t};\\n \\n  \\tdynamic endpoints = new Endpoints(\\\"client_id\\\", \\\"client_secret\\\", true);\\n  \\tresponse = endpoints.GetNotification(param);\\n}\",\n      \"language\": \"asp\",\n      \"name\": \".NET\"\n    },\n    {\n      \"code\": \"/* Para que a SDK Java funcione corretamente, é necessário que a instanciação do módulo seja feita através da criação de um objeto do tipo Gerencianet.\\n\\nSempre que quisermos chamar uma função da API, basta invocar o método call do objeto Gerencianet, passando como parâmetro o nome do método, os parâmetros da requisição (sempre será um HashMap<String, String>), e o \\\"body\\\", que consiste nas propriedades a serem passadas como argumento na chamada de um função da SDK. O \\\"body\\\" pode ser declarado de duas formas: um JSONObject ou um Map<String, Object>.\\n\\nEsta estrutura é necessária para representar o corpo da requisição http que é enviada à um determinado endpoint. Se o \\\"body\\\" for um JSONObject, o retorno do método call será um JSONObject, se for um Map<String, Object>, o retorno do método call será um Map<String, Object>\\n\\nA seguir, disponibilizamos links de nosso Github mostrando duas formas diferentes de retorno: JSONObject\\ne Map<String, Object>\\n\\n\\nJSONObject\\n\\nhttps://github.com/gerencianet/gn-api-sdk-java-examples/blob/master/src/main/java/br/com/gerencianet/notification/json/DetailNotification.java\\n\\n\\nMap<String, Object>\\n\\nhttps://github.com/gerencianet/gn-api-sdk-java-examples/blob/master/src/main/java/br/com/gerencianet/notification/map/DetailNotification.java\\n\\n*/\",\n      \"language\": \"java\"\n    },\n    {\n      \"code\": \"interface\\nfunction GetNotifications(Token: Integer): String;\\n\\nimplementation\\nuses\\n  uGerenciaNetClientUtilities, uGerenciaClient;\\n\\nfunction GetNotifications(Token: Integer): String;\\nvar\\n  Params: String;\\nbegin\\n\\tEnableService( 'GerenciaNet.dll' ); \\n  \\tConfigureService( ToPAnsiChar( 'client_id' ),ToPAnsiChar( 'client_secret' ),'sandbox','config.json',''); \\n  \\tGerenciaNetAuthorize();\\n\\n    Params := CreateRequestParams( [ 'token='+Token ] ).Text;\\n    Result := ExecuteGerenciaNetRequest( 'getNotification',Params,'','' );\\nend;\",\n      \"language\": \"json\",\n      \"name\": \"Delphi\"\n    }\n  ]\n}\n[/block]\n### Exemplos de respostas\n\nA seguir alguns exemplos de respostas de notificações:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"code\\\": 200, // retorno HTTP \\\"200\\\" informando que o pedido foi bem sucedido\\n  \\\"data\\\": [{\\n    \\\"id\\\": 1,\\n    \\\"type\\\": \\\"charge\\\",\\n    \\\"custom_id\\\": null,\\n    \\\"status\\\": {\\n      \\\"current\\\": \\\"new\\\",\\n      \\\"previous\\\": null\\n    },\\n    \\\"identifiers\\\": {\\n      \\\"charge_id\\\": 1002\\n    }\\n  }, {\\n    \\\"id\\\": 2,\\n    \\\"type\\\": \\\"charge\\\",\\n    \\\"custom_id\\\": null,\\n    \\\"status\\\": {\\n      \\\"current\\\": \\\"waiting\\\",\\n      \\\"previous\\\": \\\"new\\\"\\n    },\\n    \\\"identifiers\\\": {\\n      \\\"charge_id\\\": 1002\\n    }\\n  }, {\\n    \\\"id\\\": 3, // array representando o último status da transação\\n    \\\"type\\\": \\\"charge\\\",\\n    \\\"custom_id\\\": null,\\n    \\\"status\\\": {\\n      \\\"current\\\": \\\"paid\\\", // status ATUAL da transação: paid (\\\"pago\\\")\\n      \\\"previous\\\": \\\"waiting\\\" // status ANTERIOR da transação: waiting (\\\"aguardando\\\")\\n    },\\n    \\\"identifiers\\\": {\\n      \\\"charge_id\\\": 1002\\n    },\\n    \\\"value\\\": 2000\\n  }]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Transação\"\n    },\n    {\n      \"code\": \"{\\n  \\\"code\\\": 200,\\n  \\\"data\\\": [{\\n    \\\"id\\\": 1,\\n    \\\"type\\\": \\\"subscription\\\",\\n    \\\"custom_id\\\": null,\\n    \\\"status\\\": {\\n      \\\"current\\\": \\\"new\\\",\\n      \\\"previous\\\": null\\n    },\\n    \\\"identifiers\\\": {\\n      \\\"subscription_id\\\": 1001\\n    }\\n  }, {\\n    \\\"id\\\": 2,\\n    \\\"type\\\": \\\"subscription_charge\\\",\\n    \\\"custom_id\\\": null,\\n    \\\"status\\\": {\\n      \\\"current\\\": \\\"new\\\",\\n      \\\"previous\\\": null\\n    },\\n    \\\"identifiers\\\": {\\n      \\\"subscription_id\\\": 1001,\\n      \\\"charge_id\\\": 1043\\n    }\\n  }]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Assinatura\"\n    },\n    {\n      \"code\": \"{\\n  \\\"code\\\": 200,\\n  \\\"data\\\": [{\\n    \\\"id\\\": 1,\\n    \\\"type\\\": \\\"carnet\\\",\\n    \\\"custom_id\\\": null,\\n    \\\"status\\\": {\\n      \\\"current\\\": \\\"active\\\",\\n      \\\"previous\\\": null\\n    },\\n    \\\"identifiers\\\": {\\n      \\\"carnet_id\\\": 1001\\n    }\\n  }, {\\n    \\\"id\\\": 2,\\n    \\\"type\\\": \\\"carnet_charge\\\",\\n    \\\"custom_id\\\": null,\\n    \\\"status\\\": {\\n      \\\"current\\\": \\\"new\\\",\\n      \\\"previous\\\": null\\n    },\\n    \\\"identifiers\\\": {\\n      \\\"carnet_id\\\": 1001,\\n      \\\"charge_id\\\": 1044\\n    }\\n  }, {\\n    \\\"id\\\": 3,\\n    \\\"type\\\": \\\"carnet_charge\\\",\\n    \\\"custom_id\\\": null,\\n    \\\"status\\\": {\\n      \\\"current\\\": \\\"waiting\\\",\\n      \\\"previous\\\": \\\"new\\\"\\n    },\\n    \\\"identifiers\\\": {\\n      \\\"carnet_id\\\": 1001,\\n      \\\"charge_id\\\": 1044\\n    }\\n  }, {\\n    \\\"id\\\": 4,\\n    \\\"type\\\": \\\"carnet_charge\\\",\\n    \\\"custom_id\\\": null,\\n    \\\"status\\\": {\\n      \\\"current\\\": \\\"new\\\",\\n      \\\"previous\\\": null\\n    },\\n    \\\"identifiers\\\": {\\n      \\\"carnet_id\\\": 1001,\\n      \\\"charge_id\\\": 1045\\n    }\\n  }, {\\n    \\\"id\\\": 5,\\n    \\\"type\\\": \\\"carnet_charge\\\",\\n    \\\"custom_id\\\": null,\\n    \\\"status\\\": {\\n      \\\"current\\\": \\\"waiting\\\",\\n      \\\"previous\\\": \\\"new\\\"\\n    },\\n    \\\"identifiers\\\": {\\n      \\\"carnet_id\\\": 1001,\\n      \\\"charge_id\\\": 1045\\n    }\\n  }]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Carnê\"\n    }\n  ]\n}\n[/block]\n### Explicação dos parâmetros de resposta:\n\nA resposta de uma notificação será sempre um *array* contendo as mudanças que ocorreram em uma transação comum, assinatura, carnê, transação de assinatura ou transação de carnê nos últimos 6 meses.\n\nNote que notificações relacionadas a assinatura e carnê podem ser acompanhadas também de alterações em suas transações (ou parcelas).\n\n### Tags de resposta:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"id\",\n    \"h-0\": \"Tag\",\n    \"h-1\": \"Descrição\",\n    \"0-1\": \"Indicador de ordem, iniciado em 1. É incrementado para cada mudança de um token de notificação.\",\n    \"1-0\": \"type\",\n    \"1-1\": \"Determina o tipo da cobrança que sofreu a alteração.\\n\\n<span class=\\\"tab1\\\"><em>Os tipos possíveis são:</em></span>\\n<div class=\\\"tab2\\\"><code>charge</code>// A alteração ocorreu em uma transação</div>\\n\\n<div class=\\\"tab2\\\"><code>subscription</code>//  A alteração ocorreu em uma assinatura</div>\\n\\n<div class=\\\"tab2\\\"><code>carnet</code>// A alteração ocorreu em um carnê</div>\\n\\n<div class=\\\"tab2\\\"><code>subscription_charge</code>// A alteração ocorreu em uma parcela de assinatura</div>\\n\\n<div class=\\\"tab2\\\"><code>carnet_charge</code>// A alteração ocorreu em uma parcela de carnê</div>\",\n    \"2-0\": \"custom_id\",\n    \"2-1\": \"Informa o identificador da cobrança definido pelo integrador, se existir.\",\n    \"3-0\": \"status\",\n    \"3-1\": \"Define o status atual e o status anterior da transação, assinatura ou carnê.\\n\\n<span class=\\\"tab1\\\"><em>Atributos de status:</em></span>\\n\\n<div class=\\\"tab2\\\"><code>current</code> // Status atual da cobrança</div>\\n\\n<div class=\\\"tab2\\\"><code>previous</code> // Status da cobrança antes da alteração</div>\",\n    \"4-1\": \"Identificadores que representam a cobrança. Os atributos desta tag podem variar conforme o tipo da alteração (parâmetro <code>type</code>).\\n\\n<span class=\\\"tab1\\\"><em>Identificadores que podem ser retornados:</em></span>\\n\\n<div class=\\\"tab2\\\"><code>charge_id</code> // Retornado quando <code>type = \\\"charge\\\"</code></div>\\n\\n<div class=\\\"tab2\\\"><code>subscription_id</code> // Retornado quando <code>type = \\\"subscription\\\"</code></div>\\n\\n<div class=\\\"tab2\\\"><code>carnet_id</code> // Retornado quando <code>type = \\\"carnet\\\"</code></div>\\n\\n<div class=\\\"tab2\\\"><code>charge_id</code> e <code>subscription_id</code>  // Retornados quando <code>type = \\\"subscription_charge\\\"</code></div>\\n\\n<div class=\\\"tab2\\\"><code>charge_id</code> e <code>carnet_id</code>   // Retornados quando <code>type = \\\"carnet_charge\\\"</code></div>\",\n    \"4-0\": \"identifiers\",\n    \"5-0\": \"value\",\n    \"5-1\": \"Valor que acompanha a alteração. Esta tag existirá quando a alteração for uma confirmação de pagamento.\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]\n<strong class=\"atributo-obrigatorio-texto\">* valor obrigatório</strong>\n\n\n## 3. Vídeos Explicativos: Notificações\n<hr>\n\nPensando em oferecer novos meios de transmitir informações, a Gerencianet disponibiliza os vídeos a seguir com o objetivo de explicar, de maneira clara e objetiva, como implementar e configurar sua URL de notificação para recebimento de *callbacks*.\n\n\n### Implementando as notificações - Callback ou Retorno Automático (via Playground)\n[block:html]\n{\n  \"html\": \"<iframe width=\\\"560\\\" height=\\\"315\\\" src=\\\"https://www.youtube.com/embed/ENuawROOfE4\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>\"\n}\n[/block]\n### Configurando sua URL de notificações (integração API Gerencianet)\n[block:html]\n{\n  \"html\": \"<iframe width=\\\"560\\\" height=\\\"315\\\" src=\\\"https://www.youtube.com/embed/-_yhi1FUhvg\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>\"\n}\n[/block]\nPara acesso às demais aulas, de outros assuntos, acesse a seção \"[Curso Online de Integrações](https://dev.gerencianet.com.br/docs/curso-online-gerencianet)\".\n\n\n## Informação Complementar: *status das transações*\n<hr>\n\nCaso queira, veja [neste link](https://dev.gerencianet.com.br/docs/transacoes) a tabela contendo os possíveis status de uma transação.","excerpt":"Você está em: *\"Notificações > Recebendo as notificações\"*","slug":"notificacoes-recebendo","type":"basic","title":"Recebendo as notificações"}

Recebendo as notificações

Você está em: *"Notificações > Recebendo as notificações"*

Antes de prosseguir, [certifique-se](https://dev.gerencianet.com.br/docs#section-bibliotecas) que foi instalada uma de nossas bibliotecas em seu servidor. As notificações permitem que você seja informado quando uma transação (também chamada de "cobrança") tiver seu status alterado. Dessa forma, você poderá identificar quando um boleto for pago, por exemplo. Quando uma transação possui uma URL de notificação cadastrada, a Gerencianet dispara um POST para esta URL a cada mudança no status da cobrança. Essa notificação possui um token específico, que será o mesmo durante todo o "ciclo de alterações" da transação. Por exemplo: - Foi gerada uma cobrança. Seu sistema recebe um POST da Gerencianet contendo o token de notificação <code>09027955-5e06-4ff0-a9c7-46b47b8f1b27</code> e informando o status da transação - neste caso, <code>new</code> (novo); - Essa mesma cobrança teve o método de pagamento definido, então seu status mudou para <code>waiting</code> (aguardando) e, em seguida, chega uma nova notificação em seu sistema com o mesmo token <code>09027955-5e06-4ff0-a9c7-46b47b8f1b27</code>. - Essa mesma cobrança teve o pagamento confirmado, o status muda para <code>paid</code> (pago) e novamente seu sistema recebe uma notificação ainda com o token <code>09027955-5e06-4ff0-a9c7-46b47b8f1b27</code>. Um POST vai conter apenas uma informação: um token de notificação. Ou seja, se a URL cadastrada estiver preparada para ler o token na variável <code>$_POST['notification']</code> e consultar essa informação, a resposta será todos os dados informativos sobre a alteração sofrida pela cobrança, como por exemplo, o status anterior e atual da cobrança. Para tal, você precisa cadastrar uma URL de notificação na cobrança e prepará-la para mostrar/armazenar o token de notificação. A qualquer momento que o integrador consultar esse token de notificação, irá obter as informações mais atuais da cobrança, todas ordenadas de acordo com os acontecimentos. Toda alteração em status gera uma notificação. Na aba *"Histórico de Notificações"* é possível acompanhar todo POST de notificação disparado pelo nosso sistema. Se o integrador consulta o token enviado, consideramos que a notificação foi realizada com sucesso. Caso não consulte, tentamos novamente. Para visualizar a tabela contendo todos os status de uma transação, acesse <a href="https://dev.gerencianet.com.br/docs/transacoes" target="_blank">este link</a> em nossa documentação. ## Índice <hr> Vá direto ao ponto ­- utilize o índice abaixo e veja diretamente o que você precisa: 1. [Definindo a URL para recebimento de notificações](https://dev.gerencianet.com.br/docs/notificacoes-recebendo#section-1-definindo-a-url-para-recebimento-de-notifica-es) 2. [Consultando detalhes de uma notificação](https://dev.gerencianet.com.br/docs/notificacoes-recebendo#section-2-consultando-detalhes-de-uma-notifica-o) 3. [Vídeos Explicativos: Notificações](https://dev.gerencianet.com.br/docs/notificacoes-recebendo#section-3-v-deos-explicativos-notifica-es) <br /> ## 1. Definindo a URL para recebimento de notificações <hr> Você poderá definir uma URL que receberá as notificações durante a criação da cobrança (<code>createCharge</code>) ou posteriormente (<code>updateCharge</code>). Uma transação gerada por meio da API pode passar por diversas alterações de status conforme interações do pagador, do integrador ou das operadoras e instituições bancárias envolvidas. Para acompanhar essas mudanças, é necessário preparar seu sistema para receber as notificações enviadas pela Gerencianet. No momento da definição dos parâmetros para a criação da transação você poderá <a target="_blank" href="https://files.readme.io/Z16zb2z4SYSLhBaQk1zA_Screenshot_13.png">definir uma URL de notificação</a>. Esta URL irá receber um *token* quando uma transação sofrer uma alteração de status. Com este *token*, sua aplicação poderá realizar uma consulta em nosso webservice para obter o status da transação. [block:code] { "codes": [ { "code": "$options = [\n\t'client_id' => $clientId,\n\t'client_secret' => $clientSecret,\n\t'sandbox' => true\n],\n\n$metadata = array('notification_url'=>'http://sua_url_aqui');\n\n$body = [\n\t'items' => $items,\n\t'metadata' => $metadata\n];\n\ntry {\n\t$api = new Gerencianet($options);\n\t$charge = $api->createCharge([], $body);\n}", "language": "json", "name": "Código: definir URL de notificação" } ] } [/block] Caso você não cadastre uma URL no momento de criação da transação, poderá fazê-lo através do método de alteração de metadata, por meio do endpoint <code>PUT /charge/:id/metadata</code>. Você deve observar que o processo de notificação é realizado em duas etapas para garantir a segurança dos dados informados: 1. Na primeira, seu sistema é avisado que houve uma alteração relacionada a uma transação (o webservice envia um POST com um *token* pra você); 2. Na segunda, seu sistema consulta - passando o *token* que você recebeu como parâmetro para a Gerencianet para saber detalhes sobre essa alteração. <br /> ## 2. Consultando detalhes de uma notificação <hr> A Gerencianet considera que uma notificação foi realizada com sucesso apenas após essa consulta. Enquanto seu sistema não consultar os detalhes da notificação, ele continuará sendo notificado. [block:code] { "codes": [ { "code": "<?php\n \nrequire __DIR__.'/../../vendor/autoload.php'; // caminho relacionado ao Composer\n \nuse Gerencianet\\Exception\\GerencianetException;\nuse Gerencianet\\Gerencianet;\n \n$clientId = 'your_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod)\n$clientSecret = 'your_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod)\n \n$options = [\n 'client_id' => $clientId,\n 'client_secret' => $clientSecret,\n 'sandbox' => true // altere conforme o ambiente (true = desenvolvimento e false = producao)\n];\n \n/*\n* Este token será recebido em sua variável que representa os parâmetros do POST\n* Ex.: $_POST['notification']\n*/\n$token = $_POST[\"notification\"];\n \n$params = [\n 'token' => $token\n];\n \ntry {\n $api = new Gerencianet($options);\n $chargeNotification = $api->getNotification($params, []);\n // Para identificar o status atual da sua transação você deverá contar o número de situações contidas no array, pois a última posição guarda sempre o último status. Veja na um modelo de respostas na seção \"Exemplos de respostas\" abaixo.\n \n // Veja abaixo como acessar o ID e a String referente ao último status da transação.\n\t\t\n\t\t// Conta o tamanho do array data (que armazena o resultado)\n \t$i = count($chargeNotification[\"data\"]);\n \t// Pega o último Object chargeStatus\n\t\t$ultimoStatus = $chargeNotification[\"data\"][$i-1];\n \t// Acessando o array Status\n \t\t$status = $ultimoStatus[\"status\"];\n\t\t// Obtendo o ID da transação\t\t\n\t\t$charge_id = $ultimoStatus[\"identifiers\"][\"charge_id\"];\n \t// Obtendo a String do status atual\n\t\t$statusAtual = $status[\"current\"];\n\t\t\n \t// Com estas informações, você poderá consultar sua base de dados e atualizar o status da transação especifica, uma vez que você possui o \"charge_id\" e a String do STATUS\n \n\t\techo \"O id da transação é: \".$charge_id.\" seu novo status é: \".$statusAtual;\n \n //print_r($chargeNotification);\n} catch (GerencianetException $e) {\n print_r($e->code);\n print_r($e->error);\n print_r($e->errorDescription);\n} catch (Exception $e) {\n print_r($e->getMessage());\n}", "language": "php", "name": "PHP" }, { "code": "'use strict';\n \nvar Gerencianet = require('gn-api-sdk-node');\n \nvar clientId = 'your_client_id';\nvar clientSecret = 'your_client_secret';\n \nvar options = {\n client_id: clientId,\n client_secret: clientSecret,\n sandbox: true\n}\n \n/*\n* Este token será recebido em sua variável que representa os parâmetros do POST\n* Ex.: req.body['notification']\n*/\nvar token = 'token_da_notificacao';\n \nvar params = {\n token: token\n}\n \nvar gerencianet = new Gerencianet(options);\n \ngerencianet\n .getNotification(params)\n .then(console.log)\n .catch(console.log)\n .done();", "language": "javascript", "name": "NodeJS" }, { "code": "require \"gerencianet\"\n \noptions = {\n client_id: \"client_id\",\n client_secret: \"client_secret\",\n sandbox: true\n}\n \n# Este token será recebido em sua variável que representa os parâmetros do POST\n# Ex.: req.body['notification']\n \nparams = {\n token: \"token_da_notificacao\"\n}\n \ngerencianet = Gerencianet.new(options)\ngerencianet.get_notification(params: params)", "language": "ruby", "name": "" }, { "code": "from gerencianet import Gerencianet\n \noptions = {\n 'client_id': 'client_id',\n 'client_secret': 'client_secret',\n 'sandbox': True\n}\n \ngn = Gerencianet(options)\n \nparams = {\n 'token': notification\n}\n \nresponse = gn.get_notification(params=params)", "language": "python" }, { "code": "// supposing that this is a post route\npublic void NotificationRoute(notification) {\n \tvar param = new {\n \ttoken = notification\n \t};\n \n \tdynamic endpoints = new Endpoints(\"client_id\", \"client_secret\", true);\n \tresponse = endpoints.GetNotification(param);\n}", "language": "asp", "name": ".NET" }, { "code": "/* Para que a SDK Java funcione corretamente, é necessário que a instanciação do módulo seja feita através da criação de um objeto do tipo Gerencianet.\n\nSempre que quisermos chamar uma função da API, basta invocar o método call do objeto Gerencianet, passando como parâmetro o nome do método, os parâmetros da requisição (sempre será um HashMap<String, String>), e o \"body\", que consiste nas propriedades a serem passadas como argumento na chamada de um função da SDK. O \"body\" pode ser declarado de duas formas: um JSONObject ou um Map<String, Object>.\n\nEsta estrutura é necessária para representar o corpo da requisição http que é enviada à um determinado endpoint. Se o \"body\" for um JSONObject, o retorno do método call será um JSONObject, se for um Map<String, Object>, o retorno do método call será um Map<String, Object>\n\nA seguir, disponibilizamos links de nosso Github mostrando duas formas diferentes de retorno: JSONObject\ne Map<String, Object>\n\n\nJSONObject\n\nhttps://github.com/gerencianet/gn-api-sdk-java-examples/blob/master/src/main/java/br/com/gerencianet/notification/json/DetailNotification.java\n\n\nMap<String, Object>\n\nhttps://github.com/gerencianet/gn-api-sdk-java-examples/blob/master/src/main/java/br/com/gerencianet/notification/map/DetailNotification.java\n\n*/", "language": "java" }, { "code": "interface\nfunction GetNotifications(Token: Integer): String;\n\nimplementation\nuses\n uGerenciaNetClientUtilities, uGerenciaClient;\n\nfunction GetNotifications(Token: Integer): String;\nvar\n Params: String;\nbegin\n\tEnableService( 'GerenciaNet.dll' ); \n \tConfigureService( ToPAnsiChar( 'client_id' ),ToPAnsiChar( 'client_secret' ),'sandbox','config.json',''); \n \tGerenciaNetAuthorize();\n\n Params := CreateRequestParams( [ 'token='+Token ] ).Text;\n Result := ExecuteGerenciaNetRequest( 'getNotification',Params,'','' );\nend;", "language": "json", "name": "Delphi" } ] } [/block] ### Exemplos de respostas A seguir alguns exemplos de respostas de notificações: [block:code] { "codes": [ { "code": "{\n \"code\": 200, // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n \"data\": [{\n \"id\": 1,\n \"type\": \"charge\",\n \"custom_id\": null,\n \"status\": {\n \"current\": \"new\",\n \"previous\": null\n },\n \"identifiers\": {\n \"charge_id\": 1002\n }\n }, {\n \"id\": 2,\n \"type\": \"charge\",\n \"custom_id\": null,\n \"status\": {\n \"current\": \"waiting\",\n \"previous\": \"new\"\n },\n \"identifiers\": {\n \"charge_id\": 1002\n }\n }, {\n \"id\": 3, // array representando o último status da transação\n \"type\": \"charge\",\n \"custom_id\": null,\n \"status\": {\n \"current\": \"paid\", // status ATUAL da transação: paid (\"pago\")\n \"previous\": \"waiting\" // status ANTERIOR da transação: waiting (\"aguardando\")\n },\n \"identifiers\": {\n \"charge_id\": 1002\n },\n \"value\": 2000\n }]\n}", "language": "json", "name": "Transação" }, { "code": "{\n \"code\": 200,\n \"data\": [{\n \"id\": 1,\n \"type\": \"subscription\",\n \"custom_id\": null,\n \"status\": {\n \"current\": \"new\",\n \"previous\": null\n },\n \"identifiers\": {\n \"subscription_id\": 1001\n }\n }, {\n \"id\": 2,\n \"type\": \"subscription_charge\",\n \"custom_id\": null,\n \"status\": {\n \"current\": \"new\",\n \"previous\": null\n },\n \"identifiers\": {\n \"subscription_id\": 1001,\n \"charge_id\": 1043\n }\n }]\n}", "language": "json", "name": "Assinatura" }, { "code": "{\n \"code\": 200,\n \"data\": [{\n \"id\": 1,\n \"type\": \"carnet\",\n \"custom_id\": null,\n \"status\": {\n \"current\": \"active\",\n \"previous\": null\n },\n \"identifiers\": {\n \"carnet_id\": 1001\n }\n }, {\n \"id\": 2,\n \"type\": \"carnet_charge\",\n \"custom_id\": null,\n \"status\": {\n \"current\": \"new\",\n \"previous\": null\n },\n \"identifiers\": {\n \"carnet_id\": 1001,\n \"charge_id\": 1044\n }\n }, {\n \"id\": 3,\n \"type\": \"carnet_charge\",\n \"custom_id\": null,\n \"status\": {\n \"current\": \"waiting\",\n \"previous\": \"new\"\n },\n \"identifiers\": {\n \"carnet_id\": 1001,\n \"charge_id\": 1044\n }\n }, {\n \"id\": 4,\n \"type\": \"carnet_charge\",\n \"custom_id\": null,\n \"status\": {\n \"current\": \"new\",\n \"previous\": null\n },\n \"identifiers\": {\n \"carnet_id\": 1001,\n \"charge_id\": 1045\n }\n }, {\n \"id\": 5,\n \"type\": \"carnet_charge\",\n \"custom_id\": null,\n \"status\": {\n \"current\": \"waiting\",\n \"previous\": \"new\"\n },\n \"identifiers\": {\n \"carnet_id\": 1001,\n \"charge_id\": 1045\n }\n }]\n}", "language": "json", "name": "Carnê" } ] } [/block] ### Explicação dos parâmetros de resposta: A resposta de uma notificação será sempre um *array* contendo as mudanças que ocorreram em uma transação comum, assinatura, carnê, transação de assinatura ou transação de carnê nos últimos 6 meses. Note que notificações relacionadas a assinatura e carnê podem ser acompanhadas também de alterações em suas transações (ou parcelas). ### Tags de resposta: [block:parameters] { "data": { "0-0": "id", "h-0": "Tag", "h-1": "Descrição", "0-1": "Indicador de ordem, iniciado em 1. É incrementado para cada mudança de um token de notificação.", "1-0": "type", "1-1": "Determina o tipo da cobrança que sofreu a alteração.\n\n<span class=\"tab1\"><em>Os tipos possíveis são:</em></span>\n<div class=\"tab2\"><code>charge</code>// A alteração ocorreu em uma transação</div>\n\n<div class=\"tab2\"><code>subscription</code>// A alteração ocorreu em uma assinatura</div>\n\n<div class=\"tab2\"><code>carnet</code>// A alteração ocorreu em um carnê</div>\n\n<div class=\"tab2\"><code>subscription_charge</code>// A alteração ocorreu em uma parcela de assinatura</div>\n\n<div class=\"tab2\"><code>carnet_charge</code>// A alteração ocorreu em uma parcela de carnê</div>", "2-0": "custom_id", "2-1": "Informa o identificador da cobrança definido pelo integrador, se existir.", "3-0": "status", "3-1": "Define o status atual e o status anterior da transação, assinatura ou carnê.\n\n<span class=\"tab1\"><em>Atributos de status:</em></span>\n\n<div class=\"tab2\"><code>current</code> // Status atual da cobrança</div>\n\n<div class=\"tab2\"><code>previous</code> // Status da cobrança antes da alteração</div>", "4-1": "Identificadores que representam a cobrança. Os atributos desta tag podem variar conforme o tipo da alteração (parâmetro <code>type</code>).\n\n<span class=\"tab1\"><em>Identificadores que podem ser retornados:</em></span>\n\n<div class=\"tab2\"><code>charge_id</code> // Retornado quando <code>type = \"charge\"</code></div>\n\n<div class=\"tab2\"><code>subscription_id</code> // Retornado quando <code>type = \"subscription\"</code></div>\n\n<div class=\"tab2\"><code>carnet_id</code> // Retornado quando <code>type = \"carnet\"</code></div>\n\n<div class=\"tab2\"><code>charge_id</code> e <code>subscription_id</code> // Retornados quando <code>type = \"subscription_charge\"</code></div>\n\n<div class=\"tab2\"><code>charge_id</code> e <code>carnet_id</code> // Retornados quando <code>type = \"carnet_charge\"</code></div>", "4-0": "identifiers", "5-0": "value", "5-1": "Valor que acompanha a alteração. Esta tag existirá quando a alteração for uma confirmação de pagamento." }, "cols": 2, "rows": 6 } [/block] <strong class="atributo-obrigatorio-texto">* valor obrigatório</strong> ## 3. Vídeos Explicativos: Notificações <hr> Pensando em oferecer novos meios de transmitir informações, a Gerencianet disponibiliza os vídeos a seguir com o objetivo de explicar, de maneira clara e objetiva, como implementar e configurar sua URL de notificação para recebimento de *callbacks*. ### Implementando as notificações - Callback ou Retorno Automático (via Playground) [block:html] { "html": "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/ENuawROOfE4\" frameborder=\"0\" allowfullscreen></iframe>" } [/block] ### Configurando sua URL de notificações (integração API Gerencianet) [block:html] { "html": "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/-_yhi1FUhvg\" frameborder=\"0\" allowfullscreen></iframe>" } [/block] Para acesso às demais aulas, de outros assuntos, acesse a seção "[Curso Online de Integrações](https://dev.gerencianet.com.br/docs/curso-online-gerencianet)". ## Informação Complementar: *status das transações* <hr> Caso queira, veja [neste link](https://dev.gerencianet.com.br/docs/transacoes) a tabela contendo os possíveis status de uma transação.