feat(http): retry seguro de POST + idempotência por externalId (release v3.2.0)

[andrenfe]

Objetivo

Tornar o retry seguro por default e habilitar emissão idempotente de NFS-e, eliminando o risco de nota fiscal duplicada e o contorno de manter dois Nfe\Client (um sem retry para escrita, outro com retry para leitura).

Origem: proposta da integração WooCommerce (woo-nfe). OpenSpec change: add-safe-retry-idempotency.

O que muda

• Retry ciente de método (Nfe\Http\RetryingTransport):

  Método	429	5xx	conexão não estabelecida	ambíguo/não-classificado
  GET/PUT/DELETE/HEAD/OPTIONS	retenta	retenta	retenta	retenta
  POST	retenta	não	retenta	não
  POST + header Idempotency-Key	retenta	retenta	retenta	retenta

• Fase da falha estruturada — Nfe\Http\FailurePhase (ConnectionNotEstablished/RequestMaybeSent) + ApiConnectionException->failurePhase/->curlErrno. CurlTransport classifica por errno (allowlist 5/6/7/35); Psr18Transport por NetworkExceptionInterface.

• Override de retry por chamada — RequestOptions->retry (?RetryPolicy, 4º parâmetro). Liga/desliga o retry de uma única chamada nos dois sentidos; o decorator de retry passa a envolver sempre o transporte base.

• Reconciliação por externalId (NFS-e) — ServiceInvoicesResource::findByExternalId() (rota dedicada GET /v1/companies/{id}/serviceinvoices/external/{externalId}, contrato de coleção do fio) + isDuplicateExternalId() estático; campo externalId no DTO ServiceInvoice (anexado ao fim do construtor — puramente aditivo).

⚠️ Mudança de comportamento (safety fix, minor)

POST deixa de retentar em 5xx (e em timeout ambíguo). Reexecutar um POST pode duplicar uma NFS-e. Rota de escape: enviar externalId e reconciliar com findByExternalId() após falha ambígua; ou RequestOptions(retry: ...) por chamada.

Ciclo de emissão idempotente

try {
    $r = $nfe->serviceInvoices->create($companyId, $data + ['externalId' => $pedidoId]);
} catch (ApiErrorException $e) {
    if (ServiceInvoicesResource::isDuplicateExternalId($e) || $e instanceof ServerException) {
        $r = $nfe->serviceInvoices->findByExternalId($companyId, $pedidoId); // null = não criada, seguro reemitir
    } else { throw $e; }
}

Validação ao vivo (2026-07-06)

Sonda contra a API real reproduziu o cenário-alvo: um create() retornou HTTP 500 e mesmo assim criou a nota (Issued) — exatamente o 5xx ambíguo que, com o retry antigo, teria duplicado a NFS-e. Também confirmados: Idempotency-Key ignorado pela API; externalId como chave única (400 "already exists"); a rota /external (contrato de coleção, miss = 200 lista vazia).

Qualidade

• 215 testes verdes (novos: matriz de retry por método/fase, classificação cURL/PSR-18, override por chamada, reconciliação/duplicata), em PHP 8.2 e 8.4.
• PHPStan e php-cs-fixer limpos.
• Docs atualizadas (docs/configuration.md, cookbook NFS-e) e CHANGELOG.md ([Unreleased]).

Release v3.2.0 (corte no PR)

Seguindo o padrão do v3.1.0 (be00f2d), o corte é feito neste PR:

• src/Version.php::CURRENT → 3.2.0 (fonte canônica; o CI valida tag↔Version.php).
• CHANGELOG.md: [Unreleased] promovida para [3.2.0] — 2026-07-06.
• VERSION (arquivo órfão legado): corrigido 3.0.0-dev → 3.2.0. Nada no pipeline o lê
  (a versão canônica é src/Version.php); estava defasado desde o rewrite v3. Follow-up:
  remover o arquivo ou ensinar o release.sh a bumpá-lo, para não voltar a driftar.

🏷️ Tag v3.2.0 somente após o merge (master protegida). ⚠️ Como o CHANGELOG já foi
promovido aqui, não rodar a promoção do release.sh de novo pós-merge (duplicaria a seção);
apenas criar/pushar a tag.

SemVer

Minor (v3.2.0). Tudo aditivo; a mudança de default do POST é defendida como correção de
segurança. externalId foi anexado ao fim do construtor do DTO para ser aditivo mesmo sob
a política estrita de "construtor é contrato".

Fora deste PR (rastreio)

• Pedidos ao time da API: honrar Idempotency-Key; 503→404 para company inexistente; error code estruturado na duplicata; alinhar o YAML de /external ao fio (envelope de coleção).
• Descobertas ortogonais em aberto (não bloqueiam este PR): DTO ServiceInvoice cobre poucos campos do fio e o codegen ignora specs com schemas inline.

🏷️ Tag v3.2.0 somente após o merge (política de master protegida).