Campos da API — LubConsulta Connect

Convenções

Termo	Significado
Obrigatório	Envie o campo para uma operação válida. “Condicional” significa que a regra depende dos outros campos ou de criar versus atualizar.
Opcional / nulo	Em JSON, os nomes são `camelCase`. Um campo marcado como anulável pode voltar como `null`; listas vazias voltam como `[]`.
UUID	Identificador interno. Não confunda ID de uma linha da venda com ID de um cadastro de produto ou serviço.
Decimal	Número JSON com ponto decimal, sem “R$”; valores monetários estão em reais.
Data/hora	Envie filtros de período em ISO 8601 com fuso explícito, preferencialmente UTC (ex.: `2026-09-24T12:00:00Z`). Leia o fuso efetivamente serializado nos retornos.
Bearer	Exceto na geração do token, envie `Authorization: Bearer {accessToken}`. A chave da API não deve ir nas demais chamadas.
Escrita	POST e PATCH operacionais exigem `Idempotency-Key` novo por operação. Repetir a mesma chave e corpo devolve a resposta salva; trocar o corpo gera 409.

Consultar grupos e subgrupos

GET /v1/operacoes/produtos/classificacoes

Catálogo de classificações disponível para vincular produtos. É somente leitura nesta API.

Envio

Campo	Local / tipo	Obrigatório	Descrição
`Authorization`	Header · Bearer	Sim	Token com acesso à consulta de produtos.
`empresaId`	Query · UUID	Sim	Empresa permitida na chave; não use `X-Empresa-Id` nesta chamada.

Resposta 200

Campo	Tipo	Nulo?	Descrição
`grupos[]`	object[]	Não	Grupos disponíveis. Cada objeto inclui os subgrupos associados.
`grupos[].id`	UUID	Não	Envie como `grupoId` ao importar produto.
`grupos[].codigo`	string	Não	Código de referência do grupo.
`grupos[].nome`	string	Não	Nome exibido do grupo.
`grupos[].subgrupos[]`	object[]	Não	Subgrupos pertencentes a esse grupo.
`grupos[].subgrupos[].id`	UUID	Não	Envie como `subgrupoId` ao importar produto.
`grupos[].subgrupos[].codigo`	string	Não	Código de referência do subgrupo.
`grupos[].subgrupos[].nome`	string	Não	Nome exibido do subgrupo.
`subgruposSemGrupo[]`	object[]	Não	Subgrupos sem grupo associado; também contêm `id`, `codigo` e `nome`.

O vínculo entre grupoId e subgrupoId é validado na importação. Os campos textuais grupo e subgrupo do layout não substituem esses IDs.

Importar produtos

POST /v1/operacoes/produtos/importacoes

Valida ou grava um lote de 1 a 500 produtos. O mesmo produto externo é atualizado em novas importações. A resposta 200 não garante sucesso de todos os itens: examine resultados[].

Headers

Campo	Tipo	Obrigatório	Descrição
`Authorization`	Bearer JWT	Sim	Token com `produtos.importar`.
`Idempotency-Key`	UUID	Sim	UUID por tentativa. Use outro ao passar de validação para gravação.

Corpo enviado — lote

Campo	Tipo	Obrigatório	Descrição
`versaoLayout`	string	Não	Versão aceita: `1.0`; é o padrão se omitida.
`idLote`	string	Sim	Identificador do lote no sistema de origem, até 100 caracteres.
`sistemaOrigem`	string	Sim	Identifica o parceiro, até 80 caracteres; usado para reencontrar `idExterno`.
`empresaId`	UUID	Sim	Empresa que receberá os produtos; precisa ser permitida na chave.
`somenteValidar`	boolean	Não	Padrão `false`. Se `true`, simula as ações e pendências sem criar/atualizar produtos.
`produtos[]`	object[]	Sim	Entre 1 e 500 objetos de produto.

Corpo enviado — cada `produtos[]`

