{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"settings":"","params":[]},"next":{"description":"","pages":[]},"title":"Interpretando Erros na API","type":"basic","slug":"interpretando-erros-api","excerpt":"Veja como interpretar os códigos de erros retornados pela API Gerencianet","body":"Esta página tem como objetivo apresentar o \"Histórico de Requisições\", que permite ao integrador visualizar todas as requisições realizadas por sua aplicação à API Gerencianet. A página ainda contém um tópico sobre como consultar os códigos de erros retornados pela nossa API, assim você vai aprender a interpretar os retornos da API e, claro, corrigir possíveis erros de validação de dados ou outros similares e identificar consumos/requisições realizadas por sua aplicação aos nossos *webservices*. Ambos os fluxos estão detalhados a seguir:\n\n1. [ Aprendendo a utilizar o \"Histórico de Requisições\" da API Gerencianet](#section-aprendendo-a-utilizar-o-hist-rico-de-requisi-es-da-api-gerencianet).\n\n2. [Aprendendo a pesquisar os códigos de erros da API Gerencianet](#section-aprendendo-a-pesquisar-os-c-digos-de-erros-da-api-gerencianet).\n\n## Aprendendo a utilizar o \"Histórico de Requisições\" da API Gerencianet\n\nA API efetua validações dos dados contidos na requisição que o sistema integrado envia a nossos *webservices.* Dessa forma, conforme o endpoint que seu sistema está tentando consumir, podem ser retornados erros em determinadas situações. Isso também se aplica se você utiliza um <a href=\"https://gerencianet.com.br/artigo/sistemas-integrados/\" target=\"_blank\">sistema ou módulo</a> que tenha integração com a Gerencianet.\n\nPara acessar o \"Histórico de Requisições\", siga os passos:\n\n- <a href=\"https://gerencianet.com.br/#login\" target=\"_blank\" title=\"Link Externo\">Efetue login</a> em sua conta Gerencianet;\n- Acesse <code>API > Minhas Aplicações > Sua Aplicação</code>;\n- Escolha o ambiente utilizado (produção ou homologação) e clique em <code>Histórico de Requisições</code> (<a href=\"https://s3-sa-east-1.amazonaws.com/pe85007/portal/wp-content/uploads/2018/08/14133035/Historico-Requisicoes-API-Gerencianet.png\" target=\"_blank\">veja onde</a>).\n\nConfira o vídeo em que ensinamos a utilizar o \"Histórico de Requisições\" da API:\n[block:html]\n{\n  \"html\": \"<iframe width=\\\"560\\\" height=\\\"315\\\" src=\\\"https://www.youtube.com/embed/ad0SYoeGAZs\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>\"\n}\n[/block]\n<br>\n\nA seguir, alguns exemplos comuns de erros retornados pela API devido a algum dado não estar no formato correto.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"IMPORTANTE\",\n  \"body\": \"Os exemplos a seguir também são aplicáveis se você estiver utilizando um <a href=\\\"https://gerencianet.com.br/artigo/sistemas-integrados/\\\" target=\\\"_blank\\\">sistema ou módulo</a> que já esteja integrado com a Gerencianet, afinal, é a API que está \\\"por trás\\\" cuidando das requisições.\"\n}\n[/block]\n# Exemplo 1 - Criar transação/cobrança\n\nAo enviar um <code>POST</code> para a rota <code>/v1/charge</code>, o integrador estará criando uma cobrança (ou \"transação\") com o status <code>new</code>, ou seja, a cobrança foi gerada e está aguardando a definição da forma de pagamento.\n\nAo criar uma transação, podem ser definidos, por exemplo: nome do item, valor, se é item de marketplace, se tem frete, informar uma URL de notificação, etc.\n\nPara este exemplo, vamos tentar criar uma cobrança cujo valor total seja inferior a R$ 5,00:\n[block:html]\n{\n  \"html\": \"<img src=\\\"https://files.readme.io/458ddb8-exemplo-01_1.png\\\" alt=\\\"Exemplo-1-Dados-Entrada\\\">\"\n}\n[/block]\nAgora, após o envio do código acima, vamos através da aba *\"Histórico de Requisições\"* conferir qual foi a resposta fornecida pela API:\n[block:html]\n{\n  \"html\": \"<img src=\\\"https://files.readme.io/2d65084-exemplo-01_2.png\\\" alt=\\\"Exemplo-1-Dados-Saida\\\">\"\n}\n[/block]\nConforme pode observar na imagem acima, a resposta possui <code>code</code> diferente de <code>200</code>, ou seja, o consumo não teve sucesso. Neste caso, a API exige que o valor mínimo de uma cobrança seja de R$ 5,00 - portanto, neste caso, você deve fornecer <code>500</code>, sem pontos nem vírgulas (lembrando que <code>500</code> equivale a R$ 5,00).\n\n# Exemplo 2 - Associar à forma de pagamento\n\nAo enviar um <code>POST</code> para a rota <code>/v1/charge/:id/pay</code>, onde <code>:id</code> é o <code>charge_id</code> da transação desejada, o integrador estará associando a cobrança à uma forma de pagamento.\n\nNeste momento, podem ser definidos, por exemplo: dados do cliente final, endereço, data de vencimento (em caso de boleto), se há desconto, se há cobrança de multa/juros após o vencimento, etc.\n\nPara este exemplo, vamos tentar associar uma cobrança à forma de pagamento \"boleto bancário\" e com uma data de vencimento em um formato não aceito pela API:\n[block:html]\n{\n  \"html\": \"<img src=\\\"https://files.readme.io/8c1e09e-exemplo-02_1.png\\\" alt=\\\"Exemplo-2-Dados-Entrada\\\">\"\n}\n[/block]\nAgora, após o envio do código acima, vamos através da aba *\"Histórico de Requisições\"* conferir qual foi a resposta fornecida pela API:\n[block:html]\n{\n  \"html\": \"<img src=\\\"https://files.readme.io/8afebbf-exemplo-02_2.png\\\" alt=\\\"Exemplo-2-Dados-Saida\\\">\"\n}\n[/block]\nConforme pode observar na imagem acima, a resposta possui <code>code</code> diferente de <code>200</code>, ou seja, o consumo não teve sucesso. Neste caso, a API exige que a data de vencimento do boleto seja informado no formato correto: YYYY-MM-DD, ou seja, <code>2018-10-20</code>, que equivale a 20 de outubro de 2018.\n\n# Exemplo 3 - Criar carnê\n\nAo enviar um <code>POST</code> para a rota <code>/v1/carnet</code>, o integrador estará criando um carnê com as configurações que definiu.\n\nNeste momento, podem ser definidos, por exemplo: nome do item, valor, quantidade, dados do cliente, endereço, quantidade de parcelas, data de vencimento, etc.\n\nPara este exemplo, vamos tentar criar um carnê de 20 parcelas:\n[block:html]\n{\n  \"html\": \"<img src=\\\"https://files.readme.io/1c1140f-exemplo-03_1.png\\\" alt=\\\"Exemplo-3-Dados-Entrada\\\">\"\n}\n[/block]\nAgora, após o envio do código acima, vamos através da aba *\"Histórico de Requisições\"* conferir qual foi a resposta fornecida pela API:\n[block:html]\n{\n  \"html\": \"<img src=\\\"https://files.readme.io/d71ac4c-exemplo-03_2.png\\\" alt=\\\"Exemplo-3-Dados-Saida\\\">\"\n}\n[/block]\nConforme pode observar na imagem acima, a resposta possui <code>code</code> diferente de <code>200</code>, ou seja, o consumo não teve sucesso. Neste caso, o carnê deve possuir no máximo 12 (doze) parcelas.\n\n## Aprendendo a pesquisar os códigos de erros da API Gerencianet \n\nBuscando facilitar a compreensão de cada erro retornado por nossas APIs, disponibilizamos uma página que tem como objetivo apresentar uma lista de todos os erros para consulta.\nPara acessá-la, clique <a href=\"https://gerencianet.github.io/gn-erros-api/\" target=\"_blank\" title=\"Link Externo\"><b>neste link</b></a> .\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/adf97a7-consultando_error_exemplo.gif\",\n        \"consultando_error_exemplo.gif\",\n        1920,\n        937,\n        \"#333\"\n      ],\n      \"caption\": \"Consultando códigos de erros - API Gerencianet\"\n    }\n  ]\n}\n[/block]\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. 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.\n\nCaso queira, confira [neste link](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-c-digos-de-status-http-2xx-3xx-4xx-e-5xx-) uma tabela apresentando os códigos HTTP das respostas mais comuns, bem como suas explicações e soluções.\n\n# (+) Aba \"Histórico de Notificações\"\n\nEste 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. [Saiba mais](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes).","updates":[],"order":4,"isReference":true,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"606f2ca7c5ba910078783480","createdAt":"2017-03-03T11:28:49.903Z","parentDoc":null,"__v":0,"version":{"version":"1.1.0","version_clean":"1.1.0","codename":"2021","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["606f2ca6c5ba91007878342b","575af039a083950e004487f7","575af5c7ba4ed70e000ca288","606f2ca6c5ba91007878342c","606f2ca6c5ba91007878342d","606f2ca6c5ba91007878342e","606f2ca6c5ba91007878342f","5761a63d207db7170022fc14","5761b9a2b65324200072d79e","576832939f0bf4190014ffdf","576832c09f0bf4190014ffe1","576832cba151c10e004316f0","576832d5bb15f40e00a288ec","576832e107b1f30e0039c645","606f2ca6c5ba910078783430","606f2ca6c5ba910078783431","5783f78c5cbce30e0074e2b7","606f2ca6c5ba910078783432","606f2ca6c5ba910078783433","606f2ca6c5ba910078783434","606f2ca6c5ba910078783435","606f2ca6c5ba910078783436","606f2ca6c5ba910078783437","578529f887c9280e0090394b","606f2ca6c5ba910078783438","606f2ca6c5ba910078783439","606f2ca6c5ba91007878343a","606f2ca6c5ba91007878343b","606f2ca6c5ba91007878343c","606f2ca6c5ba91007878343d","606f2ca6c5ba91007878343e","606f2ca6c5ba91007878343f","606f2ca6c5ba910078783440","606f2ca6c5ba910078783441","60d61f026ddc3901a32ee5f1","60ec37c637005f015e54174e"],"_id":"606f2ca7c5ba9100787834c6","project":"575aeffae12cf20e002f306c","createdAt":"2016-06-10T16:51:06.080Z","releaseDate":"2016-06-10T16:51:06.080Z","__v":2,"forked_from":"575aeffae12cf20e002f306f"},"githubsync":"","project":"575aeffae12cf20e002f306c","user":"57601a13af3e090e00108059","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Visão Geral da API","slug":"documentation","order":3,"from_sync":false,"reference":true,"_id":"606f2ca6c5ba91007878342b","createdAt":"2016-06-10T16:51:06.098Z","version":"606f2ca7c5ba9100787834c6","__v":0,"project":"575aeffae12cf20e002f306c"}}

Interpretando Erros na API

Veja como interpretar os códigos de erros retornados pela API Gerencianet

Esta página tem como objetivo apresentar o "Histórico de Requisições", que permite ao integrador visualizar todas as requisições realizadas por sua aplicação à API Gerencianet. A página ainda contém um tópico sobre como consultar os códigos de erros retornados pela nossa API, assim você vai aprender a interpretar os retornos da API e, claro, corrigir possíveis erros de validação de dados ou outros similares e identificar consumos/requisições realizadas por sua aplicação aos nossos *webservices*. Ambos os fluxos estão detalhados a seguir: 1. [ Aprendendo a utilizar o "Histórico de Requisições" da API Gerencianet](#section-aprendendo-a-utilizar-o-hist-rico-de-requisi-es-da-api-gerencianet). 2. [Aprendendo a pesquisar os códigos de erros da API Gerencianet](#section-aprendendo-a-pesquisar-os-c-digos-de-erros-da-api-gerencianet). ## Aprendendo a utilizar o "Histórico de Requisições" da API Gerencianet A API efetua validações dos dados contidos na requisição que o sistema integrado envia a nossos *webservices.* Dessa forma, conforme o endpoint que seu sistema está tentando consumir, podem ser retornados erros em determinadas situações. Isso também se aplica se você utiliza um <a href="https://gerencianet.com.br/artigo/sistemas-integrados/" target="_blank">sistema ou módulo</a> que tenha integração com a Gerencianet. Para acessar o "Histórico de Requisições", siga os passos: - <a href="https://gerencianet.com.br/#login" target="_blank" title="Link Externo">Efetue login</a> em sua conta Gerencianet; - Acesse <code>API > Minhas Aplicações > Sua Aplicação</code>; - Escolha o ambiente utilizado (produção ou homologação) e clique em <code>Histórico de Requisições</code> (<a href="https://s3-sa-east-1.amazonaws.com/pe85007/portal/wp-content/uploads/2018/08/14133035/Historico-Requisicoes-API-Gerencianet.png" target="_blank">veja onde</a>). Confira o vídeo em que ensinamos a utilizar o "Histórico de Requisições" da API: [block:html] { "html": "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/ad0SYoeGAZs\" frameborder=\"0\" allowfullscreen></iframe>" } [/block] <br> A seguir, alguns exemplos comuns de erros retornados pela API devido a algum dado não estar no formato correto. [block:callout] { "type": "warning", "title": "IMPORTANTE", "body": "Os exemplos a seguir também são aplicáveis se você estiver utilizando um <a href=\"https://gerencianet.com.br/artigo/sistemas-integrados/\" target=\"_blank\">sistema ou módulo</a> que já esteja integrado com a Gerencianet, afinal, é a API que está \"por trás\" cuidando das requisições." } [/block] # Exemplo 1 - Criar transação/cobrança Ao enviar um <code>POST</code> para a rota <code>/v1/charge</code>, o integrador estará criando uma cobrança (ou "transação") com o status <code>new</code>, ou seja, a cobrança foi gerada e está aguardando a definição da forma de pagamento. Ao criar uma transação, podem ser definidos, por exemplo: nome do item, valor, se é item de marketplace, se tem frete, informar uma URL de notificação, etc. Para este exemplo, vamos tentar criar uma cobrança cujo valor total seja inferior a R$ 5,00: [block:html] { "html": "<img src=\"https://files.readme.io/458ddb8-exemplo-01_1.png\" alt=\"Exemplo-1-Dados-Entrada\">" } [/block] Agora, após o envio do código acima, vamos através da aba *"Histórico de Requisições"* conferir qual foi a resposta fornecida pela API: [block:html] { "html": "<img src=\"https://files.readme.io/2d65084-exemplo-01_2.png\" alt=\"Exemplo-1-Dados-Saida\">" } [/block] Conforme pode observar na imagem acima, a resposta possui <code>code</code> diferente de <code>200</code>, ou seja, o consumo não teve sucesso. Neste caso, a API exige que o valor mínimo de uma cobrança seja de R$ 5,00 - portanto, neste caso, você deve fornecer <code>500</code>, sem pontos nem vírgulas (lembrando que <code>500</code> equivale a R$ 5,00). # Exemplo 2 - Associar à forma de pagamento Ao enviar um <code>POST</code> para a rota <code>/v1/charge/:id/pay</code>, onde <code>:id</code> é o <code>charge_id</code> da transação desejada, o integrador estará associando a cobrança à uma forma de pagamento. Neste momento, podem ser definidos, por exemplo: dados do cliente final, endereço, data de vencimento (em caso de boleto), se há desconto, se há cobrança de multa/juros após o vencimento, etc. Para este exemplo, vamos tentar associar uma cobrança à forma de pagamento "boleto bancário" e com uma data de vencimento em um formato não aceito pela API: [block:html] { "html": "<img src=\"https://files.readme.io/8c1e09e-exemplo-02_1.png\" alt=\"Exemplo-2-Dados-Entrada\">" } [/block] Agora, após o envio do código acima, vamos através da aba *"Histórico de Requisições"* conferir qual foi a resposta fornecida pela API: [block:html] { "html": "<img src=\"https://files.readme.io/8afebbf-exemplo-02_2.png\" alt=\"Exemplo-2-Dados-Saida\">" } [/block] Conforme pode observar na imagem acima, a resposta possui <code>code</code> diferente de <code>200</code>, ou seja, o consumo não teve sucesso. Neste caso, a API exige que a data de vencimento do boleto seja informado no formato correto: YYYY-MM-DD, ou seja, <code>2018-10-20</code>, que equivale a 20 de outubro de 2018. # Exemplo 3 - Criar carnê Ao enviar um <code>POST</code> para a rota <code>/v1/carnet</code>, o integrador estará criando um carnê com as configurações que definiu. Neste momento, podem ser definidos, por exemplo: nome do item, valor, quantidade, dados do cliente, endereço, quantidade de parcelas, data de vencimento, etc. Para este exemplo, vamos tentar criar um carnê de 20 parcelas: [block:html] { "html": "<img src=\"https://files.readme.io/1c1140f-exemplo-03_1.png\" alt=\"Exemplo-3-Dados-Entrada\">" } [/block] Agora, após o envio do código acima, vamos através da aba *"Histórico de Requisições"* conferir qual foi a resposta fornecida pela API: [block:html] { "html": "<img src=\"https://files.readme.io/d71ac4c-exemplo-03_2.png\" alt=\"Exemplo-3-Dados-Saida\">" } [/block] Conforme pode observar na imagem acima, a resposta possui <code>code</code> diferente de <code>200</code>, ou seja, o consumo não teve sucesso. Neste caso, o carnê deve possuir no máximo 12 (doze) parcelas. ## Aprendendo a pesquisar os códigos de erros da API Gerencianet Buscando facilitar a compreensão de cada erro retornado por nossas APIs, disponibilizamos uma página que tem como objetivo apresentar uma lista de todos os erros para consulta. Para acessá-la, clique <a href="https://gerencianet.github.io/gn-erros-api/" target="_blank" title="Link Externo"><b>neste link</b></a> . [block:image] { "images": [ { "image": [ "https://files.readme.io/adf97a7-consultando_error_exemplo.gif", "consultando_error_exemplo.gif", 1920, 937, "#333" ], "caption": "Consultando códigos de erros - API Gerencianet" } ] } [/block] # (+) Códigos de status HTTP (2xx, 3xx, 4xx e 5xx) A Gerencianet utiliza respostas HTTP para indicar sucesso ou falha nas requisições. 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. Caso queira, confira [neste link](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes#section-c-digos-de-status-http-2xx-3xx-4xx-e-5xx-) uma tabela apresentando os códigos HTTP das respostas mais comuns, bem como suas explicações e soluções. # (+) Aba "Histórico de Notificações" 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. [Saiba mais](https://dev.gerencianet.com.br/docs/entendendo-fluxo-notificacoes).