{"__v":539,"_id":"575ea374e7089c0e006d0cb4","category":{"__v":0,"_id":"575aeffae12cf20e002f3070","project":"575aeffae12cf20e002f306c","version":"575aeffae12cf20e002f306f","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-06-10T16:51:06.098Z","from_sync":false,"order":0,"slug":"documentation","title":"Visão Geral da API"},"parentDoc":null,"project":"575aeffae12cf20e002f306c","user":"575b077ae12cf20e002f30a3","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-06-13T12:13:40.478Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":3,"body":"Para acessar o ambiente de testes você precisa de uma conta Gerencianet. <a href=\"https://gerencianet.com.br/#abrirconta\" title=\"Cadastro ao nosso sistema, seja nosso cliente\" target=\"_blank\">Crie sua conta</a>.\n\nAntes de colocar uma aplicação em produção, é muito importante certificar-se que sua implementação está correta e suas integrações estão comunicando da forma como deveriam.\n\nPara evitar que os integradores tenham que fazer testes em produção, a Gerencianet oferece um ambiente de desenvolvimento/testes (sandbox), no qual chamamos de *“Playground”*. Este é um local no qual o integrador pode utilizar para conhecer o mecanismo e o fluxo de pagamento em um ambiente 100% de teste e descomplicado. \n\nNeste ambiente, por oferecer uma semelhança com os recursos suportados pela API no ambiente de produção, é possível efetuar testes de integração antes de ir para produção, podendo assim fazer uma experiência com nossa API sem fazer alterações em sua conta Gerencianet.\n[block:html]\n{\n  \"html\": \"<p>Para iniciar a utilização do \\\"Playground\\\", siga as instruções:</p>\\n<ol>\\n  <li><p>Acesse <a href=\\\"http://www.gerencianet.com.br\\\" target=\\\"_blank\\\">nosso site</a>, clique em \\\"<a href=\\\"https://gerencianet.com.br/#login\\\" target=\\\"_blank\\\">Entrar</a>\\\" (menu superior), logue em sua conta;</p></li>\\n  \\n  <li><p>Clique em <em>\\\"API\\\"</em>, depois <em>\\\"Minhas Aplicações > Nova aplicação\\\"</em> (<a href=\\\"http://image.prntscr.com/image/80b55642a21c4837b6fee00e7ed0758a.png\\\" target=\\\"_blank\\\">?</a>), definindo um nome para a sua aplicação.</p></li>\\n</ol>\\n<p>Estando dentro da aplicação criada, é possível observar todos os endpoints disponibilizados pela API, ou seja, tudo que é possível fazer via integração. Através do Playground, o integrador pode conhecer as informações que podem ser enviadas em cada situação, quais são obrigatórias, em quais formatos devem ser enviadas, etc.</p>\\n\\n<p>Para acompanhar os procedimentos realizados no Playground, utilize a aba \\\"Desenvolvimento\\\", especificamente nas sub-abas <abbr title=\\\"Toda cobrança que for criada poderá ser vista nesta aba\\\">Transações</abbr>, <abbr title=\\\"Lista todas as assinaturas criadas\\\">Assinaturas</abbr>, <abbr title=\\\"Lista todos os carnês criados\\\">Carnês</abbr>, <abbr title=\\\"Mostra todas as requisições do seu sistema, tenha tido sucesso ou falha\\\">Histórico de Requisições</abbr> e <abbr title=\\\"Mostra toda notificação enviada pelo sistema Gerencianet e a resposta da URL que recebeu o POST\\\">Histórico de Notificações</abbr>.</p>\\n\\n<p>Cada <em>endpoint</em> possui um campo editável para informar os <abbr title=\\\"JSON com as informações que o endpoint deve receber para realizar a ação\\\">dados de entrada</abbr> e um campo não-editável para mostrar o <abbr title=\\\"JSON que descreve a estrutura dos dados, incluindo todas as informações que podem ser enviadas e as especificidades de cada uma\\\">Schema</abbr>. Os <em>endpoints</em> estão divididos em 5 (cinco) grupos principais: Transações, Carnês, Notificações, Assinaturas e Outros.</p>\"\n}\n[/block]\n## Explore nosso ambiente de testes\n\nA Gerencianet oferece duas formas de utilizar o ambiente de testes (sandbox): (a) dentro de sua conta Gerencianet através do Playground ou (b) utilizando suas chaves *Client_Id* e *Client_Secret* de desenvolvimento:\n\n- (a) O Playground é um ambiente isolado, semelhante ao ambiente de produção - é o local dentro de sua conta Gerencianet que você pode testar os recursos da API de forma online, sem precisar programar. Veja:\n\n  - Faça <a href=\"https://gerencianet.com.br/#login\" target=\"_blank\">login</a> em sua conta Gerencianet, acesse o menu *\"API\"*, depois *\"Minhas Aplicações > Nova aplicação\"* (<a href=\"http://image.prntscr.com/image/80b55642a21c4837b6fee00e7ed0758a.png\" target=\"_blank\">?</a>), definindo um nome para a sua aplicação; e\n\n  - A partir de agora, veja como usar nosso <a href=\"https://dev.gerencianet.com.br/docs/playground\" target=\"_blank\">Playground</a> e copie os códigos disponibilizados na seção \"<a href=\"https://dev.gerencianet.com.br/v1/docs/ambiente-de-testes\" target=\"_blank\">Ambiente de Testes</a>\" na documentação e explore o Playground.\n\n- (b) Você também pode realizar testes de integração direto em sua aplicação/sistema antes de ir para ambiente de produção. Para isso, utilize suas chaves *Client_Id* e *Client_Secret* da aba \"Desenvolvimento\" (<a href=\"http://image.prntscr.com/image/447be4bc64644a35bcf5eaecd1125f5d.png\" target=\"_blank\">?</a>).\n\nAdicionalmente, oferecemos vídeos ensinando mais sobre a API e nosso Playground:\n\n- Vídeo: <a href=\"https://www.youtube.com/watch?v=oy4aydoLUZA&index=5&list=PLRqvcUTH2VsWKL03a0dUMaPobAKUSXyxt\" target=\"_blank\">API Gerencianet</a>\n\n- Vídeo: <a href=\"https://www.youtube.com/watch?v=nKPb0rU8j4Q&index=6&list=PLRqvcUTH2VsWKL03a0dUMaPobAKUSXyxt\" target=\"_blank\">Métodos do Playground (ambiente de testes/sandbox da Gerencianet)</a>\n\n- Vídeo: <a href=\"https://www.youtube.com/watch?v=ylqJUpHqwfY&index=7&list=PLRqvcUTH2VsWKL03a0dUMaPobAKUSXyxt\" target=\"_blank\">Criando uma transação via Playground (ambiente de testes/sandbox da Gerencianet)</a>\n\n\n\n## GET, POST, PUT e DELETE\n\nA API é RESTful, isso significa que os *endpoints* criados seguem práticas específicas para que sejam intuitivos para os integradores que a utilizam. Essas opções (GET, POST, PUT e DELETE) são \"métodos\" (verbo) que você usará para interagir com o recurso.\n\nTodo *endpoint* do tipo **GET** é um *endpoint* de consulta, ou seja, o integrador nunca estará criando ou alterando um registro quando fizer um consumo desse tipo.\n\nOs *endpoints* do tipo **POST** sempre estão relacionados à criação de algum registro. O <code>POST /charge</code> cria uma cobrança; o <code>POST /charge/:id/pay</code> cria um pagamento para uma determinada cobrança, e assim por diante.\n\nOs *endpoints* do tipo **PUT** realizam a alteração de algum registro já existente. Quando o integrador utiliza <code>PUT /charge/:id/cancel</code>, por exemplo, ele está alterando o status de uma cobrança para <code>canceled</code>.\n\nPor fim, os *endpoints* do tipo **DELETE** são responsáveis por deletar um registro. Esse tipo de consumo sempre vai solicitar um identificador para deleção. Na API, apenas planos de assinaturas podem ser deletados.\n\n## Interpretando as Respostas da API\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>4xx</code> indicam falhas no envio de dados por parte do cliente; status <code>5xx</code> indicam erros internos de servidor.\n\nPara mais detalhes, preparamos uma seção especial mostrando [como interpretar as respostas da nossa API](https://dev.gerencianet.com.br/docs/interpretando-erros-api), com exemplos reais e práticos. Para facilitar ainda mais, também gravamos um vídeo bem curto e objetivo. [Não deixe de acessar e conferir](https://dev.gerencianet.com.br/docs/interpretando-erros-api).\n\n\n## Vídeos Explicativos: Playground\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 utilizar o nosso Playground (sandbox).\n\n### Métodos do Playground (ambiente de testes/sandbox da Gerencianet)\n[block:html]\n{\n  \"html\": \"<iframe width=\\\"560\\\" height=\\\"315\\\" src=\\\"https://www.youtube.com/embed/nKPb0rU8j4Q\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>\"\n}\n[/block]\n### Criando uma transação via Playground (ambiente de testes/sandbox da Gerencianet)\n[block:html]\n{\n  \"html\": \"<iframe width=\\\"560\\\" height=\\\"315\\\" src=\\\"https://www.youtube.com/embed/ylqJUpHqwfY\\\" 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## Próximos Passos\n\nAgora que você conheceu sobre nosso Playground, é interessante que conheça mais sobre os 5 endpoints disponíveis em nossa área de testes: [Transações](https://dev.gerencianet.com.br/docs/playground-transacoes), [Carnês](https://dev.gerencianet.com.br/docs/playground-carnes), [Notificações](https://dev.gerencianet.com.br/docs/playground-notificacoes), [Assinaturas](https://dev.gerencianet.com.br/docs/playground-assinaturas) e [Outros](https://dev.gerencianet.com.br/docs/playground-outros).","excerpt":"Você está em: *\"Visão Geral da API > Playground (sandbox)\"*","slug":"playground","type":"basic","title":"Playground (sandbox)"}