Campo	Tipo	Obrigatório	Descrição / limite
`idExterno`	string	Sim	ID estável no sistema de origem, até 100 caracteres; identifica criação versus atualização.
`sku`	string	Não	Código interno, até 50 caracteres. Na criação sem SKU, a API gera um.
`nome`	string	Na criação	Nome do produto, até 200 caracteres.
`descricao`	string	Não	Descrição, até 500 caracteres.
`ean`	string	Não	Código de barras, até 14 caracteres; não pode conflitar com outro produto.
`referenciaFabricante`	string	Não	Referência do fabricante, até 50 caracteres.
`marca`	string	Não	Marca, até 200 caracteres.
`grupoId`	UUID	Não	ID ativo retornado na consulta de classificações.
`subgrupoId`	UUID	Não	ID ativo; se houver grupo, precisa pertencer a ele.
`grupo`	string	Não enviar	Campo legado do layout. Valor preenchido é rejeitado; use `grupoId`.
`subgrupo`	string	Não enviar	Campo legado do layout. Valor preenchido é rejeitado; use `subgrupoId`.
`unidade`	string	Não	Unidade de venda, até 10 caracteres; padrão `UN` na criação.
`ativo`	boolean	Não	Disponibilidade cadastral; padrão `true` na criação.
`vendavel`	boolean	Não	Permite venda; padrão `true` na criação.
`controlaEstoque`	boolean	Na criação	Define se o estoque do produto será controlado.
`permiteFracionamento`	boolean	Não	Permite quantidades fracionadas; padrão `false` na criação.
`precificacao`	object	Não	Preço; subcampos abaixo.
`fiscal`	object	Não	Classificação fiscal; subcampos abaixo.

Objetos de preço e fiscal

Campo	Tipo	Obrigatório	Descrição
`precificacao.tipo`	string	Não	Layout prevê `PRECO_FIXO`. A implementação atual grava preço fixo; não há outra modalidade operacional.
`precificacao.precoVenda`	decimal	Não	Preço de venda em reais, maior ou igual a zero.
`precificacao.precoCusto`	decimal	Não	Custo em reais, maior ou igual a zero.
`fiscal.ncm`	string	Não	NCM com 8 dígitos.
`fiscal.cest`	string	Não	CEST com 7 dígitos.
`fiscal.origemMercadoria`	integer	Não	Código de origem fiscal de 0 a 8; consulte a classificação fiscal do produto.

Resposta 200

Campo	Tipo	Nulo?	Descrição
`idLote`	string	Não	ID enviado para correlacionar resposta e lote.
`status`	string	Não	`VALIDADO`, `VALIDADO_COM_PENDENCIAS`, `PROCESSADO` ou `PROCESSADO_COM_ERROS`.
`resultados[]`	object[]	Não	Uma resposta por produto enviado.
`resultados[].idExterno`	string	Não	ID do produto no parceiro.
`resultados[].acaoPrevista`	string	Sim	`CRIAR` ou `ATUALIZAR` no modo `somenteValidar`; pode ser nulo após gravação.
`resultados[].produtoId`	UUID	Sim	ID interno quando criado/atualizado; nulo na validação ou rejeição.
`resultados[].status`	string	Sim	`CRIADO`, `ATUALIZADO`, `REJEITADO`; nulo na simulação.
`resultados[].pendencias[]`	object[]	Não	Erros/avisos do item; inspecione mesmo quando o HTTP é 200.
`resultados[].pendencias[].campo`	string	Não	Campo ou regra afetada.
`resultados[].pendencias[].mensagem`	string	Não	Motivo da pendência.

Na atualização, campos não enviados preservam o cadastro. A validação de lote também consome a Idempotency-Key; gere outra chave ao enviar o mesmo lote para gravação.

Obter token

POST /v1/auth/token

Não usa Bearer. Responde 200; chave inválida ou revogada responde 401.

Corpo enviado

Campo	Tipo	Obrigatório	Descrição
`apiKey`	string	Sim	Chave em claro exibida uma única vez no LubConsulta. Nunca coloque em URL ou código-fonte.

Resposta 200

