PHPackages                             lucas-tonolli/asaas-php-actions - 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. lucas-tonolli/asaas-php-actions

ActiveLibrary[Payment Processing](/categories/payments)

lucas-tonolli/asaas-php-actions
===============================

PHP SDK for Asaas payment gateway

0.1.0-alpha(8mo ago)00[15 issues](https://github.com/LucasTonolli/asaas-php-actions/issues)MITPHPPHP ^8.2.0CI passing

Since Oct 10Pushed 5mo agoCompare

[ Source](https://github.com/LucasTonolli/asaas-php-actions)[ Packagist](https://packagist.org/packages/lucas-tonolli/asaas-php-actions)[ RSS](/packages/lucas-tonolli-asaas-php-actions/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (8)Versions (3)Used By (0)

Asaas PHP SDK
=============

[](#asaas-php-sdk)

[![PHP](https://camo.githubusercontent.com/351755b1ea3b8a079461d461cd8142582eb91df14fea214307a660632576b07a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e312532422d626c7565)](https://www.php.net/)[![License](https://camo.githubusercontent.com/88e1dabf4d223df0950e0985948e231325fefca9fa7fe9e446cf8b1c5e9d9e47/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e)](LICENSE)

Um SDK PHP não oficial, moderno e fluente para interagir com a [API Asaas](https://docs.asaas.com/reference).

Este SDK é construído com foco em princípios de **arquitetura limpa**, **segurança de tipo** (type-safety) e uma excelente experiência para desenvolvedores, aproveitando os recursos modernos do PHP 8.1+.

> ⚠️ **Atualmente em desenvolvimento ativo. As APIs podem sofrer alterações antes de um lançamento estável da v1.0.0.**

---

✨ Principais Funcionalidades
----------------------------

[](#-principais-funcionalidades)

- **API Fluida e Intuitiva**: Encadeie métodos de forma lógica para acessar recursos e realizar ações (ex: `$asaas->cliente()->criar(...)`).
- **Tratamento de Erros Robusto e Previsível**: Chega de adivinhações sobre o que deu errado. O Theol lança exceções específicas e tipadas para diferentes cenários de erro (`ValidationException`, `NotFoundException`, `RateLimitException`, etc.).
- **Retentativas Automáticas**: Resiliência integrada. Requisições que falham devido a problemas de rede ou erros temporários do servidor (`5xx`, `429`) são automaticamente retentadas com uma estratégia inteligente de `backoff`.
- **Estruturas de Dados Imutáveis e Seguras por Tipo**: Utiliza DTOs e Value Objects `readonly` para garantir a integridade dos dados e prevenir mutações acidentais de estado.
- **PHP 8.1+ Moderno**: Aproveita os recursos modernos do PHP, como `Enums`, propriedades `readonly` e atributos para uma base de código limpa e de fácil manutenção.

---

🛠️ Começando
------------

[](#️-começando)

### 1. Instalação via Composer

[](#1-instalação-via-composer)

```
composer require lucas-tonolli/asaas-php-sdk
```

> **Configuração de Plugins do Composer** > Este SDK depende do `php-http/discovery` para localizar automaticamente as implementações PSR-17 e PSR-18 disponíveis no seu projeto. Como o Composer só respeita a configuração `allow-plugins` do pacote raiz, você deve permitir explicitamente o uso deste plugin no seu `composer.json` para evitar prompts interativos ou falhas em ambientes de CI:
>
> ```
> composer config allow-plugins.php-http/discovery true
> ```
>
>
>
> Ou adicione manualmente ao seu `composer.json`:
>
> ```
> "config": {
>     "allow-plugins": {
>         "php-http/discovery": true
>     }
> }
> ```

### 2. Exemplos Rápidos

[](#2-exemplos-rápidos)

#### Criando um Cliente

[](#criando-um-cliente)

```
use AsaasPhpSdk\AsaasClient;
use AsaasPhpSdk\Config\AsaasConfig;

// Configura para o ambiente de sandbox
$config = new AsaasConfig(token: 'SUA_TOKEN_SANDBOX', isSandbox: true);

// Instancia o cliente principal
$asaas = new AsaasClient($config);

$novoCliente = $asaas->client()->create([
    'nome' => 'João Silva',
    'cpfCnpj' => '12345678901',
    'email' => 'joao@example.com',
]);

print_r($novoCliente);
```

#### Tratamento de Erros de Validação

[](#tratamento-de-erros-de-validação)

O Toolkit facilita a captura de erros específicos.

```
use AsaasPhpSdk\AsaasClient;
use AsaasPhpSdk\Config\AsaasConfig;
use AsaasPhpSdk\Exceptions\Api\ValidationException;

$config = new AsaasConfig(token: 'SUA_TOKEN_SANDBOX', isSandbox: true);
$asaas = new AsaasClient($config);

try {
    // Tenta criar um cliente com dados inválidos
    $asaas->client()->create(['nome' => 'Maria Silva']); // cpfCnpj está faltando
} catch (ValidationException $e) {
    echo "Falha na validação: " . $e->getMessage();
    // Saída: Falha na validação: O campo obrigatório 'cpfCnpj' está faltando.
}
```

---

🏛️ Visão Geral da Arquitetura
-----------------------------

[](#️-visão-geral-da-arquitetura)

O SDK segue os princípios de arquitetura limpa, separando as preocupações em camadas distintas.

- **Services**: A API pública para um recurso (ex: `CustomerService`). Este é o seu principal ponto de entrada para interagir com o SDK.
- **Actions**: "Casos de uso" internos que executam uma única operação específica (ex: `CreateCustomerAction`). Eles orquestram a criação de DTOs e as chamadas à API.
- **DTOs (Data Transfer Objects)**: Objetos estruturados, validados e imutáveis que transportam dados entre as camadas. Eles garantem que os dados são válidos antes que uma chamada à API seja feita.
- **Value Objects**: Objetos auto-validáveis e imutáveis que representam um único valor de domínio (ex: `Cpf`, `Email`, `CreditCard`). Eles garantem a consistência dos dados no nível mais baixo.
- **Exceptions**: Uma rica hierarquia de exceções personalizadas e tipadas que permitem um tratamento de erros preciso.
- **Helpers**: Classes utilitárias sem estado que lidam com preocupações transversais, como sanitização de dados (`DataSanitizer`), configuração de clientes HTTP (`HttpClientFactory`) e tratamento de respostas (`ResponseHandler`).

---

📂 Estrutura do Projeto
----------------------

[](#-estrutura-do-projeto)

```
src/
├── Actions/
│   ├── Base/
│   └── {Recurso}/
├── DTOs/
│   ├── Base/
│   └── {Recurso}/
├── Exceptions/
│   ├── Api/
│   └── DTOs/
│   └── ValueObjects/
├── Services/
│   └── Base/
├── Support/
│   ├── Helpers/
│   └── Traits/
├── ValueObjects/
│   ├── Base/
│   ├── Simple/
│   └── Structured/
├── AsaasClient.php
└── Config/

tests/
├── Unit/
└── Integration/

docs/
├── patterns/
└── workflow/

```

---

⚡ Fluxo de Desenvolvimento
--------------------------

[](#-fluxo-de-desenvolvimento)

- **Branching**: `feature/*`, `fix/*`, `docs/*`
- **Commits**: Siga o [Conventional Commits](https://www.conventionalcommits.org/)
- **Testes**: Testes de Unidade + Integração são obrigatórios para novas funcionalidades.
- **Documentação**: Atualize `/docs/patterns` para quaisquer novas convenções.

---

📖 Marcos Atuais
---------------

[](#-marcos-atuais)

- **v0.1.0** → Módulo Cliente (CRUD + Testes + Documentos) ✅
- **v0.2.0** → Módulo Pagamento (DTOs, Actions, Testes, Documentos) ✅
- **v0.3.0** → Módulo Webhook (CRUD + Documentos) ⏳
- **v0.3.0** → Refatorar documentação e padrões ✅
- **v1.0.0** → Lançamento Estável ⏳

---

📝 Notas
-------

[](#-notas)

- A cobertura da API é **parcial**; alguns endpoints ainda estão em implementação.
- DTOs e Value Objects são **imutáveis**. Sempre use seus métodos estáticos `from()` ou `fromArray()` para criar novas instâncias.

###  Health Score

28

—

LowBetter than 52% of packages

Maintenance67

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity35

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

Unknown

Total

1

Last Release

267d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d33127a761528fb27eaf471e981dd2dcdf7836e0cf401b15335679756363e0d3?d=identicon)[lucasTonolliDev](/maintainers/lucasTonolliDev)

---

Top Contributors

[![LucasTonolli](https://avatars.githubusercontent.com/u/78648345?v=4)](https://github.com/LucasTonolli "LucasTonolli (797 commits)")

---

Tags

sdkpaymentgatewaybrazilAsaas

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/lucas-tonolli-asaas-php-actions/health.svg)

```
[![Health](https://phpackages.com/badges/lucas-tonolli-asaas-php-actions/health.svg)](https://phpackages.com/packages/lucas-tonolli-asaas-php-actions)
```

###  Alternatives

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.3k543.5M2.6k](/packages/aws-aws-sdk-php)[shetabit/multipay

PHP Payment Gateway Integration Package

293361.0k4](/packages/shetabit-multipay)[checkout/checkout-sdk-php

Checkout.com SDK for PHP

563.6M13](/packages/checkout-checkout-sdk-php)[bitpay/sdk

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

42361.9k4](/packages/bitpay-sdk)[sebdesign/laravel-viva-payments

A Laravel package for integrating the Viva Payments gateway

4851.0k](/packages/sebdesign-laravel-viva-payments)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

273.0k](/packages/eslazarev-wildberries-sdk)

PHPackages © 2026

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