Skip to main content

Credentials, Certificate and Authorization

On this page you will find information about credentials, certificates and authorization for the Statements Efí API.


The Efí Statements API offers endpoints for managing and processing CNAB 240 files. With it, you can:
  • consult generated files;
  • create and review recurrences;
  • generate keys.

To integrate the Statements API with your system or platform, you must have an Efí Digital Account. After opening your account, you will be able to obtain the necessary credentials and certificates to communicate with the Extratos Efí API.

See below how to obtain credentials, certificates and details about the authorization and security of your integration with Efí.

Security in credential management

Within systems integrated with our API, it is important that login operations and changing integration keys be done securely. We suggest implementing two-factor authentication and other security practices.


Getting application credentials

An integrator can create as many applications as he wants. For each application, 2 pairs of keys Client_Id and Client_Secret are generated, one pair for use in Production environment (?) and another for Sandbox environment (?).

To use the Statements Efí API, it is also necessary to have the required scopes activated.

Understanding application's scopes

When creating or editing an application in your Efí Account, you will need to configure the scopes that the application will have access to. The choice of these scopes defines which actions an application will be authorized to perform via API.

The scopes available in the Statements Efí API are listed below with their respective permission descriptions:

  • gn.cnab-statement.statement.write - creation and review of recurrences;
  • gn.cnab-statement.statement.read - consultation of generated files and registered recurrences and download of the statement;
  • gn.cnab-statement.keys.write - generates key;

Create a new application or configure an existing one

Below you can see how to create an application or use an existing application to integrate with the Statements Efí API.

To create an application for use with the Statements Efí API, follow the steps below:

  1. Access your account and click on the "API" item at the bottom of the left menu of the Efí account;
  2. Click on "Criar aplicação"
  3. Enable the Statements API and choose the scopes you want to release in Production and Sandbox environments (you can edit them in the future);
  4. With the selected scopes, click "Continuar".
banner

Illustration of the steps for create a new application integrated with the Statements API


Generating and converting a P12 certificate

To generate and convert a certificate, if necessary, you can access the link.

Base route

In this documentation, you will notice references to the Base route or Base URL for the Production environment. This route is, in fact, the URL at which the Statements Efí API is located. Thus, when we refer to endpoints, it is implied that these URL segments also make up the final route of the desired resource.

Use the route below to communicate your application with the production environment offered by Efí.

EnvironmentBase route
Productionhttps://extratos.api.efipay.com.br

OAuth2 Authentication

The authorization mechanism for requests made to the Statements Efí API is compatible with the OAuth2 protocol.

Objective of OAuth2

Obtain an access token (access_token) that should be used to authorize all calls made to the API, verifying if a particular application has permissions to consume the requested endpoint.

How request authentication is done

It is done with HTTP Basic Auth using the Client_Id and Client_Secret of the application created in your Efí account.

Through this authentication, OAuth can respond with the authorizations that the application has, and consequently authorize or deny requests based on this information.

Attention!

The P12/PEM Certificate generated in the previous steps is required in all requests made to the Statements API, including the authorization request.


Postman Collection for Statements API


Setting Postman for tests

Tip

Using the Postman software is optional. The following paragraphs explain how to set it up. If you do not wish to use Postman for testing, you can skip to the topic: Obtain Authorization.


To proceed with the Postman setup step, you should have:

  1. A pair of credentials Client_Id and Client_Secret from an application registered in your Efí Account;
  2. A P12/PEM certificate generated as illustrated in the previous steps;
  3. The Postman software installed on your computer (If you don't have it, click here to download);

1. Creating an Environment

Creating an Environment in Postman is necessary for some built-in automations in the collection to work. These automations are designed to make testing easier for developers.

With them, you only need to request authorization once, and then the access_token is stored as an environment variable in Postman, available for use in subsequent requests.

To create an Environment, follow the steps below.

  1. Press the shortcut Ctrl+N and select "Environment";
  2. Assign a name, preferably specifying whether this Environment will be pointed to the Production or Sandbox environment;
  3. Create the variable efi-ext-api and, as the Initial value, enter the URL of the Statements Efí API for Production;
  4. Save your Environment;
  5. Select the desired Environment. This way, Postman will understand the created variable.

The images below illustrate the steps above. As an example, an Environment was created pointing to the Production environment of the Statements Efí API.

banner

Creating a new environment


banner

Environment settings


2. Setting the certificate in Postman

All requests made to the Statements Efí API require the certificate generated in your Efí account. Therefore, to facilitate your testing using Postman, follow the steps below to configure the use of the certificate during requests automatically:

  1. Click on the gear icon in the top right corner of Postman;
  2. Then, click on "Settings" to open the settings;
  3. In the top tab, click on "Certificates";
  4. Next, click on "Add Certificate";
  5. In the new certificate configuration window, fill in the "Host" field with the Base route of the environment to which the certificate belongs (Production or Sandbox);
  6. Use the "PFX File" field to inform Postman where your P12/PEM certificate file is located;
  7. Finish by clicking "Add" to save your settings.

By following these steps, Postman will use the certificate for any requests made to the Host of the configured environment.

banner

Accessing Postman settings


banner

Adding a new certificate in Postman


banner

Certificate settings


3. Assigning the Client_Id and Client_Secret in Postman

To complete the configuration of your Postman, you need to set up the credentials of an application from your Efí account. These credentials are used for Basic Auth and obtaining the access_token with OAuth.

Follow the steps below to include the credentials and perform your first test on the Statements API.

  1. In the imported collection, navigate to the route /v1/oauth/token and double-click to open;
  2. Access the "Authorization" menu and make sure the "Type" is selected as "Basic Auth";
  3. In the "username" and "password" fields, fill in with the credentials of your application, Client_Id and Client_Secret, respectively;
  4. To test, click the "Send" button to submit the request

The image below illustrates the steps above. If everything was followed correctly, you should receive a response in JSON format, containing the access_token, token_type, expires_in, and scope (as shown in the image below).

banner

Using the credentials of an application for request authorization


Obtain authorization

POST /v1/oauth/token

This endpoint is used to:

  • authorize the credentials of an application
  • obtain the scopes that the application has to access the other endpoints of the API.
Attention!

The P12/PEM certificate must be present in the authorization request so that the handshake with the API server is allowed.


Examples of authorization using the .P12 certificate

For using the Statements Efí API, it is necessary for the client and the server to communicate over a mutually verified connection. Verification is done through a bidirectional certificate (.PEM or .P12), meaning the server and client have implemented a private key certificate and a public key certificate that allows each to ensure the other's identity.

Therefore, to make any HTTP request to the Statements API, including the authorization request with OAuth2, the .P12 or .PEM certificate must be present in the request headers.

Below, we provide examples of how to consume authorization from the Statements Efí API, incorporating this certificate into the request.

// Developed by the Technical Consulting Team at 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://extratos.api.efipay.com.br/v1/oauth/token", // Base route, Sandbox or production
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"], // Certificate path
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>";
?>

Example of authorization response

The code snippet below represents an example of the OAuth response to your authorization request.

{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "gn.cnab-statement.keys.write gn.cnab-statement.statement.read gn.cnab-statement.statement.write"
}