{"_id":"5b717f7c0b125a00032aaca3","project":"575aeffae12cf20e002f306c","version":{"_id":"575aeffae12cf20e002f306f","project":"575aeffae12cf20e002f306c","__v":31,"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","5a7c4127490e52002a7f643c"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"2016","version_clean":"1.0.0","version":"1"},"category":{"_id":"57852aeb87c9280e0090394d","version":"575aeffae12cf20e002f306f","__v":0,"project":"575aeffae12cf20e002f306c","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 (callbacks)"},"user":"57601a13af3e090e00108059","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-08-13T12:54:20.988Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Esta página tem como objetivo apresentar o <code>Histórico de Notificações</code>. Este recurso está disponível na API de sua conta Gerencianet e permite visualizar os POSTs que a Gerencianet dispara para a URL de notificação definida pelo integrador. Este POST contém apenas uma informação: um token de notificação.\n\nAo término da leitura desta página, espera-se que você consiga interpretar os cenários pertinentes a notificações (callbacks), como em situações em que uma cobrança em seu sistema não foi baixada, o callback foi disparado para uma URL que você definiu previamente mas que não é mais válida, etc.\n\nOutras informações sobre o processo de definição da URL de notificação e a mecânica envolvendo a consulta de detalhes de uma notificação podem ser observadas na página [Recebendo as notificações](https://dev.gerencianet.com.br/docs/notificacoes-recebendo).\n\nVá direto ao ponto - utilize o índice abaixo para encontrar a resposta de maneira mais eficiente:\n\n- [Conhecendo mais sobre o fluxo de notificações](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-conhecendo-mais-sobre-o-fluxo-de-notifica-es)\n\n- [Exemplo 1: Notificação com \"Sucesso (200)\"](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-exemplo-1-notifica-o-com-sucesso-200-)\n\n- [Exemplo 2: Notificação com \"Falha (404)\"](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-exemplo-2-notifica-o-com-falha-404-)\n\n- [Exemplo 3: Notificação com \"Falha (301)\" ou \"Falha (302)\"](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-exemplo-3-notifica-o-com-falha-301-ou-falha-302-)\n\n- [Exemplo 4: Notificação com \"Falha (500)\"](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-exemplo-4-notifica-o-com-falha-500-)\n\n- [Códigos de status HTTP (2xx, 3xx, 4xx e 5xx)](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-c-digos-de-status-http-2xx-3xx-4xx-e-5xx-)\n\n# Conhecendo mais sobre o fluxo de notificações\n\nO fato do POST ter sido enviado com <em>Sucesso (200)</em> para sua URL de notificação não significa, por si só, que o fluxo ocorreu normalmente. Assim que você recebe o POST, precisará vir aqui consultar tais informações.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"IMPORTANTE\",\n  \"body\": \"O POST que a Gerencianet envia para sua URL **não contém as informações da cobrança, mas apenas o token de notificação.** Todas as informações sobre a referida cobrança serão retornadas assim que você consumir o endpoint <code>GET /notification/:token</code>.\"\n}\n[/block]\nO que ocorre, na realidade, é uma \"via de mão dupla\", ou seja, a Gerencianet dispara um POST para sua URL de notificação a cada mudança no status da cobrança e, em seguida, seu sistema, em posse do token de notificação, envia uma requisição de consumo ao endpoint <code>GET /notification/:token</code>, em que <code>:token</code> é o token de notificação contido no POST enviado.\n\nDessa forma, podemos considerar que:\n\n- Subaba <code>Histórico de Notificações</code> : indica os POSTs que a Gerencianet dispara para a URL de notificação cadastrada.\n\n- Subaba <code>Histórico de Requisições</code> : ao receber com sucesso em sua URL o POST da Gerencianet, seu sistema consultará o endpoint <code>GET /notification/:token</code>, em que <code>:token</code> será o token de notificação que te enviamos.\n\nO fluxo é determinado pela seguinte ordem:\n\n1. A Gerencianet dispara o POST contendo o token de notificação para a URL de notificação cadastrada sempre que houver uma mudança no status da cobrança. Detalhes podem ser observados na subaba <code>Histórico de Notificações</code>;\n\n2. Sua URL recebeu o POST, fazendo com que seu sistema envie uma requisição <code>GET</code> para a rota <code>/notification/:token</code>, em que <code>:token</code> será o token de notificação que enviamos para você. Você pode visualizar esta requisição na subaba <code>Histórico de Requisições</code>.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Se o integrador consulta o token enviado, consideramos que a notificação foi realizada com sucesso. Caso não consulte, tentamos novamente por até 3 dias.\\n\\nOu seja, se houver uma requisição ao endpoint <code>GET /notification/:token</code>, entendemos que você recebeu o POST com o token de notificação e que o consultou, recebendo como resposta todos os dados informativos sobre a alteração sofrida pela cobrança, como o status anterior e atual da cobrança.\\n\\nEsta informação pode ser visualizada na subaba <code>Histórico de Requisições</code>, buscando pelo token de notificação em questão.\",\n  \"title\": \"IMPORTANTE\"\n}\n[/block]\n<br>\n\nPara facilitar o entendimento e a visualização dos cenários, vamos a alguns exemplos:\n\n# Exemplo 1: Notificação com \"Sucesso (200)\"\n\n<br>\n\n<img src=\"https://s3-sa-east-1.amazonaws.com/pe85007/portal/wp-content/uploads/2018/08/17152450/Notificacao_Status_200.gif\" alt=\"Notificação API Gerencianet - Status 200\">\n\nNesta animação, demonstramos um cenário no qual o integrador recebeu com sucesso em sua URL de notificação o POST enviado pela Gerencianet e, em seguida, consultou em nosso webservice o conteúdo deste token de notificação.\n\nPara que você mesmo possa conferir, acesse primeiramente a subaba <code>Histórico de Notificações</code> e, em posse do token de notificação da cobrança que deseja verificar, acesse a subaba <code>Histórico de Requisições</code>, pesquise pelo referido token e, ao encontrá-lo, clique no ícone de um <em>\"olho\"</em> presente na última coluna. Desta forma, você visualizará todas as informações da referida cobrança que seu sistema consultou (leu).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"INFORMAÇÃO\",\n  \"body\": \"Na subaba <code>Histórico de Notificações</code>, a exibição da resposta <code>Sucesso (200)</code> indica apenas que o POST foi enviado com sucesso para sua URL de notificação, mas não garante que o seu sistema foi capaz de ler e gravar as informações do seu lado. Para isso, é necessário acessar a subaba <code>Histórico de Requisições</code> e localizar a linha contendo o consumo do <code>GET /notification/:token</code>.\"\n}\n[/block]\nResumo das etapas seguidas:\n\n- Gerencianet enviou com sucesso uma notificação (POST) para sua URL de notificação (vide subaba <code>Histórico de Notificações</code>);\n<br>\n  - Este POST contém apenas o token de notificação, que é <code>7dd52fed-3d0a-42c8-b3fb-fc24f1d75303</code>;\n<br>\n- Assim que a URL recebeu a notificação, seu sistema enviou uma requisição <code>GET</code> para a rota <code>/notification/7dd52fed-3d0a-42c8-b3fb-fc24f1d75303</code> (vide subaba <code>Histórico de Requisições</code>);\n<br>\n  - Neste momento, seu sistema recebeu como resposta um JSON com todos os dados informativos sobre a alteração ocorrida na cobrança;\n<br>\n- **Para este exemplo, todo o fluxo foi realizado com sucesso**: disparamos a notificação contendo o token de notificação e, em seguida, seu sistema consultou nosso webservice para saber (ler) as informações da referida cobrança.\n\n<br>\n<hr>\n\n# Exemplo 2: Notificação com \"Falha (404)\"\n\n<br>\n\n<img src=\"https://s3-sa-east-1.amazonaws.com/pe85007/portal/wp-content/uploads/2018/08/17182046/Notificacao_Status_404.gif\" alt=\"Notificação API Gerencianet - Status 200\">\n\nNesta animação, demonstramos um cenário no qual a Gerencianet efetuou o envio do POST (notificação), mas em <code>Histórico de Notificações</code> está sendo exibida a resposta <code>Falha (404)</code>.\n\nEsta <code>Falha (404)</code> indica que o recurso requisitado não foi encontrado. Você deve certificar que sua URL está correta, pois tentamos entregar a notificação na URL que você nos forneceu, mas o endereço não foi localizado.\n\nPortanto, como seu sistema não foi capaz de receber nosso callback, você **não visualizará** o consumo do <code>GET /notification/:token</code> na subaba <code>Histórico de Requisições</code>.\n\n<br>\n\n**Soluções Sugeridas:**\n\n- Você poderá ajustar o caminho da URL no lado de seu servidor;\n\n- Atualizar a URL de notificação para o novo (e correto) endereço. Para isso, você poderá enviar requisições <code>PUT</code> para a <a href=\"https://dev.gerencianet.com.br/docs/atualizar-transacoes\" target=\"_blank\">rota adequada da API</a>, atentando-se ao limite de até 7.500 requisições a cada 24 hs para este endpoint.\n\n  - Após alterar a URL de notificação, vamos continuar disparando a notificação da cobrança, mas agora para a nova URL fornecida, desde que nosso primeiro envio não tenha sido há mais de 3 dias. Neste caso, você poderá reenviar os callbacks da API <a href=\"https://gerencianet.com.br/artigo/fazer-o-reenvio-de-callback-na-api/\" target=\"_blank\" title=\"Link Externo\">seguindo orientações de nossa FAQ</a>.\n\n<br>\n<hr>\n\n# Exemplo 3: Notificação com \"Falha (301)\" ou \"Falha (302)\"\n\n<br>\n\n<img src=\"https://s3-sa-east-1.amazonaws.com/pe85007/portal/wp-content/uploads/2018/08/17181948/Notificacao_Status_301.gif\" alt=\"Notificação API Gerencianet - Status 301 e 302\">\n\nNesta animação, demonstramos um cenário no qual a Gerencianet efetuou o envio do POST (notificação), mas em <code>Histórico de Notificações</code> está sendo exibida a resposta <code>Falha (301)</code> ou <code>Falha (302)</code>.\n\nEstas situações ocorrem quando existe um redirecionamento permanente ou temporário (301 ou 302, respectivamente) em seu servidor, afetando especificamente a entrega da notificação para a URL de notificação que você definiu previamente. Alguns exemplos comuns de quando isto ocorre:\n\n- Você definiu sua URL de notificação como <code>http://www.meusite.com.br</code>, mas posteriormente instalou HTTPS/SSL em seu servidor e seu endereço ficou como <code>https://www.meusite.com.br</code>;\n\n- Sua URL de notificação era <code>https://www.meusite.com.br</code>, mas posteriormente você criou regras em seu servidor (via htaccess, web.config, etc) e o endereço passou a responder apenas como <code>https://meusite.com.br</code>.\n\n<br>\n\n**Soluções Sugeridas:**\n\n- Ajustar melhor a regra do redirecionamento 301 e/ou 302 em seu servidor;\n\n- Atualizar a URL de notificação para o novo (e correto) endereço. Para isso, você poderá enviar requisições <code>PUT</code> para a <a href=\"https://dev.gerencianet.com.br/docs/atualizar-transacoes\" target=\"_blank\">rota adequada da API</a>, atentando-se ao limite de até 7.500 requisições a cada 24 hs para este endpoint.\n\n  - Após alterar a URL de notificação, vamos continuar disparando a notificação da cobrança, mas agora para a nova URL fornecida, desde que nosso primeiro envio não tenha sido há mais de 3 dias. Neste caso, você poderá reenviar os callbacks da API <a href=\"https://gerencianet.com.br/artigo/fazer-o-reenvio-de-callback-na-api/\" target=\"_blank\" title=\"Link Externo\">seguindo orientações de nossa FAQ</a>.\n\n<br>\n<hr>\n\n# Exemplo 4: Notificação com \"Falha (500)\"\n\n<br>\n\n<img src=\"https://s3-sa-east-1.amazonaws.com/pe85007/portal/wp-content/uploads/2018/08/17182143/Notificacao_Status_500.gif\" alt=\"Notificação API Gerencianet - Status 500\">\n\nNesta animação, demonstramos um cenário no qual a Gerencianet efetuou o envio do POST (notificação), mas em <code>Histórico de Notificações</code> está sendo exibida a resposta <code>Falha (500)</code>.\n\nRespostas contendo <code>Falha (500)</code> ou <code>500 Internal Server Error</code> são um status de erro HTTP que indica que o servidor encontrou uma condição inesperada e que o impediu de atender à solicitação.\n\n**O erro, no entanto, é uma mensagem genérica e abrangente** que indica uma dificuldade no processamento em seu servidor e pode ocorrer por diversos fatores.\n\nPor isso, às vezes, **os arquivos de log de seu servidor** podem responder com um status *code 500* acompanhado de mais detalhes sobre o *request* para evitar que no futuro erros desse tipo possam voltar a acontecer. **Por isso, é sempre de extrema importância que você veja a mensagem de erro do log de seu servidor para ajudá-lo a resolver.**\n\nA seguir, listamos as possíveis causas que você pode explorar para solucionar o erro:\n\n- Arquivo de configuração em seu servidor, como <code>.htaccess</code>, <code>php.ini</code> ou <code>web.config</code> com parâmetros inválidos.\n\n- Bloqueio em seu servidor (rede, firewall, políticas, etc): algumas aplicações e serviços podem ter determinados filtros, por isso, assegure-se que <a href=\"https://gerencianet.com.br/artigo/quais-enderecos-de-ip-gerencianet-utiliza/\" target=\"_blank\">nossos endereços IP's</a> estejam liberados.\n\n- Alto consumo de recursos em seu servidor ou limite de processos: hosts compartilhados são mais suscetíveis a este tipo de situação.\n\n- Timeout em seu servidor.\n\n- Permissões incorretas no servidor em arquivos e/ou pastas.\n\n- Limite de memória e diretivas do PHP setadas no arquivo <code>php.ini</code>.\n\n- Conflito entre versões de PHP em seu host.\n\n- Possibilidade de plugins, módulos, extensões ou temas terem causado o erro por incompatibilidade ou atualizações automáticas.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"**Por se tratar de um erro genérico, é importante que você consulte e interprete os logs de erros do seu servidor.**\\n\\nCaso não tenha acesso a tais informações, entre em contato com o seu provedor de hospedagem ou sua equipe técnica responsável pela infraestrutura.\",\n  \"title\": \"DICA\"\n}\n[/block]\n<br>\n<hr>\n\n# Códigos de status HTTP (2xx, 3xx, 4xx e 5xx)\n\nA Gerencianet utiliza respostas HTTP para indicar sucesso ou falha nas requisições. Geralmente, você consegue visualizá-los através da subaba <code>Histórico de Notificações</code>.\n\nComumente, quando retornamos respostas com status <code>2xx</code> significa que houve sucesso na requisição; status <code>3xx</code> indicam redirecionamento; status <code>4xx</code> indicam falhas no envio de dados por parte do cliente; status <code>5xx</code> indicam erros internos de servidor.\n\nA seguir, tabela apresentando os códigos HTTP das respostas mais comuns, bem como suas explicações e soluções:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Código\",\n    \"h-1\": \"Nome\",\n    \"h-2\": \"Descrição\",\n    \"0-0\": \"200\",\n    \"1-0\": \"301\",\n    \"2-0\": \"302\",\n    \"3-0\": \"400\",\n    \"4-0\": \"401\",\n    \"5-0\": \"404\",\n    \"6-0\": \"500\",\n    \"0-1\": \"OK\",\n    \"1-1\": \"Moved Permanently\",\n    \"2-1\": \"Found\",\n    \"3-1\": \"Bad Request\",\n    \"4-1\": \"Unauthorized\",\n    \"5-1\": \"Not Found\",\n    \"6-1\": \"Internal Server Error\",\n    \"0-2\": \"Requisição ocorreu com sucesso.\",\n    \"1-2\": \"Redirecionamento de uma página para outro endereço, de forma permanente.\\n\\nVocê deve atualizar para a URL correta para recebimento do token de notificação.\\n\\nO ajuste da URL pode ser realizada no lado de seu servidor ou enviando requisições <code>PUT</code> para a rota adequada (<a href=\\\"https://dev.gerencianet.com.br/docs/atualizar-transacoes\\\">saiba como</a>).\",\n    \"2-2\": \"Redirecionamento de uma página para outro endereço, mas com indicação de caráter temporário, não permanente. \\n\\nVocê deve atualizar para a URL correta para recebimento do token de notificação.\\n\\nO ajuste da URL pode ser realizada no lado de seu servidor ou enviando requisições <code>PUT</code> para a rota adequada (<a href=\\\"https://dev.gerencianet.com.br/docs/atualizar-transacoes\\\">saiba como</a>).\",\n    \"3-2\": \"Algum parâmetro obrigatório não foi enviado ou foi enviado de maneira inválida.\\n\\nConsulte o \\\"histórico de requisições\\\" para interpretar os retornos da API (<a href=\\\"https://dev.gerencianet.com.br/docs/interpretando-erros-api\\\" target=\\\"_blank\\\">saiba como</a>) e corrija a sintaxe e/ou parâmetros da requisição que está enviando à API Gerencianet.\",\n    \"4-2\": \"Sem autorização para fazer a requisição. Ou seja, uma autenticação necessária falhou ou não pode ser feita.\\n\\nNo contexto da Gerencianet, isso ocorre quando se utiliza credenciais de produção no modo teste (desenvolvimento), ou vice-versa. <a href=\\\"https://gerencianet.com.br/artigo/estou-deparando-com-mensagem-de-unauthorized-sem-autorizacao-por-que\\\" target=\\\"_blank\\\">Saiba como</a> verificar e resolver.\",\n    \"5-2\": \"O recurso requisitado não foi encontrado. Ou seja, o retorno 404 surge quando o recurso (URL/documento/arquivo) requisitado a um servidor de destino não existe ou não é encontrado.\\n\\nCertifique-se que sua URL está correta para o recebimento do token de notificação.\\n\\nO ajuste da URL pode ser realizada no lado de seu servidor ou enviando requisições <code>PUT</code> para a rota adequada (<a href=\\\"https://dev.gerencianet.com.br/docs/atualizar-transacoes\\\">saiba como</a>).\",\n    \"6-2\": \"Erro interno do servidor. O servidor encontrou uma condição inesperada que impediu o cumprimento da solicitação.\\n\\nNormalmente indica erro oriundo do servidor web. Uma causa comum é algum erro no <code>.htaccess</code>. Para apurar, leia o log de erros do seu servidor.\\n\\nVale lembrar que esse tipo de erro não é acessível pelo PHP, por isso você não conseguirá ler os detalhes do log ativando a exibição dos erros no PHP.\\n\\nContudo, nem sempre o erro é do webserver, pois é possível configurar o ambiente para que erros do PHP ou outro módulo, por exemplo, sejam tratados pelo webserver com o status 500.\"\n  },\n  \"cols\": 3,\n  \"rows\": 7\n}\n[/block]","excerpt":"Você está em: *\"Notificações (callbacks) > Entendendo o fluxo das notificações\"*","slug":"entendendo-fluxo-notificacoes","type":"basic","title":"Entendendo o fluxo das notificações"}

