Documentação oficial

Integre seu ERP ao LubConsulta.

Envie pessoas e produtos, consulte vendas e valide o fluxo diretamente neste manual. O console usa a API real de produção. Para saber o significado, a obrigatoriedade e o retorno de cada propriedade, consulte os campos de cada chamada.

ProduçãoREST + JSONToken JWT · 60 minLayout 1.0

Fluxo da integração

A chave de integração é criada pelo administrador da organização no LubConsulta. Ela limita os recursos e as empresas que o sistema parceiro pode acessar.

1Gere a chaveEscolha as empresas e o uso da chave no LubConsulta.

2Obtenha o tokenTroque a chave por um Bearer token temporário.

3IntegreGrave cadastros e consulte vendas usando o token.

URL base

https://api.integracao.lubconsulta.com.br

Este é o ambiente de produção. Chamadas de escrita alteram dados reais; use apenas chaves, empresas e dados autorizados.

Consulte os grupos e subgrupos antes de importar produtos e o catálogo de serviços para interpretar os UUIDs de serviço retornados nas vendas. Use os IDs reais do ambiente, não valores ilustrativos.

Autenticação

A chave em claro é exibida uma única vez nas configurações do LubConsulta. Guarde-a em um cofre de segredos e use-a apenas para solicitar tokens.

POST/v1/auth/tokenSem Bearer token

{ "apiKey": "lubconsulta_erp_live_..." }

Envie o valor retornado em accessToken nas demais chamadas:

Authorization: Bearer eyJ...

Toda chave nova inclui consulta.*, que já permite consultar vendas. No PDV, a opção “Integrar cadastros e consultar vendas” acrescenta pessoas.gravar e produtos.importar; desmarcada, a chave fica somente para consulta. A chave pode ser revogada a qualquer momento; tokens emitidos por ela deixam de funcionar imediatamente. Chaves antigas podem exibir escopos individuais de pessoas e vendas, ou até nomes de permissões fiscais, mas esta versão não oferece rotas Connect para criar/concluir vendas nem emitir notas fiscais.

Pessoas

Crie clientes e fornecedores e mantenha os dados atualizados. A referência externa vincula o ID do seu ERP ao cadastro do LubConsulta.

POST/v1/operacoes/pessoas

Cria uma pessoa. Exige X-Empresa-Id e Idempotency-Key. X-Sistema-Origem é opcional; sem ele, usa ERP_PARCEIRO.

{ "tipo": "cliente", "tipoPessoa": "PF", "nome": "Maria da Silva", "cpf": "52998224725", "email": "maria@exemplo.com", "telefone": "3133334444", "celular": "31999999999", "referenciaExterna": "CLI-1001" }

tipo é o papel comercial (cliente, fornecedor ou clienteFornecedor); tipoPessoa é PF ou PJ. PF exige cpf, PJ exige cnpj. Para uma empresa, use por exemplo {"tipo":"cliente","tipoPessoa":"PJ","nome":"Oficina Exemplo Ltda","cnpj":"11222333000181","telefone":"3133334444"}. Se tipoPessoa for omitido, CPF/CNPJ determinam PF/PJ; sem documento, o cadastro é AVULSO. telefone e celular são campos independentes, com até 20 caracteres, e voltam na resposta junto de tipoPessoa.

PATCH/v1/operacoes/pessoas/{pessoaId}

Atualiza somente os campos enviados, incluindo telefone e celular. CPF e CNPJ não são alteráveis na versão 1.

Produtos

Importe de 1 a 500 produtos por lote. O par sistemaOrigem + idExterno identifica se o produto será criado ou atualizado.

Classificações disponíveis

Para a integração, grupos e subgrupos são opções prontas de classificação, não cadastros editáveis: a API Connect lista os IDs disponíveis e aceita esses IDs no produto. Não há operação Connect para criar, renomear ou excluir grupos e subgrupos.

GET/v1/operacoes/produtos/classificacoes?empresaId={uuid}

Retorna grupos com seus subgrupos e subgruposSemGrupo. Cada opção traz id, codigo e nome. Exige Bearer token e empresa permitida na chave.

{ "grupos": [{ "id": "11111111-1111-4111-8111-111111111111", "codigo": "LUBRIFICANTES", "nome": "Lubrificantes e fluidos", "subgrupos": [{ "id": "22222222-2222-4222-8222-222222222222", "codigo": "OLEO_MOTOR", "nome": "Óleo do motor" }] }], "subgruposSemGrupo": [] }

