README

SDK PHP agnóstico de framework para a API do Mercado Pago. Fornece recursos para Clientes, Cartões e Pagamentos (Pix e Cartão de Crédito), com objetos de resposta tipados (DTOs), tratamento de erros com exceções customizadas e suíte de testes baseada em mocks.

Requisitos mínimos: PHP >= 8.1

Instalação

Via Composer:

composer require integrad/mercadopago-sdk

Configuração

1. Crie um arquivo .env baseado no examples/.env.example:

cp examples/.env.example .env

1. Edite o .env e preencha o seu token de acesso:

MERCADOPAGO_TOKEN=SEU_ACCESS_TOKEN_AQUI

1. Carregue o autoload do Composer e (opcionalmente) use vlucas/phpdotenv nos exemplos e testes.

Uso Básico

Instanciando um recurso

use Integrad\MercadoPagoSDK\Customers;

$customers = new Customers($_ENV['MERCADOPAGO_TOKEN']);

Criar um cliente

$customer = $customers->create([
    'email' => 'john.doe@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
]);

echo $customer->getFullName(); // "John Doe"

// Atualizar (objeto ativo)
$customer = $customer->update(['first_name' => 'Johnny']);

Listar cartões de um cliente

use Integrad\MercadoPagoSDK\Cards;

$cards = new Cards($_ENV['MERCADOPAGO_TOKEN']);
$list = $cards->listAll('CUSTOMER_ID');

foreach ($list as $card) {
    echo $card->getMaskedNumber();
}

Criar um pagamento Pix

use Integrad\MercadoPagoSDK\Payments;

$payments = new Payments($_ENV['MERCADOPAGO_TOKEN']);
$payment = $payments->createPix([
    'transaction_amount' => 25.90,
    'description' => 'Order #123',
    'payer' => ['email' => 'buyer@example.com']
]);

// Renderizar QR Code
echo $payment->getPixQrCodeAsHtmlImage(['alt' => 'Pix QR Code']);

Criar um pagamento com Cartão de Crédito

$payment = $payments->createWithCard([
    'token' => 'CARD_TOKEN_FROM_FRONTEND',
    'transaction_amount' => 99.90,
    'installments' => 1,
    'payer' => ['email' => 'buyer@example.com']
]);

if ($payment->isApproved()) {
    echo 'Pagamento aprovado!';
}

Tratamento de Erros

Todos os erros HTTP são convertidos para exceções específicas que herdam de MercadoPagoException:

• InvalidRequestException (400)
• AuthenticationException (401/403)
• NotFoundException (404)
• ServerException (5xx)

Exemplo:

use Integrad\MercadoPagoSDK\Exceptions\MercadoPagoException;

try {
    $customer = $customers->create(['email' => 'invalid']);
} catch (MercadoPagoException $e) {
    // Log, tratar e exibir mensagem amigável
    error_log($e->getMessage());
    $context = $e->getResponseBody(); // corpo JSON de erro (se disponível)
}

Testes Automatizados

Este projeto utiliza Pest e mocks do Guzzle para evitar chamadas reais à API.

• Rodar a suíte:

composer test

Os testes cobrem os métodos públicos dos recursos e validam mapeamento para DTOs e lançamento de exceções customizadas.

Estrutura

• src/Client.php: cliente base com Guzzle e mapeamento de exceções.
• src/Customers.php, src/Cards.php, src/Payments.php: classes de recurso.
• src/Responses/*: DTOs (imutáveis) para respostas de API, com helpers úteis.
• src/Exceptions/*: hierarquia de exceções customizadas.
• tests/: suíte de testes com Pest e mocks do Guzzle.
• examples/: scripts de exemplo para uso local.

Observações

• SDK agnóstico de framework (sem dependências de Laravel, Symfony etc.).
• Segue PSR-12 e boas práticas de SOLID na arquitetura.