Consulta de Placas pela API Brasil
v26.06a
Orienta como consultar dados de veículos pela placa através da integração com a API Brasil, permitindo preenchimento automático de campos em Ordens de Serviço e Cadastro de Equipamentos.
user_manual
public
consulta-de-placas-pela-api-brasil
|
Sistemas Teorema -> 00001
25
03/08/2026 13:22
· Bernardo
- Título
- Consulta de Placas pela API Brasil
- Slug
- consulta-placas-pela-api
- Categoria
- user_manual
- Tipo
- how-to
- Sistema(s)
- Teorema
- Autor
- Antonio Marcos Zampier
- Setor
- Qualidade
- Modulo
- Balcão Caixa OS
- Chamado
- "0000558672"
- Aprovado em
- 2026-07-01
- Release
- 26.06a
- Versão Pipeline
- ia-forja
- Publico
- operadores de Balcão, gestores de Caixa
- Keywords
- placa API Brasil consulta veicular integração Mercosul
- Ultima Revisao
- 2026-08-03
--- title: Consulta de Placas pela API Brasil slug: consulta-placas-pela-api categoria: user_manual tipo: how-to sistema: Teorema autor: Antonio Marcos Zampier setor: Qualidade modulo: Balcão Caixa OS chamado: "0000558672" aprovado_em: 2026-07-01 release: 26.06a versao_pipeline: ia-forja publico: operadores de Balcão, gestores de Caixa keywords: - placa - API Brasil - consulta veicular - integração - Mercosul ultima_revisao: 2026-08-03 --- ## Visão Geral A Consulta de Placas pela API Brasil permite ao operador identificar automaticamente um veículo digitando apenas sua placa. O Teorema consulta a base da API Brasil e preenche os campos de Identificação (campos 1 a 10 + Observações) em uma Ordem de Serviço ou no Cadastro de Equipamentos, conforme um mapeamento configurável (De/Para) por empresa. O sistema normaliza a placa automaticamente — aceita ambos os formatos (antigo ABC1234 e Mercosul ABC1D23), com ou sem hífen, maiúsculas ou minúsculas — e envia a requisição à API Brasil em tempo real. ### Quando usar - Atender uma Ordem de Serviço que exija identificação rápida do veículo pela placa. - Cadastrar um novo equipamento no Cadastro de Equipamentos. - Alimentar campos de Identificação sem digitação manual. ### Pré-requisitos - Acesso ao Módulo Vendas Balcão ou ao Cadastro de Equipamentos. - Token da API Brasil configurado nos Parâmetros Gerais (veja Seção 3). - De/Para de campos configurado para a empresa (veja Seção 4). ## Como funciona A consulta segue este fluxo: 1. **Tela** — operador acessa a Ordem de Serviço ou Cadastro de Equipamentos. 2. **Placa digitada** — informada manualmente (qualquer formato). 3. **Normalização** — placa convertida para maiúsculas, sem hífen, máximo 7 caracteres. 4. **Verificação de cota** — quando aplicável (apenas para token Teorema). 5. **Requisição** — enviada à API Brasil. 6. **Resposta** — preenche automaticamente os campos conforme o De/Para. A placa é normalizada antes de qualquer consulta: o sistema converte para maiúsculas, remove hífen e qualquer caractere que não seja letra ou número, considerando no máximo 7 posições — tanto no formato antigo quanto no Mercosul. Toda consulta enviada à API Brasil é real, mesmo em treinamento ou teste — **não existe modo de teste gratuito**. Se a API Brasil não responder em até 25 segundos, a consulta é cancelada e uma mensagem de erro é exibida. ### Módulo de Licenças A integração com a API Brasil requer uma das seguintes licenças habilitadas na central de clientes: - **Integrador Consulta Placas – Gov-Br – Cliente** — se o cliente contratou diretamente com a API Brasil. - **Integrador Consulta Placas – Gov-Br – Teorema** — se o cliente utiliza o token compartilhado da Teorema. Solicite a habilitação da licença apropriada ao Comercial. ## Configurar o token da API Brasil Configure o token uma única vez por empresa, antes da primeira consulta. ### Passo 1: Abra os Parâmetros Gerais Módulo **Administrador** → **F - Parâmetros Gerais** → aba **API Config**. ### Passo 2: Inclua ou edite a configuração Clique em **+** para um novo registro, ou localize um já existente do tipo `apiBrasil` e clique em **editar**.  ### Passo 3: Preencha o diálogo Config API Você tem duas opções para o Token: **Opção 1: Token próprio do cliente** Acesse o site da API Brasil ([www.apibrasil.com.br](http://www.apibrasil.com.br)), faça cadastro, adicione os créditos e gere um Token. Cole-o no campo Token. **Opção 2: Token compartilhado da Teorema** Deixe o campo Token com o valor `APIBRASIL_TEOREMA_TOKEN` (sem aspas). Nesse caso, cada consulta passa por uma verificação de cota interna da Teorema antes de alcançar a API Brasil. > **Nota:** O campo Token aceita o JWT puro, mas também tolera variações comuns de colagem — com prefixo `Bearer`, entre aspas, com espaços em volta. O sistema tenta extrair automaticamente os três blocos separados por ponto que formam um JWT válido. Recomenda-se colar somente o token, sem prefixos. ### Passo 4: Confirme O token fica associado à empresa e é usado em todas as consultas feitas por essa empresa. ## Configurar o De/Para dos campos Depois de configurar o token, configure o mapeamento que define quais dados da API Brasil vão para cada campo de tela. Essa configuração também é feita por empresa e é realizada uma única vez. ### A partir do Cadastro de Equipamentos **1. Acesse a tela Cadastro de Placa Veículo** Vendas Balcão → Frente de Caixa → menu **Equipamentos** → **Cadastro de Placa Veículo**.  **2. Clique no botão Configurar De/Para** Na barra de ferramentas, procure e clique em **Configurar De/Para**.  **3. Configure os campos no diálogo** Abrirá um diálogo mostrando um combo para cada campo de Identificação (campos 1 a 10 + Observações). Para cada campo, escolha ou digite o caminho correspondente da resposta da API Brasil — veja a seção "Campos retornados pela API" para a lista completa de ~35 caminhos disponíveis.  **Sugestão de mapeamento padrão:** | **Campo na tela** | **Caminho sugerido** | **Dado que chega** | |-------------------|----------------------|---------------------------------------| | 1 | data.chassi | Número do chassi | | 2 | data.numeromotor | Número do motor | | 3 | data.numeromotor | Repetição, ou outro caminho à escolha | | 4 | data.modelo | Modelo do veículo | | 6 | data.anomodelo | Ano do modelo | | 7 | data.placamercosul | Placa no padrão Mercosul | | Observações | data.motordescricao | Descrição textual do motor | > **Nota:** O mapeamento fica salvo automaticamente vinculado à empresa assim que você confirma Salvar — não é preciso nenhuma instalação ou ajuste manual antes de configurar o De/Para pela primeira vez. ### A partir da Ordem de Serviço **1. Abra uma Ordem de Serviço** Vendas Balcão → Frente de Caixa → **Ordem de Serviço** (O.S.). **2. Acesse o diálogo de Consulta de Placa** Na aba **Identificação**, clique no ícone de **lupa** ao lado do campo 1 para abrir a janela "Consulta de placa".  **3. Configure o De/Para (se ainda não feito)** Se o De/Para ainda não estiver configurado para a empresa, clique em **Configurar De/Para** dentro do diálogo de consulta e repita os passos da seção anterior. Se já foi configurado, você pode pular para a consulta. > **Nota:** Se a empresa está em um grupo com múltiplas empresas, cada uma precisa da própria configuração de token e De/Para — a configuração não é compartilhada entre empresas. ## Consultar digitando a placa Após configurar o token e o De/Para, você pode fazer a consulta em tempo real. ### Na Ordem de Serviço **1. Abra a Ordem de Serviço** Vendas Balcão → Frente de Caixa → **Ordem de Serviço**. **2. Clique no ícone de lupa** Na aba **Identificação**, ao lado do campo 1. **3. Digite a placa** Informe a placa no formato antigo (ABC1234) ou Mercosul (ABC1D23) — maiúsculas ou minúsculas, com ou sem hífen. O sistema normaliza sozinho.  **4. Clique em Consultar** O sistema busca o token da empresa, verifica cota quando aplicável, e envia a requisição à API Brasil. **5. Campos preenchidos** Em caso de sucesso, uma notificação informa quantos campos foram preenchidos conforme o De/Para. A tela retorna com os dados carregados.  ### No Cadastro de Equipamentos **1. Abra o Cadastro de Placa Veículo** Vendas Balcão → Frente de Caixa → menu **Equipamentos** → **Cadastro de Placa Veículo**. **2. Clique em Consultar Placa** Na barra de ferramentas, procure e clique em **Consultar Placa**.  **3. Digite a placa** Informe a placa no formato antigo (ABC1234) ou Mercosul (ABC1D23).  **4. Clique em Consultar** A requisição é enviada à API Brasil. **5. Campos preenchidos** Em caso de sucesso, os campos são preenchidos automaticamente conforme o De/Para configurado.  ## Campos retornados pela API A resposta da API Brasil traz um envelope com informações da consulta, da conta e um bloco de dados do veículo. Veja abaixo o que está disponível para mapeamento no De/Para. ### Envelope de controle | **Caminho** | **Significado** | |--------------|------------------------------------------------------------------------| | balance | Saldo de créditos restante na conta da API Brasil usada | | error | Indica se a consulta falhou (a mensagem correspondente vem em message) | | message | Mensagem de erro ou informativa da API | | homolog | Indicador de ambiente devolvido pela API Brasil | | user.* | Dados da conta/token da API Brasil que respondeu (não do veículo) | ### Dados do veículo (data.*) Os campos abaixo compõem o bloco `data` da resposta e podem ser mapeados para os campos de Identificação: | **Caminho** | **Descrição** | |---------------------------|----------------------------------------------| | data.placa | Placa original consultada | | data.placamercosul | Placa no padrão Mercosul | | data.chassi | Número do chassi | | data.fabricante | Fabricante do veículo | | data.marca | Marca (ex.: VOLKSWAGEN) | | data.modelo | Modelo (ex.: GOL) | | data.versao | Versão do modelo | | data.anofabricacao | Ano de fabricação | | data.anomodelo | Ano do modelo | | data.motordescricao | Descrição textual do motor | | data.transmissaodescricao | Descrição da transmissão | | data.combustivel | Combustível (FLEX, GASOLINA, DIESEL...) | | data.tipoveiculo | Tipo (AUTOMÓVEL, MOTO, CAMINHÃO...) | | data.especie | Espécie do veículo (passageiro, carga...) | | data.cor | Cor predominante | | data.tipocarroceria | Tipo de carroceria | | data.nacionalidade | Nacionalidade do veículo | | data.numeromotor | Número do motor | | data.potencia | Potência (CV) | | data.carga | Capacidade de carga | | data.numerocarroceria | Número da carroceria | | data.numerocaixacambio | Número da caixa de câmbio | | data.numeroeixotraseiro | Número do eixo traseiro | | data.numeroterceiroeixo | Número do terceiro eixo, quando houver | | data.quantidadeeixo | Quantidade de eixos | | data.quantidadeportas | Quantidade de portas | | data.cilindradas | Cilindradas | | data.capacidademaxtracao | Capacidade máxima de tração | | data.pesobrutototal | Peso Bruto Total (PBT) | | data.quantidadelugares | Quantidade de lugares | | data.tipomontagem | Tipo de montagem | | data.ufjurisdicao | UF de jurisdição do registro | | data.cidade | Município de registro | | data.paisfabricacao | País de fabricação | | data.documentofaturado | CPF/CNPJ do faturado (proprietário na nota) | | data.tipofaturado | Tipo de pessoa do faturado (física/jurídica) | | data.uffaturado | UF do faturado | > **Nota:** Os caminhos usados no De/Para são sempre em minúsculas e sem separador (ex.: `data.numeromotor`, não `data.numero_motor`) — é a convenção que a lista de sugestões da tela usa. Digite exatamente assim ao configurar manualmente um campo que não esteja na lista. ## Cotas e consumo de créditos Toda consulta bem-sucedida é cobrada como crédito real pela API Brasil. Não existe modo de teste gratuito — combine com a equipe antes de "testar à vontade" com o token de produção. ### Com token Teorema Cada consulta passa por uma verificação de cota interna da Teorema. Se a cota da empresa estiver esgotada, a consulta é bloqueada antes mesmo de chamar a API Brasil, e uma notificação explica o motivo. Quando a verificação passa, o sistema exibe quantos usos ainda restam antes de atingir o limite — útil para acompanhar o consumo sem precisar abrir um painel externo. ### Com token próprio Nenhuma verificação de cota interna da Teorema é feita. O limite é exclusivamente o saldo de créditos da própria conta da empresa na API Brasil, visível no campo `balance` retornado e no painel da API Brasil. ## Erros comuns e diagnóstico | **Situação** | **Causa provável** | |---------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------| | "Não foi encontrada configuração da APIBrasil em Parâmetros Gerais" | Nenhum registro apiBrasil cadastrado para a empresa — repita o Passo 3 (Configurar o token da API Brasil). | | "Token da APIBrasil não encontrado" ou "Token inválido" | O campo Token está vazio, ou o valor colado não contém um JWT reconhecível (três blocos separados por ponto). | | Erro ao consultar (recusado pela API) | Token expirado, sem crédito, ou placa em formato que a API Brasil rejeitou. | | Consulta "trava" por vários segundos e falha | Provável timeout — o Teorema aguarda até 25s de resposta antes de desistir. | ## Segurança e boas práticas - O token pode ser salvo de forma protegida no cadastro; o Teorema cuida de recuperá-lo automaticamente ao usá-lo. - Token e De/Para são configurados por empresa — em grupos com múltiplas empresas, cada uma precisa da própria configuração. - Se o De/Para ainda não tiver sido configurado para a empresa, isso não impede a consulta em si, apenas o preenchimento automático dos campos — você pode consultar e o diálogo oferece o botão **Configurar De/Para** para resolver isso sem sair da tela. - Placas são sempre normalizadas para maiúsculas, sem hífen, no máximo 7 caracteres — não é preciso orientar o usuário a formatar antes de digitar. --- ## Informações do documento > **Autor:** Antonio Marcos Zampier > **Setor:** Qualidade > **Módulo:** Balcão Caixa OS > **Chamado:** 0000558672 > **Versão do Sistema:** 26.06a > **Versão do documento:** 01 > **Última revisão:** 2026-08-03 > **Aprovado em:** 2026-07-01 --- > 📎 **Arquivos originais:** [Manual_para_Consulta_de_Placas_pela_API_Brasil_558672.docx](https://drive.google.com/uc?export=download&id=1GNPJPG0Gi4c-quR5hYentEvKOFmby4kw)
Tags IA:
consulta
placas
pela
api
Prioridade: 7