Os IDs acima são ilustrativos; consulte os IDs reais do seu ambiente antes de importar. O catálogo padrão contém 11 grupos e 44 subgrupos. Os códigos abaixo são estáveis para identificação; consulte o endpoint para obter os UUIDs vigentes.

Grupo	Subgrupos disponíveis
Lubrificantes e fluidos `LUBRIFICANTES`	`OLEO_MOTOR`, `OLEO_CAMBIO`, `OLEO_DIFERENCIAL`, `OLEO_TRANSFERENCIA`, `FLUIDO_FREIO`, `ARREFECIMENTO`, `FLUIDO_DIRECAO`, `LIQUIDO_LIMPADOR`
Filtros `FILTROS`	`FILTRO_OLEO`, `FILTRO_AR`, `FILTRO_COMB`, `FILTRO_CABINE`, `FILTRO_CAMBIO`
Iluminação `ILUMINACAO`	`FAROIS`, `LANTERNAS`, `SINALIZACAO`, `LUZ_FREIO_RE`
Ignição e elétrica `ELETRICA`	`VELAS_CABOS`, `BATERIAS`
Pneus e rodas `PNEUS_RODAS`	`PNEUS`, `RODAS`, `ESTEPE_MACACO`
Freios `FREIOS`	`PASTILHAS_DIANT`, `PASTILHAS_TRAS`, `DISCOS_DIANT`, `DISCOS_TRAS`, `CABO_FREIO_MAO`, `MANGUEIRA_FREIO`
Suspensão e direção `SUSPENSAO`	`AMORTECEDORES`, `COIFAS`, `TERMINAIS_PIVOS`, `CAIXA_DIRECAO`, `MOLAS_BATENTES`
Motor e transmissão `MOTOR_CAMBIO`	`CORREIAS`, `VEDACOES_MOTOR`, `VEDACOES_CAMBIO`, `CARTER_BUJAO`
Escapamento `ESCAPAMENTO`	`CATALISADOR`, `ESCAP_INTERM`, `ESCAP_TRASEIRO`
Acessórios e utilidades `ACESSORIOS`	`PROTETOR_CARTER`, `PALHETAS_DIANT`, `PALHETA_TRAS`
Ar-condicionado `AR_CONDICIONADO`	`HIGIENIZACAO`

Exemplo: óleo do motor usa LUBRIFICANTES → OLEO_MOTOR; filtro de óleo usa FILTROS → FILTRO_OLEO. Essa classificação não inclui mão de obra na OS: é apenas o tipo do produto.

POST/v1/operacoes/produtos/importacoes

Use somenteValidar: true para identificar pendências sem criar ou atualizar produtos. A validação ainda registra a resposta de idempotência: use uma nova Idempotency-Key ao importar de fato. O exemplo abaixo inclui os campos de classificação por ID.

{ "versaoLayout": "1.0", "idLote": "LOTE-001", "sistemaOrigem": "ERP_CLIENTE", "empresaId": "{uuid}", "somenteValidar": true, "produtos": [{ "idExterno": "PROD-10", "sku": "OLEO-5W30-1L", "nome": "Óleo 5W30 1L", "grupoId": "11111111-1111-4111-8111-111111111111", "subgrupoId": "22222222-2222-4222-8222-222222222222", "unidade": "UN", "controlaEstoque": true, "precificacao": { "precoVenda": 49.90 } }] }

subgrupoId deve pertencer ao grupoId; se somente o subgrupo for enviado, o grupo é deduzido dele. Em atualizações, campos omitidos preservam a classificação; trocar apenas o grupo remove um subgrupo que não pertença ao novo grupo. grupo e subgrupo por nome continuam inválidos. Serviços são outro catálogo e não são criados por esta importação.

O lote pode responder HTTP 200 e ainda conter itens rejeitados: verifique status do lote, resultados[].status e resultados[].pendencias. O mesmo sistemaOrigem + idExterno atualiza inclusive um produto previamente inativado; envie ativo: true para reativá-lo. O nome deve ser único na organização, inclusive entre produtos inativos: outro cadastro com o mesmo nome gera pendência no item.

Catálogo de serviços

Os 46 serviços canônicos têm códigos estáveis. A categoria é apenas um agrupamento de apresentação; servicoPaiId e servicoPaiCodigo representam a hierarquia real do cadastro. A empresa pode habilitar somente parte dos serviços e configurar seu preço; estar nesta lista não significa estar habilitado ou precificado naquela empresa.

GET/v1/operacoes/servicos/catalogo?empresaId={uuid}

