Identificação — conector-tabela-fipe

O conector-tabela-fipe consulta preços de veículos na Tabela FIPE (Fundação Instituto de Pesquisas Econômicas) para carros, motos e caminhões. Ele roda no destino SISC conector__conector-tabela-fipe e é descrito pelo catalogo siscconectores/web-api/catalogo-conector-tabela-fipe.json.

Conector: conector-tabela-fipe (versão 1.0.0)
Destino SISC: conector__conector-tabela-fipe
Catálogo: catalogo-conector-tabela-fipe (5 mensagens ativas)
Tipo: somente leitura, sem efeitos externos

Objetivo

Permitir que qualquer consumidor do barramento descubra marcas, modelos, anos e o preço final de um veículo na Tabela FIPE a partir de códigos simples. O fluxo típico é encadeado: marcas → modelos → anos → valor. Todas as respostas chegam em payload.dados de mensagens publicadas via api.php, preservando processoId e respostaA para correlação e idempotencia da conversa.

Operações

Operação	idmensagem	Campos principais	Descrição
consultar-tabela-referencia	`conector-tabela-fipe.consultar-tabela-referencia`	nenhum	Retorna o mês de referência corrente (a API usa sempre a tabela mais recente).
consultar-marcas	`conector-tabela-fipe.consultar-marcas`	codigoTipoVeiculo	Lista marcas (Value=código, Label=nome) por tipo de veículo.
consultar-modelos	`conector-tabela-fipe.consultar-modelos`	codigoTipoVeiculo, codigoMarca	Lista modelos e anos de uma marca.
consultar-anos	`conector-tabela-fipe.consultar-anos`	codigoTipoVeiculo, codigoMarca, codigoModelo	Lista anos disponíveis de um modelo (Value no formato AAAA-C).
consultar-valor	`conector-tabela-fipe.consultar-valor`	codigoTipoVeiculo, codigoMarca, codigoModelo, codigoModeloAno	Retorna o preço FIPE final do veículo.

Cada operação viaja como idmensagem próprio no catalogo do conector-tabela-fipe, sempre com destino SISC conector__conector-tabela-fipe.

Payload de entrada

Toda chamada usa o envelope SISC com payload.idmensagem e payload.dados. Os campos de payload.dados por operação:

Campo	Tipo	Obrigatório	Descrição
operacao	string	sim	Uma das 5 operações da tabela acima.
codigoTipoVeiculo	integer	sim*	1=Carros, 2=Motos, 3=Caminhões. *Exceto em consultar-tabela-referencia.
codigoMarca	integer	modelos/anos/valor	Código da marca (campo Value de consultar-marcas).
codigoModelo	integer	anos/valor	Código do modelo (campo Value de consultar-modelos).
codigoModeloAno	string	valor	Ano-modelo no formato AAAA-C, ex: 2020-1 (gasolina), 2020-2 (álcool), 2020-3 (diesel). Vem do campo Value de consultar-anos.

Idempotencia: repita a mesma chamada com a mesma chave de idempotencia do protocolo para obter o mesmo resultado sem efeitos duplicados; o conector é só leitura, então reenvios são sempre seguros.

Exemplo — payload simples

{
  "operacao": "consultar-marcas",
  "codigoTipoVeiculo": 1
}

Exemplo — mensagem SISC completa

{
  "_sistema": {"ambiente": "producao", "criadoPara": "conector-tabela-fipe"},
  "_protocolo": {
    "nome": "siscore-protocolo-objetos",
    "versao": 1,
    "tipo": "consulta",
    "prioridade": "normal",
    "origem": "sistema__minha-aplicacao",
    "destino": "conector__conector-tabela-fipe",
    "idempotencia": {"chave": "fipe-marcas-carros-001", "escopo": "conector-tabela-fipe.consultar-marcas"}
  },
  "payload": {
    "idmensagem": "conector-tabela-fipe.consultar-marcas",
    "dados": {"operacao": "consultar-marcas", "codigoTipoVeiculo": 1}
  }
}

Exemplo — fluxo até o preço

