Integrações de CEP e pagamentos

CEP: ViaCEP

CepService::buscar($cep) delega a CepGatewayInterface::consultar(). O gateway ViaCEP existe no código e usa ApiClient; porém seu construtor passa o argumento nomeado <code>timeout</code>, enquanto ApiClient declara <code>defaultTimeout</code>. Em PHP 8 isso lança erro de argumento nomeado desconhecido antes da chamada HTTP. Normaliza para cep, logradouro, bairro, cidade, uf; CEP inválido/não encontrado/falha retorna null. Configuração CEP_PROVIDER existe, mas o match atual usa ViaCEP como default para todos os valores.

$address = (new CepService())->buscar('01001-000');
if ($address === null) {
    // CEP inválido, indisponível ou não encontrado
}

Pagamentos: apenas contrato e null object

PaymentService expõe charge(), status() e cancel(); contrato PaymentGatewayInterface define create/get/cancel. A classe concreta disponível é NullPaymentGateway e o provider resolvido cai nela. Configurações de chaves Mercado Pago/Asaas aparecem em config/api.php, porém não há gateways concretos correspondentes no código recebido.

Não use esta base como integração de cobrança pronta. Para integrar, implemente gateway, trate credenciais/webhooks idempotentes e altere o resolver. A documentação não presume que pagamentos funcionem por existir uma variável de ambiente.

ViaCEP · o service normaliza o provedor externo

Controller/Service de domínio deve consumir CepService, não conhecer URL e JSON específicos do ViaCEP. A implementação atual remove/separa a integração por interface e normaliza para cep/logradouro/bairro/cidade/uf. `buscar()` retorna array ou null em CEP inválido, ausente ou falha externa; trate null como resultado possível.

$address = (new \App\Services\Integrations\Cep\CepService())
    ->buscar('01001-000');

if ($address === null) {
    // Solicite outro CEP ou apresente indisponibilidade.
} else {
    $cidade = $address['cidade'];
}

ApiClient usa timeout de 10 s no gateway ViaCEP. CEP_PROVIDER aparece em config, porém o resolver disponível atualmente cai no gateway ViaCEP para todos os valores; trocar a variável não instala outros provedores.

Pagamentos · contrato não equivale a integração

PaymentGatewayInterface define createPayment/getPayment/cancelPayment e PaymentService oferece charge/status/cancel. O único gateway concreto enviado é NullPaymentGateway, que não processa cobranças reais. Credenciais Mercado Pago/Asaas em config/api.php são configurações previstas, não implementações.

Não use esta base para cobrar clientes. Uma integração real exige implementação concreta, credenciais apropriadas, tratamento de falha, validação de assinatura de webhook e idempotência — itens que não estão prontos no código analisado.

Compatibilidade atual do gateway ViaCEP

Incompatibilidade no código recebido: ViaCepGateway::__construct() chama new ApiClient(..., timeout: 10), mas a assinatura de ApiClient nomeia o parâmetro defaultTimeout. Em PHP 8, esse argumento nomeado desconhecido lança Error ao construir o gateway; o fluxo não chega à requisição HTTP. A correção exigiria alteração do framework/aplicação, fora do escopo desta documentação.

A página documenta o desenho pretendido e os contratos das classes, mas não apresenta a chamada como fluxo funcional na versão recebida. O valor de configuração CEP_PROVIDER não corrige a incompatibilidade do construtor.

PaymentService e gateway nulo são simulação

Contrato público: __construct(?PaymentGatewayInterface $gateway = null), charge(array $data): array, status(string $id): array e cancel(string $id): bool. O gateway nulo retorna exatamente ['id' => 'null_' . bin2hex(random_bytes(8)), 'status' => 'simulado', 'amount' => $data['amount'] ?? 0]; o ID contém 16 caracteres hexadecimais. Consulta devolve ['id' => $id, 'status' => 'simulado']; cancelamento devolve true incondicionalmente. Ele não chama provedor, não confirma a existência do ID e não representa cobrança real.

charge() captura qualquer Throwable do gateway e converte para falha do Service com código 422. Trate a resposta como demonstração local e não apresente sucesso de NullPaymentGateway como liquidação ou autorização financeira.