Pular para o conteúdo principal

Credenciais, Certificado e Autorização

Nesta página você encontra informações sobre credenciais, certificado e autorização da API Abertura de Contas Efí.


Com a API Abertura de Contas, você pode iniciar o processo de abertura de contas para seus clientes de forma prática e obter as credenciais e certificados necessários para usar a aplicação do cliente.

Aviso sobre a API em Versão Beta

Atualmente, nossa API está em versão beta. Estamos entusiasmados em compartilhar essa ferramenta com você, porém, é essencial lembrar que ela está em desenvolvimento ativo e pode passar por alterações durante este período.

Valorizamos profundamente seu feedback durante esta fase beta. Queremos ouvir suas experiências e sugestões para aprimorar continuamente a API. Sinta-se à vontade para entrar em contato conosco por meio de nossos canais de suporte ou fórum da comunidade no Discord.


Para integrar a API Abertura de Contas Efí ao seu sistema ou sua plataforma, é necessário ter uma Conta Digital Efí Empresas. Após obter o acesso à conta, você poderá adquirir as credenciais necessárias para estabelecer a comunicação com a API Abertura de Contas Efí.

Veja a seguir como obter as credenciais, certificados e detalhes sobre a autorização e segurança da sua integração com a Efí.

Segurança no gerenciamento de credenciais

Dentro dos sitemas integrados à nossa API, é importante que as operações de login e a alteração das chaves de integração sejam realizadas com segurança. Sugerimos a implementação de autenticação de dois fatores e outras práticas de segurança.


Obtendo as credenciais da aplicação

Uma pessoa integradora pode criar quantas aplicações desejar. Para cada aplicação, são gerados 2 pares de chaves Client_Id e Client_Secret, sendo um par para utilização em ambiente de Produção (?) e outro para Homologação (?). Além disso, é necessário ativar os escopos necessários para poder utilizar a API Abertura de Contas Efí.

Entendendo os escopos de aplicação

Ao criar ou editar uma aplicação em sua Conta Efí, você precisará configurar quais 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 Abertura de Contas estão listados abaixo com suas respectivas descrições:

  • gn.registration.write - realizar uma solicitação de abertura de conta simplificada;
  • gn.registration.read - recuperar credenciais da conta simplificada;
  • gn.registration.webhook.write - alteração do webhook;
  • gn.registration.webhook.read - consulta do webhook;

Atenção!

Para usar a API Abertura de Contas da Efí, é necessário ter a liberação dos escopos mencionados nesta página. Para obter essa liberação, é preciso preencher o formulário disponível aqui.


Criar uma aplicação ou configurar uma já existente

Atenção!

Para utilizar a API Abertura de Contas da Efí, é necessário que exista uma aplicação ativa com escopos em produção e homologação da API Pix ou Open Finance.


Veja como criar uma aplicação ou aproveitar uma aplicação já existente para integrar com a API Abertura de Contas Efí.

Para criar uma aplicação e utilizar a API Abertura de Contas siga os passos abaixo:

  1. Acesse sua conta Efí e clique "API", no menu à esquerda;
  2. Clique em "Criar aplicação"
  3. Habilite a API Pix e escolha os escopos que deseja liberar em ambiente de Produção e Homologação (você poderá editá-los a qualquer momento);
  4. Com os escopos selecionados, clique em "Continuar".
banner

Ilustração dos passos para a criação de uma nova aplicação integrada à API Pix

Gerando e convertendo um certificado P12

Para gerar um certificado e convertê-lo, caso seja necessário, você pode acessar este link.


Rota base

Nesta documentação, você encontrará referências à Rota base ou URL base para o ambiente de Produção. Essa rota é a URL onde a API Abertura de Contas Efí está localizada. Quando mencionarmos os endpoints, essas partes de URL também fazem parte do caminho para acessar o recurso desejado.

Para comunicar sua aplicação com os ambientes de produção e homologação da Efí, utilize a seguinte rota:

AmbienteRota base
Produçãohttps://abrircontas.api.efipay.com.br
Homologaçãohttps://abrircontas-h.api.efipay.com.br

Autenticação com OAuth2

A API Abertura de Contas Efí utiliza o protocolo OAuth2 para autorizar as requisições feitas a ela. O objetivo do OAuth2 é obter um token de acesso chamado(access_token). Esse token é usado para autorizar todas as chamadas à API, verificando se uma determinada aplicação tem permissões para acessar o recurso solicitado.

A autenticação das requisições é feita usando o HTTP Basic Auth com base no Client_Id e Client_Secret da aplicação que você criou na sua conta da Efí.

Por meio dessa autenticação, o OAuth2 pode verificar quais autorizações a aplicação possui e, assim, decidir se autoriza ou nega as requisições de acordo com essas permissões.

Atenção!

O Certificado P12/PEM gerado nos passos anteriores é obrigatório em todas as requisições feitas à API Abertura de Contas, inclusive na requisição de autorização.


