---
name: NFSe cMun do tomador resolvido por CEP com cache
description: Como NfseNacionalApi descobre codigo IBGE do tomador para o XML SEFIN, com fallback chain e cache no cadastro do cliente
type: project
originSessionId: c010475f-ff9d-400a-9abf-0c6844cef5c7
---
# NFSe — resolucao do `cMun` do tomador (cliente)

A SEFIN rejeita NFSe com erro **E0240** quando `<cMun>` no endereco do tomador nao corresponde ao municipio do CEP. Em 21/03/2026 a nota 55 (Juliana Maria Raia, CEP 31720-490 / BH) foi rejeitada porque o XML mandou `cMun=3154606` (Ribeirao das Neves, prestador) em vez de `3106200` (BH, tomador).

## Como funciona depois do fix (2026-04-28)

`NfseNacionalApi::resolverCodigoMunicipioCliente(array $cliente)`:

1. **Cache no cadastro**: le `cliente['codigo_ibge']` (coluna `clientes.codigo_ibge` CHAR(7)). Se preenchido com 7 digitos, retorna direto.
2. **ViaCEP**: timeout 10s, connect timeout 5s, SSL_VERIFYPEER true. Le campo `ibge`.
3. **BrasilAPI** (fallback): `https://brasilapi.com.br/api/cep/v2/{cep}`, le `city_ibge`.
4. **Persiste cache**: ao resolver com sucesso, faz `UPDATE clientes SET codigo_ibge = ? WHERE id = ?` para evitar consulta em proximas emissoes.
5. **Throw `RuntimeException`** se nada funcionar — emissao para em vez de mandar dado errado.

## NUNCA cair pro municipio do prestador

O bug original era cair em `$config['codigo_municipio'] ?? '3154606'` quando ViaCEP falhava. Isso foi removido — preferir falhar emissao a emitir nota com cMun errado.

## Endpoint de reemissao silenciosa

`GET /nfse/reemitir-diagnostico/{id}?token=58253c6b...`

- Token guarded (mesmo `CRON_TOKEN_SECRETO` do `cancelarDiagnostico`)
- Marca nota original como `cancelada` com motivo registrado
- Reemite com mesmos dados (cliente, valor, descricao, contrato/boleto)
- **Suprime notificacoes** (`processarEmissao` recebe `notificarCliente=false`)
- Excluido do AuthMiddleware em `app/Config/Filters.php`

## Quando usar

- Nota com status `erro` ou `rejeitada` por dado fixavel (CEP/cMun, descricao, etc.)
- Quando NAO quiser que o cliente receba WhatsApp/email da reemissao

## Onde

- `app/Libraries/NfseNacionalApi.php` — funcoes `resolverCodigoMunicipioCliente`, `buscarIbgePorCep`, `cepViaCep`, `cepBrasilApi`
- `app/Controllers/Nfse.php` — `processarEmissao(bool $notificarCliente = true)` e `reemitirDiagnostico($id)`
- `app/Models/ClienteModel.php` — `codigo_ibge` no `allowedFields`
- `app/Config/Routes.php` linha ~599 — rota `nfse/reemitir-diagnostico`
- `app/Config/Filters.php` — exclusao de auth