Campo	Tipo	Nulo?	Descrição
`accessToken`	string	Não	JWT a enviar no header Authorization.
`tokenType`	string	Não	Valor `Bearer`.
`expiresIn`	integer	Não	Validade do token em segundos; normalmente 3600.
`scopes[]`	string[]	Não	Escopos concedidos à chave, como `consulta.*` ou `produtos.importar`.

Criar pessoa

POST /v1/operacoes/pessoas

Cria cliente, fornecedor ou ambos. Responde 201 na criação; repetição idêntica da chave de idempotência responde 200.

Headers

Header	Tipo	Obrigatório	Descrição
`Authorization`	Bearer JWT	Sim	Token com `pessoas.gravar` ou `pessoas.criar`.
`Idempotency-Key`	UUID	Sim	Identifica a tentativa de criação; gere outro UUID para outra operação.
`X-Empresa-Id`	UUID	Sim	Empresa permitida na chave.
`X-Sistema-Origem`	string	Não	Identifica o ERP parceiro; padrão `ERP_PARCEIRO`. Usado com `referenciaExterna`.

Corpo enviado

Campo	Tipo	Obrigatório	Descrição / regra
`tipo`	string	Padrão cliente	Papel comercial: `cliente`, `fornecedor` ou `clienteFornecedor`. Não indica PF/PJ.
`tipoPessoa`	string	Não	`PF` ou `PJ`. PF exige CPF sem CNPJ; PJ exige CNPJ sem CPF. Se omitido, o documento determina o tipo; sem documento, é AVULSO.
`nome`	string	Sim	Nome ou razão social, até 200 caracteres.
`cpf`	string	Se PF	CPF válido, até 20 caracteres; não pode pertencer a outro cadastro.
`cnpj`	string	Se PJ	CNPJ válido, até 20 caracteres; não pode pertencer a outro cadastro.
`email`	string	Não	E-mail, até 100 caracteres.
`telefone`	string	Não	Telefone, até 20 caracteres; independente de `celular`.
`celular`	string	Não	Celular, até 20 caracteres; independente de `telefone`.
`endereco`	object	Não	Endereço principal; campos descritos na tabela abaixo.
`referenciaExterna`	string	Não	ID da pessoa no ERP parceiro, até 100 caracteres. Deve ser único para `X-Sistema-Origem`.
`observacoes`	string	Não	Observações, até 1000 caracteres.

Campos de `endereco` — também usados no PATCH

Campo	Tipo	Obrigatório	Descrição
`endereco.cep`	string	Não	CEP, até 10 caracteres.
`endereco.logradouro`	string	Não	Rua/avenida, até 200 caracteres.
`endereco.numero`	string	Não	Número, até 50 caracteres.
`endereco.complemento`	string	Não	Complemento, até 100 caracteres.
`endereco.bairro`	string	Não	Bairro, até 100 caracteres.
`endereco.municipio`	string	Não	Nome do município, até 100 caracteres.
`endereco.uf`	string	Não	UF, 2 caracteres.
`endereco.codigoMunicipioIbge`	integer	Não	Código IBGE do município.

Resposta 201/200

Campo	Tipo	Nulo?	Descrição
`id`	UUID	Não	ID interno da pessoa; use em PATCH.
`nome`	string	Não	Nome ou razão social gravada.
`tipoPessoa`	string	Não	`PF`, `PJ` ou `AVULSO`.
`cpf` / `cnpj`	string	Sim	Documento correspondente à natureza da pessoa.
`email`	string	Sim	E-mail gravado.
`telefone` / `celular`	string	Sim	Contatos gravados, em campos separados.
`referenciaExterna`	string	Sim	Referência enviada na criação, quando informada.

Atualizar pessoa

PATCH /v1/operacoes/pessoas/{id}

Responde 200 com o mesmo formato de pessoa acima; pessoa inexistente responde 404.

Rota e headers