Entendendo o fluxo das notificações

Você está em: *"Notificações (callbacks) > Entendendo o fluxo das notificações"*

Esta página tem como objetivo apresentar o <code>Histórico de Notificações</code>. Este recurso está disponível na API de sua conta Gerencianet e permite visualizar os POSTs que a Gerencianet dispara para a URL de notificação definida pelo integrador. Este POST contém apenas uma informação: um token de notificação. Ao término da leitura desta página, espera-se que você consiga interpretar os cenários pertinentes a notificações (callbacks), como em situações em que uma cobrança em seu sistema não foi baixada, o callback foi disparado para uma URL que você definiu previamente mas que não é mais válida, etc. Outras informações sobre o processo de definição da URL de notificação e a mecânica envolvendo a consulta de detalhes de uma notificação podem ser observadas na página [Recebendo as notificações](https://dev.gerencianet.com.br/docs/notificacoes-recebendo). Vá direto ao ponto - utilize o índice abaixo para encontrar a resposta de maneira mais eficiente: - [Conhecendo mais sobre o fluxo de notificações](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-conhecendo-mais-sobre-o-fluxo-de-notifica-es) - [Exemplo 1: Notificação com "Sucesso (200)"](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-exemplo-1-notifica-o-com-sucesso-200-) - [Exemplo 2: Notificação com "Falha (404)"](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-exemplo-2-notifica-o-com-falha-404-) - [Exemplo 3: Notificação com "Falha (301)" ou "Falha (302)"](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-exemplo-3-notifica-o-com-falha-301-ou-falha-302-) - [Exemplo 4: Notificação com "Falha (500)"](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-exemplo-4-notifica-o-com-falha-500-) - [Códigos de status HTTP (2xx, 3xx, 4xx e 5xx)](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-c-digos-de-status-http-2xx-3xx-4xx-e-5xx-) # Conhecendo mais sobre o fluxo de notificações O fato do POST ter sido enviado com <em>Sucesso (200)</em> para sua URL de notificação não significa, por si só, que o fluxo ocorreu normalmente. Assim que você recebe o POST, precisará vir aqui consultar tais informações. [block:callout] { "type": "warning", "title": "IMPORTANTE", "body": "O POST que a Gerencianet envia para sua URL **não contém as informações da cobrança, mas apenas o token de notificação.** Todas as informações sobre a referida cobrança serão retornadas assim que você consumir o endpoint <code>GET /notification/:token</code>." } [/block] O que ocorre, na realidade, é uma "via de mão dupla", ou seja, a Gerencianet dispara um POST para sua URL de notificação a cada mudança no status da cobrança e, em seguida, seu sistema, em posse do token de notificação, envia uma requisição de consumo ao endpoint <code>GET /notification/:token</code>, em que <code>:token</code> é o token de notificação contido no POST enviado. Dessa forma, podemos considerar que: - Subaba <code>Histórico de Notificações</code> : indica os POSTs que a Gerencianet dispara para a URL de notificação cadastrada. - Subaba <code>Histórico de Requisições</code> : ao receber com sucesso em sua URL o POST da Gerencianet, seu sistema consultará o endpoint <code>GET /notification/:token</code>, em que <code>:token</code> será o token de notificação que te enviamos. O fluxo é determinado pela seguinte ordem: 1. A Gerencianet dispara o POST contendo o token de notificação para a URL de notificação cadastrada sempre que houver uma mudança no status da cobrança. Detalhes podem ser observados na subaba <code>Histórico de Notificações</code>; 2. Sua URL recebeu o POST, fazendo com que seu sistema envie uma requisição <code>GET</code> para a rota <code>/notification/:token</code>, em que <code>:token</code> será o token de notificação que enviamos para você. Você pode visualizar esta requisição na subaba <code>Histórico de Requisições</code>. [block:callout] { "type": "warning", "body": "Se o integrador consulta o token enviado, consideramos que a notificação foi realizada com sucesso. Caso não consulte, tentamos novamente por até 3 dias.\n\nOu seja, se houver uma requisição ao endpoint <code>GET /notification/:token</code>, entendemos que você recebeu o POST com o token de notificação e que o consultou, recebendo como resposta todos os dados informativos sobre a alteração sofrida pela cobrança, como o status anterior e atual da cobrança.\n\nEsta informação pode ser visualizada na subaba <code>Histórico de Requisições</code>, buscando pelo token de notificação em questão.", "title": "IMPORTANTE" } [/block] <br> Para facilitar o entendimento e a visualização dos cenários, vamos a alguns exemplos: # Exemplo 1: Notificação com "Sucesso (200)" <br> <img src="https://s3-sa-east-1.amazonaws.com/pe85007/portal/wp-content/uploads/2018/08/17152450/Notificacao_Status_200.gif" alt="Notificação API Gerencianet - Status 200"> Nesta animação, demonstramos um cenário no qual o integrador recebeu com sucesso em sua URL de notificação o POST enviado pela Gerencianet e, em seguida, consultou em nosso webservice o conteúdo deste token de notificação. Para que você mesmo possa conferir, acesse primeiramente a subaba <code>Histórico de Notificações</code> e, em posse do token de notificação da cobrança que deseja verificar, acesse a subaba <code>Histórico de Requisições</code>, pesquise pelo referido token e, ao encontrá-lo, clique no ícone de um <em>"olho"</em> presente na última coluna. Desta forma, você visualizará todas as informações da referida cobrança que seu sistema consultou (leu). [block:callout] { "type": "info", "title": "INFORMAÇÃO", "body": "Na subaba <code>Histórico de Notificações</code>, a exibição da resposta <code>Sucesso (200)</code> indica apenas que o POST foi enviado com sucesso para sua URL de notificação, mas não garante que o seu sistema foi capaz de ler e gravar as informações do seu lado. Para isso, é necessário acessar a subaba <code>Histórico de Requisições</code> e localizar a linha contendo o consumo do <code>GET /notification/:token</code>." } [/block] Resumo das etapas seguidas: - Gerencianet enviou com sucesso uma notificação (POST) para sua URL de notificação (vide subaba <code>Histórico de Notificações</code>); <br> - Este POST contém apenas o token de notificação, que é <code>7dd52fed-3d0a-42c8-b3fb-fc24f1d75303</code>; <br> - Assim que a URL recebeu a notificação, seu sistema enviou uma requisição <code>GET</code> para a rota <code>/notification/7dd52fed-3d0a-42c8-b3fb-fc24f1d75303</code> (vide subaba <code>Histórico de Requisições</code>); <br> - Neste momento, seu sistema recebeu como resposta um JSON com todos os dados informativos sobre a alteração ocorrida na cobrança; <br> - **Para este exemplo, todo o fluxo foi realizado com sucesso**: disparamos a notificação contendo o token de notificação e, em seguida, seu sistema consultou nosso webservice para saber (ler) as informações da referida cobrança. <br> <hr> # Exemplo 2: Notificação com "Falha (404)" <br> <img src="https://s3-sa-east-1.amazonaws.com/pe85007/portal/wp-content/uploads/2018/08/17182046/Notificacao_Status_404.gif" alt="Notificação API Gerencianet - Status 200"> Nesta animação, demonstramos um cenário no qual a Gerencianet efetuou o envio do POST (notificação), mas em <code>Histórico de Notificações</code> está sendo exibida a resposta <code>Falha (404)</code>. Esta <code>Falha (404)</code> indica que o recurso requisitado não foi encontrado. Você deve certificar que sua URL está correta, pois tentamos entregar a notificação na URL que você nos forneceu, mas o endereço não foi localizado. Portanto, como seu sistema não foi capaz de receber nosso callback, você **não visualizará** o consumo do <code>GET /notification/:token</code> na subaba <code>Histórico de Requisições</code>. <br> **Soluções Sugeridas:** - Você poderá ajustar o caminho da URL no lado de seu servidor; - Atualizar a URL de notificação para o novo (e correto) endereço. Para isso, você poderá enviar requisições <code>PUT</code> para a <a href="https://dev.gerencianet.com.br/docs/atualizar-transacoes" target="_blank">rota adequada da API</a>, atentando-se ao limite de até 7.500 requisições a cada 24 hs para este endpoint. - Após alterar a URL de notificação, vamos continuar disparando a notificação da cobrança, mas agora para a nova URL fornecida, desde que nosso primeiro envio não tenha sido há mais de 3 dias. Neste caso, você poderá reenviar os callbacks da API <a href="https://gerencianet.com.br/artigo/fazer-o-reenvio-de-callback-na-api/" target="_blank" title="Link Externo">seguindo orientações de nossa FAQ</a>. <br> <hr> # Exemplo 3: Notificação com "Falha (301)" ou "Falha (302)" <br> <img src="https://s3-sa-east-1.amazonaws.com/pe85007/portal/wp-content/uploads/2018/08/17181948/Notificacao_Status_301.gif" alt="Notificação API Gerencianet - Status 301 e 302"> Nesta animação, demonstramos um cenário no qual a Gerencianet efetuou o envio do POST (notificação), mas em <code>Histórico de Notificações</code> está sendo exibida a resposta <code>Falha (301)</code> ou <code>Falha (302)</code>. Estas situações ocorrem quando existe um redirecionamento permanente ou temporário (301 ou 302, respectivamente) em seu servidor, afetando especificamente a entrega da notificação para a URL de notificação que você definiu previamente. Alguns exemplos comuns de quando isto ocorre: - Você definiu sua URL de notificação como <code>http://www.meusite.com.br</code>, mas posteriormente instalou HTTPS/SSL em seu servidor e seu endereço ficou como <code>https://www.meusite.com.br</code>; - Sua URL de notificação era <code>https://www.meusite.com.br</code>, mas posteriormente você criou regras em seu servidor (via htaccess, web.config, etc) e o endereço passou a responder apenas como <code>https://meusite.com.br</code>. <br> **Soluções Sugeridas:** - Ajustar melhor a regra do redirecionamento 301 e/ou 302 em seu servidor; - Atualizar a URL de notificação para o novo (e correto) endereço. Para isso, você poderá enviar requisições <code>PUT</code> para a <a href="https://dev.gerencianet.com.br/docs/atualizar-transacoes" target="_blank">rota adequada da API</a>, atentando-se ao limite de até 7.500 requisições a cada 24 hs para este endpoint. - Após alterar a URL de notificação, vamos continuar disparando a notificação da cobrança, mas agora para a nova URL fornecida, desde que nosso primeiro envio não tenha sido há mais de 3 dias. Neste caso, você poderá reenviar os callbacks da API <a href="https://gerencianet.com.br/artigo/fazer-o-reenvio-de-callback-na-api/" target="_blank" title="Link Externo">seguindo orientações de nossa FAQ</a>. <br> <hr> # Exemplo 4: Notificação com "Falha (500)" <br> <img src="https://s3-sa-east-1.amazonaws.com/pe85007/portal/wp-content/uploads/2018/08/17182143/Notificacao_Status_500.gif" alt="Notificação API Gerencianet - Status 500"> Nesta animação, demonstramos um cenário no qual a Gerencianet efetuou o envio do POST (notificação), mas em <code>Histórico de Notificações</code> está sendo exibida a resposta <code>Falha (500)</code>. Respostas contendo <code>Falha (500)</code> ou <code>500 Internal Server Error</code> são um status de erro HTTP que indica que o servidor encontrou uma condição inesperada e que o impediu de atender à solicitação. **O erro, no entanto, é uma mensagem genérica e abrangente** que indica uma dificuldade no processamento em seu servidor e pode ocorrer por diversos fatores. Por isso, às vezes, **os arquivos de log de seu servidor** podem responder com um status *code 500* acompanhado de mais detalhes sobre o *request* para evitar que no futuro erros desse tipo possam voltar a acontecer. **Por isso, é sempre de extrema importância que você veja a mensagem de erro do log de seu servidor para ajudá-lo a resolver.** A seguir, listamos as possíveis causas que você pode explorar para solucionar o erro: - Arquivo de configuração em seu servidor, como <code>.htaccess</code>, <code>php.ini</code> ou <code>web.config</code> com parâmetros inválidos. - Bloqueio em seu servidor (rede, firewall, políticas, etc): algumas aplicações e serviços podem ter determinados filtros, por isso, assegure-se que <a href="https://gerencianet.com.br/artigo/quais-enderecos-de-ip-gerencianet-utiliza/" target="_blank">nossos endereços IP's</a> estejam liberados. - Alto consumo de recursos em seu servidor ou limite de processos: hosts compartilhados são mais suscetíveis a este tipo de situação. - Timeout em seu servidor. - Permissões incorretas no servidor em arquivos e/ou pastas. - Limite de memória e diretivas do PHP setadas no arquivo <code>php.ini</code>. - Conflito entre versões de PHP em seu host. - Possibilidade de plugins, módulos, extensões ou temas terem causado o erro por incompatibilidade ou atualizações automáticas. [block:callout] { "type": "info", "body": "**Por se tratar de um erro genérico, é importante que você consulte e interprete os logs de erros do seu servidor.**\n\nCaso não tenha acesso a tais informações, entre em contato com o seu provedor de hospedagem ou sua equipe técnica responsável pela infraestrutura.", "title": "DICA" } [/block] <br> <hr> # Códigos de status HTTP (2xx, 3xx, 4xx e 5xx) A Gerencianet utiliza respostas HTTP para indicar sucesso ou falha nas requisições. Geralmente, você consegue visualizá-los através da subaba <code>Histórico de Notificações</code>. Comumente, quando retornamos respostas com status <code>2xx</code> significa que houve sucesso na requisição; status <code>3xx</code> indicam redirecionamento; status <code>4xx</code> indicam falhas no envio de dados por parte do cliente; status <code>5xx</code> indicam erros internos de servidor. A seguir, tabela apresentando os códigos HTTP das respostas mais comuns, bem como suas explicações e soluções: [block:parameters] { "data": { "h-0": "Código", "h-1": "Nome", "h-2": "Descrição", "0-0": "200", "1-0": "301", "2-0": "302", "3-0": "400", "4-0": "401", "5-0": "404", "6-0": "500", "0-1": "OK", "1-1": "Moved Permanently", "2-1": "Found", "3-1": "Bad Request", "4-1": "Unauthorized", "5-1": "Not Found", "6-1": "Internal Server Error", "0-2": "Requisição ocorreu com sucesso.", "1-2": "Redirecionamento de uma página para outro endereço, de forma permanente.\n\nVocê deve atualizar para a URL correta para recebimento do token de notificação.\n\nO ajuste da URL pode ser realizada no lado de seu servidor ou enviando requisições <code>PUT</code> para a rota adequada (<a href=\"https://dev.gerencianet.com.br/docs/atualizar-transacoes\">saiba como</a>).", "2-2": "Redirecionamento de uma página para outro endereço, mas com indicação de caráter temporário, não permanente. \n\nVocê deve atualizar para a URL correta para recebimento do token de notificação.\n\nO ajuste da URL pode ser realizada no lado de seu servidor ou enviando requisições <code>PUT</code> para a rota adequada (<a href=\"https://dev.gerencianet.com.br/docs/atualizar-transacoes\">saiba como</a>).", "3-2": "Algum parâmetro obrigatório não foi enviado ou foi enviado de maneira inválida.\n\nConsulte o \"histórico de requisições\" para interpretar os retornos da API (<a href=\"https://dev.gerencianet.com.br/docs/interpretando-erros-api\" target=\"_blank\">saiba como</a>) e corrija a sintaxe e/ou parâmetros da requisição que está enviando à API Gerencianet.", "4-2": "Sem autorização para fazer a requisição. Ou seja, uma autenticação necessária falhou ou não pode ser feita.\n\nNo contexto da Gerencianet, isso ocorre quando se utiliza credenciais de produção no modo teste (desenvolvimento), ou vice-versa. <a href=\"https://gerencianet.com.br/artigo/estou-deparando-com-mensagem-de-unauthorized-sem-autorizacao-por-que\" target=\"_blank\">Saiba como</a> verificar e resolver.", "5-2": "O recurso requisitado não foi encontrado. Ou seja, o retorno 404 surge quando o recurso (URL/documento/arquivo) requisitado a um servidor de destino não existe ou não é encontrado.\n\nCertifique-se que sua URL está correta para o recebimento do token de notificação.\n\nO ajuste da URL pode ser realizada no lado de seu servidor ou enviando requisições <code>PUT</code> para a rota adequada (<a href=\"https://dev.gerencianet.com.br/docs/atualizar-transacoes\">saiba como</a>).", "6-2": "Erro interno do servidor. O servidor encontrou uma condição inesperada que impediu o cumprimento da solicitação.\n\nNormalmente indica erro oriundo do servidor web. Uma causa comum é algum erro no <code>.htaccess</code>. Para apurar, leia o log de erros do seu servidor.\n\nVale lembrar que esse tipo de erro não é acessível pelo PHP, por isso você não conseguirá ler os detalhes do log ativando a exibição dos erros no PHP.\n\nContudo, nem sempre o erro é do webserver, pois é possível configurar o ambiente para que erros do PHP ou outro módulo, por exemplo, sejam tratados pelo webserver com o status 500." }, "cols": 3, "rows": 7 } [/block]