# cepis-telegram

Bot de Telegram para consulta de CEP, sobre a API pública da
[cep.is](https://cep.is) — base oficial dos Correios (DNE), atualizada a cada
quinzena.

Escrito em Go, usa o cliente oficial [`cep.is/go`](https://cep.is/go) e recebe
as mensagens por *long polling*: não precisa de porta aberta, de hostname
público nem de segredo de webhook.

## O que ele faz

| onde | como se usa |
| --- | --- |
| conversa privada | manda o CEP direto: `01001000` ou `01001-000` |
| grupos e canais | `/cep 01001000` — e também `/cep@seubot 01001000` |
| qualquer conversa | `@seubot 01001000` (modo inline, sem precisar adicionar o bot) |

Também responde `/start` e `/help`.

A resposta traz o endereço formatado e, quando o CEP tem coordenada, distingue
os dois casos: com precisão de logradouro sai um link de mapa; quando o CEP é
geral do município, sai um aviso com o raio da área em vez de um pino, porque o
ponto é o centroide da cidade e pode errar dezenas de quilómetros.

## Quando o CEP não existe

Um CEP que falha quase nunca é um número aleatório — é alguém que sabe a cidade
e chutou o resto, quase sempre no `-000` que 957 municípios nunca receberam.
Dizer só "não encontrei" desperdiça a viagem, então o bot diz de que cidade o
número seria:

```
🔍 CEP não encontrado na base dos Correios (DNE).
Ele cairia em Areal/RJ, que tem 118 CEPs, de 25845-001 a 25849-899.
A faixa é esparsa: nem todo número entre os dois é um CEP válido.
Confira os oito dígitos — a base é atualizada a cada quinze dias.
```

Continua sendo um erro, e a resposta é escrita para não ser confundida com um
acerto: não é um endereço, e os dois extremos não são uma lista de CEPs
válidos — os 118 de Areal estão espalhados por quase cinco mil números, que é
para isso que a contagem vai junto. O bot também nunca sugere um CEP de dentro
da faixa.

A cidade vem no próprio 404 da API, no objeto `faixa`. Quando o CEP cai num
intervalo que os Correios não deram a município nenhum, o objeto não vem e a
resposta é a de sempre, sem a linha do meio.

Não custa requisição nenhuma a mais: quem lê o objeto é o `cep.is/go` v0.2.0,
em `Error.Faixa`. Faixa ausente ou sem município cai de volta na resposta de
sempre.

## Criando o bot

O username e o token são criados por você no
[@BotFather](https://t.me/BotFather) e pertencem a você — este repositório não
contém nem nunca deve conter um token.

1. `/newbot` no @BotFather, escolha nome e username. Guarde o token.
2. `/setinline` no @BotFather, para o mesmo bot, com um texto de placeholder
   (por exemplo `01001000`). Sem isso o modo inline fica desligado.
3. Opcional, `/setcommands`:

   ```
   cep - consulta um CEP
   help - como usar
   ```

O *privacy mode* pode continuar ligado (é o padrão). Em grupos o bot só recebe
os comandos endereçados a ele, que é exatamente o que ele precisa.

## Rodando

```sh
export TELEGRAM_BOT_TOKEN=... # o token do @BotFather
make build
./bin/cepis-telegram
```

Em container:

```sh
docker build -t cepis-telegram .
docker run --rm -e TELEGRAM_BOT_TOKEN=... cepis-telegram
```

Só uma instância por token: o Telegram entrega cada update uma única vez, e dois
processos com o mesmo token disputam os mesmos updates.

## Configuração

Tudo vem do ambiente.

| variável | padrão | o que faz |
| --- | --- | --- |
| `TELEGRAM_BOT_TOKEN` | — | obrigatória; o processo aborta na partida sem ela |
| `CEPIS_BASE_URL` | `https://cep.is` | aponta as consultas para outra instância da API |
| `TELEGRAM_API_BASE_URL` | `https://api.telegram.org` | aponta o bot para outro host da Bot API |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn` ou `error` |

Os logs saem em JSON no stdout. O token nunca aparece neles, e o conteúdo das
mensagens dos usuários não é registrado.

Há um limite por usuário de 5 consultas em rajada e uma a cada 3 segundos
depois disso.

## Desenvolvimento

```sh
make            # lista os alvos
make test       # sobe um Telegram falso e uma cep.is falsa, em processo
make lint       # gofmt -l + go vet, não escreve nada
make format     # aplica o gofmt
make check      # lint + test + build
```

Para testar contra uma cep.is local (o repositório da API sobe uma com
`just up`):

```sh
CEPIS_BASE_URL=http://localhost:8080 TELEGRAM_BOT_TOKEN=... ./bin/cepis-telegram
```

## Licença

ISC. Veja [LICENSE](LICENSE).