PHPackages                             matfatjoe/api-santander - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. matfatjoe/api-santander

ActiveLibrary[Payment Processing](/categories/payments)

matfatjoe/api-santander
=======================

Library for Santander Boleto Emission

1.0.4(1mo ago)011MITPHPPHP ^7.4

Since Mar 25Pushed 1mo agoCompare

[ Source](https://github.com/matfatjoe/api-santander)[ Packagist](https://packagist.org/packages/matfatjoe/api-santander)[ RSS](/packages/matfatjoe-api-santander/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (5)Dependencies (2)Versions (6)Used By (0)

Santander Boleto API - PHP Library
==================================

[](#santander-boleto-api---php-library)

[![PHP Version](https://camo.githubusercontent.com/204b1791e3a57f86a93de1422b2a6e584f5045431629c5b9abd4e28dbc8b5357/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344372e342d626c75652e737667)](https://php.net)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE)

Biblioteca PHP para integração com a API de Cobrança do Santander, permitindo o gerenciamento completo de boletos bancários e workspaces.

📋 Índice
--------

[](#-índice)

- [Características](#-caracter%C3%ADsticas)
- [Requisitos](#-requisitos)
- [Instalação](#-instala%C3%A7%C3%A3o)
- [Configuração](#-configura%C3%A7%C3%A3o)
- [Uso Básico](#-uso-b%C3%A1sico)
- [Módulos](#-m%C3%B3dulos)
- [Exemplos](#-exemplos)
- [Testes](#-testes)
- [Documentação da API](#-documenta%C3%A7%C3%A3o-da-api)
- [Contribuindo](#-contribuindo)
- [Licença](#-licen%C3%A7a)

✨ Características
-----------------

[](#-características)

- ✅ **Autenticação mTLS** - Suporte completo a certificados digitais
- ✅ **Gerenciamento de Workspaces** - CRUD completo de workspaces
- ✅ **Registro de Boletos** - Emissão de boletos com todos os campos suportados
- ✅ **Consultas Avançadas** - Múltiplos métodos de consulta (SONDA, por nosso número, por seu número, lista)
- ✅ **Instruções de Boleto** - Envio de comandos (descontos, multas, baixas, etc.)
- ✅ **Testes Unitários** - 17 testes, 46 asserções
- ✅ **PSR-4 Autoloading** - Estrutura moderna e organizada
- ✅ **Type Hints** - Código fortemente tipado para PHP 7.4+

📦 Requisitos
------------

[](#-requisitos)

- PHP >= 7.4
- Composer
- Extensões PHP:
    - `ext-json`
    - `ext-openssl`
    - `ext-curl`
- Certificado digital PFX do Santander
- Credenciais da API (Client ID e Client Secret)

🚀 Instalação
------------

[](#-instalação)

```
composer require matfatjoe/api-santander
```

Ou clone o repositório:

```
git clone https://github.com/matfatjoe/api-santander.git
cd api-santander
composer install
```

⚙️ Configuração
---------------

[](#️-configuração)

### 1. Certificado Digital

[](#1-certificado-digital)

Coloque seu certificado `.pfx` no diretório do projeto e configure as credenciais:

```
$pfxPath = __DIR__ . '/certificate.pfx';
$passphrase = 'sua_senha_do_certificado';
$clientId = 'seu_client_id';
$clientSecret = 'seu_client_secret';
```

### 2. Ambiente

[](#2-ambiente)

```
// Sandbox (Testes)
$baseUrl = 'https://trust-sandbox.api.santander.com.br';

// Produção
$baseUrl = 'https://trust-open.api.santander.com.br';
```

💡 Uso Básico
------------

[](#-uso-básico)

### Autenticação

[](#autenticação)

```
use Matfatjoe\SantanderBoleto\Auth\Authenticator;
use Matfatjoe\SantanderBoleto\Auth\TokenRequest;
use Matfatjoe\SantanderBoleto\HttpClientFactory;

$tokenRequest = new TokenRequest($pfxPath, $passphrase, $clientId, $clientSecret);
$httpClient = HttpClientFactory::createFromTokenRequest($tokenRequest);
$authenticator = new Authenticator($httpClient, $baseUrl);
$token = $authenticator->getToken($tokenRequest);
```

### Criar Workspace

[](#criar-workspace)

```
use Matfatjoe\SantanderBoleto\Workspace\WorkspaceService;
use Matfatjoe\SantanderBoleto\Workspace\CreateWorkspaceRequest;
use Matfatjoe\SantanderBoleto\Models\Covenant;

$workspaceService = new WorkspaceService($httpClient, $token, $clientId, $baseUrl);

$request = new CreateWorkspaceRequest(
    'BILLING',
    [new Covenant('3567206')],
    'Meu Workspace',
    true,  // Webhook boleto ativo
    true,  // Webhook PIX ativo
    'https://meu-site.com/webhook'
);

$workspace = $workspaceService->create($request);
echo "Workspace criado: " . $workspace->getId();
```

### Registrar Boleto

[](#registrar-boleto)

```
use Matfatjoe\SantanderBoleto\Boleto\BoletoService;
use Matfatjoe\SantanderBoleto\Boleto\RegisterBoletoRequest;
use Matfatjoe\SantanderBoleto\Models\Boleto;
use Matfatjoe\SantanderBoleto\Models\Payer;
use Matfatjoe\SantanderBoleto\Models\Beneficiary;

$boletoService = new BoletoService($httpClient, $token, $clientId, $baseUrl);

$payer = new Payer(
    'João da Silva',
    'CPF',
    '12345678901',
    'Rua das Flores, 123',
    'Centro',
    'São Paulo',
    'SP',
    '01234-567'
);

$beneficiary = new Beneficiary(
    'Minha Empresa LTDA',
    'CNPJ',
    '12345678000199'
);

$boleto = new Boleto(
    'TESTE',
    '1014',
    date('Y-m-d'),
    '3567206',
    '000001',
    'CLI-001',
    date('Y-m-d', strtotime('+7 days')),
    date('Y-m-d'),
    'VENDA-001',
    '150.00',
    $payer,
    $beneficiary
);

$registeredBoleto = $boletoService->register($workspaceId, new RegisterBoletoRequest($boleto));
echo "Código de Barras: " . $registeredBoleto->getBarcode();
```

### Consultar Boleto

[](#consultar-boleto)

```
use Matfatjoe\SantanderBoleto\Query\QueryService;

$queryService = new QueryService($httpClient, $token, $clientId, $baseUrl);

// Por Nosso Número
$boleto = $queryService->queryByBankNumber('3567206', '000001', 'default');

// Por Seu Número
$boleto = $queryService->queryByClientNumber('3567206', 'CLI-001', '2024-01-01', '150.00');

// SONDA (confirma registro - até D+2)
$boleto = $queryService->querySonda($workspaceId, '1014', '2024-01-01', 'TESTE', '3567206', '000001');
```

📚 Módulos
---------

[](#-módulos)

### 🔐 Auth Module

[](#-auth-module)

- `Authenticator` - Autenticação mTLS
- `TokenRequest` / `TokenResponse` - Gerenciamento de tokens
- `HttpClientFactory` - Cliente HTTP configurado

### 🏢 Workspace Module

[](#-workspace-module)

- `WorkspaceService` - CRUD de workspaces
- `CreateWorkspaceRequest` / `UpdateWorkspaceRequest` - Requests
- `Workspace` / `Covenant` - Models

### 📄 Boleto Module

[](#-boleto-module)

- `BoletoService` - Registro e instruções
- `RegisterBoletoRequest` / `InstructionRequest` - Requests
- `Boleto` / `Payer` / `Beneficiary` / `Discount` / `Fine` / `Interest` - Models

### 🔍 Query Module

[](#-query-module)

- `QueryService` - Consultas de boletos
- `QueryFilter` - Filtros de consulta
- Métodos: SONDA, por nosso número, por seu número, lista

📖 Exemplos
----------

[](#-exemplos)

Veja a pasta `examples/` para exemplos completos:

- [`example-auth.php`](examples/example-auth.php) - Autenticação
- [`example-workspace.php`](examples/example-workspace.php) - Gerenciamento de workspaces
- [`example-boleto.php`](examples/example-boleto.php) - Registro de boletos
- [`example-query.php`](examples/example-query.php) - Consultas

🧪 Testes
--------

[](#-testes)

Execute os testes unitários:

```
composer test
```

Ou com Docker:

```
docker-compose run --rm php vendor/bin/phpunit --testdox
```

**Cobertura atual:** 17 testes, 46 asserções ✅

📘 Documentação da API
---------------------

[](#-documentação-da-api)

- [Portal do Desenvolvedor Santander](https://developer.santander.com.br/)

🤝 Contribuindo
--------------

[](#-contribuindo)

Contribuições são bem-vindas! Por favor:

1. Fork o projeto
2. Crie uma branch para sua feature (`git checkout -b feature/MinhaFeature`)
3. Commit suas mudanças (`git commit -m 'Add: Minha nova feature'`)
4. Push para a branch (`git push origin feature/MinhaFeature`)
5. Abra um Pull Request

📝 Licença
---------

[](#-licença)

Este projeto está sob a licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes.

🆘 Suporte
---------

[](#-suporte)

- 🐛 Issues: [GitHub Issues](https://github.com/matfatjoe/api-santander/issues)

---

**Desenvolvido por [Matheus Furquim de Camargo](https://github.com/matfatjoe)**

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance89

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity37

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

5

Last Release

54d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/35349edc0be58383ba4e73e66262342586bcfbecdf38bc40fe8ae8cf860e3e03?d=identicon)[matfatjoe](/maintainers/matfatjoe)

---

Top Contributors

[![matfatjoe](https://avatars.githubusercontent.com/u/38146311?v=4)](https://github.com/matfatjoe "matfatjoe (10 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/matfatjoe-api-santander/health.svg)

```
[![Health](https://phpackages.com/badges/matfatjoe-api-santander/health.svg)](https://phpackages.com/packages/matfatjoe-api-santander)
```

###  Alternatives

[chargebee/chargebee-php

ChargeBee API client implementation for PHP

768.0M9](/packages/chargebee-chargebee-php)[imdhemy/google-play-billing

Google Play Billing

491.3M5](/packages/imdhemy-google-play-billing)[bitpay/sdk

Complete version of the PHP library for the new cryptographically secure BitPay API

42337.5k4](/packages/bitpay-sdk)[buckaroo/sdk

Buckaroo payment SDK

12189.1k9](/packages/buckaroo-sdk)[contica/facturador-electronico-cr

Un facturador de código libre para integrar facturación electrónica en Costa Rica a un proyecto PHP

2128.8k](/packages/contica-facturador-electronico-cr)[karson/mpesa-php-sdk

172.2k](/packages/karson-mpesa-php-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)