Playground (sandbox)

Você está em: *"Visão Geral da API > Playground (sandbox)"*

Para acessar o ambiente de testes você precisa de uma conta Gerencianet. <a href="https://gerencianet.com.br/#abrirconta" title="Cadastro ao nosso sistema, seja nosso cliente" target="_blank">Crie sua conta</a>. Antes de colocar uma aplicação em produção, é muito importante certificar-se que sua implementação está correta e suas integrações estão comunicando da forma como deveriam. Para evitar que os integradores tenham que fazer testes em produção, a Gerencianet oferece um ambiente de desenvolvimento/testes (sandbox), no qual chamamos de *“Playground”*. Este é um local no qual o integrador pode utilizar para conhecer o mecanismo e o fluxo de pagamento em um ambiente 100% de teste e descomplicado. Neste ambiente, por oferecer uma semelhança com os recursos suportados pela API no ambiente de produção, é possível efetuar testes de integração antes de ir para produção, podendo assim fazer uma experiência com nossa API sem fazer alterações em sua conta Gerencianet. [block:html] { "html": "<p>Para iniciar a utilização do \"Playground\", siga as instruções:</p>\n<ol>\n <li><p>Acesse <a href=\"http://www.gerencianet.com.br\" target=\"_blank\">nosso site</a>, clique em \"<a href=\"https://gerencianet.com.br/#login\" target=\"_blank\">Entrar</a>\" (menu superior), logue em sua conta;</p></li>\n \n <li><p>Clique em <em>\"API\"</em>, depois <em>\"Minhas Aplicações > Nova aplicação\"</em> (<a href=\"http://image.prntscr.com/image/80b55642a21c4837b6fee00e7ed0758a.png\" target=\"_blank\">?</a>), definindo um nome para a sua aplicação.</p></li>\n</ol>\n<p>Estando dentro da aplicação criada, é possível observar todos os endpoints disponibilizados pela API, ou seja, tudo que é possível fazer via integração. Através do Playground, o integrador pode conhecer as informações que podem ser enviadas em cada situação, quais são obrigatórias, em quais formatos devem ser enviadas, etc.</p>\n\n<p>Para acompanhar os procedimentos realizados no Playground, utilize a aba \"Desenvolvimento\", especificamente nas sub-abas <abbr title=\"Toda cobrança que for criada poderá ser vista nesta aba\">Transações</abbr>, <abbr title=\"Lista todas as assinaturas criadas\">Assinaturas</abbr>, <abbr title=\"Lista todos os carnês criados\">Carnês</abbr>, <abbr title=\"Mostra todas as requisições do seu sistema, tenha tido sucesso ou falha\">Histórico de Requisições</abbr> e <abbr title=\"Mostra toda notificação enviada pelo sistema Gerencianet e a resposta da URL que recebeu o POST\">Histórico de Notificações</abbr>.</p>\n\n<p>Cada <em>endpoint</em> possui um campo editável para informar os <abbr title=\"JSON com as informações que o endpoint deve receber para realizar a ação\">dados de entrada</abbr> e um campo não-editável para mostrar o <abbr title=\"JSON que descreve a estrutura dos dados, incluindo todas as informações que podem ser enviadas e as especificidades de cada uma\">Schema</abbr>. Os <em>endpoints</em> estão divididos em 5 (cinco) grupos principais: Transações, Carnês, Notificações, Assinaturas e Outros.</p>" } [/block] ## Explore nosso ambiente de testes A Gerencianet oferece duas formas de utilizar o ambiente de testes (sandbox): (a) dentro de sua conta Gerencianet através do Playground ou (b) utilizando suas chaves *Client_Id* e *Client_Secret* de desenvolvimento: - (a) O Playground é um ambiente isolado, semelhante ao ambiente de produção - é o local dentro de sua conta Gerencianet que você pode testar os recursos da API de forma online, sem precisar programar. Veja: - Faça <a href="https://gerencianet.com.br/#login" target="_blank">login</a> em sua conta Gerencianet, acesse o menu *"API"*, depois *"Minhas Aplicações > Nova aplicação"* (<a href="http://image.prntscr.com/image/80b55642a21c4837b6fee00e7ed0758a.png" target="_blank">?</a>), definindo um nome para a sua aplicação; e - A partir de agora, veja como usar nosso <a href="https://dev.gerencianet.com.br/docs/playground" target="_blank">Playground</a> e copie os códigos disponibilizados na seção "<a href="https://dev.gerencianet.com.br/v1/docs/ambiente-de-testes" target="_blank">Ambiente de Testes</a>" na documentação e explore o Playground. - (b) Você também pode realizar testes de integração direto em sua aplicação/sistema antes de ir para ambiente de produção. Para isso, utilize suas chaves *Client_Id* e *Client_Secret* da aba "Desenvolvimento" (<a href="http://image.prntscr.com/image/447be4bc64644a35bcf5eaecd1125f5d.png" target="_blank">?</a>). Adicionalmente, oferecemos vídeos ensinando mais sobre a API e nosso Playground: - Vídeo: <a href="https://www.youtube.com/watch?v=oy4aydoLUZA&index=5&list=PLRqvcUTH2VsWKL03a0dUMaPobAKUSXyxt" target="_blank">API Gerencianet</a> - Vídeo: <a href="https://www.youtube.com/watch?v=nKPb0rU8j4Q&index=6&list=PLRqvcUTH2VsWKL03a0dUMaPobAKUSXyxt" target="_blank">Métodos do Playground (ambiente de testes/sandbox da Gerencianet)</a> - Vídeo: <a href="https://www.youtube.com/watch?v=ylqJUpHqwfY&index=7&list=PLRqvcUTH2VsWKL03a0dUMaPobAKUSXyxt" target="_blank">Criando uma transação via Playground (ambiente de testes/sandbox da Gerencianet)</a> ## GET, POST, PUT e DELETE A API é RESTful, isso significa que os *endpoints* criados seguem práticas específicas para que sejam intuitivos para os integradores que a utilizam. Essas opções (GET, POST, PUT e DELETE) são "métodos" (verbo) que você usará para interagir com o recurso. Todo *endpoint* do tipo **GET** é um *endpoint* de consulta, ou seja, o integrador nunca estará criando ou alterando um registro quando fizer um consumo desse tipo. Os *endpoints* do tipo **POST** sempre estão relacionados à criação de algum registro. O <code>POST /charge</code> cria uma cobrança; o <code>POST /charge/:id/pay</code> cria um pagamento para uma determinada cobrança, e assim por diante. Os *endpoints* do tipo **PUT** realizam a alteração de algum registro já existente. Quando o integrador utiliza <code>PUT /charge/:id/cancel</code>, por exemplo, ele está alterando o status de uma cobrança para <code>canceled</code>. Por fim, os *endpoints* do tipo **DELETE** são responsáveis por deletar um registro. Esse tipo de consumo sempre vai solicitar um identificador para deleção. Na API, apenas planos de assinaturas podem ser deletados. ## Interpretando as Respostas da API 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>4xx</code> indicam falhas no envio de dados por parte do cliente; status <code>5xx</code> indicam erros internos de servidor. Para mais detalhes, preparamos uma seção especial mostrando [como interpretar as respostas da nossa API](https://dev.gerencianet.com.br/docs/interpretando-erros-api), com exemplos reais e práticos. Para facilitar ainda mais, também gravamos um vídeo bem curto e objetivo. [Não deixe de acessar e conferir](https://dev.gerencianet.com.br/docs/interpretando-erros-api). ## Vídeos Explicativos: Playground 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 utilizar o nosso Playground (sandbox). ### Métodos do Playground (ambiente de testes/sandbox da Gerencianet) [block:html] { "html": "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/nKPb0rU8j4Q\" frameborder=\"0\" allowfullscreen></iframe>" } [/block] ### Criando uma transação via Playground (ambiente de testes/sandbox da Gerencianet) [block:html] { "html": "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/ylqJUpHqwfY\" 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)". ## Próximos Passos Agora que você conheceu sobre nosso Playground, é interessante que conheça mais sobre os 5 endpoints disponíveis em nossa área de testes: [Transações](https://dev.gerencianet.com.br/docs/playground-transacoes), [Carnês](https://dev.gerencianet.com.br/docs/playground-carnes), [Notificações](https://dev.gerencianet.com.br/docs/playground-notificacoes), [Assinaturas](https://dev.gerencianet.com.br/docs/playground-assinaturas) e [Outros](https://dev.gerencianet.com.br/docs/playground-outros).