Campo	Tipo	Obrigatório	Descrição
`id`	UUID	Sim	ID interno retornado ao criar a pessoa; vai na URL.
`Authorization`	Bearer JWT	Sim	Escopo `pessoas.gravar` ou `pessoas.atualizar`.
`Idempotency-Key`	UUID	Sim	UUID novo para esta atualização.
`X-Empresa-Id`	UUID	Sim	Empresa permitida na chave.
`X-Sistema-Origem`	string	Não	Padrão `ERP_PARCEIRO`.

Corpo enviado

Campo	Tipo	Obrigatório	Descrição
`nome`	string	Não	Novo nome/razão social, até 200 caracteres.
`email`	string	Não	Novo e-mail, até 100 caracteres.
`telefone`	string	Não	Novo telefone, até 20 caracteres.
`celular`	string	Não	Novo celular, até 20 caracteres.
`observacoes`	string	Não	Novas observações, até 1000 caracteres.
`endereco`	object	Não	Atualiza o endereço principal; subcampos estão na tabela da criação.

O PATCH preserva campos omitidos; valores nulos ou vazios não apagam os dados atuais. CPF, CNPJ, tipoPessoa, tipo e referenciaExterna não são alteráveis por esta rota. No retorno atual do PATCH, referenciaExterna vem null, mesmo que a pessoa tenha referência cadastrada; isso não remove o vínculo.

Consultar catálogo de serviços

GET /v1/operacoes/servicos/catalogo

Expõe o código canônico, a hierarquia e os tipos de produto esperados para cada serviço. Não é uma tabela de preços nem informa quais serviços foram habilitados por empresa.

Envio

Campo	Local / tipo	Obrigatório	Descrição
`Authorization`	Header · Bearer	Sim	Token com `consulta.*` ou `vendas.consultar`.
`empresaId`	Query · UUID	Sim	Empresa permitida na chave.

Resposta 200

Campo	Tipo	Nulo?	Descrição
`servicos[]`	object[]	Não	Serviços do catálogo.
`servicos[].id`	UUID	Sim	ID do serviço cadastrado; pode ser nulo quando o item canônico ainda não está materializado.
`servicos[].codigo`	string	Não	Código estável para integração, como `TROCA_OLEO_MOTOR`.
`servicos[].nome`	string	Não	Nome exibido ao usuário.
`servicos[].categoria`	string	Não	Categoria funcional do catálogo.
`servicos[].servicoPaiId`	UUID	Sim	ID cadastral do serviço pai, quando há vínculo e cadastro disponível.
`servicos[].servicoPaiCodigo`	string	Sim	Código canônico do serviço pai; útil mesmo quando o ID é nulo.
`servicos[].produtosEsperados[]`	object[]	Não	Tipos de produto associados ao serviço; não são produtos de uma venda.
`servicos[].produtosEsperados[].codigo`	string	Não	Código do tipo de produto esperado.
`servicos[].produtosEsperados[].nome`	string	Não	Nome do tipo de produto.
`servicos[].produtosEsperados[].grupoCodigo`	string	Sim	Código de grupo recomendado, quando mapeado.
`servicos[].produtosEsperados[].subgrupoCodigo`	string	Sim	Código de subgrupo recomendado, quando mapeado.

Na venda, servicos[].codigo identifica o serviço histórico e itens[].servicoComponenteId identifica o componente associado ao produto. servicoPaiId do catálogo é diferente de itemPedidoServicoPaiId de uma linha de venda.

Listar vendas

GET /v1/operacoes/vendas

Consulta vendas e OSs por período. Cada registro em vendas[] usa o contrato completo detalhado abaixo.

Envio

Campo	Local / tipo	Obrigatório	Descrição
`Authorization`	Header · Bearer	Sim	Token com `vendas.consultar` ou `consulta.*`.
`empresaId`	Query · UUID	Sim	Empresa permitida na chave.
`inicio`	Query · data/hora	Sim para consulta útil	Início do intervalo ISO 8601 UTC; use com `fim`.
`fim`	Query · data/hora	Sim para consulta útil	Fim do intervalo ISO 8601 UTC. Janela máxima: 31 dias.
`pagina`	Query · integer	Não	Página iniciada em 1; padrão 1.
`limite`	Query · integer	Não	Itens por página; padrão 100, limitado a 1–100.
`sistemaOrigem`	Query · string	Não	Padrão `ERP_PARCEIRO`. Controla qual vínculo externo preenche `itens[].idExterno`.

