Documentação oficial

Integre seu ERP ao LubConsulta.

Integre cadastros, consulte vendas e receba notificações de alterações por webhook. Esta referência descreve o contrato da API Connect; o console ao lado envia chamadas reais ao ambiente de produção. Consulte também 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, consulte vendas e configure webhooks conforme os escopos concedidos.

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.*, suficiente para consultar vendas. No painel de Integrações, conceda separadamente os escopos de gravação de cadastros e webhooks.gerenciar apenas à integração que precisa deles. A revogação da chave interrompe imediatamente seu uso, inclusive para tokens emitidos por ela. Criação e conclusão de vendas, recebimento de pagamentos e emissão fiscal pertencem ao fluxo operacional do LubConsulta.

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[]. Para serviços sem cadastro nessa empresa, id é nulo e codigo continua disponível. 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.

Pagamentos e documentos fiscais associados são retornados na consulta da venda quando existirem. As operações de recebimento, criação/conclusão de venda e emissão/cancelamento fiscal são realizadas no LubConsulta, fora da API Connect.

Webhooks de vendas

O LubConsulta notifica seu endpoint HTTPS somente após a primeira conclusão de uma venda e quando essa venda é alterada posteriormente. A criação ou edição de rascunhos e orçamentos não dispara webhooks. Configure o destino no painel Integrações → Chaves da API → Webhooks de vendas ou pelas rotas abaixo, usando uma chave com webhooks.gerenciar e acesso à empresa.

Evento	Significado
`venda.criada`	A venda foi concluída pela primeira vez. Se ela começou como orçamento, este é seu primeiro webhook; alterações na mesma transação compõem a conclusão.
`venda.atualizada`	Uma venda já concluída foi alterada em uma transação posterior, inclusive em pedidos, itens, serviços, pagamentos, documentos fiscais ou situação. Um eventual cancelamento posterior também é informado para manter a integração sincronizada.

Vendas concluídas antes da ativação de um destino não são enviadas retroativamente. Se uma delas mudar depois, o evento será venda.atualizada.

O evento é uma notificação, não uma cópia da venda. Após validar a assinatura, obtenha o estado atual em GET /v1/operacoes/vendas/{vendaId}?empresaId={empresaId}. Se precisar de itens[].idExterno, acrescente sistemaOrigem com o identificador usado na importação de produtos. Várias alterações da mesma venda dentro de uma transação geram, no máximo, uma entrega por tipo de evento e destino. Transações distintas podem gerar notificações sucessivas.

Configurar um destino

POST/v1/webhooks

Cria um destino pausado para uma empresa. Aceita somente URL HTTPS pública na porta 443, sem credenciais, parâmetros de consulta ou fragmento. São permitidos até dez destinos cadastrados, dos quais cinco podem estar ativos. O segredo da resposta é exibido apenas nessa criação; armazene-o em um cofre, configure a validação no seu servidor e então ative o destino por PATCH ou pelo painel.

{ "empresaId": "11111111-1111-4111-8111-111111111111", "url": "https://erp.exemplo.com.br/webhooks/lubconsulta", "eventos": ["venda.criada", "venda.atualizada"] }

Exemplo de resposta 201 Created; a propriedade eventos da resposta é uma lista separada por espaços:

{ "id": "55555555-5555-4555-8555-555555555555", "empresaId": "11111111-1111-4111-8111-111111111111", "url": "https://erp.exemplo.com.br/webhooks/lubconsulta", "eventos": "venda.atualizada venda.criada", "ativo": false, "segredo": "<valor Base64 exibido uma vez>" }

