Manual do conector-cep-endereco

Identificação

Item	Valor
Conector	`conector-cep-endereco`
Destino SISC	`conector__conector-cep-endereco`
Catálogo modular	`web-api/catalogo-conector-cep-endereco.json`
Mensagem principal	`conector-cep-endereco.buscar`
Formato	`conectores/conector-cep-endereco/formatos/formato-conector-cep-endereco.json`

Objetivo

O conector-cep-endereco recebe dados de endereço brasileiro e retorna o CEP mais provável. Ele foi criado para consumidores SISC que precisam transformar um endereço textual em um CEP, mantendo o padrão de comunicação por mensagem catalogada. O consumidor não chama a implementação interna do conector. O consumidor publica uma mensagem JSON com idmensagem conhecido, dados em payload.dados ou no campo dados da API externa, e aguarda a resposta registrada pelo SISC conforme o modo de uso disponível no ambiente.

O serviço externo usado é o ViaCEP público. A consulta é somente leitura, não grava informações no serviço externo, não altera dados cadastrais, não envia email, não cobra valores e não depende de credencial para a operação documentada.

Operações

Operação	idmensagem	Campos principais	Descrição
`buscar-cep`	`conector-cep-endereco.buscar`	`endereco` ou `uf` + `cidade` + `logradouro`	Consulta CEP provável para o endereço informado.
`consultar-cep`	`conector-cep-endereco.buscar`	Mesmos campos da operação principal	Alias compatível para consumidores que preferem o verbo consultar.

Payload de entrada

Os dados devem ser enviados em payload.dados quando a mensagem completa for montada, ou em dados quando o consumidor usa a API HTTP externa do SISC. Em ambos os casos, o conteúdo lógico é o mesmo.

Campo	Tipo	Obrigatório	Descrição
`operacao`	string	não	Use `buscar-cep` ou `consultar-cep`. Se ausente, o conector assume `buscar-cep`.
`endereco`	string	alternativo	Endereço em texto livre, preferencialmente no formato `logradouro, cidade - UF`.
`uf`	string	alternativo	Sigla do estado com duas letras, por exemplo `SP`.
`cidade`	string	alternativo	Nome do município.
`logradouro`	string	alternativo	Rua, avenida, praça ou outro logradouro.
`bairro`	string	não	Campo de apoio para consumidores; pode ser usado para conferência quando houver múltiplos candidatos.
`numero`	string	não	Número do imóvel. O ViaCEP por endereço normalmente não usa número, mas o consumidor pode manter o dado para auditoria.

Exemplo de payload simples

{
  "operacao": "buscar-cep",
  "endereco": "Praça da Sé, São Paulo - SP"
}

Exemplo de mensagem SISC completa

{
  "_protocolo": {
    "origem": "sistema__cliente-exemplo",
    "destino": "conector__conector-cep-endereco",
    "idmensagem": "conector-cep-endereco.buscar",
    "idempotencia": {
      "chave": "cep-praca-se-sp-001",
      "escopo": "conector-cep-endereco.buscar"
    }
  },
  "payload": {
    "dados": {
      "operacao": "buscar-cep",
      "endereco": "Praça da Sé, São Paulo - SP"
    }
  }
}

Exemplo de chamada de consumidor externo

O programa consumidor de exemplo recebe parâmetros locais para montar o JSON catalogado. Esses argumentos não são o protocolo SISC; eles apenas alimentam o exemplo. A comunicação oficial é a requisição HTTP com JSON contendo idmensagem, origem, dados, modo de execução e idempotencia. O token deve ir no cabeçalho HTTP Authorization, nunca dentro de payload.dados.

php conectores/conector-cep-endereco/exemplos/exemplo-cliente.php \
  --url="https://servidor/sisc/sistema/conexao-externo/api.php" \
  --token="token-do-cliente" \
  --origem="sistema__cliente-exemplo" \
  --endereco="Praça da Sé, São Paulo - SP"

Saída esperada

A saída do conector é JSON. Em caso de sucesso, o campo cep apresenta o primeiro candidato retornado pelo ViaCEP. A lista completa de candidatos pode ser usada por consumidores que precisam validar bairro, logradouro ou cidade.