Resposta 200

Campo	Tipo	Nulo?	Descrição
`pagina`	integer	Não	Página retornada.
`limite`	integer	Não	Tamanho aplicado à página.
`total`	integer	Não	Quantidade total de vendas no filtro, antes da paginação.
`vendas[]`	object[]	Não	Vendas da página; veja todos os campos de cada venda.

Detalhar venda

GET /v1/operacoes/vendas/{numero}

Retorna uma venda diretamente, sem envelope vendas[]. Responde 404 se não encontrada na empresa.

Envio

Campo	Local / tipo	Obrigatório	Descrição
`Authorization`	Header · Bearer	Sim	Token com `vendas.consultar` ou `consulta.*`.
`numero`	Rota · string	Sim	Número comercial da venda/OS; a API também aceita o UUID interno como alternativa.
`empresaId`	Query · UUID	Sim	Empresa permitida na chave.
`sistemaOrigem`	Query · string	Não	Padrão `ERP_PARCEIRO`; seleciona o mapeamento de `idExterno` dos produtos.

Resposta 200

Objeto de venda com todos os campos abaixo. Não é apenas um resumo: inclui itens, serviços, preços, pagamentos e documentos fiscais quando existentes.

Campos do objeto de venda

O mesmo objeto aparece em vendas[] da listagem e como resposta direta do detalhe. A ligação é feita por IDs: itens[].itemPedidoServicoId aponta para servicos[].id. Um item sem serviço tem esse ID nulo.

Venda e cliente

Campo	Tipo	Nulo?	Descrição
`id`	UUID	Não	ID interno da venda.
`numero`	string	Não	Número comercial para consultar o detalhe.
`empresaId`	UUID	Não	Empresa proprietária.
`status`	string	Não	Estado operacional em maiúsculas, como `ABERTA`, `FINALIZADA`, `CANCELADA`, `TRANSFERIDA`, `PREVENDA`, `PROPOSTA`, `PERDIDA` ou `AGUARDANDOPAGAMENTO`. Não é o status fiscal.
`data`	data/hora	Não	Data de fechamento, quando existe; caso contrário, data de criação.
`plataforma`	string	Não	Origem operacional, por exemplo `PDV`, `RETAGUARDA`, `SITEPROPRIO`, `IFOOD` ou `WHATSAPP`.
`tipo`	string	Sim	Tipo comercial, por exemplo `BALCAO`, `MESA`, `COMANDA`, `DELIVERY` ou `OFICINA`.
`cliente`	object	Não	Dados do cliente na venda.
`cliente.id`	UUID	Sim	ID do cadastro de pessoa, quando vinculado.
`cliente.nome`	string	Não	Nome apresentado na venda.
`cliente.cpf`	string	Sim	CPF do cliente, se houver.
`cliente.cnpj`	string	Sim	CNPJ do cliente, se houver.
`cliente.telefone`	string	Sim	Telefone disponível para o cliente.
`veiculo`	object	Sim	Veículo associado à OS, quando existe.
`observacoes`	string	Sim	Observações registradas na venda.

Veículo

Campo	Tipo	Nulo?	Descrição
`veiculo.placa`	string	Não*	Placa do veículo quando `veiculo` existe.
`veiculo.marca`	string	Não*	Marca apresentada.
`veiculo.modelo`	string	Não*	Modelo apresentado.
`veiculo.versao`	string	Sim	Versão do veículo, quando conhecida.
`veiculo.ano`	integer	Sim	Ano do veículo, quando conhecido.
`veiculo.odometroKm`	integer	Sim	Odômetro em quilômetros registrado na OS.
`veiculo.codigoFipe`	string	Sim	Código FIPE do cadastro do veículo (ex.: `004504-7`); `null` se não informado. Preserve zeros à esquerda e o hífen.

