README

SDK Oficial em PHP para integração com as APIs Financeiras e Não Financeiras do Sicoob.

Este SDK foi gerado a partir das especificações Swagger (OpenAPI) da Sicoob e foi projetado de forma modular, unificando as chamadas em um Client que gerencia a autenticação e certificados.

Estrutura do Pacote

sicoob_sdk_php/
├── auth/                         - API de Geração de Tokens
├── pix/                          - API Pix (Recebimentos, Cobranças imediatas)
├── pagamentos-pix/               - API Pagamentos Pix
├── cobrancav3/                   - API Cobrança Bancária V3 (Boletos)
├── pagamentosv3/                 - API Cobrança Bancária Pagamentos
├── conta-corrente/               - API Conta Corrente (Extrato, Saldo)
├── convenio-pagamentos/          - API Arrecadação e Convênios
├── investimentos/                - API Investimentos Renda Fixa
├── poupanca-api/                 - API de Poupança (Extrato, Saldo)
├── openfinance-consentimento/    - API Open Finance Consentimentos
├── spb-transferencias/           - API Transferências SPB (TEDs)
└── SicoobClient.php              - Orquestrador principal unificado

Requisitos de Autenticação e mTLS (Certificados)

Diferente de outras linguagens, o cliente HTTP subjacente ao SDK PHP (o GuzzleHttp) possui excelente suporte a certificados .pfx ou .p12 que contenham senha, bem como suporte a arquivos .pem.

Portanto, não é estritamente obrigatória a conversão do seu certificado .pfx via OpenSSL para usar este SDK (embora arquivos .pem descriptografados continuem sendo aceitos).

Exemplo de Uso

Instancie a classe SicoobClient passando o caminho do seu certificado digital (e a senha se houver), e invoque authenticate().

O token gerado será automaticamente distribuído para todas as APIs de negócio.

<?php

require_once(__DIR__ . '/vendor/autoload.php');
require_once(__DIR__ . '/SicoobClient.php');

use Sicoob\SicoobClient;

// Instanciando passando um .pfx e sua respectiva senha
// O último parâmetro (isSandbox) define se vai rodar em Prod ou Sandbox (false = Produção)
$clientId = "SEU_CLIENT_ID";
$sicoob = new SicoobClient(
    $clientId,
    "cert.pfx",
    "SENHA_DO_PFX",
    false
);

// --- EM AMBIENTE DE PRODUÇÃO ---
// Autentica (gera o Token e injeta nos módulos de Pix, Cobranca, etc)
// É obrigatório informar os escopos desejados na primeira chamada
$token = $sicoob->authenticate("cco_transferencias cco_consulta openid");

// --- EM AMBIENTE DE SANDBOX ---
// Em Sandbox, não chame o authenticate(). Obtenha o token fixo no Portal Developers e injete:
// $sicoob->setSandboxToken("1301865f-c6bc-38f3-9f49-666dbcfc59c3");

try {
    $responseSaldo = $sicoob->contaCorrenteSaldoApi->obterSaldo($clientId, "123456");
    echo "Saldo: " . $responseSaldo->getSaldo() . "\n";
    
    // Exemplo: Consultar Cobranças Pix
    $inicio = date("Y-m-d\TH:i:s\Z", strtotime("-5 days"));
    $fim = date("Y-m-d\TH:i:s\Z");
    $responseCobs = $sicoob->pixCobApi->cobGet($inicio, $fim);
    
    print_r($responseCobs);


} catch (\Exception $e) {
    echo "Exception: ", $e->getMessage(), PHP_EOL;
}

🔄 Renovação Automática de Token

O SDK possui inteligência embutida para lidar com a expiração do token OAuth2. Ao receber um erro 401 Unauthorized de qualquer API de negócio, o Client intercepta a falha, utiliza os escopos informados na primeira autenticação para gerar um novo token de acesso, e refaz a requisição original de forma 100% transparente. Você não precisa se preocupar com caches ou temporizadores na sua aplicação!

Instalação (Composer)

composer require sicoob-cooperativa/sicoob_sdk_php

Escopos (Scopes) por API

Ao chamar o método de autenticação, dependendo da API que você for utilizar, é estritamente necessário fornecer os escopos (scopes) apropriados separados por espaço. Abaixo a tabela de referência das APIs e seus escopos:

API de Negócio	Escopos Comuns Necessários
Cobrança Bancária V3	`cobranca_boletos_consultar` `cobranca_boletos_incluir` `cobranca_boletos_pagador` `cobranca_boletos_segunda_via` `cobranca_boletos_baixa` `cobranca_boletos_rateio_credito`
Cobrança Bancária Pagamentos	`pagamentos_boletos_pagar` `pagamentos_boletos_agendar` `pagamentos_boletos_consultar`
Conta Corrente	`cco_extrato` `cco_saldo` `cco_transferencias`
Convênio Pagamentos	`conveniopagamentos_arrecadacao` `conveniopagamentos_debitos_automaticos`
Investimentos	`investimentos_renda_fixa`
Open Finance	`openid` (Necessita de diretrizes específicas do fluxo OIDC)
Pagamentos PIX	`pixpagamentos_escrita` `pixpagamentos_consulta` `pixpagamentos_webhook`
PIX (Recebimentos)	`cob.read` `cob.write` `cobv.read` `cobv.write` `lotecobv.read` `lotecobv.write` `pix.read` `pix.write` `webhook.read` `webhook.write` `payloadlocation.read` `payloadlocation.write`
Poupança	`poupanca_saldo` `poupanca_extrato` `poupanca_aplicacao` `poupanca_resgate`
SPB Transferências	`spb_transferencias_ted`

Nota: Alguns escopos exigem liberação específica nas chaves da sua aplicação no Portal de Desenvolvedores do Sicoob.

Documentação Específica

Para detalhes exatos sobre métodos, parâmetros de requisição e construtores de DTO de cada API, verifique o README.md individual que foi gerado dentro da pasta de cada submódulo:

sicoob-cooperativa / sicoob_sdk_php

Maintainers

Package info

Statistics

Security