{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"Introdução","type":"basic","slug":"api-pagamentos","excerpt":"Esta página contém uma breve introdução da API de Pagamentos da Gerencianet e informações sobre como configurar um ambiente para seu consumo.","body":"## API de Pagamentos Gerencianet\nA API de Pagamentos Gerencianet disponibiliza os nossos serviços para a realização de pagamentos de cobranças. Com nossa API é possível consultar cobranças à serem pagas, enviar ordens de pagamento e verificar o status de um pagamento.\n\n**Sumário**\n1. [Entendendo os escopos de aplicação](#section-entendendo-os-escopos-de-aplica-o)\n2. [Autenticação com OAuth2](#section-autentica-o-com-oauth2)\n    2.1 [Autorização](#section-autoriza-o)\n3. [Configurando o Postman para testes](#section-configurando-o-postman-para-testes)\n    3.1 [Importando a Collection da API de Pagamentos](#section-1-importando-a-collection-da-api-de-pagamentos)\n    3.2 [Criando um Environment](#section-2-criando-um-environment)\n    3.3 [Configurando o certificado no Postman](#section-3-configurando-o-certificado-no-postman)\n    3.4 [Atribuindo o Client_Id e Client_Secret no Postman](#section-4-atribuindo-o-client_id-e-client_secret-no-postman)\n\n<hr>\n<br>\n\n## Entendendo os escopos de aplicação\nAo criar ou editar uma aplicação em sua Conta Gerencianet, você precisará configurar os escopos que a aplicação terá acesso. A escolha desses escopos define quais ações uma aplicação estará **autorizada** a realizar via API.\n\nOs escopos disponíveis na API de Pagamentos Gerencianet estão listados abaixo com suas respectivas descrições:\n- **`gn.barcode.read`** - Permissão para **consulta de cobranças à serem pagas**;\n- **`gn.barcode.pay.write`** - Permissão para **realizar uma ordem de pagamento**;\n- **`gn.barcode.pay.read`** - Permissão para **consulta de pagamentos**;\n\n<br>\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Liberação dos escopos\",\n  \"body\": \"Caso queira utilizar a API de Pagamentos é necessário liberar os escopos citados acima, para isso entre em contato conosco pelo canal <a href=\\\"https://discord.gg/Xsb3AmKtyC\\\" target=\\\"_blank\\\">api-pagamentos</a> no Discord.\"\n}\n[/block]\n<br>\n\n## Autenticação com OAuth2\n\nO processo de autenticação na API de Pagamentos segui o protocolo  [`OAuth2`]((http://oauth.net/2/), incluindo a utilização do certificado de segurança gerado em sua conta Gerencianet. Através dessa autenticação o OAuth2 poderá responder quais as autorizações que a aplicação tem e, consequentemente, autorizar ou negar as requisições de acordo com essa informação.\n\nPara mais detalhes referentes à autenticação com OAuth2, basta clicar no botão abaixo:\n\n\n\n[block:html]\n{\n  \"html\": \"<a href=\\\"https://dev.gerencianet.com.br/docs/endpoint-autorizacao-oauth\\\" target=\\\"_blank\\\" title=\\\"Autenticação API\\\"><button type=\\\"button\\\" class=\\\"btn btn-default navbar-btn buttonorange\\\">Autenticação OAuth2</button></a>\"\n}\n[/block]\n### Autorização\n\nA API de Pagamentos requer o uso de um certificado `PFX(.p12)` que é gerado em sua conta Gerencianet. O Auth2  fornece um mecanismo de autorização chamado de *mutual Transport Layer Security*(mTLS) por meio do certificado emitido em sua conta Gerencianet, tal método acrescenta mais um nível de segurança às requisições trafegadas entre sua aplicação e a API de Pagamentos.\n\nPara mais detalhes referentes a geração do `PFX(.p12)` e do padrão mTLS, basta clicar no botão abaixo:\n[block:html]\n{\n  \"html\": \"<a href=\\\"https://dev.gerencianet.com.br/v1.1.0/docs/autorizacao-api-mtls\\\" target=\\\"_blank\\\" title=\\\"Autorização com mTLS\\\"><button type=\\\"button\\\" class=\\\"btn btn-default navbar-btn buttonorange\\\">Autorização com mTLS</button></a>\"\n}\n[/block]\n<br>\n\n## Configurando o Postman para testes\n\nPara seguir com a etapa de configuração do Postman, você deve ter:\n\n1. Um par de credenciais `Client_Id` e `Client_Secret` de uma aplicação cadastrada em sua Conta Gerencianet;\n2. Um certificado P12/PEM gerado em sua conta Gerencianet;\n3. O software Postman instalado em seu computador (Caso não tenha, [clique aqui para baixar](https://www.postman.com/downloads/));\n\n### 1. Importando a Collection da API de Pagamentos\n\nEste é o <a href=\"https://documenter.getpostman.com/view/13574984/UyrDCurw\" target=\"_blank\" alt=\"link\">link</a> da nossa Collection que manteremos atualizada com o endpoints da API de Pagamentos da Gerencianet.\n\n[![Run in Postman](https://run.pstmn.io/button.svg)](https://documenter.getpostman.com/view/13574984/UyrDCurw)\n2. Com o Postman iniciado, use o atalho `Ctrl+O` para abrir a tela de importação;\n3. Selecione o arquivo da *Collection*;\n4. Por último, clique em *Import* \n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/9e9b734-1.png\",\n        \"1.png\",\n        1920,\n        1040,\n        \"#333\"\n      ],\n      \"caption\": \"Ilustração do início do processo de importação\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a8ef473-23.png\",\n        \"23.png\",\n        1920,\n        1040,\n        \"#333\"\n      ],\n      \"caption\": \"Ilustração da importação do arquivo\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b7e3b1e-4.png\",\n        \"4.png\",\n        1920,\n        1040,\n        \"#333\"\n      ],\n      \"caption\": \"Ilustração da etapa final da importação\"\n    }\n  ]\n}\n[/block]\n### 2. Criando um Environment\nA criação de um *Environment* no Postman é necessária para que algumas automações embutidas na collection funcionem. Essas automações foram projetadas para dar mais facilidade aos desenvolvedores durante os testes.\n\nCom elas você precisa solicitar a autorização apenas uma vez e, então, o `access_token` fica gravado como uma variável de ambiente (*environment*) do Postman, disponível para utilização nas requisições subsequentes.\n\nPara criar um Environment siga os passos abaixo.\n\n1. Acione o atalho `Ctrl+N` e selecione \"Environment\";\n2. Atribua um nome preferencialmente especificando se esse Environment será apontado para o ambiente de Produção ou Homologação;\n3. Crie a variável `gn-api-pag` e como valor inicial (*Initial value*) insira a URL da API de Pagamentos de Produção ou Homologação;\n4. Salve o seu Environment;\n5. Selecione o Environment desejado, assim o Postman entenderá a variável criada.\n\nAs imagens abaixo ilustram os passos acima. Como exemplo, foi criado um Environment apontado para o ambiente de Produção da API de Pagamentos Gerencianet.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/04c4ca4-1e.png\",\n        \"1e.png\",\n        1920,\n        1040,\n        \"#333\"\n      ],\n      \"caption\": \"Criando um novo environment\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/6876da8-2e.png\",\n        \"2e.png\",\n        1920,\n        1040,\n        \"#333\"\n      ],\n      \"caption\": \"Configurações do environment\"\n    }\n  ]\n}\n[/block]\n### 3. Configurando o certificado no Postman\n\nTodas as requisições feitas à API de Pagamentos precisam do certificado gerado em sua conta Gerencianet. Portanto, para facilitar seus testes utilizando o Postman, siga os passos abaixo para configurar o uso do certificado durante as requisições de maneira automática:\n\n1. Clique no ícone de engrenagem no canto superior direito do Postman;\n2. Depois, clique em \"Settings\" para abrir as configurações;\n3. Na aba superior, clique em \"Certificates\";\n4. Em seguida, clique em \"Add Certificate\";\n3. Na janela de configuração do novo certificado, preencha o campo \"Host\" com a Rota base do ambiente ao qual o certificado pertence (Produção ou Homologação);\n4. Utilize o campo \"PFX File\" para informar ao Postman onde o arquivo do seu certificado P12/PEM se encontra;\n5. Finalize clicando em \"Add\" para salvar suas configurações.\n\nSeguindo esses passos, o Postman usará o certificado para quaisquer requisições feitas ao Host do ambiente configurado.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/66604ca-3e.png\",\n        \"3e.png\",\n        1920,\n        1040,\n        \"#333\"\n      ],\n      \"caption\": \"Acessando as configurações do Postman\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f3158a7-4e.png\",\n        \"4e.png\",\n        1920,\n        1040,\n        \"#333\"\n      ],\n      \"caption\": \"Adicionando um novo certificado no Postman\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/bd24fa2-5e.png\",\n        \"5e.png\",\n        1920,\n        1040,\n        \"#333\"\n      ],\n      \"caption\": \"Configurações do certificado\"\n    }\n  ]\n}\n[/block]\n### 4. Atribuindo o Client_Id e Client_Secret no Postman\n\nPara finalizar a configuração do seu Postman é necessário configurar as credenciais de uma aplicação da sua conta Gerencianet. Essas credenciais são usadas para o Basic Auth e obtenção do `access_token` junto ao OAuth.\n\nSiga os passos abaixo para incluir as credenciais e realizar o seu primeiro teste na API de Pagamentos.\n\n1. Na collection importada, navegue até a rota `/oauth/token` e clique duas vezes para abrir;\n2. Acesse o menu \"Authorization\" e certifique-se de que o \"Type\" (tipo de autorização) esteja selecionado como \"Basic Auth\";\n3. Nos campos \"username\" e \"password\" preencha com as credenciais da sua aplicação, Client_Id e Client_Secret, respectivamente;\n4. Para testar, clique no botão \"Send\" para submeter a requisição\n\nA imagem abaixo ilustra os passos acima. Se tudo foi seguido corretamente, você deve obter uma resposta em formato JSON, contendo o `access_token`, `token_type`, `expires_in` e `scope` (como na imagem abaixo).\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/942056c-auth.png\",\n        \"auth.png\",\n        1920,\n        1040,\n        \"#333\"\n      ],\n      \"caption\": \"Uso das credenciais de uma aplicação para autorização de requisições\"\n    }\n  ]\n}\n[/block]","updates":[],"order":0,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"6138af24617cee006a385de3","createdAt":"2021-09-08T12:40:04.885Z","user":"5e8b36bc27ee9b00181b36bf","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"API Pagamentos","slug":"api-pagamentos","order":1,"from_sync":false,"reference":false,"_id":"60d61f026ddc3901a32ee5f1","createdAt":"2021-06-25T18:22:58.645Z","version":"606f2ca7c5ba9100787834c6","project":"575aeffae12cf20e002f306c","__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","61473375119247002a9c14d7","6283a3819575c60045513ea2"],"_id":"606f2ca7c5ba9100787834c6","project":"575aeffae12cf20e002f306c","createdAt":"2016-06-10T16:51:06.080Z","releaseDate":"2016-06-10T16:51:06.080Z","__v":4,"forked_from":"575aeffae12cf20e002f306f"},"project":"575aeffae12cf20e002f306c","__v":0,"parentDoc":null}

Introdução

Esta página contém uma breve introdução da API de Pagamentos da Gerencianet e informações sobre como configurar um ambiente para seu consumo.

## API de Pagamentos Gerencianet A API de Pagamentos Gerencianet disponibiliza os nossos serviços para a realização de pagamentos de cobranças. Com nossa API é possível consultar cobranças à serem pagas, enviar ordens de pagamento e verificar o status de um pagamento. **Sumário** 1. [Entendendo os escopos de aplicação](#section-entendendo-os-escopos-de-aplica-o) 2. [Autenticação com OAuth2](#section-autentica-o-com-oauth2) 2.1 [Autorização](#section-autoriza-o) 3. [Configurando o Postman para testes](#section-configurando-o-postman-para-testes) 3.1 [Importando a Collection da API de Pagamentos](#section-1-importando-a-collection-da-api-de-pagamentos) 3.2 [Criando um Environment](#section-2-criando-um-environment) 3.3 [Configurando o certificado no Postman](#section-3-configurando-o-certificado-no-postman) 3.4 [Atribuindo o Client_Id e Client_Secret no Postman](#section-4-atribuindo-o-client_id-e-client_secret-no-postman) <hr> <br> ## Entendendo os escopos de aplicação Ao criar ou editar uma aplicação em sua Conta Gerencianet, você precisará configurar os escopos que a aplicação terá acesso. A escolha desses escopos define quais ações uma aplicação estará **autorizada** a realizar via API. Os escopos disponíveis na API de Pagamentos Gerencianet estão listados abaixo com suas respectivas descrições: - **`gn.barcode.read`** - Permissão para **consulta de cobranças à serem pagas**; - **`gn.barcode.pay.write`** - Permissão para **realizar uma ordem de pagamento**; - **`gn.barcode.pay.read`** - Permissão para **consulta de pagamentos**; <br> [block:callout] { "type": "warning", "title": "Liberação dos escopos", "body": "Caso queira utilizar a API de Pagamentos é necessário liberar os escopos citados acima, para isso entre em contato conosco pelo canal <a href=\"https://discord.gg/Xsb3AmKtyC\" target=\"_blank\">api-pagamentos</a> no Discord." } [/block] <br> ## Autenticação com OAuth2 O processo de autenticação na API de Pagamentos segui o protocolo [`OAuth2`]((http://oauth.net/2/), incluindo a utilização do certificado de segurança gerado em sua conta Gerencianet. Através dessa autenticação o OAuth2 poderá responder quais as autorizações que a aplicação tem e, consequentemente, autorizar ou negar as requisições de acordo com essa informação. Para mais detalhes referentes à autenticação com OAuth2, basta clicar no botão abaixo: [block:html] { "html": "<a href=\"https://dev.gerencianet.com.br/docs/endpoint-autorizacao-oauth\" target=\"_blank\" title=\"Autenticação API\"><button type=\"button\" class=\"btn btn-default navbar-btn buttonorange\">Autenticação OAuth2</button></a>" } [/block] ### Autorização A API de Pagamentos requer o uso de um certificado `PFX(.p12)` que é gerado em sua conta Gerencianet. O Auth2 fornece um mecanismo de autorização chamado de *mutual Transport Layer Security*(mTLS) por meio do certificado emitido em sua conta Gerencianet, tal método acrescenta mais um nível de segurança às requisições trafegadas entre sua aplicação e a API de Pagamentos. Para mais detalhes referentes a geração do `PFX(.p12)` e do padrão mTLS, basta clicar no botão abaixo: [block:html] { "html": "<a href=\"https://dev.gerencianet.com.br/v1.1.0/docs/autorizacao-api-mtls\" target=\"_blank\" title=\"Autorização com mTLS\"><button type=\"button\" class=\"btn btn-default navbar-btn buttonorange\">Autorização com mTLS</button></a>" } [/block] <br> ## Configurando o Postman para testes Para seguir com a etapa de configuração do Postman, você deve ter: 1. Um par de credenciais `Client_Id` e `Client_Secret` de uma aplicação cadastrada em sua Conta Gerencianet; 2. Um certificado P12/PEM gerado em sua conta Gerencianet; 3. O software Postman instalado em seu computador (Caso não tenha, [clique aqui para baixar](https://www.postman.com/downloads/)); ### 1. Importando a Collection da API de Pagamentos Este é o <a href="https://documenter.getpostman.com/view/13574984/UyrDCurw" target="_blank" alt="link">link</a> da nossa Collection que manteremos atualizada com o endpoints da API de Pagamentos da Gerencianet. [![Run in Postman](https://run.pstmn.io/button.svg)](https://documenter.getpostman.com/view/13574984/UyrDCurw) 2. Com o Postman iniciado, use o atalho `Ctrl+O` para abrir a tela de importação; 3. Selecione o arquivo da *Collection*; 4. Por último, clique em *Import* [block:image] { "images": [ { "image": [ "https://files.readme.io/9e9b734-1.png", "1.png", 1920, 1040, "#333" ], "caption": "Ilustração do início do processo de importação" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/a8ef473-23.png", "23.png", 1920, 1040, "#333" ], "caption": "Ilustração da importação do arquivo" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/b7e3b1e-4.png", "4.png", 1920, 1040, "#333" ], "caption": "Ilustração da etapa final da importação" } ] } [/block] ### 2. Criando um Environment A criação de um *Environment* no Postman é necessária para que algumas automações embutidas na collection funcionem. Essas automações foram projetadas para dar mais facilidade aos desenvolvedores durante os testes. Com elas você precisa solicitar a autorização apenas uma vez e, então, o `access_token` fica gravado como uma variável de ambiente (*environment*) do Postman, disponível para utilização nas requisições subsequentes. Para criar um Environment siga os passos abaixo. 1. Acione o atalho `Ctrl+N` e selecione "Environment"; 2. Atribua um nome preferencialmente especificando se esse Environment será apontado para o ambiente de Produção ou Homologação; 3. Crie a variável `gn-api-pag` e como valor inicial (*Initial value*) insira a URL da API de Pagamentos de Produção ou Homologação; 4. Salve o seu Environment; 5. Selecione o Environment desejado, assim o Postman entenderá a variável criada. As imagens abaixo ilustram os passos acima. Como exemplo, foi criado um Environment apontado para o ambiente de Produção da API de Pagamentos Gerencianet. [block:image] { "images": [ { "image": [ "https://files.readme.io/04c4ca4-1e.png", "1e.png", 1920, 1040, "#333" ], "caption": "Criando um novo environment" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/6876da8-2e.png", "2e.png", 1920, 1040, "#333" ], "caption": "Configurações do environment" } ] } [/block] ### 3. Configurando o certificado no Postman Todas as requisições feitas à API de Pagamentos precisam do certificado gerado em sua conta Gerencianet. Portanto, para facilitar seus testes utilizando o Postman, siga os passos abaixo para configurar o uso do certificado durante as requisições de maneira automática: 1. Clique no ícone de engrenagem no canto superior direito do Postman; 2. Depois, clique em "Settings" para abrir as configurações; 3. Na aba superior, clique em "Certificates"; 4. Em seguida, clique em "Add Certificate"; 3. Na janela de configuração do novo certificado, preencha o campo "Host" com a Rota base do ambiente ao qual o certificado pertence (Produção ou Homologação); 4. Utilize o campo "PFX File" para informar ao Postman onde o arquivo do seu certificado P12/PEM se encontra; 5. Finalize clicando em "Add" para salvar suas configurações. Seguindo esses passos, o Postman usará o certificado para quaisquer requisições feitas ao Host do ambiente configurado. [block:image] { "images": [ { "image": [ "https://files.readme.io/66604ca-3e.png", "3e.png", 1920, 1040, "#333" ], "caption": "Acessando as configurações do Postman" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/f3158a7-4e.png", "4e.png", 1920, 1040, "#333" ], "caption": "Adicionando um novo certificado no Postman" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/bd24fa2-5e.png", "5e.png", 1920, 1040, "#333" ], "caption": "Configurações do certificado" } ] } [/block] ### 4. Atribuindo o Client_Id e Client_Secret no Postman Para finalizar a configuração do seu Postman é necessário configurar as credenciais de uma aplicação da sua conta Gerencianet. Essas credenciais são usadas para o Basic Auth e obtenção do `access_token` junto ao OAuth. Siga os passos abaixo para incluir as credenciais e realizar o seu primeiro teste na API de Pagamentos. 1. Na collection importada, navegue até a rota `/oauth/token` e clique duas vezes para abrir; 2. Acesse o menu "Authorization" e certifique-se de que o "Type" (tipo de autorização) esteja selecionado como "Basic Auth"; 3. Nos campos "username" e "password" preencha com as credenciais da sua aplicação, Client_Id e Client_Secret, respectivamente; 4. Para testar, clique no botão "Send" para submeter a requisição A imagem abaixo ilustra os passos acima. Se tudo foi seguido corretamente, você deve obter uma resposta em formato JSON, contendo o `access_token`, `token_type`, `expires_in` e `scope` (como na imagem abaixo). [block:image] { "images": [ { "image": [ "https://files.readme.io/942056c-auth.png", "auth.png", 1920, 1040, "#333" ], "caption": "Uso das credenciais de uma aplicação para autorização de requisições" } ] } [/block]