* Estes campos pertencem ao objeto veiculo; o objeto inteiro pode ser nulo numa venda sem veículo.

Produtos em `itens[]`

Campo	Tipo	Nulo?	Descrição
`itens[]`	object[]	Não	Linhas de produtos, inclusive vinculadas a serviços; vazio se não há produtos.
`itens[].produtoId`	UUID	Não	ID do produto no LubConsulta.
`itens[].idExterno`	string	Sim	ID do produto no `sistemaOrigem` consultado; nulo se não houver mapeamento.
`itens[].sku`	string	Sim	SKU cadastrado.
`itens[].nome`	string	Não	Nome do produto na linha.
`itens[].unidade`	string	Não	Unidade vendida.
`itens[].quantidade`	decimal	Não	Quantidade vendida; pode ser fracionada.
`itens[].precoUnitario`	decimal	Não	Preço por unidade em reais.
`itens[].desconto`	decimal	Não	Desconto dessa linha em reais.
`itens[].acrescimo`	decimal	Não	Acréscimo dessa linha em reais.
`itens[].valorTotal`	decimal	Não	Total da linha após ajustes.
`itens[].itemPedidoServicoId`	UUID	Sim	ID da linha de mão de obra em `servicos[].id` à qual o produto foi ligado; nulo para produto avulso.
`itens[].servicoComponenteId`	UUID	Sim	ID cadastral do componente/tipo de serviço que classificou o produto (ex.: filtro de óleo). Não é a linha cobrada.

Mão de obra em `servicos[]`

Campo	Tipo	Nulo?	Descrição
`servicos[]`	object[]	Não	Linhas de serviço cobradas na venda; vazio se não houver.
`servicos[].id`	UUID	Não	ID desta linha da venda. É o alvo de `itens[].itemPedidoServicoId`.
`servicos[].servicoId`	UUID	Não	ID do serviço cadastrado no catálogo.
`servicos[].codigo`	string	Sim	Código canônico do serviço, quando disponível no histórico.
`servicos[].nome`	string	Não	Nome da mão de obra na venda.
`servicos[].itemPedidoServicoPaiId`	UUID	Sim	ID de outra linha em `servicos[].id` que é pai desta linha; não é `servicoPaiId` cadastral.
`servicos[].quantidade`	decimal	Não	Quantidade do serviço.
`servicos[].precoUnitario`	decimal	Não	Preço unitário da mão de obra em reais.
`servicos[].valorTotal`	decimal	Não	Valor total desta linha de serviço.

Exemplo de vínculo: procure uma linha de itens[] cujo itemPedidoServicoId seja igual ao id de uma linha em servicos[]. O produto e a mão de obra têm preços próprios. O componente indica a natureza do produto dentro do serviço e pode ser comparado com o catálogo, mas não substitui essa ligação.

Totais, pagamentos e documentos fiscais

