Nova API: veja como integrar utilizando o composer

Se você é um programador PHP, provavelmente já ouviu falar do composer: um gerenciador de dependências utilizado para instalar/atualizar todas as bibliotecas que um projeto necessita.

Com o composer, o integrador controla a versão de cada dependência que deseja utilizar sem se preocupar em baixar cada uma individualmente. Além disso, ele ainda cria um arquivo de autoload e realiza todo o trabalho de organização quando você precisa alterar uma versão ou apagar uma dependência.

Neste artigo vamos mostrar como utilizar o composer para integrar com a Nova API Efí.

Primeiro Passo: Criando uma aplicação

Acesse o menu “API” na barrinha superior da sua conta Efí*:

*Se não consegue visualizar este menu, envie um ticket para nosso suporte ou um e-mail para [email protected]. O menu será habilitado para sua conta em no máximo um dia útil.

Você terá acesso à página de documentação da Nova API. Para começar a integrar, crie sua primeira aplicação. Você pode criar quantas aplicações quiser e definir o nome que achar melhor. Esse nome não é mostrado para seu cliente em momento algum e serve apenas para sua organização.

A imagem a seguir mostra como é a página inicial de uma aplicação:

Tela Minhas Aplicações - API Emissões Efí

Nessa tela é possível acompanhar todas as ações realizadas pelo sistema integrador, tanto em ambiente de produção quanto em ambiente de homologação.

A aba “Playground” exibe todos os endpoints possíveis da API Emissões. Em um próximo artigo, iremos mostrar como utilizá-los. O importante aqui é saber que as SDKs disponibilizadas pela Efí abstraem toda a parte de autorização de consumo e disponibilizam funções específicas para cada endpoint exibido nessa tela de Playground.

Instalando a SDK

Para Linux

Primeiro, vamos instalar o composer localmente na pasta do seu projeto:

Abra um terminal de comando;
Navegue até o diretório do seu projeto;
Rode o comando:

$ curl -sS https://getcomposer.org/installer | php

Esse comando baixa um script em php que faz algumas verificações nas configurações e baixa, em seguida o arquivo composer.phar para seu diretório.

Para Windows

Faça o download e rode o Composer-Setup.exe. A última versão do Composer será instalada em sua máquina. Você não precisa realizar esse processo novamente caso queira criar outros projetos usando Composer.

Composer.json

Agora precisamos criar o arquivo responsável por informar quais são as dependências do projeto e suas respectivas versões. As informações nesse arquivo devem vir em formato de JSON. Para saber mais sobre ele, consulte a documentação do composer.

Neste artigo vamos nos limitar a explicação à instalação da SDK, por isso, nosso arquivo composer.json ficará assim:

{
    “require”: {
        “gerencianet/gerencianet-sdk-php”: “1.*”
    }
}

Com o arquivo composer.json criado no mesmo diretório que o composer.phar, rode o comando:

$ php composer.phar install
(Linux)

$ composer install
(Windows)

Esse comando vai baixar todas as dependências e subdependências da SDK.

Ao final da execução, é possível perceber uma pasta chamada “vendor” que contém todas as bibliotecas baixadas e um arquivo chamado autoload.php.

Utilização

Vamos mostrar um exemplo de página que cria uma cobrança no ambiente de homologação da sua aplicação.

Para isso, crie um formulário como mostrado a seguir:

<!DOCTYPE html>
<html>

<head>
  <meta charset="UTF-8">
  <title>SDK Efí</title>
</head>

<body>
  <form action="backend.php" method="post">
    <h1>Exemplo de utilização</h1>
    <table border="1" cellspacing="1">
      <thead>
        <tr>
          <th>Produto</th>
          <th>Quantidade</th>
          <th>Valor</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>Primeiro item</td>
          <td>
            <input type="number" name="item[0][amount]" value="1" />
          </td>
          <td>
            <input type="number" name="item[0][value]" value="500" />
          </td>
        </tr>
        <tr>
          <td>Segundo item</td>
          <td>
            <input type="number" name="item[1][amount]" value="2" />
          </td>
          <td>
            <input type="number" name="item[1][value]" value="1000" />
          </td>
        </tr>
      </tbody>
    </table>
    <br />
    <div>
      <input type="submit" value="Gerar Boleto" />
    </div>
  </form>
</body>

</html>

Crie também um arquivo backend.php, que será o action do formulário:

<?php

require_once(__DIR__ . "/vendor/autoload.php");

use Efí\Exception\EfíException;
use Efí\Efí;

try {
  
$options = [
    "client_id" => "Client_Id",
    "client_secret" => "Client_Secret",
    "sandbox" => true
];

$api = new Efí($options);
    
$items = array();
if(isset($_POST["item"]) && is_array($_POST["item"])) {
    foreach($_POST["item"] as $k => $v) {
$items[$k] = [
    "name" => "Item ".$k,
    "amount" => (int)$v["amount"],
    "value" => (int)$v["value"]
];
    }
}

$body = [
    "items" => $items
];

$charge = $api->createCharge([], $body);
    echo "<pre>";
    print_r($charge);
    echo "<pre>";
} catch(EfíException $e) {
    print_r($e->code);
    print_r($e->error);
    print_r($e->errorDescription);
} catch(Exception $ex) {
    print_r($ex->getMessage());
}

*Lembre-se de inserir suas credenciais nas linhas 11 e 12.

O arquivo backend.php utiliza a função createCharge(), que cria uma cobrança na Efí com o status ‘new’.

Na página da aplicação, aba “Desenvolvedor”, é possível ver essa transação:

Esse é um exemplo simplificado da utilização da API. Na prática, é importante fazer o tratamento dos erros e não confiar em dados que chegam em seu backend via POST. Recomendamos que os valores dos itens estejam sempre armazenados em seu servidor.

Em caso de dúvidas, envie um ticket ou um e-mail para [email protected].