-- 1. marcas de carros -------------------------------------------
{"operacao": "consultar-marcas", "codigoTipoVeiculo": 1}
-- 2. modelos da marca 21 (Fiat) ------------------------------------
{"operacao": "consultar-modelos", "codigoTipoVeiculo": 1, "codigoMarca": 21}
-- 3. anos do modelo 437 --------------------------------------------
{"operacao": "consultar-anos", "codigoTipoVeiculo": 1, "codigoMarca": 21, "codigoModelo": 437}
-- 4. valor final ----------------------------------------------------
{"operacao": "consultar-valor", "codigoTipoVeiculo": 1, "codigoMarca": 21,
 "codigoModelo": 437, "codigoModeloAno": "1987-1"}

Saída esperada

Resposta de consultar-valor (campos em dados da mensagem de retorno):

{
  "sucesso": true,
  "Valor": "R$ 6.136,00",
  "CodigoFipe": "001124-0",
  "Marca": "Fiat",
  "Modelo": "147 C/ CL",
  "AnoModelo": 1987,
  "Combustivel": "Gasolina",
  "MesReferencia": "setembro de 2026",
  "SiglaCombustivel": "G"
}

Resposta de erro segue o mesmo envelope com sucesso: false, erro e codigoErro.

Programa de exemplo

O pacote inclui siscconectores/conector-tabela-fipe-uso.php, que monta um payload.dados realista com o idmensagem conector-tabela-fipe.consultar-valor e documenta a saída esperada, e siscconectores/conector-tabela-fipe-cliente.php, que demonstra o consumo via biblioteca cliente (método de envio com idmensagem e dados). Ambos respondem a --self-test com JSON contendo sucesso, conector, idmensagem, payload.dados e saidaEsperada.

Credenciais

Nenhuma credencial é exigida: a fonte de dados é uma API pública de leitura. O pacote traz apenas siscconectores/secretos/conector-tabela-fipe.sample.json como modelo de configuração (baseUrl e timeouts). Nunca envie segredos reais; o operador cria o arquivo real somente no servidor, se um dia for necessário.

Erros comuns

Erro / códigoErro	Causa provável	Ação recomendada
PARAM_OBRIGATORIO	Faltou campo obrigatório em payload.dados.	Confira a tabela de Payload de entrada e reenvie completo.
PARAM_INVALIDO	códigoTipoVeiculo fora de 1-3 ou codigoModeloAno malformado.	Use 1/2/3 e o Value exato retornado por consultar-anos.
OPERACAO_INVALIDA	operacao diferente das 5 documentadas.	Corrija para uma operação da tabela Operações.
NAO_ENCONTRADO	Combinação marca/modelo/ano inexistente na FIPE.	Refaça o encadeamento marcas → modelos → anos.
VAZIO	API retornou lista vazia.	Tente outro código ou mês de referência.
TIMEOUT / HTTP_5XX	Instabilidade momentânea da fonte pública.	Aguarde e repita com a mesma chave de idempotencia.

Limites

Timeout de 20 segundos por consulta; em caso de estouro, repita a chamada.
A fonte pública pode aplicar rate limit em rajadas; espace chamadas em lote.
Os preços refletem a tabela FIPE mais recente; não há consulta a meses antigos.
Valores são referenciais de mercado e podem variar por região e estado do veículo.

Segurança de uso

O conector só lê dados públicos; não envie dados sensíveis (documentos, senhas) em payload.dados.
Autentique suas chamadas ao barramento com seu próprio token de cliente; tokens nunca transitam no HTML.
Use chaves de idempotencia distintas por intenção de consulta para evitar confusão de correlação.
Valide os códigos recebidos (Value/Label) antes de encadear a próxima chamada.

Boas práticas

Armazene em cache as tabelas de marcas/modelos/anos e só reconsulte valores no momento da precificação.
Sempre parta do Value retornado pela etapa anterior em vez de digitar códigos manualmente.
Trate sucesso: false exibindo erro e sugerindo a correção da tabela Erros comuns.
Registre MesReferencia junto ao preço exibido ao usuário final.
Para frotas, processe um veículo por mensagem para manter a idempotencia por item.

conector-tabela-fipe v1.0.0 — destino SISC conector__conector-tabela-fipe — catalogo catalogo-conector-tabela-fipe.