SDK de Integração para API Integra Bancos

Este SDK visa simplificar a integração do seu sistema com a nossa API, oferencendo classes com funções pré-definidas para acessar as rotas da API. Isso Elimina a necessidade de desenvolver uma aplicação para se comunicar diretamente com a nossa API, tornado o processo mais eficiente e direto.

NOTA: usa apenas o cURL diretamente sem usar pacotes de terceiros.

Forma de instalação do SDK

composer require integrabancos/sdk-php

Regras de Autenticação

Para autenticar o uso da API é necessario obter o Token de Acesso (Access Token) no qual vai permitir realizar operações desejadas.

Para obtenção do token é preciso ter as seguintes Credenciais.

• Client ID: Fornecido pelo IntegraBancos após o cadastro na aplicação.
• Client Secret: Fornecido pelo IntegraBancos após o cadastro na aplicação.
• Login: Seu Email usado no cadastro da aplicação.
• Senha: Sua senha cadastrada na aplicação.

Código Exemplo para obteção do Token de Acesso.

Pode se utilizar qualquer uma das classes de operação no exemplo abaixo vamos utilizar a de Emitente.

<?php

use IntegraBancos\SdkPHP\Auth;
use IntegraBancos\SdkPHP\Crypto;

$is_production = false;

// Se não for a primeira vez rodando o codigo e já possuir o refresh_token salvo
$refresh_token = "SEU_REFRESH_TOKEN";

// Chave para criptografar o token e salva-lo no banco de dados
// IMPORTANTE: A chave deve conter 32 caracteres ou 32 bytes
// OBS: Logo abaixo é ensinado como pode ser gerado essa crypto_key 
$crypto_key = getenv("CRYPTO_KEY");

/**
 * RECOMENDAÇÃO: obtenha os valores da função getenv()
 * OBS: A função getenv() lê direto do sistema/servidor e 
 * não lê arquivos .env físicos automaticamente.
*/
$credentials = [
    "client_id"     => getenv("INTEGRABANCOS_CLIENT_ID"),
    "client_secret" => getenv("INTEGRABANCOS_CLIENT_SECRET"),
    "login"         => getenv("INTEGRABANCOS_LOGIN"),
    "password"      => getenv("INTEGRABANCOS_SENHA")
];

try {
    // Requisição de geração do Access e Refresh Token
    $response = Auth::getAccessToken($credentials, $refresh_token, $is_production);

    if (empty($response->access_token)) {
        // Retornar erro ao solicitar access_token
        throw new \Exception("Falha ao obter o access_token.");  
    }

    $access_token = $response->access_token;
    $refresh_token = $response->refresh_token;
    $expires_in = $response->expires_in;

    // Salvar os dados no Banco de dados
    
    // Visualização dos Campos
    echo json_encode(array(
        "access_token" => $access_token,
        "refresh_token" => $refresh_token,
        "expires_in" => $expires_in
    ));
} catch (\Exception $e) {
    // Exemplo de visualização de erro
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode(["erro" => $e->getMessage()]);
}

Boas Práticas e Segurança da Informação

A manipulação de dados financeiros, credenciais e tokens de autenticação exige um controle rígido de segurança no ambiente da aplicação integradora. Caso informações sensíveis ou tokens de acesso venham a vazar por falta de proteção adequada, agentes maliciosos poderão obter acesso não autorizado aos serviços, gerando cobranças ou Pix falsos e causando graves prejuízos financeiros aos seus clientes.

Por que utilizamos a abordagem AES-256-GCM?

A classe Crypto incluída neste SDK utiliza o padrão de criptografia avançada AES-256-GCM via extensão OpenSSL do PHP. Essa abordagem foi definida para atender aos mais altos critérios de proteção do mercado devido às seguintes características:

• Criptografia Autenticada: Ao contrário de modos mais antigos (como CBC), o modo GCM (Galois/Counter Mode) fornece criptografia autenticada. Isso significa que, além de ocultar a informação (confidencialidade), o algoritmo gera uma tag de autenticação que impede que os dados criptografados sejam adulterados ou modificados de forma maliciosa em trânsito ou no banco de dados.
• Segurança de Nível Militar (256 bits): O uso de uma chave simétrica robusta com exatamente 32 bytes (256 bits) oferece resistência extrema contra ataques modernos de força bruta.
• Vetor de Inicialização Único (IV): Cada operação de criptografia gera um IV inteiramente aleatório. Isso garante que, mesmo se você criptografar o mesmo token repetidas vezes, o resultado final gerado em formato Base64 será sempre completamente diferente, eliminando padrões previsíveis.

Estrutura Educacional para Armazenamento de Tokens

Para apoiar a implementação segura do seu sistema, recomenda-se salvar os dados retornados pela autenticação em uma tabela dedicada, aplicando a encriptação fornecida pela classe Crypto nos campos indicados:

Campo	Tipo	Formato do Dado	Descrição
access_token	text	Criptografado	Token de acesso retornado pela API, encriptado via SDK.
refresh_token	text	Criptografado	Token de renovação de sessão, encriptado via SDK.
valid_at	datetime	Texto Limpo	Data e hora calculada do vencimento com base no expires_in.

💡 Dica de Implementação: Sempre transforme o valor inteiro de segundos recebido no campo expires_in em um formato de data/hora real (Y-m-d H:i:s) no momento em que salvar o registro. Isso tornará simples criar validações rotineiras no seu sistema para disparar o fluxo de renovação por refresh_token de maneira automatizada e preventiva antes da expiração acontecer.

Realizando operações

Com o Access Token agora é possível operar ações na API. Porém para realizar ações de emitente é necessario cadastrar um emitente, que pode ser por via Painel ou via API.

Código exemplo de cadastro de emitente via API

<?php

use IntegraBancos\SdkPHP\Emitente;

$config = [
    "access_token" => "ACCESS_TOKEN",
    "is_production" => false
];

// Dados do emitente
$data = [
    "nome" => "EMPRESA TESTE",
    "razao" => "EMPRESA TESTE",
    "cnpj" => "44354598000192",
    "cpf" => "12345678901",
    "telefone" => "46998895532",
    "email" => "empresa@teste.com",
    "rua" => "TESTE",
    "numero" => "1",
    "complemento" => "NENHUM",
    "bairro" => "TESTE",
    "nome_municipio" => "CIDADE TESTE",
    "codigo_municipio" => "5300108",
    "uf" => "PR",
    "cep" => "85000100"
];

try {
    $emitente = new Emitente($config);
    
    // Requisição para criação do emitente
    $response = $emitente->cria($data);

    // Obtenção do x-api-token
    $x_api_key = $response->x_api_key;

    // Visualização do retorno
    echo json_encode($response);
} catch (\Exception $e) {
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode(["erro" => $e->getMessage()]);
}

Seguindo esse passo a passo agora você pode encontrar todos os exemplos de métodos disponíveis na pasta examples