{
  "sucesso": true,
  "conector": "conector-cep-endereco",
  "operacao": "buscar-cep",
  "cep": "01001-000",
  "fonte": "viacep",
  "consulta": {
    "endereco": "Praça da Sé, São Paulo - SP",
    "uf": "SP",
    "cidade": "São Paulo",
    "logradouro": "Praça da Sé"
  },
  "candidatos": [
    {
      "cep": "01001-000",
      "logradouro": "Praça da Sé",
      "bairro": "Sé",
      "localidade": "São Paulo",
      "uf": "SP"
    }
  ]
}

Programa de exemplo

O pacote traz dois exemplos. O primeiro é conectores/conector-cep-endereco/exemplos/exemplo-uso.php, que mostra como montar o payload e a mensagem SISC. O segundo é conectores/conector-cep-endereco/exemplos/exemplo-cliente.php, um consumidor portátil que pode ser copiado para a máquina do cliente e executar chamada HTTP contra a API pública do SISC.

php conectores/conector-cep-endereco/exemplos/exemplo-uso.php
php conectores/conector-cep-endereco/exemplos/exemplo-uso.php --self-test
php conectores/conector-cep-endereco/exemplos/exemplo-cliente.php --self-test

Credenciais

Nenhuma credencial externa é necessária para o ViaCEP público. O consumidor precisa apenas de credencial de acesso ao SISC, fornecida pelo operador do ambiente. Essa credencial é usada para autenticar o transporte HTTP e não pertence ao payload do conector.

Não envie senha, token, cookie, certificado privado ou qualquer segredo em payload.dados. Caso uma implantação futura use outro provedor de CEP com credenciais, o operador deve configurar o segredo no ambiente do SISC e o pacote deve conter apenas arquivo .sample.json de documentação.

Erros comuns

Erro	Causa provável	Ação recomendada
`operacao invalida`	O campo `operacao` não é aceito.	Use `buscar-cep` ou `consultar-cep`.
`informe endereco...`	O payload não trouxe endereço suficiente.	Informe `endereco` no formato recomendado ou envie `uf`, `cidade` e `logradouro`.
`falha ao consultar ViaCEP`	Indisponibilidade de rede, timeout ou bloqueio temporário.	Tente novamente com idempotência adequada e trate indisponibilidade no consumidor.
`cep null`	Nenhum candidato retornado.	Revise grafia, acentos, cidade, UF e logradouro.

Limites

Item	Limite ou comportamento
Timeout	A chamada externa usa timeout curto para evitar travamento de execução.
Precisão	Endereços genéricos podem retornar múltiplos candidatos. O consumidor deve conferir bairro e cidade.
Rate limit	O ViaCEP é público; consumidores devem evitar volume abusivo e aplicar cache quando necessário.
Dados pessoais	Evite enviar complemento, nome de morador ou dados sensíveis. Para CEP, logradouro/cidade/UF costumam ser suficientes.

Segurança de uso

O conector preserva a separação entre transporte, autenticação e dados de negócio. O token do SISC autentica a requisição HTTP e deve ser tratado como segredo pelo consumidor. O campo payload.dados deve conter somente dados necessários à busca de CEP. A idempotencia é obrigatória para reduzir duplicidade de chamadas e facilitar auditoria. Consumidores devem gerar chaves idempotentes por tentativa lógica, não por repetição cega.

Boas práticas para consumidores

Consulte o catálogo antes de montar integrações automatizadas.
Use idmensagem=conector-cep-endereco.buscar exatamente como declarado.
Trate resposta sem candidato como resultado possível, não como falha fatal do sistema.
Registre a origem sistema__... de forma estável para auditoria.
Não faça scraping nem chame o handler diretamente; use sempre a API/mensagem SISC.
Implemente cache de resultados quando o mesmo endereço for consultado repetidamente.

Fluxo GitHub, segurança e sandbox

Procedimento atual: o programador clona git@github.com:jrcostarrear/gitprog.git em qualquer diretório da própria máquina; o conteúdo baixado traz o necessário para produzir, validar e enviar o conector ao SISC. Handlers devem ficar em conectores/<nome>/handlers/, sem link simbólico, com execução direta e caminho relativo seguro. No servidor, pacotes externos só entram no SISC real depois de selo-validacao e selo-sandbox válidos para o SHA256 exato.