PHPAY-83: adicionar o gateway Cielo (API E-commerce 3.0)

[mariolucasdev]

Closes #83

Sexto gateway, e a primeira adquirente da biblioteca. A Cielo lidera o mercado por número de usuários (28%, ~30% no varejo).

Capacidades: 2 de 5

Capacidade	Declara?	Motivo
SupportsCharges	✅	POST /1/sales, captura, cancelamento
SupportsSubscriptions	✅	Recorrência via /1/RecurrentPayment
SupportsCustomers	❌	Não há recurso de cliente — ele é um campo da venda
SupportsWebhooks	❌	Notificação configurada no backoffice ou por transação
SupportsPixKeys	❌	Pix é tipo de pagamento da venda

É a forma mais estreita depois do Efí, e é a esperada para uma adquirente. Adquirente autoriza e captura transação; cadastro de cliente e cobrança recorrente rica são domínio de gateway.

A particularidade que mexeu no código

A Cielo separa dois hosts por tipo de operação, não por domínio:

Operação	Sandbox
Escrita	apisandbox.cieloecommerce.cielo.com.br
Consulta	apiquerysandbox.cieloecommerce.cielo.com.br

O PagBank também tem dois hosts, mas divididos por domínio (pedidos vs assinaturas) — lá cada recurso boota um client. Aqui o mesmo recurso precisa dos dois: create() vai num, find() no outro.

Por isso HasHttpClient::request() passa a aceitar um client opcional em vez de usar sempre $this->client. Mudança retrocompatível — nenhum gateway existente foi tocado — e o trait da Cielo a usa em queryGet(). Quem consome a biblioteca não vê diferença: o roteamento é interno.

Há teste verificando que find() não encosta no host de escrita.

Outras decisões de modelagem

A recorrência não tem endpoint de criação. Ela nasce de uma venda carregando um bloco RecurrentPayment, e só então ganha um RecurrentPaymentId próprio para ser gerenciada. O recurso Subscription expressa isso em vez de fingir um create() direto:

$recorrencia = $phpay->subscription()
    ->setCustomer(['Name' => 'Mário Lucas'])
    ->setCard($cartao)
    ->setInterval(RecurrentIntervalEnum::MONTHLY)
    ->create(15700);   // vai para POST /1/sales

Os updates da recorrência recebem JSON puro, não objeto: PUT .../Amount com corpo 19900, PUT .../Interval com corpo "Monthly". Daí o putValue() privado, e um teste que assevera o corpo exato.

Valores em centavos inteiros, recusados na validação se vierem decimais.

Header RequestId como chave de idempotência, gerado por chamada e fixável com setRequestId().

Recursos

• Charge — setOrderId, setCustomer, setPix, setBoleto, setCreditCard, setRequestId, create, find, findByOrderId, getStatus, getPixCode, capture, cancel
• Subscription — setCard, setInterval, setEndDate, create, find, deactivate, reactivate, updateAmount, updateInterval, updateEndDate, updateNextPaymentDate

Verificação

179 testes (463 asserções), PHPStan nível 9 limpo, Pint limpo. Endpoints, hosts, autenticação e o modelo de recorrência foram conferidos na documentação oficial da Cielo.

O sandbox dela é self-service — o cadastro devolve MerchantId e MerchantKey sem exigir afiliação comercial, o que é incomum para adquirente e torna viável testar de verdade.