Exige Bearer token com consulta.* ou vendas.consultar e empresa permitida. Retorna servicos[] com id, codigo, nome, categoria, servicoPaiId, servicoPaiCodigo e produtosEsperados[]. O id é nulo se o serviço ainda não foi materializado no ambiente. Consulte os UUIDs reais aqui; não fixe os exemplos em sua integração. Serviços personalizados de outros módulos não integram esta lista padrão.

{ "servicos": [{ "id": "{uuid-real-do-ambiente}", "codigo": "TROCA_FILTRO_OLEO", "nome": "Troca do filtro de óleo", "categoria": "Motor", "servicoPaiId": "{uuid-real-da-troca-de-oleo}", "servicoPaiCodigo": "TROCA_OLEO_MOTOR", "produtosEsperados": [{ "codigo": "FILTRO_OLEO", "nome": "Filtro de óleo", "grupoCodigo": "FILTROS", "subgrupoCodigo": "FILTRO_OLEO" }] }] }

Hierarquia e vínculo com produtos

O padrão atual em produção tem seis relações pai–filho. A categoria não determina o pai: TROCA_FILTRO_CABINE pertence à categoria Ar-condicionado, mas é filho cadastral de TROCA_OLEO_MOTOR.

Serviço pai	Serviços filhos
`TROCA_OLEO_MOTOR`	`TROCA_FILTRO_OLEO`, `TROCA_FILTRO_AR`, `TROCA_FILTRO_COMBUSTIVEL`, `TROCA_FILTRO_CABINE`
`TROCA_OLEO_CAMBIO`	`TROCA_FILTRO_CAMBIO`
`TROCA_PALHETAS_DIANTEIRAS`	`TROCA_PALHETA_TRASEIRA`

O código histórico TROCA_PALHETAS_DIANTEIRAS preserva “dianteiras”, mas a mão de obra comercial se chama “Troca de palhetas” e abrange dianteiras e traseira. Os demais serviços não têm pai no padrão. O endpoint lê o vínculo real do ambiente; se ele foi alterado, prevalece a resposta da API.

Um filho cadastral não cria uma segunda cobrança automaticamente. Quando um filtro é adicionado à linha da troca de óleo, itens[].itemPedidoServicoId identifica essa linha da venda e itens[].servicoComponenteId pode identificar o cadastro de TROCA_FILTRO_OLEO. Resolva esse UUID pelo id do catálogo. Só servicos[] mostra as linhas de mão de obra efetivamente lançadas e seus valores; não crie outra linha apenas porque há filho ou produto vinculado.

