Pular para o conteúdo principal

Autenticação

A autenticação é feita por meio do fluxo OAuth2 Authorization Code (documentação em inglês).

Para realizar a autenticação, primeiramente é necessário credenciar-se como desenvolvedor parceiro DFranquias Pay, cadastrar seu aplicativo e gerar suas credenciais Client ID e Client Secret.

Cadastrando seu aplicativo​

No menu lateral do painel de controle do seu ambiente web, na seção de Desenvolvedores, selecione Aplicativos conectados.
Para cadastrar um novo aplicativo, selecione Novo e digite o nome desejado para identificar a aplicação.

Feito isso, você verá na tela seu Client ID, o Client Secret e a URL de redirecionamento. Salve essas informações num lugar seguro - no seu aplicativo, essas informações normalmente ficam salvas em variáveis de ambiente, uma vez que são sensíveis e fornecem acesso à sua conta DFranquias Pay.

O próximo passo é escolher as permissões desejadas e gerar um código de autorização, que será utilizado para solicitar seu token de acesso.

Gerando um código de autorização​

Para gerar um código de autorização, entre em Aplicativos conectados, selecione o menu de ações do aplicativo desejado e clique em Ver detalhes. A tela que se abrirá terá no canto superior direito o menu Ações. Selecione-o e clique na opção Nova autorização.

Feito isso, basta escolher as permissões desejadas para acessar, e confirmar a escolha. Após a confirmação, você será redirecionado para a URL de redirecionamento configurada quando criou o aplicativo.

Utilizando o código de autorização​

Requisição​

Para gerar o seu token de acesso, é necessário fazer uma requisição POST para o endpoint /oauth/token a partir da URL base da API, considerando o ambiente que será utilizado - teste ou produção.

O tipo de conteúdo deve ser multipart/form-data e o conteúdo deve ser como segue:

Atenção

Os trechos de código abaixo representam apenas alguns exemplos de como fazer a requisição em diferentes linguagens de programação. Utilize o cliente HTTP de sua preferência para seus testes. Recomendamos o Postman ou o Insomnia para realização de testes com precisão.

<?php

use Psr\Http\Message\ResponseInterface;
use GuzzleHttp\Exception\RequestException;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Utils;
use GuzzleHttp\Psr7\Request;

$client = new Client();

$options = [
  'multipart' => [
    [
      'name' => 'grant_type',
      'contents' => 'authorization_code'
    ],
    [
      'name' => 'client_id',
      'contents' => 'seu Client ID'
    ],
    [
      'name' => 'client_secret',
      'contents' => 'seu Client Secret'
    ],
    [
      'name' => 'redirect_uri',
      'contents' => 'sua URL de redirecionamento'
    ],
    [
      'name' => 'code',
      'contents' => 'seu código de autorização'
    ]
  ]
];

$request = new Request('POST', 'https://dev.dfranquiaspay.com.br/oauth/token');

$response = $client->sendAsync($request, $options)->wait();

Resposta​

A resposta do endpoint contém a seguinte estrutura:

{
  "access_token":"token de acesso",
  "token_type":"Bearer",
  "expires_in":3600,
  "refresh_token":"refresh token",
}

Para acessar a API, utilize o access_token. O primeiro token gerado a partir do código de autorização tem duração de uma hora. Os subsequentes, gerados a partir dos refresh tokens, duram 15 minutos cada.
Recomendamos utilizar um cron job na sua aplicação para automatizar o processo de renovação dos tokens de acesso.

Utilizando o refresh token​

A requisição para consumir um refresh token é muito similar à requisição feita com o código de autorização:

<?php

use Psr\Http\Message\ResponseInterface;
use GuzzleHttp\Exception\RequestException;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Utils;
use GuzzleHttp\Psr7\Request;

$client = new Client();

$options = [
  'multipart' => [
    [
      'name' => 'grant_type',
      'contents' => 'refresh_token'
    ],
    [
      'name' => 'client_id',
      'contents' => 'seu Client ID'
    ],
    [
      'name' => 'client_secret',
      'contents' => 'seu Client Secret'
    ],
    [
      'name' => 'refresh_token',
      'contents' => 'seu refresh token'
    ]
  ]
];

$request = new Request('POST', 'https://dev.dfranquiaspay.com.br/oauth/token');

$response = $client->sendAsync($request, $options)->wait();

A resposta é idêntica à resposta anterior, com a diferença apenas na duração do token, que será de 900 segundos ou 15 minutos.