Collection Postman API Abertura de Contas


Configurando o Postman para testes

Dica

O uso do software Postman é opcional. A seguir, explicaremos como configurá-lo. Caso não deseje usar o Postman para testes, você pode avançar para o tópico: Obter Autorização.


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 Efí;
  2. Um certificado P12/PEM gerado como ilustrado nas etapas anteriores;
  3. O software Postman instalado em seu computador (Caso não tenha, clique aqui para baixar);

1. 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.

Isso permitirá que você solicite a autorização apenas uma vez, gravando o access_token como uma variável de ambiente (environment) do Postman, disponível para uso em outras requisições subsequentes.

Para criar um Environment siga os passos a seguir:

  1. Pressione Ctrl+N para acionar o atalho 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 efi-cadastro-api como valor inicial (Initial value) e insira a URL da API Abertura de Contas Efí de Produção;
  4. Salve o seu Environment;
  5. Selecione o Environment desejado para que o Postman entenda a variável criada.

As imagens a seguir mostram os passos ilustrados acima. Neste exemplo, foi criado um Environment para o ambiente de Produção API Abertura de Contas Efí.

banner

Criando um novo environment


banner

Configurações do environment


2. Configurando o certificado no Postman

Todas as requisições feitas à API Abertura de Contas Efí precisam do certificado gerado em sua conta Efí. Portanto, para facilitar seus testes utilizando o Postman, siga os passos a seguir 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";
  5. 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);
  6. Utilize o campo "PFX File" para indicar ao Postman onde está localizado o arquivo do seu certificado P12/PEM;
  7. Finalize clicando em "Add" para salvar as configurações.

Seguindo esses passos, o Postman usará o certificado para quaisquer requisições feitas ao Host do ambiente configurado.

banner

Acessando as configurações do Postman


banner

Adicionando um novo certificado no Postman


banner

Configurações do certificado


3. 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 Efí. Essas credenciais são usadas para o Basic Auth e para obter o access_token junto ao OAuth.

Siga os passos a seguir para incluir as credenciais e realizar o seu primeiro teste na API Abertura de Contas Efí .

  1. Na collection importada, vá até a rota /v1/oauth/token e clique duas vezes para abrir;
  2. Acesse o menu "Authorization" e verifique se o "Type" (tipo de autorização) está selecionado como "Basic Auth";
  3. Preencha os campos "username" e "password" com as credenciais da sua aplicação, ou seja, o Client_Id e o Client_Secret, respectivamente;
  4. Para testar, clique no botão "Send" para enviar 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 mostrado na imagem abaixo):

banner

Uso das credenciais de uma aplicação para autorização de requisições


Obter autorização

POST /v1/oauth/token

Este endpoint é utilizado para autorizar as credenciais de uma aplicação e obter os escopos de acesso à API Abertura de Contas Efí. Para garantir a segurança na comunicação entre cliente e servidor, é essencial que o certificado P12/PEM esteja presente na requisição de autorização.

Exemplos de autorização utilizando o certificado .P12

Para usar a API Abertura de Contas Efí, o cliente e o servidor devem se comunicar por uma conexão verificada. Isso é feito através do certificado bidirecional (.PEM ou .P12), onde servidor e cliente possuem um certificado de chave privada e um de chave pública para garantir suas identidades.

Portanto, ao fazer qualquer requisição HTTP à API Abertura de Contas, incluindo a solicitação de autorização pelo OAuth2, é fundamental que o certificado .P12 ou .PEM esteja presente nos cabeçalhos da requisição.

A seguir, apresentamos exemplos de como obter a autorização na API Abertura de Contas Efí, incorporando esse certificado na requisição.

//Desenvolvido pela Consultoria Técnica da Efí
<?php
$config = [
"certificado" => "./certificado.pem",
"client_id" => "YOUR-CLIENT-ID",
"client_secret" => "YOUR-CLIENT-SECRET"
];
$autorizacao = base64_encode($config["client_id"] . ":" . $config["client_secret"]);

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => "https://abrircontas.api.efipay.com.br/v1/oauth/token", // Rota base, homologação ou produção
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{"grant_type": "client_credentials"}',
CURLOPT_SSLCERT => $config["certificado"], // Caminho do certificado
CURLOPT_SSLCERTPASSWD => "",
CURLOPT_HTTPHEADER => array(
"Authorization: Basic $autorizacao",
"Content-Type: application/json"
),
));

$response = curl_exec($curl);

curl_close($curl);

echo "<pre>";
echo $response;
echo "</pre>";
?>

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.

{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "gn.registration.write gn.registration.read gn.registration.webhook.write gn.registration.webhook.read"
}

Tutorial API Abertura de Contas Efí

Neste vídeo vamos demonstrar, na prática, o processo de abertura e autenticação, além de apresentar os webhooks, endpoints e outros detalhes importantes da API de abertura de contas.