Categoria	Código do serviço	Nome
Motor	`TROCA_OLEO_MOTOR`	Troca de óleo do motor
Motor	`TROCA_FILTRO_OLEO`	Troca do filtro de óleo
Motor	`TROCA_FILTRO_AR`	Troca do filtro de ar
Motor	`TROCA_FILTRO_COMBUSTIVEL`	Troca do filtro de combustível
Motor	`TROCA_LIQUIDO_ARREFECIMENTO`	Troca do líquido de arrefecimento
Motor	`TROCA_VELAS_CABOS`	Troca de velas e cabos
Motor	`TROCA_CORREIAS_TENSIONADOR`	Troca de correias e tensionador
Motor	`REPARO_VAZAMENTO_MOTOR`	Reparo de vazamento no motor
Motor	`TROCA_BUJAO_CARTER`	Troca do bujão ou reparo do cárter
Transmissão	`TROCA_OLEO_CAMBIO`	Troca de óleo da transmissão/câmbio
Transmissão	`TROCA_OLEO_DIFERENCIAL`	Troca de óleo do diferencial
Transmissão	`TROCA_OLEO_TRANSFERENCIA`	Troca de óleo da caixa de transferência
Transmissão	`TROCA_FILTRO_CAMBIO`	Troca do filtro de câmbio automático
Transmissão	`REPARO_VAZAMENTO_TRANSMISSAO`	Reparo de vazamento na transmissão
Ar-condicionado	`TROCA_FILTRO_CABINE`	Troca do filtro de cabine
Ar-condicionado	`HIGIENIZACAO_AR_CONDICIONADO`	Higienização do ar-condicionado
Acessórios	`TROCA_PALHETAS_DIANTEIRAS`	Troca de palhetas · pai
Acessórios	`TROCA_PALHETA_TRASEIRA`	Troca da palheta traseira · filha de `TROCA_PALHETAS_DIANTEIRAS`
Acessórios	`REPOSICAO_LIQUIDO_LIMPADOR`	Reposição do líquido do para-brisa
Acessórios	`INSTALACAO_PROTETOR_CARTER`	Instalação ou reparo do protetor de cárter
Freios	`TROCA_FLUIDO_FREIO`	Troca do fluido de freio
Freios	`TROCA_PASTILHAS_DIANTEIRAS`	Troca de pastilhas dianteiras
Freios	`TROCA_PASTILHAS_TRASEIRAS`	Troca de pastilhas traseiras
Freios	`RETIFICA_DISCOS_DIANTEIROS`	Retífica de discos dianteiros
Freios	`RETIFICA_DISCOS_TRASEIROS`	Retífica de discos traseiros
Freios	`TROCA_CABOS_FREIO_MAO`	Troca dos cabos do freio de mão
Freios	`TROCA_MANGUEIRAS_FREIO`	Troca de tubulações e mangueiras de freio
Direção	`TROCA_FLUIDO_DIRECAO`	Troca do fluido da direção hidráulica
Direção	`REPARO_CAIXA_DIRECAO`	Reparo da caixa de direção
Iluminação	`REPARO_FAROIS`	Reparo dos faróis
Iluminação	`REPARO_LANTERNAS`	Reparo das lanternas traseiras
Iluminação	`REPARO_SETAS_ALERTA`	Reparo das setas e pisca-alerta
Iluminação	`REPARO_LUZ_FREIO_RE`	Reparo da luz de freio e de ré
Elétrica	`TROCA_BATERIA`	Troca da bateria
Pneus	`TROCA_PNEUS`	Troca de pneus
Pneus	`ALINHAMENTO`	Alinhamento
Pneus	`CALIBRAGEM_PNEUS`	Calibragem dos pneus
Pneus	`REPARO_RODAS_PARAFUSOS`	Reparo de rodas e parafusos
Pneus	`REVISAO_ESTEPE_MACACO`	Revisão do estepe e macaco
Suspensão	`TROCA_AMORTECEDORES`	Troca de amortecedores
Suspensão	`TROCA_COIFA_HOMOCINETICA`	Troca da coifa de homocinética
Suspensão	`TROCA_TERMINAIS_PIVOS`	Troca de terminais e pivôs
Suspensão	`TROCA_MOLAS_BATENTES`	Troca de molas e batentes
Escapamento	`TROCA_CATALISADOR`	Troca do catalisador
Escapamento	`TROCA_ESCAPAMENTO_INTERMEDIARIO`	Troca do escapamento intermediário
Escapamento	`TROCA_ESCAPAMENTO_TRASEIRO`	Troca do escapamento traseiro

Vendas

Consulte vendas pelo período ou número. A resposta inclui cliente, veículo (com codigoFipe quando informado), produtos, serviços, totais, pagamentos e documentos fiscais. Vendas não encerradas também podem aparecer; confira o campo status antes de importá-las.

GET/v1/operacoes/vendasPeríodo máximo: 31 dias

Parâmetros: empresaId, inicio, fim, pagina, limite e sistemaOrigem.

GET/v1/operacoes/vendas/{numero}

Use o campo numero retornado na listagem. Normalmente é o número comercial do pedido; quando não há pedido associado, é o UUID da venda, também aceito no detalhe.

Produtos, serviços e vínculos

itens são os produtos vendidos. servicos são as linhas de mão de obra efetivamente lançadas na OS, com quantidade, preço e valor próprios. Um produto não cria automaticamente uma cobrança de serviço. O idExterno do produto só é preenchido quando ele tem vínculo com o sistemaOrigem informado na consulta.

Campo	O que identifica	Quando usar
`itens[].itemPedidoServicoId`	A linha de `servicos[]` à qual aquele produto foi adicionado; corresponde a `servicos[].id`.	Para apresentar os produtos agrupados sob a mão de obra. Nulo significa produto avulso.
`itens[].servicoComponenteId`	O ID do serviço de componente que originou o produto dentro do serviço principal, como “troca do filtro de óleo”. É referência de catálogo, não uma linha cobrada da venda.	Resolva seu código pelo `id` do catálogo de serviços. Ignore se não precisar dessa origem.
`servicos[].servicoId` e `servicos[].codigo`	Identificam o cadastro do serviço e seu código no momento da venda; são diferentes de `servicos[].id`, que identifica a linha daquela venda.	Para reconhecer a mão de obra entre vendas. O código pode ser nulo em registros antigos.
`servicos[].itemPedidoServicoPaiId`	Outra linha de `servicos[]` da mesma venda, à qual esta linha está subordinada. Corresponde ao `id` da linha pai.	Para mostrar serviços agrupados. Nulo indica serviço principal ou independente.
`quantidade`, `precoUnitario`, `valorTotal`	Presentes em cada produto e serviço; mostram quanto foi lançado em cada linha.	Exiba os valores por linha. Use `totais` para a conciliação final, pois pode haver descontos, acréscimos, frete e impostos.

