{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"Endpoints","type":"basic","slug":"endpoints-api-open-finance","excerpt":"Informações de todos os endpoints disponíveis na API Open Finance","body":"Nesta página você encontra todos os endpoints disponíveis na API Open Finance  da Gerencianet e informações de como utilizá-los corretamente, como por exemplo os escopos necessários para o consumo de cada rota e os detalhes de retorno dos mesmos.\n\nUtilize o sumário abaixo para navegar rapidamente entre os grupos de endpoints da API.\n\n**Sumário**\n1. [Participantes](#section-participantes)\n1.1 [Recuperar as instituições participantes do Open Finance](#section-recuperar-as-institui-es-participantes-do-open-finance)\n2. [Pagamentos](#section-pagamentos)\n2.1 [Solicitar iniciação de Pix via Open Finance](#section-solicitar-inicia-o-de-pix-via-open-finance)\n2.2 [Listar pagamentos por um determinado período](#section-listar-pagamentos-por-um-determinado-per-odo)\n3. [Config](#section-config)\n3.1 [Configurar URLs da aplicação](#section-configurar-urls-da-aplica-o)\n3.2 [Retornar as configurações da aplicação](#section-retornar-as-configura-es-da-aplica-o)\n4. [Recebendo Callbacks](#section-recebendo-callbacks)\n \n\n## Tutorial API Open Finance da Gerencianet\n\n## Rota base\n\n Rotas base ou URL's base para ambientes, utilize as rotas abaixo para realizar a comunicação da sua aplicação com o ambiente de produção ou homologação oferecidos pela Gerencianet.\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"**Produção**\",\n    \"0-1\": \"`https://apis.gerencianet.com.br`\",\n    \"1-0\": \"**Homologação**\",\n    \"1-1\": \"`https://apis-h.gerencianet.com.br`\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n<br>\n## Obter Autorização\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"gn-endpoint\\\">\\n    <span class=\\\"http-method post\\\">POST</span>\\n  \\t<span class=\\\"endpoint\\\">\\n        /oauth/token\\n    </span>\\n</div>\"\n}\n[/block]\nEste endpoint é utilizado para autorizar as credenciais de uma aplicação e obter os escopos que a aplicação possui para acessar os outros endpoints da API. É necessário que o certificado P12/PEM esteja presente na requisição de autorização a fim de que o *handshake* com o servidor da API seja permitido.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Para habilitar os escopos da API Open Finance, basta [abrir um ticket](https://gerencianet.com.br/fale-conosco/) informando o número da conta e o Client_Id da aplicação desejada.\\nÉ possível também, solicitar a liberação através de nossa [comunidade no Discord](https://discord.gg/ptGHMtczcV).\",\n  \"title\": \"Atenção\"\n}\n[/block]\n### Exemplos de autorização utilizando o certificado .P12\n\nPara a utilização da API Open Finance da Gerencianet é necessário que o cliente e o servidor se comuniquem em uma conexão verificada um com o outro. A verificação é feita pelo certificado bidirecional (.PEM ou .P12), isto é, o servidor e o cliente implementaram um certificado de chave privada e um certificado de chave pública que permite que um possa assegurar-se da identidade do outro.\n\nPor isso para fazer qualquer requisição HTTP à API Open Finance da Gerencianet, incluindo a requisição de autorização junto ao OAuth2, é necessário que o certificado .P12, ou .PEM, esteja presente nos cabeçalhos da requisição.\n\nAbaixo, trazemos exemplos de como consumir a autorização da API Open Finance da Gerencianet, incorporando esse certificado na requisição.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php //Desenvolvido pela Consultoria Técnica da Gerencianet\\n\\n$config = [\\n  \\\"certificado\\\" => \\\"./certificado.pem\\\",\\n  \\\"client_id\\\" => \\\"YOUR-CLIENT-ID\\\",\\n  \\\"client_secret\\\" => \\\"YOUR-CLIENT-SECRET\\\"\\n];\\n$autorizacao =  base64_encode($config[\\\"client_id\\\"] . \\\":\\\" . $config[\\\"client_secret\\\"]);\\n\\n$curl = curl_init();\\n\\ncurl_setopt_array($curl, array(\\n    CURLOPT_URL => \\\"https://apis.gerencianet.com.br/open-finance/oauth/token\\\", // Rota base, homologação ou produção\\n    CURLOPT_RETURNTRANSFER => true,\\n    CURLOPT_ENCODING => \\\"\\\",\\n    CURLOPT_MAXREDIRS => 10,\\n    CURLOPT_TIMEOUT => 0,\\n    CURLOPT_FOLLOWLOCATION => true,\\n    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\\n    CURLOPT_CUSTOMREQUEST => \\\"POST\\\",\\n    CURLOPT_POSTFIELDS => '{\\\"grant_type\\\": \\\"client_credentials\\\"}',\\n    CURLOPT_SSLCERT => $config[\\\"certificado\\\"], // Caminho do certificado\\n    CURLOPT_SSLCERTPASSWD => \\\"\\\",\\n    CURLOPT_HTTPHEADER => array(\\n        \\\"Authorization: Basic $autorizacao\\\",\\n        \\\"Content-Type: application/json\\\"\\n    ),\\n));\\n\\n$response = curl_exec($curl);\\n\\ncurl_close($curl);\\n\\necho \\\"<pre>\\\";\\necho $response;\\necho \\\"</pre>\\\";\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"//Desenvolvido pela Consultoria Técnica da Gerencianet\\n\\n\\\"use strict\\\";\\nconst https = require(\\\"https\\\");\\nvar axios = require(\\\"axios\\\");\\nvar fs = require(\\\"fs\\\");\\n\\n//Insira o caminho de seu certificado .p12 dentro de seu projeto\\nvar certificado = fs.readFileSync(\\\"./certificado.p12\\\");\\n\\n//Insira os valores de suas credenciais em desenvolvimento do pix\\nvar credenciais = {\\n  client_id: \\\"YOUR-CLIENT-ID\\\",\\n  client_secret: \\\"YOUR-CLIENT-SECRET\\\",\\n};\\n\\nvar data = JSON.stringify({ grant_type: \\\"client_credentials\\\" });\\nvar data_credentials = credenciais.client_id + \\\":\\\" + credenciais.client_secret;\\n\\n// Codificando as credenciais em base64\\nvar auth = Buffer.from(data_credentials).toString(\\\"base64\\\");\\n\\nconst agent = new https.Agent({\\n  pfx: certificado,\\n  passphrase: \\\"\\\",\\n});\\n//Consumo em desenvolvimento da rota post oauth/token\\nvar config = {\\n  method: \\\"POST\\\",\\n  url: \\\"https://apis.gerencianet.com.br/open-finance/oauth/token\\\",\\n  headers: {\\n    Authorization: \\\"Basic \\\" + auth,\\n    \\\"Content-Type\\\": \\\"application/json\\\",\\n  },\\n  httpsAgent: agent,\\n  data: data,\\n};\\n\\naxios(config)\\n  .then(function (response) {\\n    console.log(JSON.stringify(response.data));\\n  })\\n  .catch(function (error) {\\n    console.log(error);\\n  });\",\n      \"language\": \"javascript\",\n      \"name\": \"Node\"\n    },\n    {\n      \"code\": \"#Desenvolvido pela Consultoria Técnica da Gerencianet\\n\\nimport requests\\nimport base64\\n\\ncredentials = {\\n    \\\"client_id\\\": \\\"YOUR-CLIENT-ID\\\",\\n    \\\"client_secret\\\": \\\"YOUR-CLIENT-SECRET\\\",\\n}\\n\\ncertificado = './certificado.pem'  # A variável certificado é o diretório em que seu certificado em formato .pem deve ser inserido\\n\\nauth = base64.b64encode(\\n    (f\\\"{credentials['client_id']}:{credentials['client_secret']}\\\"\\n     ).encode()).decode()\\n\\nurl = \\\"https://apis.gerencianet.com.br/open-finance/oauth/token\\\"  #Para ambiente de Desenvolvimento\\n\\npayload=\\\"{\\\\r\\\\n    \\\\\\\"grant_type\\\\\\\": \\\\\\\"client_credentials\\\\\\\"\\\\r\\\\n}\\\"\\nheaders = {\\n    'Authorization': f\\\"Basic {auth}\\\",\\n    'Content-Type': 'application/json'\\n}\\n\\nresponse = requests.request(\\\"POST\\\",\\n                            url,\\n                            headers=headers,\\n                            data=payload,\\n                            cert=certificado)\\n\\nprint(response.text)\",\n      \"language\": \"python\",\n      \"name\": \"Python\"\n    },\n    {\n      \"code\": \"//Desenvolvido pela Consultoria Técnica da Gerencianet\\n\\nusing System;\\nusing System.Security.Cryptography.X509Certificates;\\nusing System.Collections.Generic;\\nusing RestSharp;\\n\\nnamespace PixGerencianet\\n{\\n    class Authorize\\n    {\\n        public static string Base64Encode(string plainText)\\n        {\\n            var plainTextBytes = System.Text.Encoding.UTF8.GetBytes(plainText);\\n            return System.Convert.ToBase64String(plainTextBytes);\\n        }\\n\\n        static void Main(string[] args)\\n        {\\n\\n            var credencials = new Dictionary<string, string>{\\n                {\\\"client_id\\\", \\\"YOUR-CLIENT-ID\\\"},\\n                {\\\"client_secret\\\", \\\"YOUR-CLIENT-SECRET\\\"}\\n            };\\n            var authorization = Base64Encode(credencials[\\\"client_id\\\"] + \\\":\\\" + credencials[\\\"client_secret\\\"]);\\n            var client = new RestSharp.RestClient(\\\"https://apis.gerencianet.com.br/open-finance/oauth/token\\\");\\n            var request = new RestRequest(Method.POST);\\n\\n            X509Certificate2 uidCert = new X509Certificate2(\\\"./certificado.p12\\\", \\\"\\\");\\n            client.ClientCertificates = new X509CertificateCollection() { uidCert };\\n\\n            request.AddHeader(\\\"Authorization\\\", \\\"Basic \\\" + authorization);\\n            request.AddHeader(\\\"Content-Type\\\", \\\"application/json\\\");\\n            request.AddParameter(\\\"application/json\\\", \\\"{\\\\r\\\\n    \\\\\\\"grant_type\\\\\\\": \\\\\\\"client_credentials\\\\\\\"\\\\r\\\\n}\\\", ParameterType.RequestBody);\\n            \\n            IRestResponse restResponse = client.Execute(request);\\n            string response = restResponse.Content;\\n\\n            Console.WriteLine(response);\\n        }\\n    }\\n}\",\n      \"language\": \"csharp\"\n    },\n    {\n      \"code\": \"#Desenvolvido pela Consultoria Técnica da Gerencianet\\n\\nrequire \\\"uri\\\"\\nrequire \\\"net/http\\\"\\nrequire \\\"openssl\\\"\\n\\nclient_id = \\\"YOUR-CLIENT-ID\\\";\\nclient_secret = \\\"YOUR-CLIENT-SECRET\\\";\\n\\ncertfile = File.read(\\\"certificado.pem\\\") # A variável certfile é o diretório em que seu certificado em formato .pem deve ser inserido\\n\\nurl = URI(\\\"https://apis.gerencianet.com.br/open-finance/oauth/token\\\") #Para ambiente de Desenvolvimento\\n\\nhttps = Net::HTTP.new(url.host, url.port);\\nhttps.use_ssl = true\\nhttps.cert = OpenSSL::X509::Certificate.new(certfile)\\nhttps.key = OpenSSL::PKey::RSA.new(certfile)\\n\\nrequest = Net::HTTP::Post.new(url)\\nrequest.basic_auth(client_id, client_secret)\\nrequest[\\\"Content-Type\\\"] = \\\"application/json\\\"\\nrequest.body = \\\"{\\\\r\\\\n    \\\\\\\"grant_type\\\\\\\": \\\\\\\"client_credentials\\\\\\\"\\\\r\\\\n}\\\"\\n\\nresponse = https.request(request)\\nputs response.read_body\",\n      \"language\": \"ruby\"\n    },\n    {\n      \"code\": \"//Desenvolvido pela Consultoria Técnica da Gerencianet\\n\\nimport java.io.BufferedReader;\\nimport java.io.InputStreamReader;\\nimport java.io.OutputStream;\\nimport java.net.URL;\\nimport java.util.Base64;\\n\\nimport javax.net.ssl.HttpsURLConnection;\\nimport javax.net.ssl.SSLSocketFactory;\\n\\npublic class Auth {\\n    public static void main(String[] args) throws Exception {\\n        String client_id = \\\"YOUR-CLIENT-ID\\\";\\n        String client_secret = \\\"YOUR-CLIENT-SECRET\\\";;\\n        String basicAuth = Base64.getEncoder().encodeToString(((client_id+':'+client_secret).getBytes()));\\n      \\n      \\t//Diretório em que seu certificado em formato .p12 deve ser inserido\\n        System.setProperty(\\\"javax.net.ssl.keyStore\\\", \\\"certificado.p12\\\"); \\n        SSLSocketFactory sslsocketfactory = (SSLSocketFactory) SSLSocketFactory.getDefault();\\n        \\n        URL url = new URL (\\\"https://apis.gerencianet.com.br/open-finance/oauth/token\\\"); //Para ambiente de Desenvolvimento              \\n        HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();\\n        conn.setDoOutput(true);\\n        conn.setRequestMethod(\\\"POST\\\");\\n        conn.setRequestProperty(\\\"Content-Type\\\", \\\"application/json\\\");\\n        conn.setRequestProperty(\\\"Authorization\\\", \\\"Basic \\\"+ basicAuth);\\n        conn.setSSLSocketFactory(sslsocketfactory);\\n        String input = \\\"{\\\\\\\"grant_type\\\\\\\": \\\\\\\"client_credentials\\\\\\\"}\\\";\\n       \\n        OutputStream os = conn.getOutputStream();\\n        os.write(input.getBytes());\\n        os.flush();\\t\\t\\n\\n        InputStreamReader reader = new InputStreamReader(conn.getInputStream());\\n        BufferedReader br = new BufferedReader(reader);\\n\\n        String response;\\n        while ((response = br.readLine()) != null) {\\n          System.out.println(response);\\n        }\\n        conn.disconnect();\\n\\n    }\\n}\",\n      \"language\": \"java\"\n    },\n    {\n      \"code\": \"//Desenvolvido pela Consultoria Técnica da Gerencianet\\npackage main\\n\\nimport (\\n  \\\"fmt\\\"\\n  \\\"strings\\\"\\n  \\\"net/http\\\"\\n  \\\"io/ioutil\\\"\\n  \\\"crypto/tls\\\"\\n)\\n\\nconst(\\n  client_id = \\\"YOUR-CLIENT-ID\\\"\\n  client_secret = \\\"YOUR-CLIENT-SECRET\\\"\\n)\\n\\nfunc main() {\\n\\n  url := \\\"https://apis.gerencianet.com.br/open-finance/oauth/token\\\"// Rota base, homologação ou produção\\n  method := \\\"POST\\\"\\n\\n  payload := strings.NewReader(`{\\\"grant_type\\\": \\\"client_credentials\\\"}`)\\n\\n\\n  cert, _ := tls.LoadX509KeyPair(\\\"CA.crt.pem\\\", \\\"KEY.crt.pem\\\")// Seu certificado e chave privada gerada a partir dos comandos de conversão OpenSSL\\n\\n  client := &http.Client{\\n    Transport: &http.Transport{\\n        TLSClientConfig: &tls.Config{\\n            Certificates: []tls.Certificate{cert},\\n        },\\n    },\\n}\\n\\n  req, err := http.NewRequest(method, url, payload)\\n\\n  if err != nil {\\n    fmt.Println(err)\\n    return\\n  }\\n  req.SetBasicAuth(client_id, client_secret)\\n  req.Header.Add(\\\"Content-Type\\\", \\\"application/json\\\")\\n\\n  res, err := client.Do(req)\\n  if err != nil {\\n    fmt.Println(err)\\n    return\\n  }\\n  defer res.Body.Close()\\n\\n  body, err := ioutil.ReadAll(res.Body)\\n  if err != nil {\\n    fmt.Println(err)\\n    return\\n  }\\n  fmt.Println(string(body))\\n}\",\n      \"language\": \"go\"\n    }\n  ]\n}\n[/block]\n#### Exemplo de resposta da autorização\n\nO trecho de código abaixo representa um exemplo de resposta do OAuth à sua requisição de autorização.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"access_token\\\": \\\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\\\",\\n    \\\"token_type\\\": \\\"Bearer\\\",\\n    \\\"expires_in\\\": 3600,\\n    \\\"scope\\\": \\\"gn.opb.paticipants.read gn.opb.pix.send gn.opb.config.write gn.opb.config.read\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Resposta\"\n    }\n  ]\n}\n[/block]\n<br>\n\n## Participantes\n\n### Recuperar as instituições participantes do Open Finance\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"gn-endpoint\\\">\\n    <span class=\\\"http-method get\\\">GET</span>\\n    <span class=\\\"endpoint\\\">/open-finance/participantes/<span class=\\\"variable\\\">:nome</span></span>\\n</div>\"\n}\n[/block]\n\nEsse endpoint retorna um ou mais  participantes que estão ativos no Open Finance. \n**Requer autorização para o escopo:** **`gn.opb.paticipants.read`**\n\n#### Requisição \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Atributo\",\n    \"h-1\": \"Descrição\",\n    \"h-2\": \"Obrigatório\",\n    \"h-3\": \"Tipo\",\n    \"0-0\": \"Nome\",\n    \"0-1\": \"Nome do psp que será pesquisado\",\n    \"0-2\": \"Não\",\n    \"0-3\": \"String\"\n  },\n  \"cols\": 4,\n  \"rows\": 1\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"\",\n  \"body\": \"Caso não seja enviado o atributo nome, serão retornados todos os participantes ativos no Open Finance.\"\n}\n[/block]\n\n\n\n#### Respostas\nAs respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Lista com um ou mais participantes do Open Finance\\n{\\n  \\\"participantes\\\": [\\n    {\\n      \\\"identificador\\\": \\\"9f4cd202-8f2b-11ec-b909-0242ac120002\\\",\\n      \\\"nome\\\": \\\"MARCA GERENCIANET\\\",\\n      \\\"descricao\\\": \\\"Descrição da marca\\\",\\n      \\\"portal\\\": \\\"https://openbankingbrasil.org.br/quem-participa/\\\",\\n      \\\"logo\\\": \\\"https://www.gerencianet.com.br/logo.png\\\",\\n      \\\"organizacoes\\\": [\\n        {\\n          \\\"nome\\\": \\\"Gerencianet\\\",\\n          \\\"cnpj\\\": \\\"09089356000118,\\\",\\n          \\\"status\\\": \\\"Ativo\\\"\\n        }\\n      ]\\n    }\\n  ]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"200(Success)\"\n    },\n    {\n      \"code\": \"Nome inválido\\n{\\n  \\\"nome\\\": \\\"participante_nao_encontrado\\\",\\n  \\\"mensagem\\\": \\\"Nenhum participante encontrado\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"404(Not Found)\"\n    },\n    {\n      \"code\": \"Este erro ocorre nas seguintes situações:\\n\\n* Certificado ou credenciais não existem;\\n* Certificado ou credenciais estão desativados;\\n* Certificado e credenciais não estão vinculados a mesma conta Gerencianet;\\n* Integrador não tem permissão para o escopo de serviço necessário para consumir este endpoint.\",\n      \"language\": \"json\",\n      \"name\": \"401(Unauthorized)\"\n    },\n    {\n      \"code\": \"Este erro ocorre nas seguintes situações:\\n\\n* Integrador solicita acesso a um escopo ao qual não tem permissão.\",\n      \"language\": \"json\",\n      \"name\": \"403(Forbidden)\"\n    },\n    {\n      \"code\": \"Precondition Failed. Este erro ocorre nas seguintes situações:\\n\\n* Integrador deve ter pelo menos um Webhook cadastrado.\\n{\\n  \\\"nome\\\": \\\"webhook_nao_cadastrado\\\",\\n  \\\"mensagem\\\": \\\"Sua conta não possui webhook cadastrado na API de Cadastro.\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"412(Precondition Failed)\"\n    },\n    {\n      \"code\": \"Erro na aplicação\\n{\\n  \\\"nome\\\": \\\"erro_aplicacao\\\",\\n  \\\"mensagem\\\": \\\"Erro interno do servidor\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"500(Error)\"\n    }\n  ]\n}\n[/block]\n## Pagamentos\n### Solicitar iniciação de Pix via Open Finance\n[block:html]\n{\n  \"html\": \"<div class=\\\"gn-endpoint\\\">\\n    <span class=\\\"http-method post\\\">POST</span>\\n    <span class=\\\"endpoint\\\">/open-finance/pagamentos/pix</span>\\n</div>\"\n}\n[/block]\n\nEste endpoint é utilizado para a inserção das informações do pagamento a ser iniciado e a saída é uma url de redirecionamento, que deve ser inserida em um botão para que o usuário clique e seja redirecionado para a instituição detentora de conta.\n#### Requisição\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Atributo\",\n    \"h-1\": \"Descrição\",\n    \"h-2\": \"Obrigatório\",\n    \"0-0\": \"**x-idempotency-key**\",\n    \"0-1\": \"Chave única para evitar duplicidade em requisições em um curto espaço de tempo. Caso ocorra o envio de várias requisições com a mesma informação no mesmo instante, uma delas será processada com sucesso. Se outra requisição for enviada com a mesma chave, será retornado o erro 409.\\n(Este atributo deve ser enviado no Header)\",\n    \"0-2\": \"Sim\",\n    \"h-3\": \"Tipo\",\n    \"0-3\": \"String \\n`minLength: 36`\\n`maxLength: 72`\"\n  },\n  \"cols\": 4,\n  \"rows\": 1\n}\n[/block]\n.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Exemplo de iniciação de pagamento\\n{\\n  \\\"pagador\\\": {\\n    \\\"idParticipante\\\": \\\"9f4cd202-8f2b-11ec-b909-0242ac120002\\\",\\n    \\\"cpf\\\": \\\"45204392050\\\", // cpf ou cnpj\\n    \\\"cnpj\\\": \\\"90293071000112\\\"\\n  },\\n  \\\"favorecido\\\": {\\n    \\\"contaBanco\\\": {\\n      \\\"codigoBanco\\\": \\\"364\\\",\\n      \\\"agencia\\\": \\\"0001\\\",\\n      \\\"documento\\\": \\\"11122233344\\\",\\n      \\\"nome\\\": \\\"Luiz Silva\\\",\\n      \\\"conta\\\": \\\"654984\\\",\\n      \\\"tipoConta\\\": \\\"CACC\\\"\\n    }\\n  },\\n  \\\"valor\\\": \\\"9.90\\\",\\n  \\\"codigoCidadeIBGE\\\": \\\"3540000\\\",\\n  \\\"infoPagador\\\": \\\"Compra dia xx\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Iniciação de pagamento\"\n    }\n  ]\n}\n[/block]\nDados que podem ser utilizados na requisição de iniciação de pagamento:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Atributo\",\n    \"h-1\": \"Descrição\",\n    \"h-2\": \"Obrigatório\",\n    \"h-3\": \"Tipo\",\n    \"0-0\": \"**Pagador**\",\n    \"0-1\": \"Os campos aninhados sob o identificador pagador organizam informações a respeito de dados do cliente final ao qual vai se gerar a cobrança.\\n\\npagador:\\n<div class=\\\"tab2\\\">`idParticipante*`// Identificador do participante no diretório do Banco Central. (String)\\n\\n`cpf*`// CPF do cliente final pessoa física. (String)\\n\\n`cnpj*`// CNPJ do cliente final pessoa jurídica. (String)\\n</div>\",\n    \"1-0\": \"**Favorecido**\",\n    \"1-1\": \"Os campos aninhados sob o identificador favorecido organizam informações a respeito dos dados da  conta final que irá receber.\\n\\nfavorecido:\\n<div class=\\\"tab2\\\">`contaBanco*`:\\n<div class=\\\"tab2\\\">\\n`codigoBanco*`// Código do banco (String)\\n\\n`agencia*`\\n (String)\\n\\n`documento*`// Documento do dono da conta (String)\\n`nome*`// Nome do titular (String)\\n\\n`conta*`// Número da conta com dígito (String)\\n\\n`tipoConta*`:\\n  *   CACC: Conta Corrente, usada para lançar débitos e créditos em geral.\\n  * SLRY: Conta Salário, utilizadas para pagamentos de salários.\\n  * SVGS: Conta Poupança, usada para poupança.\\n  * TRAN: Conta de Transações, usada como tipo básico de conta.\\n (Enum)\\n//[ CACC, SLRY, SVGS, TRAN ]\\n\\n</div>\\n</div>\",\n    \"1-2\": \"Sim\",\n    \"2-0\": \"**Valor**\",\n    \"2-1\": \"Valor do pagamento\",\n    \"0-2\": \"Sim\",\n    \"2-2\": \"Sim\",\n    \"0-3\": \"Object\",\n    \"1-3\": \"Object\",\n    \"2-3\": \"String\",\n    \"3-0\": \"**codigoCidadeIBGE**\",\n    \"3-1\": \"Código da cidade segundo o IBGE\",\n    \"3-2\": \"Não\",\n    \"3-3\": \"String\",\n    \"4-0\": \"**infoPagador**\",\n    \"4-1\": \"Informações pertinentes ao pagador final\\n200(Success)\",\n    \"4-2\": \"Não\",\n    \"4-3\": \"String\"\n  },\n  \"cols\": 4,\n  \"rows\": 5\n}\n[/block]\n#### Respostas\nAs respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\n{\\n  \\\"identificadorPagamento\\\": \\\"ae71713f-875b-4af3-9d85-0bcb43288847\\\",\\n  \\\"redirectURL\\\": \\\"https://open-banking.banco.com.br/authorize?request=eyJjd&redirect_uri=https://pub.opb.testegerencianet.com.br/callback&scope=openid%20pagamentos%20consent:urn:gerencianet:fdf36ac8-f213-4057-bf2e-2ce7bd828abf&response_type=code%20id_token\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"200(Success)\"\n    },\n    {\n      \"code\": \"\\n{\\n  \\\"nome\\\": \\\"codigo_banco_favorecido_obrigatorio\\\",\\n  \\\"mensagem\\\": \\\"O código do banco favorecido é obrigatório\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"400(Bad Request)\"\n    },\n    {\n      \"code\": \"\\nEste erro ocorre nas seguintes situações:\\n\\n* Certificado ou credenciais não existem;\\n* Certificado ou credenciais estão desativados;\\n* Certificado e credenciais não estão vinculados a mesma conta Gerencianet;\\n* Integrador não tem permissão para o escopo de serviço necessário para consumir este endpoint.\",\n      \"language\": \"json\",\n      \"name\": \"401(Unauthorized)\"\n    },\n    {\n      \"code\": \"\\nEste erro ocorre nas seguintes situações:\\n\\n* Integrador solicita acesso a um escopo ao qual não tem permissão.\",\n      \"language\": \"json\",\n      \"name\": \"403(Forbbiden)\"\n    },\n    {\n      \"code\": \"\\n{\\n  \\\"nome\\\": \\\"conflito_chave_idempotencia\\\",\\n  \\\"mensagem\\\": \\\"Chave de idempotência repetida para pagamento diferente\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"409(Conflict)\"\n    },\n    {\n      \"code\": \"\\n{\\n  \\\"nome\\\": \\\"codigo_banco_nao_permitido\\\",\\n  \\\"mensagem\\\": \\\"O código do banco informado não é permitido\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"422(Unprocessable)\"\n    },\n    {\n      \"code\": \"\\n{\\n  \\\"nome\\\": \\\"chave_idempotencia_invalida\\\",\\n  \\\"mensagem\\\": \\\"Tamanho da chave de idempotência inválido\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"431(Fields Too Large)\"\n    },\n    {\n      \"code\": \"\\n{\\n  \\\"nome\\\": \\\"erro_aplicacao\\\",\\n  \\\"mensagem\\\": \\\"Ocorreu um erro ao criar o pagamento\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"500(Error)\"\n    }\n  ]\n}\n[/block]\n### Listar pagamentos por um determinado período\n[block:html]\n{\n  \"html\": \"<div class=\\\"gn-endpoint\\\">\\n    <span class=\\\"http-method get\\\">GET</span>\\n    <span class=\\\"endpoint\\\">/open-finance/pagamentos/pix</span>\\n</div>\"\n}\n[/block]\nEste endpoint é utilizado para listar as informações dos pagamentos que foram efetuados em um período de tempo.\n\nEste endpoint possui os filtros obrigatórios de inicio e fim que representam o intervalo de datas em que as cobranças consultadas devem estar compreendidas.\n#### Requisição\n\nDados que podem ser utilizados na requisição de listagem das informações:\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Atributo\",\n    \"h-1\": \"Descrição\",\n    \"h-2\": \"Obrigatório\",\n    \"0-0\": \"**inicio**\",\n    \"1-0\": \"**fim**\",\n    \"2-0\": \"**quantidade**\",\n    \"3-0\": \"**página**\",\n    \"0-1\": \"Data início da criação do pagamento \\n\\nExemplo : 2022-04-29\",\n    \"0-2\": \"Sim\",\n    \"1-2\": \"Sim\",\n    \"2-2\": \"Não\",\n    \"3-2\": \"Não\",\n    \"1-1\": \"Data início da criação do pagamento \\n\\nExemplo : 2022-04-29\",\n    \"2-1\": \"Quantidade de retornos por página \\n\\nExemplo : 5\",\n    \"3-1\": \"número da página que deseja consultar de acordo com a quantidade \\n\\nExemplo : 2\",\n    \"h-3\": \"Tipo\",\n    \"0-3\": \"String\",\n    \"1-3\": \"String\",\n    \"2-3\": \"String\",\n    \"3-3\": \"String\",\n    \"4-0\": \"**status**\",\n    \"4-1\": \"Status do pagamento\",\n    \"4-2\": \"Não\",\n    \"4-3\": \"String\",\n    \"5-0\": \"**identificador**\",\n    \"5-1\": \"Identificador do pagamento (Se este campo é informado os demais são desconsiderados na busca)\",\n    \"5-2\": \"Não\",\n    \"5-3\": \"String\"\n  },\n  \"cols\": 4,\n  \"rows\": 6\n}\n[/block]\n#### Respostas\nAs respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"pagamentos\\\": [\\n    {\\n      \\\"identificadorPagamento\\\": \\\"urn:gerencianet:49315a93-d39c-4564-9edb-9a73678dbdb1\\\",\\n      \\\"valor\\\": \\\"1.99\\\",\\n      \\\"status\\\": \\\"pendente\\\",\\n      \\\"dataCriacao\\\": \\\"2022-04-29T11:55:03.000Z\\\"\\n    }\\n  ],\\n  \\\"total\\\": 3,\\n  \\\"porPagina\\\": 1,\\n  \\\"ultimo\\\": \\\"/pagamentos/pix?inicio=2022-04-29&fim=2022-04-29&quantidade=1&pagina=3\\\",\\n  \\\"proximo\\\": \\\"/pagamentos/pix?inicio=2022-04-29&fim=2022-04-29&quantidade=1&pagina=2\\\",\\n  \\\"anterior\\\": null,\\n  \\\"atual\\\": \\\"/pagamentos/pix?inicio=2022-04-29&fim=2022-04-29&quantidade=1&pagina=1\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"200(Sucess)\"\n    },\n    {\n      \"code\": \"{\\n  \\\"nome\\\": \\\"data_inicio_invalido\\\",\\n  \\\"mensagem\\\": \\\"A data início é inválido\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"400(Bad Request)\"\n    },\n    {\n      \"code\": \"{\\n  \\\"nome\\\": \\\"pagamento_nao_encontrado\\\",\\n  \\\"mensagem\\\": \\\"Nenhum pagamento encontrado\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"404(Unkown Payment Error)\"\n    },\n    {\n      \"code\": \"{\\n  \\\"nome\\\": \\\"data_inicio_obrigatorio\\\",\\n  \\\"mensagem\\\": \\\"A data início é obrigatório\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"422(Unprocessable)\"\n    },\n    {\n      \"code\": \"{\\n  \\\"nome\\\": \\\"data_inicio_obrigatorio\\\",\\n  \\\"mensagem\\\": \\\"A data início é obrigatório\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"500(Server Error)\"\n    }\n  ]\n}\n[/block]\n## Configurações da aplicação\n### Configurar URLs da aplicação\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"gn-endpoint\\\">\\n    <span class=\\\"http-method post\\\">PUT</span>\\n    <span class=\\\"endpoint\\\">/open-finance/config</span>\\n</div>\"\n}\n[/block]\nEsse endpoint é utilizado para criar ou modificar uma configuração na aplicação relacionada a API Open Finance.\n\n#### Requisição\n\nDados para a configuração.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Exemplo configurando uma URL\\n{\\n  \\\"redirectURL\\\": \\\"https://client.com/redirect/here\\\",\\n  \\\"webhookURL\\\": \\\"https://client.com/send/callback/here\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Configuração das URLS\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Atributo\",\n    \"h-1\": \"Descrição\",\n    \"h-2\": \"Obrigatório\",\n    \"h-3\": \"Tipo\",\n    \"0-0\": \"**redirectURL**\",\n    \"1-0\": \"**webhookURL**\",\n    \"0-1\": \"Url para onde o cliente final vai ser direcionado após a transação\",\n    \"1-1\": \"Url para onde a notificação vai ser enviada\",\n    \"0-2\": \"Sim\",\n    \"1-2\": \"Sim\",\n    \"0-3\": \"string\",\n    \"1-3\": \"string\"\n  },\n  \"cols\": 4,\n  \"rows\": 2\n}\n[/block]\n#### Respostas\n\nAs respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"redirectURL\\\": \\\"https://client.com/redirect/here\\\",\\n  \\\"webhookURL\\\": \\\"https://client.com/send/callback/here\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"201(Success)\"\n    },\n    {\n      \"code\": \"{\\n  \\\"nome\\\": \\\"redirect_url_obrigatorio\\\",\\n  \\\"mensagem\\\": \\\"O redirectURL é obrigatório\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"400(Bad request)\"\n    },\n    {\n      \"code\": \"{\\n  \\\"nome\\\": \\\"conta_nao_encontrada\\\",\\n  \\\"mensagem\\\": \\\"A conta não foi encontrada\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"422(Unprocessable)\"\n    },\n    {\n      \"code\": \"{\\n  \\\"nome\\\": \\\"erro_aplicacao\\\",\\n  \\\"mensagem\\\": \\\"Erro interno do servidor\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"500(Error)\"\n    }\n  ]\n}\n[/block]\n### Retornar as configurações da aplicação \n[block:html]\n{\n  \"html\": \"<div class=\\\"gn-endpoint\\\">\\n    <span class=\\\"http-method post\\\">GET</span>\\n    <span class=\\\"endpoint\\\">/open-finance/config</span>\\n</div>\"\n}\n[/block]\nEsse endpoint é utilizado para retornar as configurações da aplicação relacionada a API Open Finance, não é necessário informar nenhum parâmetro.\n \n#### Respostas\n\nAs respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"redirectURL\\\": \\\"https://client.com/redirect/here\\\",\\n  \\\"webhookURL\\\": \\\"https://client.com/send/callback/here\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"200(Success)\"\n    },\n    {\n      \"code\": \"{\\n  \\\"nome\\\": \\\"configuracao_nao_encontrada\\\",\\n  \\\"mensagem\\\": \\\"Nenhuma configuração encontrada\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"400(Bad request)\"\n    },\n    {\n      \"code\": \"{\\n  \\\"nome\\\": \\\"configuracao_nao_encontrada\\\",\\n  \\\"mensagem\\\": \\\"Nenhuma configuração encontrada\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"500(Error)\"\n    }\n  ]\n}\n[/block]\n## Recebendo Callbacks\n\nEsse serviço está protegido por uma camada de autenticação mTLS. \n\n### Requisição\n\nUma requisição POST é enviada pela Gerencianet para a URL que você cadastrou como webhook para uma determinada chave. Quando houver alteração no status de uma transação Open Finance, envolvendo a chave associada, um objeto JSON (como os exemplos abaixo) será enviado ao seu servidor. Cada requisição enviada possui um timeout de 60 segundos, isto é, uma requisição de callback é interrompida ao atingir 60 segundos sem resposta.\n\nAs respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Exemplo - 200 (Notificação enviada com sucesso)\\n{\\n  \\\"identificadorPagamento\\\": \\\"ae71713f-875b-4af3-9d85-0bcb43288847\\\",\\n  \\\"statusPagamento\\\": \\\"pendente\\\",\\n  \\\"valorPagamento\\\": \\\"9.90\\\",\\n  \\\"dataCriacao\\\": \\\"2022-04-29T11:55:03.000Z\\\",\\n  \\\"endToEndId\\\": \\\"E090993562002060954525a47762581f\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Exemplo - Dados de Callback \"\n    }\n  ]\n}\n[/block]\nA tabela a seguir detalha os campos presentes no objeto JSON que será enviado na notificação.\n\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Atributo\",\n    \"h-1\": \"Descrição\",\n    \"h-2\": \"Obrigatório\",\n    \"0-0\": \"<b>identificadorPagamento</b>\",\n    \"1-0\": \"<b>statusPagamento</b>\",\n    \"2-0\": \"<b>valorPagamento</b>\",\n    \"0-1\": \"Identificador do pagamento iniciado na API Open Finance.\\n\\nexemplo: ae71713f-875b-4af3-9d85-0bcb43288847\",\n    \"0-2\": \"Sim\",\n    \"1-2\": \"Sim\",\n    \"2-2\": \"Sim\",\n    \"1-1\": \"Status do pagamento iniciado.\\n\\nexemplo: <code>pendente</code>, <code>agendado</code>, <code>rejeitado</code> e <code>aceito</code>.\",\n    \"2-1\": \"Valor da transação recebida.\\n\\nexemplo: 9.90\",\n    \"h-3\": \"Tipo\",\n    \"0-3\": \"String\",\n    \"1-3\": \"String\",\n    \"2-3\": \"String <code>\\\\d{1,10}\\\\.\\\\d{2}</code>\",\n    \"3-0\": \"<b>dataCriacao</b>\",\n    \"3-1\": \"Data  de criação da transação.\",\n    \"3-2\": \"Sim\",\n    \"3-3\": \"string (Horário) <code><date-time></code>\",\n    \"4-0\": \"<b>endToEndId</b>\",\n    \"4-3\": \"String (32 characters) <code>^[a-zA-Z0-9]{32}$</code>\",\n    \"4-2\": \"Não\",\n    \"4-1\": \"EndToEndIdentification que transita na PACS002, PACS004 e PACS008\"\n  },\n  \"cols\": 4,\n  \"rows\": 5\n}\n[/block]\n#### Resposta\n\nAs requisições de callback aguardam uma resposta com status HTTP 2XX. Caso o servidor do cliente retorne um status diferente, a Gerencianet fará até 10 novas tentativas de notificação. A primeira nova tentativa será feita 5 minutos após a falha do envio do callback. Persistindo o erro, as tentativas subsequentes serão enviadas em intervalos de tempo cada vez maiores, conforme mostra a tabela abaixo.\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Importante\",\n  \"body\": \"Em casos onde o servidor do cliente retorna o status HTTP 429 (*too many requests*), os servidores da Gerencianet tentarão enviar a notificação até 10 vezes também de acordo com a tabela abaixo.\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Nº da tentativa\",\n    \"h-1\": \"Tempo (em minutos)\",\n    \"0-0\": \"1\",\n    \"1-0\": \"2\",\n    \"2-0\": \"3\",\n    \"3-0\": \"4\",\n    \"4-0\": \"5\",\n    \"5-0\": \"6\",\n    \"6-0\": \"7\",\n    \"7-0\": \"8\",\n    \"8-0\": \"9\",\n    \"9-0\": \"10\",\n    \"0-1\": \"5\",\n    \"1-1\": \"10\",\n    \"2-1\": \"20\",\n    \"3-1\": \"40\",\n    \"4-1\": \"80\",\n    \"5-1\": \"160\",\n    \"6-1\": \"320\",\n    \"7-1\": \"640\",\n    \"8-1\": \"1280\",\n    \"9-1\": \"2560\"\n  },\n  \"cols\": 2,\n  \"rows\": 10\n}\n[/block]","updates":[],"order":1,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"6284fd3825c4450058627665","createdAt":"2022-05-18T14:05:44.232Z","user":"5e8b36bc27ee9b00181b36bf","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"API Open Finance","slug":"api-open-banking","order":3,"from_sync":false,"reference":false,"_id":"6283a3819575c60045513ea2","createdAt":"2022-05-17T13:30:41.706Z","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}

Endpoints

Informações de todos os endpoints disponíveis na API Open Finance

Nesta página você encontra todos os endpoints disponíveis na API Open Finance da Gerencianet e informações de como utilizá-los corretamente, como por exemplo os escopos necessários para o consumo de cada rota e os detalhes de retorno dos mesmos. Utilize o sumário abaixo para navegar rapidamente entre os grupos de endpoints da API. **Sumário** 1. [Participantes](#section-participantes) 1.1 [Recuperar as instituições participantes do Open Finance](#section-recuperar-as-institui-es-participantes-do-open-finance) 2. [Pagamentos](#section-pagamentos) 2.1 [Solicitar iniciação de Pix via Open Finance](#section-solicitar-inicia-o-de-pix-via-open-finance) 2.2 [Listar pagamentos por um determinado período](#section-listar-pagamentos-por-um-determinado-per-odo) 3. [Config](#section-config) 3.1 [Configurar URLs da aplicação](#section-configurar-urls-da-aplica-o) 3.2 [Retornar as configurações da aplicação](#section-retornar-as-configura-es-da-aplica-o) 4. [Recebendo Callbacks](#section-recebendo-callbacks) ## Tutorial API Open Finance da Gerencianet ## Rota base Rotas base ou URL's base para ambientes, utilize as rotas abaixo para realizar a comunicação da sua aplicação com o ambiente de produção ou homologação oferecidos pela Gerencianet. [block:parameters] { "data": { "0-0": "**Produção**", "0-1": "`https://apis.gerencianet.com.br`", "1-0": "**Homologação**", "1-1": "`https://apis-h.gerencianet.com.br`" }, "cols": 2, "rows": 2 } [/block] <br> ## Obter Autorização [block:html] { "html": "<div class=\"gn-endpoint\">\n <span class=\"http-method post\">POST</span>\n \t<span class=\"endpoint\">\n /oauth/token\n </span>\n</div>" } [/block] Este endpoint é utilizado para autorizar as credenciais de uma aplicação e obter os escopos que a aplicação possui para acessar os outros endpoints da API. É necessário que o certificado P12/PEM esteja presente na requisição de autorização a fim de que o *handshake* com o servidor da API seja permitido. [block:callout] { "type": "warning", "body": "Para habilitar os escopos da API Open Finance, basta [abrir um ticket](https://gerencianet.com.br/fale-conosco/) informando o número da conta e o Client_Id da aplicação desejada.\nÉ possível também, solicitar a liberação através de nossa [comunidade no Discord](https://discord.gg/ptGHMtczcV).", "title": "Atenção" } [/block] ### Exemplos de autorização utilizando o certificado .P12 Para a utilização da API Open Finance da Gerencianet é necessário que o cliente e o servidor se comuniquem em uma conexão verificada um com o outro. A verificação é feita pelo certificado bidirecional (.PEM ou .P12), isto é, o servidor e o cliente implementaram um certificado de chave privada e um certificado de chave pública que permite que um possa assegurar-se da identidade do outro. Por isso para fazer qualquer requisição HTTP à API Open Finance da Gerencianet, incluindo a requisição de autorização junto ao OAuth2, é necessário que o certificado .P12, ou .PEM, esteja presente nos cabeçalhos da requisição. Abaixo, trazemos exemplos de como consumir a autorização da API Open Finance da Gerencianet, incorporando esse certificado na requisição. [block:code] { "codes": [ { "code": "<?php //Desenvolvido pela Consultoria Técnica da Gerencianet\n\n$config = [\n \"certificado\" => \"./certificado.pem\",\n \"client_id\" => \"YOUR-CLIENT-ID\",\n \"client_secret\" => \"YOUR-CLIENT-SECRET\"\n];\n$autorizacao = base64_encode($config[\"client_id\"] . \":\" . $config[\"client_secret\"]);\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, array(\n CURLOPT_URL => \"https://apis.gerencianet.com.br/open-finance/oauth/token\", // Rota base, homologação ou produção\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 0,\n CURLOPT_FOLLOWLOCATION => true,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"POST\",\n CURLOPT_POSTFIELDS => '{\"grant_type\": \"client_credentials\"}',\n CURLOPT_SSLCERT => $config[\"certificado\"], // Caminho do certificado\n CURLOPT_SSLCERTPASSWD => \"\",\n CURLOPT_HTTPHEADER => array(\n \"Authorization: Basic $autorizacao\",\n \"Content-Type: application/json\"\n ),\n));\n\n$response = curl_exec($curl);\n\ncurl_close($curl);\n\necho \"<pre>\";\necho $response;\necho \"</pre>\";", "language": "php" }, { "code": "//Desenvolvido pela Consultoria Técnica da Gerencianet\n\n\"use strict\";\nconst https = require(\"https\");\nvar axios = require(\"axios\");\nvar fs = require(\"fs\");\n\n//Insira o caminho de seu certificado .p12 dentro de seu projeto\nvar certificado = fs.readFileSync(\"./certificado.p12\");\n\n//Insira os valores de suas credenciais em desenvolvimento do pix\nvar credenciais = {\n client_id: \"YOUR-CLIENT-ID\",\n client_secret: \"YOUR-CLIENT-SECRET\",\n};\n\nvar data = JSON.stringify({ grant_type: \"client_credentials\" });\nvar data_credentials = credenciais.client_id + \":\" + credenciais.client_secret;\n\n// Codificando as credenciais em base64\nvar auth = Buffer.from(data_credentials).toString(\"base64\");\n\nconst agent = new https.Agent({\n pfx: certificado,\n passphrase: \"\",\n});\n//Consumo em desenvolvimento da rota post oauth/token\nvar config = {\n method: \"POST\",\n url: \"https://apis.gerencianet.com.br/open-finance/oauth/token\",\n headers: {\n Authorization: \"Basic \" + auth,\n \"Content-Type\": \"application/json\",\n },\n httpsAgent: agent,\n data: data,\n};\n\naxios(config)\n .then(function (response) {\n console.log(JSON.stringify(response.data));\n })\n .catch(function (error) {\n console.log(error);\n });", "language": "javascript", "name": "Node" }, { "code": "#Desenvolvido pela Consultoria Técnica da Gerencianet\n\nimport requests\nimport base64\n\ncredentials = {\n \"client_id\": \"YOUR-CLIENT-ID\",\n \"client_secret\": \"YOUR-CLIENT-SECRET\",\n}\n\ncertificado = './certificado.pem' # A variável certificado é o diretório em que seu certificado em formato .pem deve ser inserido\n\nauth = base64.b64encode(\n (f\"{credentials['client_id']}:{credentials['client_secret']}\"\n ).encode()).decode()\n\nurl = \"https://apis.gerencianet.com.br/open-finance/oauth/token\" #Para ambiente de Desenvolvimento\n\npayload=\"{\\r\\n \\\"grant_type\\\": \\\"client_credentials\\\"\\r\\n}\"\nheaders = {\n 'Authorization': f\"Basic {auth}\",\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.request(\"POST\",\n url,\n headers=headers,\n data=payload,\n cert=certificado)\n\nprint(response.text)", "language": "python", "name": "Python" }, { "code": "//Desenvolvido pela Consultoria Técnica da Gerencianet\n\nusing System;\nusing System.Security.Cryptography.X509Certificates;\nusing System.Collections.Generic;\nusing RestSharp;\n\nnamespace PixGerencianet\n{\n class Authorize\n {\n public static string Base64Encode(string plainText)\n {\n var plainTextBytes = System.Text.Encoding.UTF8.GetBytes(plainText);\n return System.Convert.ToBase64String(plainTextBytes);\n }\n\n static void Main(string[] args)\n {\n\n var credencials = new Dictionary<string, string>{\n {\"client_id\", \"YOUR-CLIENT-ID\"},\n {\"client_secret\", \"YOUR-CLIENT-SECRET\"}\n };\n var authorization = Base64Encode(credencials[\"client_id\"] + \":\" + credencials[\"client_secret\"]);\n var client = new RestSharp.RestClient(\"https://apis.gerencianet.com.br/open-finance/oauth/token\");\n var request = new RestRequest(Method.POST);\n\n X509Certificate2 uidCert = new X509Certificate2(\"./certificado.p12\", \"\");\n client.ClientCertificates = new X509CertificateCollection() { uidCert };\n\n request.AddHeader(\"Authorization\", \"Basic \" + authorization);\n request.AddHeader(\"Content-Type\", \"application/json\");\n request.AddParameter(\"application/json\", \"{\\r\\n \\\"grant_type\\\": \\\"client_credentials\\\"\\r\\n}\", ParameterType.RequestBody);\n \n IRestResponse restResponse = client.Execute(request);\n string response = restResponse.Content;\n\n Console.WriteLine(response);\n }\n }\n}", "language": "csharp" }, { "code": "#Desenvolvido pela Consultoria Técnica da Gerencianet\n\nrequire \"uri\"\nrequire \"net/http\"\nrequire \"openssl\"\n\nclient_id = \"YOUR-CLIENT-ID\";\nclient_secret = \"YOUR-CLIENT-SECRET\";\n\ncertfile = File.read(\"certificado.pem\") # A variável certfile é o diretório em que seu certificado em formato .pem deve ser inserido\n\nurl = URI(\"https://apis.gerencianet.com.br/open-finance/oauth/token\") #Para ambiente de Desenvolvimento\n\nhttps = Net::HTTP.new(url.host, url.port);\nhttps.use_ssl = true\nhttps.cert = OpenSSL::X509::Certificate.new(certfile)\nhttps.key = OpenSSL::PKey::RSA.new(certfile)\n\nrequest = Net::HTTP::Post.new(url)\nrequest.basic_auth(client_id, client_secret)\nrequest[\"Content-Type\"] = \"application/json\"\nrequest.body = \"{\\r\\n \\\"grant_type\\\": \\\"client_credentials\\\"\\r\\n}\"\n\nresponse = https.request(request)\nputs response.read_body", "language": "ruby" }, { "code": "//Desenvolvido pela Consultoria Técnica da Gerencianet\n\nimport java.io.BufferedReader;\nimport java.io.InputStreamReader;\nimport java.io.OutputStream;\nimport java.net.URL;\nimport java.util.Base64;\n\nimport javax.net.ssl.HttpsURLConnection;\nimport javax.net.ssl.SSLSocketFactory;\n\npublic class Auth {\n public static void main(String[] args) throws Exception {\n String client_id = \"YOUR-CLIENT-ID\";\n String client_secret = \"YOUR-CLIENT-SECRET\";;\n String basicAuth = Base64.getEncoder().encodeToString(((client_id+':'+client_secret).getBytes()));\n \n \t//Diretório em que seu certificado em formato .p12 deve ser inserido\n System.setProperty(\"javax.net.ssl.keyStore\", \"certificado.p12\"); \n SSLSocketFactory sslsocketfactory = (SSLSocketFactory) SSLSocketFactory.getDefault();\n \n URL url = new URL (\"https://apis.gerencianet.com.br/open-finance/oauth/token\"); //Para ambiente de Desenvolvimento \n HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();\n conn.setDoOutput(true);\n conn.setRequestMethod(\"POST\");\n conn.setRequestProperty(\"Content-Type\", \"application/json\");\n conn.setRequestProperty(\"Authorization\", \"Basic \"+ basicAuth);\n conn.setSSLSocketFactory(sslsocketfactory);\n String input = \"{\\\"grant_type\\\": \\\"client_credentials\\\"}\";\n \n OutputStream os = conn.getOutputStream();\n os.write(input.getBytes());\n os.flush();\t\t\n\n InputStreamReader reader = new InputStreamReader(conn.getInputStream());\n BufferedReader br = new BufferedReader(reader);\n\n String response;\n while ((response = br.readLine()) != null) {\n System.out.println(response);\n }\n conn.disconnect();\n\n }\n}", "language": "java" }, { "code": "//Desenvolvido pela Consultoria Técnica da Gerencianet\npackage main\n\nimport (\n \"fmt\"\n \"strings\"\n \"net/http\"\n \"io/ioutil\"\n \"crypto/tls\"\n)\n\nconst(\n client_id = \"YOUR-CLIENT-ID\"\n client_secret = \"YOUR-CLIENT-SECRET\"\n)\n\nfunc main() {\n\n url := \"https://apis.gerencianet.com.br/open-finance/oauth/token\"// Rota base, homologação ou produção\n method := \"POST\"\n\n payload := strings.NewReader(`{\"grant_type\": \"client_credentials\"}`)\n\n\n cert, _ := tls.LoadX509KeyPair(\"CA.crt.pem\", \"KEY.crt.pem\")// Seu certificado e chave privada gerada a partir dos comandos de conversão OpenSSL\n\n client := &http.Client{\n Transport: &http.Transport{\n TLSClientConfig: &tls.Config{\n Certificates: []tls.Certificate{cert},\n },\n },\n}\n\n req, err := http.NewRequest(method, url, payload)\n\n if err != nil {\n fmt.Println(err)\n return\n }\n req.SetBasicAuth(client_id, client_secret)\n req.Header.Add(\"Content-Type\", \"application/json\")\n\n res, err := client.Do(req)\n if err != nil {\n fmt.Println(err)\n return\n }\n defer res.Body.Close()\n\n body, err := ioutil.ReadAll(res.Body)\n if err != nil {\n fmt.Println(err)\n return\n }\n fmt.Println(string(body))\n}", "language": "go" } ] } [/block] #### Exemplo de resposta da autorização O trecho de código abaixo representa um exemplo de resposta do OAuth à sua requisição de autorização. [block:code] { "codes": [ { "code": "{\n \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600,\n \"scope\": \"gn.opb.paticipants.read gn.opb.pix.send gn.opb.config.write gn.opb.config.read\"\n}", "language": "json", "name": "Resposta" } ] } [/block] <br> ## Participantes ### Recuperar as instituições participantes do Open Finance [block:html] { "html": "<div class=\"gn-endpoint\">\n <span class=\"http-method get\">GET</span>\n <span class=\"endpoint\">/open-finance/participantes/<span class=\"variable\">:nome</span></span>\n</div>" } [/block] Esse endpoint retorna um ou mais participantes que estão ativos no Open Finance. **Requer autorização para o escopo:** **`gn.opb.paticipants.read`** #### Requisição [block:parameters] { "data": { "h-0": "Atributo", "h-1": "Descrição", "h-2": "Obrigatório", "h-3": "Tipo", "0-0": "Nome", "0-1": "Nome do psp que será pesquisado", "0-2": "Não", "0-3": "String" }, "cols": 4, "rows": 1 } [/block] [block:callout] { "type": "info", "title": "", "body": "Caso não seja enviado o atributo nome, serão retornados todos os participantes ativos no Open Finance." } [/block] #### Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo. [block:code] { "codes": [ { "code": "Lista com um ou mais participantes do Open Finance\n{\n \"participantes\": [\n {\n \"identificador\": \"9f4cd202-8f2b-11ec-b909-0242ac120002\",\n \"nome\": \"MARCA GERENCIANET\",\n \"descricao\": \"Descrição da marca\",\n \"portal\": \"https://openbankingbrasil.org.br/quem-participa/\",\n \"logo\": \"https://www.gerencianet.com.br/logo.png\",\n \"organizacoes\": [\n {\n \"nome\": \"Gerencianet\",\n \"cnpj\": \"09089356000118,\",\n \"status\": \"Ativo\"\n }\n ]\n }\n ]\n}", "language": "json", "name": "200(Success)" }, { "code": "Nome inválido\n{\n \"nome\": \"participante_nao_encontrado\",\n \"mensagem\": \"Nenhum participante encontrado\"\n}", "language": "json", "name": "404(Not Found)" }, { "code": "Este erro ocorre nas seguintes situações:\n\n* Certificado ou credenciais não existem;\n* Certificado ou credenciais estão desativados;\n* Certificado e credenciais não estão vinculados a mesma conta Gerencianet;\n* Integrador não tem permissão para o escopo de serviço necessário para consumir este endpoint.", "language": "json", "name": "401(Unauthorized)" }, { "code": "Este erro ocorre nas seguintes situações:\n\n* Integrador solicita acesso a um escopo ao qual não tem permissão.", "language": "json", "name": "403(Forbidden)" }, { "code": "Precondition Failed. Este erro ocorre nas seguintes situações:\n\n* Integrador deve ter pelo menos um Webhook cadastrado.\n{\n \"nome\": \"webhook_nao_cadastrado\",\n \"mensagem\": \"Sua conta não possui webhook cadastrado na API de Cadastro.\"\n}", "language": "json", "name": "412(Precondition Failed)" }, { "code": "Erro na aplicação\n{\n \"nome\": \"erro_aplicacao\",\n \"mensagem\": \"Erro interno do servidor\"\n}", "language": "json", "name": "500(Error)" } ] } [/block] ## Pagamentos ### Solicitar iniciação de Pix via Open Finance [block:html] { "html": "<div class=\"gn-endpoint\">\n <span class=\"http-method post\">POST</span>\n <span class=\"endpoint\">/open-finance/pagamentos/pix</span>\n</div>" } [/block] Este endpoint é utilizado para a inserção das informações do pagamento a ser iniciado e a saída é uma url de redirecionamento, que deve ser inserida em um botão para que o usuário clique e seja redirecionado para a instituição detentora de conta. #### Requisição [block:parameters] { "data": { "h-0": "Atributo", "h-1": "Descrição", "h-2": "Obrigatório", "0-0": "**x-idempotency-key**", "0-1": "Chave única para evitar duplicidade em requisições em um curto espaço de tempo. Caso ocorra o envio de várias requisições com a mesma informação no mesmo instante, uma delas será processada com sucesso. Se outra requisição for enviada com a mesma chave, será retornado o erro 409.\n(Este atributo deve ser enviado no Header)", "0-2": "Sim", "h-3": "Tipo", "0-3": "String \n`minLength: 36`\n`maxLength: 72`" }, "cols": 4, "rows": 1 } [/block] . [block:code] { "codes": [ { "code": "Exemplo de iniciação de pagamento\n{\n \"pagador\": {\n \"idParticipante\": \"9f4cd202-8f2b-11ec-b909-0242ac120002\",\n \"cpf\": \"45204392050\", // cpf ou cnpj\n \"cnpj\": \"90293071000112\"\n },\n \"favorecido\": {\n \"contaBanco\": {\n \"codigoBanco\": \"364\",\n \"agencia\": \"0001\",\n \"documento\": \"11122233344\",\n \"nome\": \"Luiz Silva\",\n \"conta\": \"654984\",\n \"tipoConta\": \"CACC\"\n }\n },\n \"valor\": \"9.90\",\n \"codigoCidadeIBGE\": \"3540000\",\n \"infoPagador\": \"Compra dia xx\"\n}", "language": "json", "name": "Iniciação de pagamento" } ] } [/block] Dados que podem ser utilizados na requisição de iniciação de pagamento: [block:parameters] { "data": { "h-0": "Atributo", "h-1": "Descrição", "h-2": "Obrigatório", "h-3": "Tipo", "0-0": "**Pagador**", "0-1": "Os campos aninhados sob o identificador pagador organizam informações a respeito de dados do cliente final ao qual vai se gerar a cobrança.\n\npagador:\n<div class=\"tab2\">`idParticipante*`// Identificador do participante no diretório do Banco Central. (String)\n\n`cpf*`// CPF do cliente final pessoa física. (String)\n\n`cnpj*`// CNPJ do cliente final pessoa jurídica. (String)\n</div>", "1-0": "**Favorecido**", "1-1": "Os campos aninhados sob o identificador favorecido organizam informações a respeito dos dados da conta final que irá receber.\n\nfavorecido:\n<div class=\"tab2\">`contaBanco*`:\n<div class=\"tab2\">\n`codigoBanco*`// Código do banco (String)\n\n`agencia*`\n (String)\n\n`documento*`// Documento do dono da conta (String)\n`nome*`// Nome do titular (String)\n\n`conta*`// Número da conta com dígito (String)\n\n`tipoConta*`:\n * CACC: Conta Corrente, usada para lançar débitos e créditos em geral.\n * SLRY: Conta Salário, utilizadas para pagamentos de salários.\n * SVGS: Conta Poupança, usada para poupança.\n * TRAN: Conta de Transações, usada como tipo básico de conta.\n (Enum)\n//[ CACC, SLRY, SVGS, TRAN ]\n\n</div>\n</div>", "1-2": "Sim", "2-0": "**Valor**", "2-1": "Valor do pagamento", "0-2": "Sim", "2-2": "Sim", "0-3": "Object", "1-3": "Object", "2-3": "String", "3-0": "**codigoCidadeIBGE**", "3-1": "Código da cidade segundo o IBGE", "3-2": "Não", "3-3": "String", "4-0": "**infoPagador**", "4-1": "Informações pertinentes ao pagador final\n200(Success)", "4-2": "Não", "4-3": "String" }, "cols": 4, "rows": 5 } [/block] #### Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo. [block:code] { "codes": [ { "code": "\n{\n \"identificadorPagamento\": \"ae71713f-875b-4af3-9d85-0bcb43288847\",\n \"redirectURL\": \"https://open-banking.banco.com.br/authorize?request=eyJjd&redirect_uri=https://pub.opb.testegerencianet.com.br/callback&scope=openid%20pagamentos%20consent:urn:gerencianet:fdf36ac8-f213-4057-bf2e-2ce7bd828abf&response_type=code%20id_token\"\n}", "language": "json", "name": "200(Success)" }, { "code": "\n{\n \"nome\": \"codigo_banco_favorecido_obrigatorio\",\n \"mensagem\": \"O código do banco favorecido é obrigatório\"\n}", "language": "json", "name": "400(Bad Request)" }, { "code": "\nEste erro ocorre nas seguintes situações:\n\n* Certificado ou credenciais não existem;\n* Certificado ou credenciais estão desativados;\n* Certificado e credenciais não estão vinculados a mesma conta Gerencianet;\n* Integrador não tem permissão para o escopo de serviço necessário para consumir este endpoint.", "language": "json", "name": "401(Unauthorized)" }, { "code": "\nEste erro ocorre nas seguintes situações:\n\n* Integrador solicita acesso a um escopo ao qual não tem permissão.", "language": "json", "name": "403(Forbbiden)" }, { "code": "\n{\n \"nome\": \"conflito_chave_idempotencia\",\n \"mensagem\": \"Chave de idempotência repetida para pagamento diferente\"\n}", "language": "json", "name": "409(Conflict)" }, { "code": "\n{\n \"nome\": \"codigo_banco_nao_permitido\",\n \"mensagem\": \"O código do banco informado não é permitido\"\n}", "language": "json", "name": "422(Unprocessable)" }, { "code": "\n{\n \"nome\": \"chave_idempotencia_invalida\",\n \"mensagem\": \"Tamanho da chave de idempotência inválido\"\n}", "language": "json", "name": "431(Fields Too Large)" }, { "code": "\n{\n \"nome\": \"erro_aplicacao\",\n \"mensagem\": \"Ocorreu um erro ao criar o pagamento\"\n}", "language": "json", "name": "500(Error)" } ] } [/block] ### Listar pagamentos por um determinado período [block:html] { "html": "<div class=\"gn-endpoint\">\n <span class=\"http-method get\">GET</span>\n <span class=\"endpoint\">/open-finance/pagamentos/pix</span>\n</div>" } [/block] Este endpoint é utilizado para listar as informações dos pagamentos que foram efetuados em um período de tempo. Este endpoint possui os filtros obrigatórios de inicio e fim que representam o intervalo de datas em que as cobranças consultadas devem estar compreendidas. #### Requisição Dados que podem ser utilizados na requisição de listagem das informações: [block:parameters] { "data": { "h-0": "Atributo", "h-1": "Descrição", "h-2": "Obrigatório", "0-0": "**inicio**", "1-0": "**fim**", "2-0": "**quantidade**", "3-0": "**página**", "0-1": "Data início da criação do pagamento \n\nExemplo : 2022-04-29", "0-2": "Sim", "1-2": "Sim", "2-2": "Não", "3-2": "Não", "1-1": "Data início da criação do pagamento \n\nExemplo : 2022-04-29", "2-1": "Quantidade de retornos por página \n\nExemplo : 5", "3-1": "número da página que deseja consultar de acordo com a quantidade \n\nExemplo : 2", "h-3": "Tipo", "0-3": "String", "1-3": "String", "2-3": "String", "3-3": "String", "4-0": "**status**", "4-1": "Status do pagamento", "4-2": "Não", "4-3": "String", "5-0": "**identificador**", "5-1": "Identificador do pagamento (Se este campo é informado os demais são desconsiderados na busca)", "5-2": "Não", "5-3": "String" }, "cols": 4, "rows": 6 } [/block] #### Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo. [block:code] { "codes": [ { "code": "{\n \"pagamentos\": [\n {\n \"identificadorPagamento\": \"urn:gerencianet:49315a93-d39c-4564-9edb-9a73678dbdb1\",\n \"valor\": \"1.99\",\n \"status\": \"pendente\",\n \"dataCriacao\": \"2022-04-29T11:55:03.000Z\"\n }\n ],\n \"total\": 3,\n \"porPagina\": 1,\n \"ultimo\": \"/pagamentos/pix?inicio=2022-04-29&fim=2022-04-29&quantidade=1&pagina=3\",\n \"proximo\": \"/pagamentos/pix?inicio=2022-04-29&fim=2022-04-29&quantidade=1&pagina=2\",\n \"anterior\": null,\n \"atual\": \"/pagamentos/pix?inicio=2022-04-29&fim=2022-04-29&quantidade=1&pagina=1\"\n}", "language": "json", "name": "200(Sucess)" }, { "code": "{\n \"nome\": \"data_inicio_invalido\",\n \"mensagem\": \"A data início é inválido\"\n}", "language": "json", "name": "400(Bad Request)" }, { "code": "{\n \"nome\": \"pagamento_nao_encontrado\",\n \"mensagem\": \"Nenhum pagamento encontrado\"\n}", "language": "json", "name": "404(Unkown Payment Error)" }, { "code": "{\n \"nome\": \"data_inicio_obrigatorio\",\n \"mensagem\": \"A data início é obrigatório\"\n}", "language": "json", "name": "422(Unprocessable)" }, { "code": "{\n \"nome\": \"data_inicio_obrigatorio\",\n \"mensagem\": \"A data início é obrigatório\"\n}", "language": "json", "name": "500(Server Error)" } ] } [/block] ## Configurações da aplicação ### Configurar URLs da aplicação [block:html] { "html": "<div class=\"gn-endpoint\">\n <span class=\"http-method post\">PUT</span>\n <span class=\"endpoint\">/open-finance/config</span>\n</div>" } [/block] Esse endpoint é utilizado para criar ou modificar uma configuração na aplicação relacionada a API Open Finance. #### Requisição Dados para a configuração. [block:code] { "codes": [ { "code": "// Exemplo configurando uma URL\n{\n \"redirectURL\": \"https://client.com/redirect/here\",\n \"webhookURL\": \"https://client.com/send/callback/here\"\n}", "language": "json", "name": "Configuração das URLS" } ] } [/block] [block:parameters] { "data": { "h-0": "Atributo", "h-1": "Descrição", "h-2": "Obrigatório", "h-3": "Tipo", "0-0": "**redirectURL**", "1-0": "**webhookURL**", "0-1": "Url para onde o cliente final vai ser direcionado após a transação", "1-1": "Url para onde a notificação vai ser enviada", "0-2": "Sim", "1-2": "Sim", "0-3": "string", "1-3": "string" }, "cols": 4, "rows": 2 } [/block] #### Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo. [block:code] { "codes": [ { "code": "{\n \"redirectURL\": \"https://client.com/redirect/here\",\n \"webhookURL\": \"https://client.com/send/callback/here\"\n}", "language": "json", "name": "201(Success)" }, { "code": "{\n \"nome\": \"redirect_url_obrigatorio\",\n \"mensagem\": \"O redirectURL é obrigatório\"\n}", "language": "json", "name": "400(Bad request)" }, { "code": "{\n \"nome\": \"conta_nao_encontrada\",\n \"mensagem\": \"A conta não foi encontrada\"\n}", "language": "json", "name": "422(Unprocessable)" }, { "code": "{\n \"nome\": \"erro_aplicacao\",\n \"mensagem\": \"Erro interno do servidor\"\n}", "language": "json", "name": "500(Error)" } ] } [/block] ### Retornar as configurações da aplicação [block:html] { "html": "<div class=\"gn-endpoint\">\n <span class=\"http-method post\">GET</span>\n <span class=\"endpoint\">/open-finance/config</span>\n</div>" } [/block] Esse endpoint é utilizado para retornar as configurações da aplicação relacionada a API Open Finance, não é necessário informar nenhum parâmetro. #### Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo. [block:code] { "codes": [ { "code": "{\n \"redirectURL\": \"https://client.com/redirect/here\",\n \"webhookURL\": \"https://client.com/send/callback/here\"\n}", "language": "json", "name": "200(Success)" }, { "code": "{\n \"nome\": \"configuracao_nao_encontrada\",\n \"mensagem\": \"Nenhuma configuração encontrada\"\n}", "language": "json", "name": "400(Bad request)" }, { "code": "{\n \"nome\": \"configuracao_nao_encontrada\",\n \"mensagem\": \"Nenhuma configuração encontrada\"\n}", "language": "json", "name": "500(Error)" } ] } [/block] ## Recebendo Callbacks Esse serviço está protegido por uma camada de autenticação mTLS. ### Requisição Uma requisição POST é enviada pela Gerencianet para a URL que você cadastrou como webhook para uma determinada chave. Quando houver alteração no status de uma transação Open Finance, envolvendo a chave associada, um objeto JSON (como os exemplos abaixo) será enviado ao seu servidor. Cada requisição enviada possui um timeout de 60 segundos, isto é, uma requisição de callback é interrompida ao atingir 60 segundos sem resposta. As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo. [block:code] { "codes": [ { "code": "// Exemplo - 200 (Notificação enviada com sucesso)\n{\n \"identificadorPagamento\": \"ae71713f-875b-4af3-9d85-0bcb43288847\",\n \"statusPagamento\": \"pendente\",\n \"valorPagamento\": \"9.90\",\n \"dataCriacao\": \"2022-04-29T11:55:03.000Z\",\n \"endToEndId\": \"E090993562002060954525a47762581f\"\n}", "language": "json", "name": "Exemplo - Dados de Callback " } ] } [/block] A tabela a seguir detalha os campos presentes no objeto JSON que será enviado na notificação. [block:parameters] { "data": { "h-0": "Atributo", "h-1": "Descrição", "h-2": "Obrigatório", "0-0": "<b>identificadorPagamento</b>", "1-0": "<b>statusPagamento</b>", "2-0": "<b>valorPagamento</b>", "0-1": "Identificador do pagamento iniciado na API Open Finance.\n\nexemplo: ae71713f-875b-4af3-9d85-0bcb43288847", "0-2": "Sim", "1-2": "Sim", "2-2": "Sim", "1-1": "Status do pagamento iniciado.\n\nexemplo: <code>pendente</code>, <code>agendado</code>, <code>rejeitado</code> e <code>aceito</code>.", "2-1": "Valor da transação recebida.\n\nexemplo: 9.90", "h-3": "Tipo", "0-3": "String", "1-3": "String", "2-3": "String <code>\\d{1,10}\\.\\d{2}</code>", "3-0": "<b>dataCriacao</b>", "3-1": "Data de criação da transação.", "3-2": "Sim", "3-3": "string (Horário) <code><date-time></code>", "4-0": "<b>endToEndId</b>", "4-3": "String (32 characters) <code>^[a-zA-Z0-9]{32}$</code>", "4-2": "Não", "4-1": "EndToEndIdentification que transita na PACS002, PACS004 e PACS008" }, "cols": 4, "rows": 5 } [/block] #### Resposta As requisições de callback aguardam uma resposta com status HTTP 2XX. Caso o servidor do cliente retorne um status diferente, a Gerencianet fará até 10 novas tentativas de notificação. A primeira nova tentativa será feita 5 minutos após a falha do envio do callback. Persistindo o erro, as tentativas subsequentes serão enviadas em intervalos de tempo cada vez maiores, conforme mostra a tabela abaixo. [block:callout] { "type": "info", "title": "Importante", "body": "Em casos onde o servidor do cliente retorna o status HTTP 429 (*too many requests*), os servidores da Gerencianet tentarão enviar a notificação até 10 vezes também de acordo com a tabela abaixo." } [/block] [block:parameters] { "data": { "h-0": "Nº da tentativa", "h-1": "Tempo (em minutos)", "0-0": "1", "1-0": "2", "2-0": "3", "3-0": "4", "4-0": "5", "5-0": "6", "6-0": "7", "7-0": "8", "8-0": "9", "9-0": "10", "0-1": "5", "1-1": "10", "2-1": "20", "3-1": "40", "4-1": "80", "5-1": "160", "6-1": "320", "7-1": "640", "8-1": "1280", "9-1": "2560" }, "cols": 2, "rows": 10 } [/block]