Pular para o conteúdo principal

Credenciais e Autorização

Nesta página, você encontra informações sobre credenciais e autorização da API Cobranças Efí.


A API Cobranças Efí oferece recursos avançados que permitem emitir diferentes tipos de cobranças, tais como Boleto, Cartão de crédito, Carnê, Links de pagamento, Assinaturas (Recorrência) e Marketplace (Split de pagamento).

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

A seguir, veja como obter as credenciais 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

Para obter as credenciais da aplicação, a pessoa integradora pode criar quantas aplicações desejar. Cada aplicação é associada a 2 pares de chaves: Client_Id e Client_Secret, sendo um par destinado ao ambiente de Produção (?) e outro para o ambiente de Homologação (?). É fundamental ativar o escopo em sua aplicação para poder utilizar a API Cobranças da Efí.

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

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

Para criar uma aplicação e utilizar a API Cobranças 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 de Emissões e escolha o escopo para liberar os ambientes de Produção/Homologação;
  4. Com o escopo selecionados, clique em "Continuar".
banner

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

Rota base

Nesta documentação, você encontrará referências às Rotas base ou URL's base para ambientes de Produção ou Homologação. Essas rotas representam o endereço da API Cobranças Efí. 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 as seguintes rotas:

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

Autenticação com OAuth2

O processo de autenticação na API Cobranças segue o protocolo OAuth2. As requisições são autenticadas usando HTTP Basic Auth.

Collection Postman API Cobranças


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.


Antes de prosseguir com a configuração do Postman, certifique-se de ter:

  1. Um par de credenciais Client_Id e Client_Secret de uma aplicação cadastrada em sua Conta Efí;
  2. O software Postman instalado em seu computador (Caso não tenha, baixe aqui);

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. Presione 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 efi-cob-api e como valor inicial (Initial value) insira a URL da API Cobranças de Produção ou Homologaçã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 da API Cobranças da Efí.

banner

Criando um novo environment


banner

Configurações do environment


2. 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 Cobranças.

  1. Na collection importada, vá até a rota /v1/authorize 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 na imagem abaixo).

banner

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


Obter Autorização

POST /v1/authorize

O endpoint POST /v1/authorize é usado para autorizar as credenciais de uma aplicação e obter os acessos necessários para utilizar os outros recursos da API.

Exemplos de autorização

A seguir, apresentamos exemplos de como realizar a autorização na API Cobranças:

//Desenvolvido pela Consultoria Técnica da Efí
<?php
$config = [
"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://cobrancas-h.api.efipay.com.br/v1/authorize',
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_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

A seguir, o trecho de código representa um exemplo de resposta do OAuth à sua requisição de autorização:

{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MTYyOTY2NTYsImV4cCI6MTcxNjI5NzI1NiwiZGF0YSI6eyJrZXlfaWQiOjUyOTU2MSwidHlwZSI6ImFjY2Vzc1Rva2VuIn19._d22EAjlsmuCKxTCtYDMd2ZVK04fS7xWNWSjE-JWEpc",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MTYyOTY2NTYsImV4cCI6MTcxNjI5Nzg1NiwiZGF0YSI6eyJrZXlfaWQiOjUyOTU2MSwidHlwZSI6InJlZnJlc2hUb2tlbiJ9fQ.4txXqR4g5FMQvCU3jL8LnrQ002xfEAK1EwKaJjlyCOU",
"expires_in": 600,
"expire_at": "1690986856033",
"token_type": "Bearer"
}

A tabela abaixo descreve os atributos presentes no JSON retornado.

AtributoDescriçãoTipo
access_tokenToken de autorização a ser usado nas outras requisições feitas à API.string
refresh_tokenToken de autorização que será utilizado para atualizar um access token expirado.string
expires_inTempo de expiração do access_token em segundos.
Padrão 600
Integer (int32)
expire_atTempo de expiração do access_token em Timestamp ISO 8601string
token_typeTipo de autorização na qual o access_token deve ser usado
Padrão: "Bearer"
string