Exemplo ilustrativo de uma venda com um filtro de R$ 45,00 vinculado à troca de óleo do motor de R$ 70,00. Os demais campos da venda foram omitidos apenas para focar nos vínculos:

{ "itens": [{ "produtoId": "bc9a2603-79f1-4e7a-9726-2790f9cdfaca", "idExterno": "FILTRO-10", "sku": "FILTRO-10", "nome": "Filtro de óleo", "unidade": "UN", "quantidade": 1, "precoUnitario": 45.00, "desconto": 0, "acrescimo": 0, "valorTotal": 45.00, "itemPedidoServicoId": "9f71fa72-ab5a-4c4f-aee4-46c848d9a33e", "servicoComponenteId": "74e48dcc-50f0-4644-a2cd-883340902941" }], "servicos": [{ "id": "9f71fa72-ab5a-4c4f-aee4-46c848d9a33e", "servicoId": "2d147758-a5e4-425e-a186-c658b4199ae7", "codigo": "TROCA_OLEO_MOTOR", "nome": "Troca de óleo do motor", "itemPedidoServicoPaiId": null, "quantidade": 1, "precoUnitario": 70.00, "valorTotal": 70.00 }], "totais": { "subtotal": 115.00, "desconto": 0, "acrescimo": 0, "frete": 0, "impostos": 0, "total": 115.00 } }

No catálogo de serviços, o servicoComponenteId do filtro corresponde a esta entrada (UUIDs ilustrativos):

{ "id": "74e48dcc-50f0-4644-a2cd-883340902941", "codigo": "TROCA_FILTRO_OLEO", "servicoPaiId": "2d147758-a5e4-425e-a186-c658b4199ae7", "servicoPaiCodigo": "TROCA_OLEO_MOTOR" }

Leia o exemplo assim: o produto aponta para a linha da troca de óleo pelo itemPedidoServicoId; o servicoComponenteId identifica que ele é um filtro de óleo. A conta é R$ 45,00 em produto + R$ 70,00 em mão de obra = R$ 115,00. O filho no catálogo não é uma segunda cobrança: só servicos[] contém mão de obra lançada. Se houver uma linha própria para a troca do filtro, ela aparecerá em servicos[], com seu próprio valor e, quando subordinada, itemPedidoServicoPaiId apontando para a linha principal.

Esta versão permite consultar pagamentos e documentos fiscais retornados na venda, mas não oferece rotas Connect para receber pagamento, criar venda ou emitir/cancelar nota fiscal.

Regras e limites

Item	Regra
Formato	JSON em UTF-8; propriedades em camelCase.
Datas	ISO 8601 em UTC, por exemplo `2026-09-23T12:00:00Z`.
Idempotência	UUID novo em `Idempotency-Key` para cada escrita. Mesmo UUID + mesmo corpo devolve a resposta anterior; mesmo UUID + corpo diferente gera 409. Validação e importação efetiva precisam de UUIDs diferentes.
Lote de produtos	De 1 a 500 itens.
Consulta de vendas	Até 31 dias e 100 vendas por página.
Empresa	Deve pertencer à lista de empresas liberadas na chave.

Erros

Todos os erros possuem código estável e uma mensagem legível.

{ "codigo": "EMPRESA_NAO_PERMITIDA", "mensagem": "..." }

HTTP	Código	Quando ocorre
400	`VALIDACAO`	Payload, período ou campo obrigatório inválido.
401	`CHAVE_INVALIDA` / `TOKEN_INVALIDO`	Chave inválida/revogada ou token ausente/inválido/expirado.
403	`ESCOPO_INSUFICIENTE`	A chave não permite a operação.
403	`EMPRESA_NAO_PERMITIDA`	A empresa não foi liberada para a chave.
404	`VENDA_NAO_ENCONTRADA`	Registro não localizado no contexto permitido.
409	`IDEMPOTENCIA_CONFLITANTE`	A mesma chave foi usada com outro corpo.
422	`VALIDACAO_NEGOCIO`	Uma regra de negócio impediu a gravação.