Rota	Uso
`GET /v1/webhooks?empresaId={uuid}`	Lista destinos e eventos cadastrados. Não retorna segredos.
`GET /v1/webhooks/{id}?empresaId={uuid}`	Consulta um destino pelo ID, sem expor o segredo.
`PATCH /v1/webhooks/{id}`	Altera `ativo` e/ou `eventos`; informe `empresaId` no corpo. Para trocar a URL, crie outro destino e pause o anterior.
`DELETE /v1/webhooks/{id}?empresaId={uuid}`	Remove o destino da operação e interrompe suas entregas. O histórico permanece armazenado para auditoria.
`POST /v1/webhooks/{id}/rotacionar-segredo`	Informe `empresaId` no corpo. Retorna o novo segredo uma única vez e invalida o anterior imediatamente.
`GET /v1/webhooks/{id}/entregas?empresaId={uuid}&limite=30`	Consulta as últimas entregas, tentativas, resposta HTTP e estado final; limite entre 1 e 100.
`POST /v1/webhooks/{id}/entregas/{entregaId}/reenviar`	Reagenda uma entrega em estado `falhou` após corrigir o receptor. Informe `empresaId` no corpo; o destino deve estar ativo. A entrega mantém o mesmo ID.

Mensagem recebida

O LubConsulta envia POST com Content-Type: application/json. Os IDs do exemplo são ilustrativos.

X-LubConsulta-Event: venda.criada X-LubConsulta-Delivery-Id: 22222222-2222-4222-8222-222222222222 X-LubConsulta-Timestamp: 1790604000 X-LubConsulta-Signature: sha256=<hexadecimal-hmac-sha256> { "versao": 1, "id": "22222222-2222-4222-8222-222222222222", "evento": "venda.criada", "tipoAlteracao": "nova", "vendaId": "33333333-3333-4333-8333-333333333333", "empresaId": "11111111-1111-4111-8111-111111111111", "organizacaoId": "44444444-4444-4444-8444-444444444444", "ocorridoEm": "2026-09-28T12:00:00Z", "consulta": "/v1/operacoes/vendas/33333333-3333-4333-8333-333333333333?empresaId=11111111-1111-4111-8111-111111111111" }

Em venda.atualizada, tipoAlteracao é alteracao. O campo id do corpo e X-LubConsulta-Delivery-Id identificam a mesma entrega e permanecem iguais em todas as tentativas.

No histórico, pendente aguarda envio ou nova tentativa, processando está reservado por uma instância, entregue recebeu HTTP 2xx, falhou esgotou as tentativas ou recebeu resposta definitiva e cancelado indica destino/evento desativado.

Validar autenticidade e evitar duplicidade

O segredo retornado é Base64. Calcule HMAC-SHA256 com os bytes decodificados desse segredo sobre os bytes UTF-8 de {timestamp}.{corpo JSON bruto}. Compare em tempo constante com o valor hexadecimal do header X-LubConsulta-Signature. Rejeite timestamps fora de uma tolerância de cinco minutos e registre o ID de entrega já processado. A validação deve usar o corpo recebido sem reserializar o JSON; no exemplo Node.js, corpoBruto é um Buffer.

const crypto = require('node:crypto'); const base = Buffer.concat([Buffer.from(timestamp + '.', 'utf8'), corpoBruto]); const assinaturaEsperada = 'sha256=' + crypto.createHmac('sha256', Buffer.from(segredo, 'base64')) .update(base).digest('hex'); const recebida = Buffer.from(assinaturaHeader, 'utf8'); const esperada = Buffer.from(assinaturaEsperada, 'utf8'); const valida = recebida.length === esperada.length && crypto.timingSafeEqual(recebida, esperada);

Responda 2xx somente depois de registrar o evento de forma durável. A entrega é pelo menos uma vez: use id como chave de deduplicação e não dependa da ordem de chegada. Respostas 408, 429, 5xx e falhas de rede são repetidas com espera progressiva, até 12 tentativas, com intervalos crescentes limitados a duas horas. Redirecionamentos 3xx não são seguidos; eles e os demais 4xx encerram a entrega. Ao pausar um destino ou remover um evento, suas entregas pendentes são canceladas. Após corrigir o receptor, reenvie uma entrega com falha pelo painel ou pela API.

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.
Webhooks	Até dez destinos cadastrados e cinco ativos por empresa; HTTPS público na porta 443; 10 segundos para resposta; entrega pelo menos uma vez.

Erros

Erros de negócio da API Connect são retornados com codigo e mensagem. Erros de validação automática e autenticação do framework podem usar o formato Problem Details; trate também o status HTTP e os campos title, detail e errors quando presentes.

{ "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.