Campo	Tipo	Nulo?	Descrição
`totais`	object	Não	Consolidação monetária da venda.
`totais.subtotal`	decimal	Não	Soma antes dos ajustes gerais.
`totais.desconto`	decimal	Não	Desconto total.
`totais.acrescimo`	decimal	Não	Acréscimo total.
`totais.frete`	decimal	Não	Frete da venda.
`totais.impostos`	decimal	Não	Impostos informados no total.
`totais.total`	decimal	Não	Total final autoritativo da venda em reais.
`pagamentos[]`	object[]	Não	Pagamentos não cancelados. Pode ser `[]` mesmo com venda concluída sem pagamento registrado.
`pagamentos[].forma`	string	Não	Descrição da forma de pagamento; pode vir “Não informado”.
`pagamentos[].valor`	decimal	Não	Valor pago neste registro.
`pagamentos[].parcelas`	integer	Não	Número de parcelas.
`pagamentos[].status`	string	Não	Status do pagamento, como `PENDENTE` ou `CONFIRMADO`; cancelados não entram no array.
`pagamentos[].data`	data/hora	Não	Data do registro de pagamento.
`pagamentos[].referencia`	string	Sim	Referência externa, se houver.
`pagamentos[].autorizacao`	string	Sim	Código de autorização, se houver.
`pagamentos[].bandeira`	string	Sim	Bandeira de cartão, se houver.
`documentosFiscais[]`	object[]	Não	Notas associadas; `[]` se nenhuma foi emitida. Consulta não emite nota.
`documentosFiscais[].numero`	string	Sim	Número da nota, quando atribuído.
`documentosFiscais[].serie`	string	Sim	Série, quando atribuída.
`documentosFiscais[].chaveAcesso`	string	Sim	Chave fiscal, quando disponível.
`documentosFiscais[].modelo`	string	Não	Modelo, como `NFe`, `NFCe` ou `NFSe`.
`documentosFiscais[].situacao`	string	Não	`PENDENTE`, `EMITIDA`, `CANCELADA` ou `ERROEMISSAO`.
`documentosFiscais[].dataEmissao`	data/hora	Não	Data da emissão/registro.
`documentosFiscais[].dataCancelamento`	data/hora	Sim	Data de cancelamento, quando houve.

Não infira o status operacional a partir de pagamentos[] ou documentosFiscais[]. Venda finalizada pode ter saldo a receber, e orçamento/OS em aberto podem não ter pagamento. Use status, tipo e os valores financeiros separadamente.

Erros e saúde

Em falhas de negócio, a API normalmente devolve {"codigo":"...","mensagem":"..."}. Erros automáticos de desserialização ou validação HTTP podem usar o formato Problem Details do ASP.NET; trate o status HTTP como principal e exiba a mensagem quando presente.

Status	Quando ocorre	O que fazer
400	Campo obrigatório, layout/lote inválido, UUID ou JSON malformado.	Corrija a requisição; na importação, confira também `resultados[].pendencias[]`.
401	Chave inválida/revogada ou Bearer ausente/expirado.	Gere um token com uma chave ativa e autorizada.
403	Escopo ou empresa não autorizados.	Confira o vínculo da chave com a empresa e os escopos concedidos.
404	Pessoa ou venda não encontrada na empresa consultada.	Verifique o ID/número e a empresa.
409	Mesma `Idempotency-Key` reutilizada com corpo diferente ou outro conflito.	Para operação nova, gere um UUID novo; para repetição, preserve o corpo original.
422	Regra de negócio ou dados inconsistentes.	Leia `codigo` e `mensagem`; corrija o campo indicado.

Saúde do serviço

GET /health

Sem autenticação, parâmetros ou corpo. Responde 200 quando a aplicação está atendendo; não é uma operação de negócio.

Campo da resposta	Tipo	Valor / significado
`status`	string	`ok`: processo HTTP ativo.
`service`	string	`lubconsulta-connect-api`: identificador do serviço.

Esta rota confirma que a aplicação responde. Ela não faz uma transação de teste nem garante, sozinha, que banco ou integrações externas estão disponíveis.

Campos de cada chamada

Convenções

Consultar grupos e subgrupos

Envio

Resposta 200

Importar produtos

Headers

Corpo enviado — lote

Corpo enviado — cada produtos[]

Objetos de preço e fiscal

Resposta 200

Obter token

Corpo enviado

Resposta 200

Criar pessoa

Headers

Corpo enviado

Campos de endereco — também usados no PATCH

Resposta 201/200

Atualizar pessoa

Rota e headers

Corpo enviado

Consultar catálogo de serviços

Envio

Resposta 200

Listar vendas

Envio

Resposta 200

Detalhar venda

Envio

Resposta 200

Campos do objeto de venda

Venda e cliente

Veículo

Produtos em itens[]

Mão de obra em servicos[]

Totais, pagamentos e documentos fiscais

Erros e saúde

Saúde do serviço

Corpo enviado — cada `produtos[]`

Campos de `endereco` — também usados no PATCH

Produtos em `itens[]`

Mão de obra em `servicos[]`