{"openapi":"3.1.0","info":{"title":"Vero IA Hub API","description":"API central do **Vero Monitor PDV**.\n\n**Integrações de vendas:** consulte o [Guia de integração — POST /bi/movimentos](https://claude.ai/code/artifact/e40eecf9-f632-416b-9011-091e37375891) para o passo a passo completo de envio de cupons fiscais.","version":"2.1.0"},"paths":{"/bi/operadores":{"post":{"tags":["BI Vendas"],"summary":"Cadastro de operadores","description":"Cadastro e atualização de operadores.","operationId":"receber_operadores_bi_operadores_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API gerado no portal Varejo IA","title":"Api-Key"},"description":"Token de API gerado no portal Varejo IA"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ItemOperador"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"protocolo":"b1e2c3d4-5f6a-7b8c-9d0e-1f2a3b4c5d6e","status":"recebido","itens":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, dados de algum operador inválidos, ou loja (tenant) não encontrada/inativa.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"loja_invalida":{"summary":"Loja (tenant) não encontrada ou inativa","value":{"detail":"Loja não encontrada ou inativa."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum item","value":{"detail":[{"loc":["body",0,"codigo"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou processar o lote. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_processamento":{"summary":"Falha ao enfileirar os dados para processamento","value":{"detail":"Erro ao enfileirar dados. Tente novamente."}}}}}}},"x-endpoint-key":"bi.operadores"}},"/bi/supervisores":{"post":{"tags":["BI Vendas"],"summary":"Cadastro de supervisores","description":"Cadastro e atualização de supervisores.","operationId":"receber_supervisores_bi_supervisores_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API gerado no portal Varejo IA","title":"Api-Key"},"description":"Token de API gerado no portal Varejo IA"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ItemSupervisor"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"protocolo":"b1e2c3d4-5f6a-7b8c-9d0e-1f2a3b4c5d6e","status":"recebido","itens":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, dados de algum supervisor inválidos, ou loja (tenant) não encontrada/inativa.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"loja_invalida":{"summary":"Loja (tenant) não encontrada ou inativa","value":{"detail":"Loja não encontrada ou inativa."}},"codigo_com_letra":{"summary":"Campo `codigo` com letra (só é aceito número)","value":{"detail":[{"loc":["body",0,"codigo"],"msg":"Formato inválido.","type":"string_pattern_mismatch"}]}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum item","value":{"detail":[{"loc":["body",0,"codigo"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou processar o lote. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_processamento":{"summary":"Falha ao enfileirar os dados para processamento","value":{"detail":"Erro ao enfileirar dados. Tente novamente."}}}}}}},"x-endpoint-key":"bi.supervisores"}},"/bi/produtos":{"post":{"tags":["BI Vendas"],"summary":"Cadastro de produtos","description":"Cadastro e atualização de produtos.","operationId":"receber_produtos_bi_produtos_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API gerado no portal Varejo IA","title":"Api-Key"},"description":"Token de API gerado no portal Varejo IA"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ItemProduto"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"protocolo":"b1e2c3d4-5f6a-7b8c-9d0e-1f2a3b4c5d6e","status":"recebido","itens":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, limite de itens excedido, dados de algum produto inválidos, ou loja (tenant) não encontrada/inativa.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"limite_excedido":{"summary":"Mais de 100.000 produtos na mesma chamada","value":{"detail":"Limite de 100.000 produtos por requisição."}},"loja_invalida":{"summary":"Loja (tenant) não encontrada ou inativa","value":{"detail":"Loja não encontrada ou inativa."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum item","value":{"detail":[{"loc":["body",0,"cdprod"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou processar o lote. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_processamento":{"summary":"Falha ao enfileirar os dados para processamento","value":{"detail":"Erro ao enfileirar dados. Tente novamente."}}}}}}},"x-endpoint-key":"bi.produtos"}},"/bi/produtos-precos":{"post":{"tags":["BI Vendas"],"summary":"Enviar custo/preço de produto por loja","description":"Cadastra ou atualiza o custo/preço de venda de um produto, com recorte por loja — para uso quando o custo ou o preço varia entre as unidades da mesma rede (ex: uma filial compra do fornecedor com um frete diferente, ou pratica um preço de venda diferente por região).\n\n**Opcional:** só use este endpoint se o seu sistema realmente guarda custo/preço por loja. Se todo o catálogo tem um único custo/preço vigente pra rede inteira, basta o campo `custo` em `/bi/produtos` — não é necessário chamar este endpoint.\n\nAceita as variantes de custo mais comuns em sistemas de varejo — preencha só as que fizerem sentido pro seu sistema, o restante fica vazio: custo sem imposto, custo com imposto, custo médio (ponderado pelas últimas entradas) sem/com imposto, e preço de venda.\n\nCada chamada substitui o valor vigente daquele produto/loja — o histórico de mudanças é mantido automaticamente pelo BI, sem esforço adicional do seu lado.\n\n**Exemplo real:** uma rede de 5 lojas negocia o mesmo produto com fornecedores diferentes por região — o custo em uma loja é R$ 12,50 e em outra é R$ 14,20. Sem este endpoint, o BI trataria as duas lojas como se tivessem o mesmo custo, distorcendo a margem calculada pra cada unidade.","operationId":"receber_produtos_precos_bi_produtos_precos_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API gerado no portal Varejo IA","title":"Api-Key"},"description":"Token de API gerado no portal Varejo IA"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ItemProdutoPreco"},"title":"Payload"}}}},"responses":{"200":{"description":"Lote enfileirado.","content":{"application/json":{"schema":{},"example":{"protocolo":"b1e2c3d4-5f6a-7b8c-9d0e-1f2a3b4c5d6e","status":"enfileirado","itens":1}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-endpoint-key":"bi.produtos-precos"}},"/bi/produtos-codigos-barras":{"post":{"tags":["BI Vendas"],"summary":"Enviar códigos de barra adicionais","description":"Cadastra códigos de barras adicionais de um produto, além do código principal já enviado em `/bi/produtos` (campo `codbarra`) — para uso quando o mesmo produto é vendido/embalado de mais de uma forma (unidade, caixa fechada, fardo, etc.), cada uma com seu próprio código de barras.\n\n**Opcional:** só use este endpoint se o seu sistema realmente tiver mais de um código de barras por produto. Se cada produto tem um único código, o campo `codbarra` em `/bi/produtos` já é suficiente.\n\nCada código de barras pertence a exatamente um produto (`cdprod`) — usado, por exemplo, para reconhecer automaticamente o produto a partir da leitura de um código de barras (foto, leitor óptico), mesmo quando o código lido não é o \"principal\" cadastrado.\n\n**Exemplo real:** um produto vendido tanto na unidade (um código) quanto em caixa fechada de 12 unidades (outro código, lido quando o PDV bipa a caixa no atacado) — sem este endpoint, a leitura do código da caixa fechada não seria reconhecida como o mesmo produto.","operationId":"receber_produtos_codigos_barras_bi_produtos_codigos_barras_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API gerado no portal Varejo IA","title":"Api-Key"},"description":"Token de API gerado no portal Varejo IA"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ItemProdutoCodigoBarras"},"title":"Payload"}}}},"responses":{"200":{"description":"Lote enfileirado.","content":{"application/json":{"schema":{},"example":{"protocolo":"b1e2c3d4-5f6a-7b8c-9d0e-1f2a3b4c5d6e","status":"enfileirado","itens":1}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-endpoint-key":"bi.produtos-codigos-barras"}},"/bi/divisoes-mercadologicas":{"post":{"tags":["BI Vendas"],"summary":"Cadastro de divisões mercadológicas","description":"Cadastro e atualização de divisões mercadológicas.","operationId":"receber_divisoes_bi_divisoes_mercadologicas_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API gerado no portal Varejo IA","title":"Api-Key"},"description":"Token de API gerado no portal Varejo IA"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ItemDivisao"},"title":"Payload"},"examples":{"tipos_misturados":{"summary":"Tipos misturados (departamentos, grupos, armação e marca)","description":"Envie todos os tipos em um único array.","value":[{"tipo":"departamento","codigo":"01","descricao":"MERCEARIA"},{"tipo":"departamento","codigo":"02","descricao":"FRIOS E LATICINIOS"},{"tipo":"grupo","codigo":"101","descricao":"BISCOITOS"},{"tipo":"grupo","codigo":"201","descricao":"QUEIJOS"},{"tipo":"armacao","codigo":"A01","descricao":"GONDOLA CENTRAL 01"},{"tipo":"marca","codigo":"M01","descricao":"NESTLE"}]},"so_departamentos":{"summary":"Apenas departamentos","value":[{"tipo":"departamento","codigo":"01","descricao":"MERCEARIA"},{"tipo":"departamento","codigo":"02","descricao":"FRIOS E LATICINIOS"}]}}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"protocolo":"b1e2c3d4-5f6a-7b8c-9d0e-1f2a3b4c5d6e","status":"recebido","itens":6}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, tipo desconhecido, dados de algum item inválidos, ou loja (tenant) não encontrada/inativa.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"tipo_invalido":{"summary":"Campo `tipo` fora da lista permitida","value":{"detail":[{"loc":["body",0,"tipo"],"msg":"tipo deve ser um de: departamento, grupo, armacao, marca.","type":"value_error"}]}},"loja_invalida":{"summary":"Loja (tenant) não encontrada ou inativa","value":{"detail":"Loja não encontrada ou inativa."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum item","value":{"detail":[{"loc":["body",0,"codigo"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou processar o lote. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_processamento":{"summary":"Falha ao enfileirar os dados para processamento","value":{"detail":"Erro ao enfileirar dados. Tente novamente."}}}}}}},"x-endpoint-key":"bi.divisoes"}},"/bi/movimentos":{"post":{"tags":["BI Vendas"],"summary":"Enviar cupons fiscais completos","description":"Enfileira cupons fiscais completos para gravação em **`fato_vendas`**.\n\nCada cupom contém:\n- **capa** — cabeçalho com identificação, operador, NFC-e e cancelamento\n- **itens** — produtos vendidos → geram linhas `status='01'` (alimenta `fato_cmv`)\n- **pagamentos** — formas de pagamento → geram linhas `status='03'` (alimenta `fato_pagamentos`)\n\n**Protocolo de rastreamento:** formato `YYYYMMDD-{id:010d}` (ex: `20260619-0000000001`). Use `GET /bi/movimentos/{protocolo}` para consultar o status do processamento e recuperar o payload enviado.\n\n**Campos extras:** cada item e cada pagamento aceitam um campo `dados_extras` (dicionário livre) que é mesclado em `dados_adicionais`. Os campos do padrão sempre têm precedência.\n\n**Idempotência:** cupons com mesma combinação `(tenant_id, loja, caixa, cupom, data)` substituem o registro anterior em `fato_vendas` — a data entra na chave porque o número de cupom do PDV pode se repetir em períodos diferentes (reinício de contador do ECF).\n\n**Limite:** máximo de 1.000 cupons por requisição. Envie lotes menores se necessário.\n\n**Corte temporal:** cupons com `data_hora` anterior à `data_inicio_importacao` configurada para a loja são silenciosamente descartados. Se todos os cupons forem descartados, retorna `status='sem_dados'` sem protocolo.","operationId":"receber_cupons_bi_movimentos_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API gerado no portal Varejo IA","title":"Api-Key"},"description":"Token de API gerado no portal Varejo IA"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CupomCompleto"},"title":"Payload"},"examples":{"exemplo_real":{"summary":"Cupom completo — 1 item + 1 pagamento","description":"Cupom 100345 com 1 item e pagamento em dinheiro.","value":[{"capa":{"loja":1,"caixa":2,"cupom":100345,"data_hora":"2025-06-15T14:32:00","operador":"42","supervisor":"10","cancelado":"N","motivo_cancelamento":"","nfce_chave":"35250612345678000100650010001003451234567890","nfce_numero":"1003","nfce_serie":"001","nfce_protocolo":"135250612345678","valor_total_cupom":11.98,"valor_desconto_cupom":0.0,"valor_acrescimo_cupom":0.0},"itens":[{"item":1,"cdprod":"PRD001","desprod":"LEITE INTEGRAL 1L","quant":2.0,"preco":5.99,"valortot":11.98,"precocusto":3.5,"descitem":0.0,"descprcamp":0.0,"descprmult":0.0,"descontoScanntech":0.0,"desccupom":0.0,"valorIBS_UF":0.0,"valorCBS":0.0,"valorIS":0.0,"dados_extras":{"referencia_interna":"REF-001","codigo_promocao":"PROMO10"}}],"pagamentos":[{"tipopagto":1,"valor":11.98,"bandeiratef":"","instituicaotef":"","nsu":"","parcelas":1,"dados_extras":{}}]}]}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaMovimentos"},"examples":{"enfileirado":{"summary":"Lote aceito","value":{"protocolo":"20260619-0000000001","status":"enfileirado","itens":2}},"sem_dados":{"summary":"Todos anteriores ao corte","value":{"status":"sem_dados","mensagem":"Nenhum cupom dentro do periodo configurado."}}}}}},"403":{"description":"Token invalido ou sem permissao para bi.movimentos"},"422":{"description":"Payload invalido ou limite excedido (1.000 cupons)"},"503":{"description":"Erro ao enfileirar no Kafka"}},"x-endpoint-key":"bi.movimentos"}},"/bi/movimentos/{protocolo}":{"get":{"tags":["BI Vendas"],"summary":"Consulta de lote de movimento","description":"Retorna o recibo do lote relacionado ao protocolo enviado em <code style=\"background:rgba(90,24,154,.08);color:#5a189a;padding:1px 6px;border-radius:4px;font-weight:600;\">POST /bi/movimentos</code>.","operationId":"consultar_lote_cupons_bi_movimentos__protocolo__get","parameters":[{"name":"protocolo","in":"path","required":true,"schema":{"type":"string","title":"Protocolo"}},{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API gerado no portal Varejo IA","title":"Api-Key"},"description":"Token de API gerado no portal Varejo IA"}],"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"protocolo":"20260619-0000000001","tenant_id":42,"tipo":"movimentos","total_cupons":2,"total_linhas":5,"status":"processado","recebido_em":"2026-06-19T14:32:00","processado_em":"2026-06-19T14:33:10","payload_json":[]}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"404":{"description":"Protocolo não encontrado.","content":{"application/json":{"example":{"detail":"Protocolo não encontrado."}}}},"422":{"description":"Loja (tenant) não encontrada ou inativa.","content":{"application/json":{"example":{"detail":"Loja não encontrada ou inativa."}}}},"503":{"description":"Erro interno ao consultar o lote ou validar a loja. Tente novamente.","content":{"application/json":{"example":{"detail":"Erro ao consultar lote."}}}}},"x-endpoint-key":"bi.movimentos"}},"/bi/fornecedores":{"post":{"tags":["BI Compras"],"summary":"Cadastro de fornecedores","description":"Cadastro e atualização de fornecedores.","operationId":"receber_fornecedores_bi_fornecedores_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API","title":"Api-Key"},"description":"Token de API"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FornecedorIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","recebidos":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, dados de algum fornecedor inválidos, loja (tenant) não encontrada/inativa, ou token sem loja vinculada (ex.: CHAVE_MESTRE).","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"loja_invalida":{"summary":"Loja (tenant) não encontrada ou inativa","value":{"detail":"Loja não encontrada ou inativa."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum item","value":{"detail":[{"loc":["body",0,"erp_codigo"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar os fornecedores. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar fornecedores."}}}}}}},"x-endpoint-key":"bi.fornecedores"}},"/bi/compradores":{"post":{"tags":["BI Compras"],"summary":"Cadastro de compradores","description":"Cadastro e atualização de compradores.","operationId":"receber_compradores_bi_compradores_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API","title":"Api-Key"},"description":"Token de API"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CompradorIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","recebidos":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, dados de algum comprador inválidos, loja (tenant) não encontrada/inativa, ou token sem loja vinculada (ex.: CHAVE_MESTRE).","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"loja_invalida":{"summary":"Loja (tenant) não encontrada ou inativa","value":{"detail":"Loja não encontrada ou inativa."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum item","value":{"detail":[{"loc":["body",0,"erp_codigo"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar os compradores. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar compradores."}}}}}}},"x-endpoint-key":"bi.compradores"}},"/bi/pedidos-compra":{"post":{"tags":["BI Compras"],"summary":"Cadastro de pedidos de compra","description":"Cadastro e atualização de pedidos de compra.","operationId":"receber_pedidos_compra_bi_pedidos_compra_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API","title":"Api-Key"},"description":"Token de API"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PedidoCompraIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","pedidos":1,"itens":2}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, limite de pedidos/itens excedido, fornecedor não cadastrado, dados inválidos, loja (tenant) não encontrada/inativa, ou token sem loja vinculada.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"limite_pedidos":{"summary":"Mais de 1000 pedidos na mesma chamada","value":{"detail":"Limite de 1000 pedidos por requisição."}},"limite_itens":{"summary":"Mais de 20000 itens somados na mesma chamada","value":{"detail":"Limite de 20000 itens por requisição."}},"fornecedor_nao_cadastrado":{"summary":"fornecedor_id não cadastrado via /bi/fornecedores","value":{"detail":"Fornecedor(es) com erp_codigo [1234] não encontrado(s). Envie /bi/fornecedores antes."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"loja_invalida":{"summary":"Loja (tenant) não encontrada ou inativa","value":{"detail":"Loja não encontrada ou inativa."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum pedido ou item","value":{"detail":[{"loc":["body",0,"numero_pedido"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar os pedidos de compra. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar pedidos de compra."}}}}}}},"x-endpoint-key":"bi.pedidos-compra"}},"/bi/notas-entrada":{"post":{"tags":["BI Compras"],"summary":"Cadastro de notas de entrada","description":"Cadastro e atualização de notas de entrada.","operationId":"receber_notas_entrada_bi_notas_entrada_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API","title":"Api-Key"},"description":"Token de API"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NotaEntradaIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","notas":1,"itens":3}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, limite de notas/itens excedido, fornecedor não cadastrado, dados inválidos, loja (tenant) não encontrada/inativa, ou token sem loja vinculada.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"limite_notas":{"summary":"Mais de 1000 notas na mesma chamada","value":{"detail":"Limite de 1000 notas por requisição."}},"limite_itens":{"summary":"Mais de 20000 itens somados na mesma chamada","value":{"detail":"Limite de 20000 itens por requisição."}},"fornecedor_nao_cadastrado":{"summary":"fornecedor_id não cadastrado via /bi/fornecedores","value":{"detail":"Fornecedor(es) com erp_codigo [1234] não encontrado(s). Envie /bi/fornecedores antes."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"loja_invalida":{"summary":"Loja (tenant) não encontrada ou inativa","value":{"detail":"Loja não encontrada ou inativa."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em alguma nota ou item","value":{"detail":[{"loc":["body",0,"numero_nota"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja, remover notas duplicadas ou gravar as notas de entrada. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco (inclui dedup por chave_nfe)","value":{"detail":"Erro ao gravar notas de entrada."}}}}}}},"x-endpoint-key":"bi.notas-entrada"}},"/bi/contas-pagar":{"post":{"tags":["BI Financeiro"],"summary":"Cadastro de contas a pagar","description":"Cadastro e atualização de contas a pagar. `pagto` nulo indica título em aberto.","operationId":"receber_contas_pagar_bi_contas_pagar_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API (mesmo de /bi/movimentos)","title":"Api-Key"},"description":"Token de API (mesmo de /bi/movimentos)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ContaPagarIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","recebidos":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, limite excedido, dados inválidos, ou token sem loja vinculada.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"limite_excedido":{"summary":"Mais de 5000 títulos na mesma chamada","value":{"detail":"Limite de 5000 títulos por requisição."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum título","value":{"detail":[{"loc":["body",0,"erp_id"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar contas a pagar. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar contas a pagar."}}}}}}},"x-endpoint-key":"bi.contas-pagar"}},"/bi/contas-receber":{"post":{"tags":["BI Financeiro"],"summary":"Cadastro de contas a receber","description":"Cadastro e atualização de contas a receber. `recebimento` nulo indica título em aberto; `previsao_rec` alimenta o fluxo de caixa e `convenio` o fiado.","operationId":"receber_contas_receber_bi_contas_receber_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API (mesmo de /bi/movimentos)","title":"Api-Key"},"description":"Token de API (mesmo de /bi/movimentos)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ContaReceberIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","recebidos":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, limite excedido, dados inválidos, ou token sem loja vinculada.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"limite_excedido":{"summary":"Mais de 5000 títulos na mesma chamada","value":{"detail":"Limite de 5000 títulos por requisição."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum título","value":{"detail":[{"loc":["body",0,"erp_id"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar contas a receber. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar contas a receber."}}}}}}},"x-endpoint-key":"bi.contas-receber"}},"/bi/recebimentos-pdv":{"post":{"tags":["BI Financeiro"],"summary":"Cadastro de recebimentos do PDV","description":"Cadastro e atualização de recebimentos do PDV (como cada cupom foi pago).","operationId":"receber_recebimentos_pdv_bi_recebimentos_pdv_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API","title":"Api-Key"},"description":"Token de API"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RecebimentoPdvIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","recebidos":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, limite excedido, dados inválidos, ou token sem loja vinculada.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"limite_excedido":{"summary":"Mais de 5000 registros na mesma chamada","value":{"detail":"Limite de 5000 registros por requisição."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum registro","value":{"detail":[{"loc":["body",0,"erp_id"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar recebimentos PDV. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar recebimentos PDV."}}}}}}},"x-endpoint-key":"bi.recebimentos-pdv"}},"/bi/movimentos-tef":{"post":{"tags":["BI Financeiro"],"summary":"Cadastro de transações TEF","description":"Cadastro e atualização de transações TEF (com NSU).","operationId":"receber_movimentos_tef_bi_movimentos_tef_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API","title":"Api-Key"},"description":"Token de API"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MovimentoTefIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","recebidos":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, limite excedido, dados inválidos, ou token sem loja vinculada.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"limite_excedido":{"summary":"Mais de 5000 registros na mesma chamada","value":{"detail":"Limite de 5000 registros por requisição."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum registro","value":{"detail":[{"loc":["body",0,"erp_id"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar movimentos TEF. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar movimentos TEF."}}}}}}},"x-endpoint-key":"bi.movimentos-tef"}},"/bi/movimentos-bancarios":{"post":{"tags":["BI Financeiro"],"summary":"Cadastro de movimentos bancários","description":"Cadastro e atualização de movimentos bancários (extrato + conciliação).","operationId":"receber_movimentos_bancarios_bi_movimentos_bancarios_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API","title":"Api-Key"},"description":"Token de API"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MovimentoBancarioIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","recebidos":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, limite excedido, dados inválidos, ou token sem loja vinculada.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"limite_excedido":{"summary":"Mais de 5000 registros na mesma chamada","value":{"detail":"Limite de 5000 registros por requisição."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum registro","value":{"detail":[{"loc":["body",0,"erp_id"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar movimentos bancários. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar movimentos bancários."}}}}}}},"x-endpoint-key":"bi.movimentos-bancarios"}},"/bi/bancos":{"post":{"tags":["BI Financeiro"],"summary":"Cadastro de bancos e contas correntes","description":"Cadastro e atualização de bancos e contas correntes.","operationId":"receber_bancos_bi_bancos_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API","title":"Api-Key"},"description":"Token de API"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BancoIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","recebidos":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, dados inválidos, ou token sem loja vinculada.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum registro","value":{"detail":[{"loc":["body",0,"erp_codigo"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar bancos. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar bancos."}}}}}}},"x-endpoint-key":"bi.bancos"}},"/bi/taxas-cartao":{"post":{"tags":["BI Financeiro"],"summary":"Cadastro de taxas de cartão (MDR)","description":"Cadastro e atualização de taxas de cartão (MDR por rede × bandeira × parcelas).","operationId":"receber_taxas_cartao_bi_taxas_cartao_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API","title":"Api-Key"},"description":"Token de API"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaxaCartaoIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","recebidos":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, dados inválidos, ou token sem loja vinculada.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum registro","value":{"detail":[{"loc":["body",0,"erp_codigo"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar taxas de cartão. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar taxas de cartão."}}}}}}},"x-endpoint-key":"bi.taxas-cartao"}},"/bi/estoque-saldo":{"post":{"tags":["BI Financeiro"],"summary":"Cadastro de saldo de estoque","description":"Cadastro e atualização de snapshot diário de saldo de estoque.","operationId":"receber_estoque_saldo_bi_estoque_saldo_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API","title":"Api-Key"},"description":"Token de API"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EstoqueSaldoIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","recebidos":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, limite de 100.000 itens excedido, dados inválidos, ou token sem loja vinculada.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"limite_excedido":{"summary":"Mais de 100.000 itens na mesma chamada","value":{"detail":"Limite de 100.000 itens por requisição."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum item","value":{"detail":[{"loc":["body",0,"cdprod"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar saldo de estoque. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar saldo de estoque."}}}}}}},"x-endpoint-key":"bi.estoque-saldo"}},"/bi/estoque-inventario":{"post":{"tags":["BI Financeiro"],"summary":"Cadastro de inventário de estoque","description":"Cadastro de contagem física de estoque (inventário) por produto e data. Use tanto para a carga inicial (primeira vez que a loja reporta estoque) quanto para reancoragens periódicas seguintes (nova contagem física a qualquer momento — diária, semanal, mensal, ou uma vez só, no ritmo que o seu ERP permitir).\n\nSemântica importante: para cada produto, a contagem com a data (data_snapshot) mais recente que você enviar é sempre tratada como o estoque real daquela loja a partir daquele dia — qualquer estoque que tenhamos calculado internamente (a partir de vendas e compras) para aquele produto dali em diante é descartado e recalculado a partir do valor que você enviou. Reenviar a mesma data substitui o valor anterior daquela data (upsert por produto+data, idempotente — pode reenviar sem medo de duplicar). Quanto mais frequente o envio, mais precisos ficam os cálculos entre uma contagem e outra.","operationId":"receber_estoque_inventario_bi_estoque_inventario_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API","title":"Api-Key"},"description":"Token de API"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EstoqueInventarioIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","recebidos":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, limite de 100.000 itens excedido, dados inválidos, ou token sem loja vinculada.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"limite_excedido":{"summary":"Mais de 100.000 itens na mesma chamada","value":{"detail":"Limite de 100.000 itens por requisição."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum item","value":{"detail":[{"loc":["body",0,"cdprod"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar inventário de estoque. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar inventário de estoque."}}}}}}},"x-endpoint-key":"bi.estoque-inventario"}},"/bi/clientes":{"post":{"tags":["BI Financeiro"],"summary":"Cadastro de clientes da loja","description":"Cadastro e atualização de clientes finais da loja (não confundir com os tenants do SaaS). `limite_credito` alimenta a Gestão de Convênio (fiado).","operationId":"receber_clientes_bi_clientes_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API","title":"Api-Key"},"description":"Token de API"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ClienteIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","recebidos":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, dados inválidos, ou token sem loja vinculada.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum cliente","value":{"detail":[{"loc":["body",0,"erp_codigo"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar clientes. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar clientes."}}}}}}},"x-endpoint-key":"bi.clientes"}},"/bi/plano-contas":{"post":{"tags":["BI Financeiro"],"summary":"Cadastro de plano de contas","description":"Cadastro e atualização do plano de contas (de/para categoria do DRE). categoria_dre classifica cada código para separar CMV de despesa operacional e financeira no DRE Gerencial.","operationId":"receber_plano_contas_bi_plano_contas_post","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string","description":"Token de API","title":"Api-Key"},"description":"Token de API"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PlanoContaIn"},"title":"Payload"}}}},"responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{},"example":{"status":"ok","recebidos":1}}}},"403":{"description":"Token ausente, inválido, sem permissão para este endpoint, ou não vinculado a nenhuma loja (tenant).","content":{"application/json":{"example":{"detail":"Token não vinculado a nenhuma loja (tenant)."}}}},"422":{"description":"Payload vazio, dados inválidos, ou token sem loja vinculada.","content":{"application/json":{"examples":{"payload_vazio":{"summary":"Lista vazia","value":{"detail":"Payload vazio."}},"sem_tenant":{"summary":"Token não vinculado a uma loja (ex.: chave mestra)","value":{"detail":"Use um token vinculado a um tenant (loja)."}},"campo_invalido":{"summary":"Campo obrigatório ausente/inválido em algum código","value":{"detail":[{"loc":["body",0,"codigo"],"msg":"Campo obrigatório.","type":"missing"}]}}}}}},"503":{"description":"Erro interno ao validar a loja ou gravar plano de contas. Tente novamente.","content":{"application/json":{"examples":{"erro_loja":{"summary":"Falha ao validar a loja no banco","value":{"detail":"Erro interno ao validar loja."}},"erro_gravacao":{"summary":"Falha ao gravar no banco","value":{"detail":"Erro ao gravar plano de contas."}}}}}}},"x-endpoint-key":"bi.plano-contas"}},"/whatsapp/instancia":{"get":{"tags":["WhatsApp"],"summary":"Consulta status da instância e lojas do cliente","description":"Retorna o status de conexão do WhatsApp e a lista de lojas que o e-mail informado tem acesso.","operationId":"consultar_instancia_whatsapp_instancia_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","description":"E-mail do cliente final.","title":"Email"},"description":"E-mail do cliente final.","example":"cliente@empresa.com.br"},{"name":"lojas","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"CNPJs separados por vírgula, para restringir a lojas específicas.","title":"Lojas"},"description":"CNPJs separados por vírgula, para restringir a lojas específicas.","example":"12345678000190"},{"name":"api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Token gerado em Cadastros > Tokens de API, com o endpoint whatsapp.status liberado.","title":"Api-Key"},"description":"Token gerado em Cadastros > Tokens de API, com o endpoint whatsapp.status liberado."}],"responses":{"200":{"description":"Consulta bem-sucedida.","content":{"application/json":{"schema":{},"example":{"instancia":"varejoia","status":"CONECTADO","lojas":[{"cnpj":"12345678000190","nome":"Loja Centro"}]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-endpoint-key":"whatsapp.status","x-endpoint-exato":true}},"/whatsapp/enviar":{"post":{"tags":["WhatsApp"],"summary":"Envia mensagem de texto (ou PDF) via WhatsApp","description":"Envia uma mensagem de texto — ou, se `pdf_base64` for informado, um documento PDF (ex: cupom fiscal) com `mensagem` como legenda — para o número informado, usando a instância WhatsApp do parceiro (com fallback automático para a instância Global se a do parceiro estiver desconectada). Ao atingir o rate limit (15/min), mensagens de texto são represadas e enviadas automaticamente em instantes; envio de PDF ainda não é represado — retorna HTTP 429 nesse caso.","operationId":"enviar_mensagem_whatsapp_enviar_post","parameters":[{"name":"api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Token gerado em Cadastros > Tokens de API, com o endpoint whatsapp.enviar liberado.","title":"Api-Key"},"description":"Token gerado em Cadastros > Tokens de API, com o endpoint whatsapp.enviar liberado."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnviarWhatsAppIn"}}}},"responses":{"200":{"description":"Enviada ou represada com sucesso.","content":{"application/json":{"schema":{},"examples":{"enviada_na_hora":{"summary":"Enviada imediatamente","value":{"success":true,"queued":false,"msg":"Enviado via WhatsApp da Revenda."}},"represada_no_limite":{"summary":"Rate limit atingido — represada (só texto)","value":{"success":true,"queued":true,"msg":"Limite atingido — mensagem agendada para envio no próximo minuto."}},"pdf_enviado":{"summary":"PDF enviado como documento","value":{"success":true,"queued":false,"msg":"Enviado via WhatsApp da Revenda."}}}}}},"422":{"description":"PDF inválido (não é base64, não é PDF, ou excede o limite de tamanho).","content":{"application/json":{"example":{"detail":"O arquivo enviado não é um PDF."}}}},"429":{"description":"Rate limit atingido ao tentar enviar PDF (não represado).","content":{"application/json":{"example":{"detail":"Limite de envios atingido (15/min). Envio de PDF ainda não é represado — tente novamente em instantes."}}}},"502":{"description":"Falha no envio (nenhuma instância conectada).","content":{"application/json":{"example":{"success":false,"queued":false,"msg":"Nenhuma instância de WhatsApp conectada (revenda nem Global)."}}}}},"x-endpoint-key":"whatsapp.enviar","x-endpoint-exato":true}},"/iaas/produto/analisar":{"post":{"tags":["IAaaS"],"summary":"Identifica um produto e compara com o preço de mercado","description":"Identifica um produto por texto (nome ou código de barras), foto (decodificação local de código de barras) ou, como último recurso, LLM com visão — e compara com o preço de mercado (Scanntech) do tenant do e-mail informado, quando disponível. Também devolve `vendas` (preço atual e quantidade vendida na semana atual/anterior, dado 100% interno) e `produtos_relacionados` (\"costuma vir junto\", top 5, também interno) — os dois agregados entre todas as lojas visíveis do e-mail, `null`/vazio quando o tenant nunca vendeu o produto. Diferente de `mercado`, nenhum dos dois depende do Scanntech. Se o e-mail não tiver cadastro e a revenda tiver configurado um cliente/grupo padrão (`parceiros.grupo_padrao_id`/`cliente_padrao_id`), responde com dados de demonstração (`lead: true`) e registra um lead em vez de bloquear.","operationId":"analisar_produto_iaas_produto_analisar_post","parameters":[{"name":"api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Token gerado em Cadastros > Tokens de API, com o endpoint iaas.produto.analisar liberado.","title":"Api-Key"},"description":"Token gerado em Cadastros > Tokens de API, com o endpoint iaas.produto.analisar liberado."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalisarProdutoIn"}}}},"responses":{"200":{"description":"Consulta concluída (identificado ou não).","content":{"application/json":{"schema":{},"examples":{"identificado_com_preco":{"summary":"Produto identificado, com preço de mercado e vendas internas","value":{"identificado":true,"fonte":"cache","produto":{"codigo_barras":"7891000100103","nome_produto":"Leite Ninho 400g","marca":"Nestlé","categoria":"Laticínios"},"mercado":{"preco_medio":24.9,"preco_mediana":24.5,"data_referencia":"2026-08-15"},"vendas":{"preco_atual":24.9,"semana_atual":{"quantidade":4.0,"preco_medio":24.9},"semana_passada":{"quantidade":61.0,"preco_medio":24.5}},"produtos_relacionados":[{"nome_produto":"Leite Condensado Italac 395g","qtd_vezes":18},{"nome_produto":"Achocolatado Nescau 400g","qtd_vezes":11}]}},"nao_identificado":{"summary":"Não foi possível identificar","value":{"identificado":false,"motivo":"Não foi possível identificar o produto automaticamente. Informe o código de barras ou o nome do produto."}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-endpoint-key":"iaas.produto.analisar","x-endpoint-exato":true}},"/iaas/perguntar":{"post":{"tags":["IAaaS"],"summary":"Recebe a pergunta de um cliente final e responde pela IA","description":"Repassa a pergunta de um cliente final pro mesmo motor de IA que responde no chat/WhatsApp internos, e devolve a resposta pelo canal informado. Mesma resolução de acesso do /produto/analisar: se o e-mail não tiver cadastro e a revenda tiver um cliente/grupo padrão configurado, responde no lugar do usuário de demonstração e registra um lead, em vez de bloquear. A resposta sempre vem com `ambiente`: 'producao', 'demonstracao' (loja(s) sem integração real, números fictícios) ou 'misto' (e-mail com acesso a lojas dos dois tipos) — o texto continua natural, só o JSON sinaliza a origem dos números. Mensagens do mesmo e-mail formam uma conversa com memória de curto prazo (~20 min) — envie `nova_conversa: true` na primeira mensagem de uma aba/sessão nova do seu lado pra garantir que ela não herde contexto de uma conversa anterior. **Contexto do ERP:** se `contexto` abrir com o bloco `[REGRAS DE ACESSO DO SISTEMA] … [FIM DAS REGRAS]` seguido de `Pergunta do usuário:` e `Contexto da tela \"…\" (JSON):`, a API interpreta as regras (telas, temas e lojas permitidos). Quem NÃO tem contrato é atendido só com o contexto enviado — nunca com dados da plataforma —, respeitando essas regras, com limite de análises (`cota` na resposta); tema proibido recebe a frase de negativa do próprio ERP, sem gastar análise. Resposta desse modo: `ambiente: 'contexto_erp'`, `tem_contrato`, `visao` (resumo estruturado dos dados da tela), `bloqueio` e `cota`.","operationId":"perguntar_iaas_perguntar_post","parameters":[{"name":"api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Token gerado em Cadastros > Tokens de API, com o endpoint iaas.perguntar liberado.","title":"Api-Key"},"description":"Token gerado em Cadastros > Tokens de API, com o endpoint iaas.perguntar liberado."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerguntarIn"}}}},"responses":{"200":{"description":"IA respondeu com sucesso.","content":{"application/json":{"schema":{},"examples":{"erp_sem_contrato":{"summary":"contexto do ERP, e-mail sem contrato","value":{"canal":"chat","resposta":"O maior cupom de hoje foi o nº 5520 (loja 3), R$ 342,90.","ambiente":"contexto_erp","tem_contrato":false,"visao":{"tela":"Consulta de Cupons","listas":[{"fonte":"cupons","registros":2,"totais":{"total":530.3}}]},"cota":{"limite":5,"usadas":1,"restantes":4,"janela":"dia","renova_em":"2026-10-15T00:00:00-03:00"}}},"erp_tema_proibido":{"summary":"pergunta de tema que o ERP não permite","value":{"canal":"chat","resposta":"Você não tem permissão para acessar essa informação. Fale com o administrador do sistema.","ambiente":"contexto_erp","tem_contrato":false,"bloqueio":{"motivo":"sem_permissao"}}},"canal_chat":{"summary":"canal='chat' — resposta devolvida no corpo","value":{"canal":"chat","resposta":"Ontem você vendeu R$ 4.230,00 em 87 cupons.","ambiente":"producao"}},"canal_whatsapp":{"summary":"canal='whatsapp' — resposta enviada por WhatsApp","value":{"canal":"whatsapp","enviado":true,"ambiente":"producao"}},"canal_chat_demonstracao":{"summary":"loja sem integração real — dados fictícios","value":{"canal":"chat","resposta":"Ontem você vendeu R$ 4.230,00 em 87 cupons.","ambiente":"demonstracao"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-endpoint-key":"iaas.perguntar","x-endpoint-exato":true}},"/iaas/usuario/verificar":{"get":{"tags":["IAaaS"],"summary":"Verifica se um e-mail é cliente do parceiro (sem acionar a IA)","description":"Confirma se o e-mail informado é um usuário ativo do parceiro do token — mesma checagem usada por /iaas/perguntar, exposta sem o custo de gerar uma resposta de IA. Recomendado chamar ANTES da primeira pergunta de uma conversa: se `cadastrado=true`, o campo `ambiente` já avisa se esse cliente está em lojas de 'producao', 'demonstracao' (sem integração real, números fictícios) ou 'misto' (acesso a lojas dos dois tipos) — útil pra decidir a UX antes de começar, em vez de descobrir só depois de já ter perguntado. Resposta sempre genérica quanto ao cadastro (não informa SE o e-mail existe em outro parceiro, só se está disponível para o seu). Limite: 30 chamadas a cada 5 min por token.","operationId":"verificar_usuario_iaas_usuario_verificar_get","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}},{"name":"api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Token gerado em Cadastros > Tokens de API, com o endpoint iaas.usuario.verificar liberado.","title":"Api-Key"},"description":"Token gerado em Cadastros > Tokens de API, com o endpoint iaas.usuario.verificar liberado."}],"responses":{"200":{"description":"Consulta concluída.","content":{"application/json":{"schema":{},"examples":{"cadastrado":{"summary":"E-mail é cliente ativo do parceiro","value":{"cadastrado":true,"ambiente":"producao"}},"cadastrado_demonstracao":{"summary":"Cliente ativo, mas ainda sem integração real","value":{"cadastrado":true,"ambiente":"demonstracao"}},"nao_cadastrado":{"summary":"E-mail não disponível para este token","value":{"cadastrado":false}}}}}},"429":{"description":"Limite de verificações excedido para este token.","content":{"application/json":{"example":{"detail":"Limite de verificações excedido. Tente novamente em instantes."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-endpoint-key":"iaas.usuario.verificar","x-endpoint-exato":true}},"/iaas/parceiro/cadastrocliente":{"post":{"tags":["IAaaS"],"summary":"Cadastra um cliente novo (grupo + loja + usuário admin)","description":"Cria, numa chamada só, um grupo econômico, uma loja e o usuário administrador dessa loja — direto nas tabelas reais, sem fila de aprovação. A credencial de primeiro acesso é enviada por WhatsApp em background logo em seguida. Exige, além do token, uma assinatura HMAC-SHA256 por requisição (headers `X-Timestamp` e `X-Signature`) — segundo fator de segurança específico deste endpoint, por criar acesso real ao sistema. Rejeita CNPJ ou e-mail já cadastrados.\n\n**Como assinar (exemplo em Python):**\n```python\nimport hmac, hashlib, time, requests\n\ntimestamp = str(int(time.time()))\ncorpo = b'{\"grupo\":{\"nome\":\"Rede Exemplo\"}, ...}'  # bytes EXATOS do corpo enviado\nmensagem = f'{timestamp}.'.encode() + corpo\nassinatura = hmac.new(HMAC_SECRET.encode(), mensagem, hashlib.sha256).hexdigest()\n\nrequests.post(url, data=corpo, headers={\n    'api-key': API_KEY, 'X-Timestamp': timestamp, 'X-Signature': assinatura,\n    'Content-Type': 'application/json',\n})\n```\n`HMAC_SECRET` é entregue separadamente no momento em que o token foi gerado — não é o valor do `api-key`. Use os bytes **exatos** do corpo (`data=corpo`, não `json=payload`) — reserializar o JSON entre assinar e enviar muda os bytes e invalida a assinatura.","operationId":"cadastrar_cliente_iaas_parceiro_cadastrocliente_post","parameters":[{"name":"api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Token do parceiro liberado para este endpoint.","title":"Api-Key"},"description":"Token do parceiro liberado para este endpoint."},{"name":"x-timestamp","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Timestamp Unix (segundos, UTC) do momento do envio. A requisição é rejeitada se estiver a mais de 5 minutos do horário do servidor — sincronize o relógio de quem assina.","title":"X-Timestamp"},"description":"Timestamp Unix (segundos, UTC) do momento do envio. A requisição é rejeitada se estiver a mais de 5 minutos do horário do servidor — sincronize o relógio de quem assina.","example":"1755640800"},{"name":"x-signature","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"HMAC-SHA256 em hexadecimal (lowercase) da string `{X-Timestamp}.{corpo da requisição}` — o timestamp deste header, um ponto literal, e o corpo exatamente como será enviado (mesmos bytes; não reformate o JSON entre assinar e enviar). A chave é o segredo HMAC do seu token, entregue a você separadamente no momento em que o token foi gerado — não é o valor do `api-key`.","title":"X-Signature"},"description":"HMAC-SHA256 em hexadecimal (lowercase) da string `{X-Timestamp}.{corpo da requisição}` — o timestamp deste header, um ponto literal, e o corpo exatamente como será enviado (mesmos bytes; não reformate o JSON entre assinar e enviar). A chave é o segredo HMAC do seu token, entregue a você separadamente no momento em que o token foi gerado — não é o valor do `api-key`.","example":"a1b2c3d4e5f6...64_chars_hex"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CadastroClienteIn"}}}},"responses":{"200":{"description":"Cliente criado.","content":{"application/json":{"schema":{},"example":{"status":"ativo","grupo_id":88,"tenant_id":452,"usuario_id":1301}}}},"401":{"description":"Assinatura ausente ou inválida.","content":{"application/json":{"example":{"detail":"Assinatura inválida."}}}},"409":{"description":"CNPJ ou e-mail já cadastrados.","content":{"application/json":{"example":{"detail":"CNPJ já cadastrado nesta revenda."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-endpoint-key":"iaas.parceiro.cadastrocliente","x-endpoint-exato":true}},"/coletas/criar":{"post":{"tags":["Coleta"],"summary":"Dispara uma pesquisa de satisfação (QR code ou WhatsApp)","description":"**É esta chamada que gera o `token_publico`** — o PDV nunca cria esse valor, só o `identificador` (a chave de idempotência, escolhida pelo PDV). A API devolve o `token_publico` (aleatório, opaco) na resposta; guarde-o (ou extraia da URL do campo `link`, que é `.../c/{token_publico}`) para consultar o status depois em `GET /coletas/{token_publico}/status`.\n\nRepetir a chamada com o mesmo `identificador` **não cria uma coleta nova** — devolve o mesmo `token_publico` de novo (`reaproveitado: true`), sem duplicar linha nem reenviar WhatsApp. É assim que um retry do PDV fica seguro.","operationId":"criar_coleta_coletas_criar_post","parameters":[{"name":"api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Token gerado em Cadastros > Tokens de API, com o endpoint coletas.criar liberado.","title":"Api-Key"},"description":"Token gerado em Cadastros > Tokens de API, com o endpoint coletas.criar liberado."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ColetaCriarIn"}}}},"responses":{"200":{"description":"Coleta criada (ou reaproveitada, se o identificador já existia).","content":{"application/json":{"schema":{},"examples":{"criada_agora":{"summary":"Primeira chamada com este identificador","value":{"identificador":"12345678000190-01-03-20260819-1432","token_publico":"Q75jARAk53U5QP_TyFIWIVmAxqmabj_CdtUB5etB9Q4","link":"https://varejo.ia.br/c/Q75jARAk53U5QP_TyFIWIVmAxqmabj_CdtUB5etB9Q4","expira_em":"2026-08-20T01:05:13-03:00","canal":"qrcode","reaproveitado":false}},"reaproveitada":{"summary":"Retry com o mesmo identificador","value":{"identificador":"12345678000190-01-03-20260819-1432","token_publico":"Q75jARAk53U5QP_TyFIWIVmAxqmabj_CdtUB5etB9Q4","link":"https://varejo.ia.br/c/Q75jARAk53U5QP_TyFIWIVmAxqmabj_CdtUB5etB9Q4","expira_em":"2026-08-20T01:05:13-03:00","canal":"qrcode","reaproveitado":true}}}}}},"400":{"description":"Canal inválido ou 'whatsapp' faltando quando canal='whatsapp'.","content":{"application/json":{"example":{"detail":"Informe 'whatsapp' quando canal='whatsapp'."}}}},"403":{"description":"Token não vinculado a uma loja.","content":{"application/json":{"example":{"detail":"Token não vinculado a uma loja (tenant_id)."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-endpoint-key":"coletas.criar","x-endpoint-exato":true}},"/coletas/{token_publico}/status":{"get":{"tags":["Coleta"],"summary":"Consulta o status de uma coleta","description":"`{token_publico}` é o valor devolvido por `POST /coletas/criar` (não é o `identificador` que o PDV escolheu). Suporta `ETag`/`If-None-Match`: manda de volta o `ETag` recebido na consulta anterior e, se nada mudou, a resposta é `304` sem corpo — mais barato que reconsultar o JSON inteiro em polling.","operationId":"consultar_status_coletas__token_publico__status_get","parameters":[{"name":"token_publico","in":"path","required":true,"schema":{"type":"string","title":"Token Publico"}},{"name":"If-None-Match","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"If-None-Match"}},{"name":"api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Token gerado em Cadastros > Tokens de API, com o endpoint coletas.consultar liberado.","title":"Api-Key"},"description":"Token gerado em Cadastros > Tokens de API, com o endpoint coletas.consultar liberado."}],"responses":{"200":{"description":"Consulta bem-sucedida.","content":{"application/json":{"schema":{},"examples":{"pendente":{"summary":"Ainda não respondida","value":{"status":"pendente","expira_em":"2026-08-20T01:05:13-03:00","canal":"qrcode"}},"respondida":{"summary":"Cliente já respondeu","value":{"status":"respondida","respondido_em":"2026-08-20T00:06:32-03:00","expira_em":"2026-08-20T01:05:13-03:00","canal":"qrcode"}}}}}},"304":{"description":"Nada mudou desde o ETag enviado em If-None-Match — sem corpo."},"404":{"description":"token_publico não existe (ou pertence a outra revenda).","content":{"application/json":{"example":{"detail":"Coleta não encontrada."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-endpoint-key":"coletas.consultar","x-endpoint-exato":true}},"/coletas/{token_publico}/responder":{"post":{"tags":["Coleta"],"summary":"Registra a resposta do cliente final (página pública, sem autenticação)","description":"Sem `api-key` — quem abre o link não tem (nem deveria ter) o token do parceiro. Aceita **uma única resposta** por `token_publico`: a segunda tentativa recebe `409`, mesmo que os dados enviados sejam diferentes.","operationId":"responder_coleta_coletas__token_publico__responder_post","parameters":[{"name":"token_publico","in":"path","required":true,"schema":{"type":"string","title":"Token Publico"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ColetaResponderIn"}}}},"responses":{"200":{"description":"Resposta registrada.","content":{"application/json":{"schema":{},"example":{"status":"ok"}}}},"404":{"description":"Link inválido.","content":{"application/json":{"example":{"detail":"Link inválido."}}}},"409":{"description":"Esta coleta já foi respondida.","content":{"application/json":{"example":{"detail":"Esta pesquisa já foi respondida."}}}},"410":{"description":"O link expirou.","content":{"application/json":{"example":{"detail":"Este link expirou."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/status":{"get":{"tags":["API"],"summary":"Status da API","description":"Status da API","operationId":"health_check_status_get","responses":{"200":{"description":"API online.","content":{"application/json":{"schema":{},"example":{"status":"online","server_time":"2026-08-20T10:00:00.123456"}}}},"503":{"description":"API fora do ar.","content":{"application/json":{"example":{"detail":"Serviço indisponível."}}}}}}},"/token/validar":{"get":{"tags":["API"],"summary":"Validar token","description":"Valida o token informado e retorna as requisições na qual o token tem acesso.","operationId":"validar_token_token_validar_get","parameters":[{"name":"api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api-Key"}}],"responses":{"200":{"description":"Token válido.","content":{"application/json":{"schema":{},"example":{"valido":true,"descricao":"Token de integração — Loja Centro","endpoints":["bi.vendas/*","monitor.devices"]}}}},"403":{"description":"Token ausente, inválido, inativo ou vencido, ou IP bloqueado por excesso de tentativas.","content":{"application/json":{"example":{"detail":"Token inválido, inativo ou vencido"}}}},"503":{"description":"Erro ao consultar o banco de dados.","content":{"application/json":{"example":{"detail":"Erro ao consultar banco"}}}}}}}},"components":{"schemas":{"AnalisarProdutoIn":{"properties":{"email":{"type":"string","title":"Email","description":"E-mail do cliente final (usuário ativo do mesmo parceiro do token).","example":"cliente@empresa.com.br"},"texto":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Texto","description":"Nome do produto ou código de barras digitado.","example":"7891000100103"},"imagem_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Imagem Base64","description":"Foto do produto ou do código de barras, em base64 (sem o prefixo data:image/...)."}},"type":"object","required":["email"],"title":"AnalisarProdutoIn"},"BancoIn":{"properties":{"erp_codigo":{"type":"integer","title":"Erp Codigo"},"loja_id":{"type":"integer","title":"Loja Id","default":0},"banco_nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Banco Nome"},"codban":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codban"},"agencia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agencia"},"nr_conta":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nr Conta"},"razsoc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Razsoc"},"saldo_atual":{"type":"number","title":"Saldo Atual","default":0},"saldo_inicial":{"type":"number","title":"Saldo Inicial","default":0},"inclui_fluxo":{"type":"boolean","title":"Inclui Fluxo","default":true},"convenio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Convenio"},"ativo":{"type":"boolean","title":"Ativo","default":true}},"type":"object","required":["erp_codigo"],"title":"BancoIn","example":{"agencia":"1234-5","ativo":true,"banco_nome":"Banco do Brasil","codban":"001","erp_codigo":1,"inclui_fluxo":true,"loja_id":1,"nr_conta":"67890-1","razsoc":"Loja Exemplo LTDA","saldo_atual":15230.4,"saldo_inicial":10000.0}},"CadastroClienteIn":{"properties":{"grupo":{"$ref":"#/components/schemas/GrupoCadastroIn"},"loja":{"$ref":"#/components/schemas/LojaCadastroIn"},"usuario_admin":{"$ref":"#/components/schemas/UsuarioAdminCadastroIn"}},"type":"object","required":["grupo","loja","usuario_admin"],"title":"CadastroClienteIn"},"CapaCupom":{"properties":{"loja":{"type":"integer","title":"Loja","description":"Número da loja","example":1},"caixa":{"type":"integer","title":"Caixa","description":"Número do PDV","example":2},"cupom":{"type":"integer","title":"Cupom","description":"Número do cupom","example":100345},"data_hora":{"type":"string","format":"date-time","title":"Data Hora","description":"Data e hora de emissão.","example":"2025-06-15T14:32:00"},"operador":{"type":"string","title":"Operador","description":"Código do operador","default":"","example":"42"},"supervisor":{"type":"string","title":"Supervisor","description":"Código do supervisor","default":"","example":"10"},"cancelado":{"type":"string","title":"Cancelado","description":"Cupom cancelado: 'S' ou 'N'","default":"N","example":"N"},"motivo_cancelamento":{"type":"string","title":"Motivo Cancelamento","description":"Motivo do cancelamento (quando cancelado='S')","default":"","example":""},"nfce_chave":{"type":"string","title":"Nfce Chave","description":"Chave de acesso da NFC-e (44 dígitos)","default":"","example":""},"nfce_numero":{"type":"string","title":"Nfce Numero","description":"Número da NFC-e","default":"","example":""},"nfce_serie":{"type":"string","title":"Nfce Serie","description":"Série da NFC-e","default":"","example":""},"nfce_protocolo":{"type":"string","title":"Nfce Protocolo","description":"Protocolo de autorização SEFAZ","default":"","example":""},"valor_total_cupom":{"type":"number","title":"Valor Total Cupom","description":"Valor total do cupom (R$)","default":0.0,"example":11.98},"valor_desconto_cupom":{"type":"number","title":"Valor Desconto Cupom","description":"Desconto total no cupom (R$)","default":0.0,"example":0.0},"valor_acrescimo_cupom":{"type":"number","title":"Valor Acrescimo Cupom","description":"Acréscimo total no cupom (R$)","default":0.0,"example":0.0}},"type":"object","required":["loja","caixa","cupom","data_hora"],"title":"CapaCupom","description":"Cabeçalho do cupom fiscal.\n\nCupons com a mesma loja, caixa e número substituem o registro anterior."},"ClienteIn":{"properties":{"erp_codigo":{"type":"integer","title":"Erp Codigo"},"cpf_cnpj":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cpf Cnpj"},"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome"},"limite_credito":{"type":"number","title":"Limite Credito","default":0},"ativo":{"type":"boolean","title":"Ativo","default":true}},"type":"object","required":["erp_codigo"],"title":"ClienteIn","example":{"ativo":true,"cpf_cnpj":"12345678900","erp_codigo":5001,"limite_credito":500.0,"nome":"Maria da Silva"}},"ColetaCriarIn":{"properties":{"identificador":{"type":"string","maxLength":120,"title":"Identificador","description":"Chave de idempotência do PDV — reenviar o mesmo valor retorna o token_publico já existente, sem duplicar nem reenviar WhatsApp.","example":"12345678000190-01-03-20260819-1432"},"canal":{"type":"string","title":"Canal","description":"'qrcode' ou 'whatsapp'.","example":"qrcode"},"whatsapp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Whatsapp","description":"Número de WhatsApp de destino — obrigatório quando canal='whatsapp'.","example":"5511999998888"},"perguntas":{"items":{},"type":"array","title":"Perguntas","description":"Estrutura livre — repassada como está pro relatório e pra página de resposta.","example":[{"texto":"Como foi seu atendimento?","tipo":"nota_1_5"},{"texto":"Quer deixar um comentário?","tipo":"texto_livre"}]},"ttl_minutos":{"anyOf":[{"type":"integer","maximum":1440.0,"minimum":1.0},{"type":"null"}],"title":"Ttl Minutos","description":"Minutos até expirar (padrão: 60).","example":60}},"type":"object","required":["identificador","canal","perguntas"],"title":"ColetaCriarIn"},"ColetaResponderIn":{"properties":{"respostas":{"additionalProperties":true,"type":"object","title":"Respostas","description":"Estrutura livre, correspondente às 'perguntas' originais.","example":{"comentario":"Muito bom atendimento!","nota":5}}},"type":"object","required":["respostas"],"title":"ColetaResponderIn"},"CompradorIn":{"properties":{"erp_codigo":{"type":"integer","title":"Erp Codigo","description":"Código do comprador.","example":10},"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome","description":"Nome do comprador/responsável pelas compras.","example":"Maria Souza"}},"type":"object","required":["erp_codigo"],"title":"CompradorIn"},"ContaPagarIn":{"properties":{"erp_id":{"type":"integer","title":"Erp Id"},"destino":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Destino"},"fornecedor_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fornecedor Id"},"tipo_doc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Doc"},"nr_doc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nr Doc"},"desdobr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Desdobr"},"emissao":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Emissao"},"vencto":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Vencto"},"pagto":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Pagto","description":"Data de pagamento. Deixe nulo (`null`) para indicar título em aberto."},"valor":{"type":"number","title":"Valor","default":0},"desc_obtido":{"type":"number","title":"Desc Obtido","default":0},"acrescimos":{"type":"number","title":"Acrescimos","default":0},"valor_pago":{"type":"number","title":"Valor Pago","default":0},"historico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Historico"},"plano_conta":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Plano Conta"},"loja_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Loja Id"}},"type":"object","required":["erp_id"],"title":"ContaPagarIn","example":{"acrescimos":0,"desc_obtido":0,"desdobr":"01","destino":"Fornecedor XYZ Ltda","emissao":"2026-08-01","erp_id":88123,"fornecedor_id":451,"historico":"Compra de mercadorias","loja_id":1,"nr_doc":"123456","plano_conta":12,"tipo_doc":"NF","valor":1500.0,"valor_pago":0,"vencto":"2026-09-01"}},"ContaReceberIn":{"properties":{"erp_id":{"type":"integer","title":"Erp Id"},"tipo_doc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Doc"},"nr_doc":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Nr Doc"},"desdobr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Desdobr"},"emissao":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Emissao"},"cliente_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cliente Id"},"vencto":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Vencto"},"previsao_rec":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Previsao Rec"},"recebimento":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Recebimento","description":"Data de recebimento. Deixe nulo (`null`) para indicar título em aberto."},"valor":{"type":"number","title":"Valor","default":0},"mora_perc":{"type":"number","title":"Mora Perc","default":0},"multa_perc":{"type":"number","title":"Multa Perc","default":0},"desc_obtido":{"type":"number","title":"Desc Obtido","default":0},"valor_recebido":{"type":"number","title":"Valor Recebido","default":0},"convenio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Convenio"},"barcode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Barcode"},"loja_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Loja Id"}},"type":"object","required":["erp_id"],"title":"ContaReceberIn","example":{"barcode":"34191790010104351004791020150008291070026000","cliente_id":220,"desc_obtido":0,"desdobr":"01","emissao":"2026-08-01","erp_id":55012,"loja_id":1,"mora_perc":0,"multa_perc":0,"nr_doc":9834,"previsao_rec":"2026-09-01","tipo_doc":"DUP","valor":320.5,"valor_recebido":0,"vencto":"2026-09-01"}},"CupomCompleto":{"properties":{"capa":{"$ref":"#/components/schemas/CapaCupom","description":"Cabeçalho do cupom"},"itens":{"items":{"$ref":"#/components/schemas/ItemCupom"},"type":"array","title":"Itens","description":"Produtos vendidos no cupom","default":[]},"pagamentos":{"items":{"$ref":"#/components/schemas/PagamentoCupom"},"type":"array","title":"Pagamentos","description":"Formas de pagamento","default":[]}},"type":"object","required":["capa"],"title":"CupomCompleto","description":"Cupom fiscal completo, usado pelo endpoint POST /bi/movimentos.\n\nRepresenta um cupom fiscal com cabeçalho, itens e formas de pagamento."},"EnviarWhatsAppIn":{"properties":{"email":{"type":"string","title":"Email","description":"E-mail do cliente final (usuário ativo do mesmo parceiro do token).","example":"cliente@empresa.com.br"},"numero":{"type":"string","title":"Numero","description":"Número de WhatsApp de destino (com ou sem DDI/55).","example":"11999998888"},"mensagem":{"type":"string","maxLength":3800,"title":"Mensagem","description":"Texto da mensagem (máx. 3.800 caracteres). Suporta formatação nativa do WhatsApp (*negrito*, _itálico_, ~tachado~, \\n). Quando pdf_base64 é enviado, este texto vira a legenda do documento.","example":"Olá! Seu pedido nº 4821 já foi entregue. Obrigado pela preferência!"},"lojas":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Lojas","description":"CNPJs para restringir a lojas específicas. Omitido = todas as lojas do e-mail.","example":["12345678000190"]},"pdf_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pdf Base64","description":"Opcional: PDF em base64 (ex: cupom fiscal, nota, boleto) para enviar como documento anexo, em vez de mensagem de texto pura. `mensagem` vira a legenda exibida junto ao arquivo. Máximo 10 MB."},"pdf_nome_arquivo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pdf Nome Arquivo","description":"Nome do arquivo exibido no WhatsApp (ex: 'cupom_4821.pdf'). Padrão: 'documento.pdf'.","example":"cupom_4821.pdf"}},"type":"object","required":["email","numero","mensagem"],"title":"EnviarWhatsAppIn"},"EstoqueInventarioIn":{"properties":{"cdprod":{"type":"string","title":"Cdprod"},"data_snapshot":{"type":"string","format":"date","title":"Data Snapshot"},"quantidade":{"type":"number","title":"Quantidade","default":0}},"type":"object","required":["cdprod","data_snapshot"],"title":"EstoqueInventarioIn","example":{"cdprod":"7891234567890","data_snapshot":"2026-08-19","quantidade":42.0}},"EstoqueSaldoIn":{"properties":{"cdprod":{"type":"string","title":"Cdprod"},"data_snapshot":{"type":"string","format":"date","title":"Data Snapshot"},"quantidade":{"type":"number","title":"Quantidade","default":0}},"type":"object","required":["cdprod","data_snapshot"],"title":"EstoqueSaldoIn","example":{"cdprod":"7891234567890","data_snapshot":"2026-08-19","quantidade":42.0}},"FornecedorIn":{"properties":{"erp_codigo":{"type":"integer","title":"Erp Codigo","description":"Código do fornecedor.","example":1234},"cnpj":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cnpj","description":"CNPJ do fornecedor.","example":"12345678000199"},"razao_social":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Razao Social","description":"Razão social do fornecedor.","example":"Distribuidora Alimentos LTDA"},"nome_fantasia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome Fantasia","description":"Nome fantasia do fornecedor.","example":"Distribuidora Alimentos"},"prazo_entrega_dias":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prazo Entrega Dias","description":"Prazo médio de entrega em dias.","example":7},"situacao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Situacao","description":"Situação cadastral do fornecedor no ERP: 'L' = liberado e 'I' = inativo","example":"L"},"regime_tributario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regime Tributario","description":"Regime tributário do fornecedor.","example":"1"},"simples_nacional":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Simples Nacional","description":"Fornecedor optante pelo Simples Nacional: 'S' ou 'N'","example":"N"},"aliquota_simples_nacional":{"type":"number","title":"Aliquota Simples Nacional","description":"Alíquota do Simples Nacional (%), quando aplicável.","default":0,"example":0.0},"dias_pagamento":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Dias Pagamento","description":"Prazo padrão de pagamento negociado, em dias.","example":30},"dia_corte":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Dia Corte","description":"Dia do mês usado como corte de fechamento de pedidos/faturamento.","example":25},"ramo":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ramo","description":"Código do ramo de atividade do fornecedor no ERP de origem.","example":1},"ativo":{"type":"boolean","title":"Ativo","description":"Fornecedor ativo no cadastro 'True' = Ativo, 'False' = Inativo.","default":true,"example":true}},"type":"object","required":["erp_codigo"],"title":"FornecedorIn"},"GrupoCadastroIn":{"properties":{"nome":{"type":"string","title":"Nome","example":"Rede Exemplo"}},"type":"object","required":["nome"],"title":"GrupoCadastroIn"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ItemCupom":{"properties":{"item":{"type":"integer","title":"Item","description":"Sequencial do item (1, 2, 3...)","example":1},"cdprod":{"type":"string","minLength":1,"title":"Cdprod","description":"Código do produto no ERP","example":"PRD001"},"desprod":{"type":"string","title":"Desprod","description":"Descrição do produto","default":"","example":"LEITE INTEGRAL 1L"},"quant":{"type":"number","title":"Quant","description":"Quantidade vendida (maior ou igual a zero)","example":2.0},"preco":{"type":"number","title":"Preco","description":"Preço unitário de venda (R$)","example":5.99},"valortot":{"type":"number","title":"Valortot","description":"Valor total do item após descontos (R$)","example":11.98},"precocusto":{"type":"number","title":"Precocusto","description":"Custo unitário do produto (R$)","default":0.0,"example":3.5},"descitem":{"type":"number","title":"Descitem","description":"Desconto direto no item (R$)","default":0.0,"example":0.0},"descprcamp":{"type":"number","title":"Descprcamp","description":"Desconto de campanha promocional (R$)","default":0.0,"example":0.0},"descprmult":{"type":"number","title":"Descprmult","description":"Desconto por multiplas unidades (R$)","default":0.0,"example":0.0},"descontoScanntech":{"type":"number","title":"Descontoscanntech","description":"Desconto Scanntech / fidelidade (R$)","default":0.0,"example":0.0},"desccupom":{"type":"number","title":"Desccupom","description":"Desconto de cupom rateado neste item (R$)","default":0.0,"example":0.0},"valorIBS_UF":{"type":"number","title":"Valoribs Uf","description":"IBS destinado à UF, Reforma Tributária (R$)","default":0.0,"example":0.0},"valorCBS":{"type":"number","title":"Valorcbs","description":"CBS federal, Reforma Tributária (R$)","default":0.0,"example":0.0},"valorIS":{"type":"number","title":"Valoris","description":"Imposto Seletivo, Reforma Tributária (R$)","default":0.0,"example":0.0},"dados_extras":{"additionalProperties":true,"type":"object","title":"Dados Extras","description":"Campos adicionais da sua retaguarda, como referencia_interna, codigo_promocao, codigo_vendedor ou lote_produto. Os campos do padrão (item, cdprod, quant, preco, precocusto e outros) sempre têm precedência e não podem ser sobrescritos aqui.","example":{"codigo_promocao":"PROMO10","lote_produto":"L2026A","referencia_interna":"REF-001"}}},"type":"object","required":["item","cdprod","quant","preco","valortot"],"title":"ItemCupom","description":"Item de produto dentro do cupom.\n\nUse dados_extras para enviar campos adicionais da sua retaguarda. Eles\nficam disponíveis para consulta posterior. Os campos do padrão sempre têm\nprecedência sobre dados_extras."},"ItemDivisao":{"properties":{"tipo":{"type":"string","title":"Tipo","description":"Divisão mercadológica. Use um destes valores: departamento, grupo, armacao, marca.","example":"departamento"},"codigo":{"type":"string","maxLength":50,"minLength":1,"title":"Codigo","description":"Código da divisão no ERP. Pode conter letras, como no prefixo usado para marcas.","example":"01"},"descricao":{"type":"string","minLength":1,"title":"Descricao","description":"Nome/descrição da divisão mercadológica.","example":"MERCEARIA"}},"type":"object","required":["tipo","codigo","descricao"],"title":"ItemDivisao","description":"Divisão mercadológica, usada pelo endpoint POST /bi/divisoes-mercadologicas.\n\nEnvie tipos misturados no mesmo array. Registros existentes com o mesmo\ntenant, tipo e código são atualizados."},"ItemOperador":{"properties":{"codigo":{"type":"string","maxLength":50,"minLength":1,"title":"Codigo","description":"Código do operador no ERP.","example":"007"},"nome":{"type":"string","minLength":1,"title":"Nome","example":"João Pereira"}},"type":"object","required":["codigo","nome"],"title":"ItemOperador"},"ItemProduto":{"properties":{"cdprod":{"type":"string","minLength":1,"title":"Cdprod","description":"Código interno do produto.","example":"7891234567890"},"descricao":{"type":"string","minLength":1,"title":"Descricao","description":"Descrição do produto.","example":"ARROZ TIPO 1 5KG"},"grupo":{"type":"string","title":"Grupo","description":"Grupo ao qual o produto pertence.","default":"","example":"101"},"marca":{"type":"string","title":"Marca","description":"Marca do produto.","default":"","example":"M01"},"custo":{"type":"number","title":"Custo","description":"Custo unitário do produto.","default":0.0,"example":18.9},"codbarra":{"type":"string","title":"Codbarra","description":"Código de barras do produto.","default":"","example":"7891234567890"},"referencia":{"type":"string","title":"Referencia","description":"Referência do produto.","default":"","example":"ARR5KG"},"tipoprod":{"type":"string","title":"Tipoprod","description":"Tipo do produto.","default":"ATIVO","example":"ATIVO"}},"type":"object","required":["cdprod","descricao"],"title":"ItemProduto"},"ItemProdutoCodigoBarras":{"properties":{"cdprod":{"type":"string","minLength":1,"title":"Cdprod","example":"7893249781471"},"codigo_barras":{"type":"string","minLength":1,"title":"Codigo Barras","example":"17893249781478"},"tipo_embalagem":{"type":"string","title":"Tipo Embalagem","default":"","example":"CAIXA"},"qtd_embalagem":{"type":"number","title":"Qtd Embalagem","default":1,"example":6}},"type":"object","required":["cdprod","codigo_barras"],"title":"ItemProdutoCodigoBarras"},"ItemProdutoPreco":{"properties":{"cdprod":{"type":"string","minLength":1,"title":"Cdprod","example":"7893249781471"},"loja":{"type":"integer","title":"Loja","example":1},"custo_sem_imposto":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Custo Sem Imposto","example":12.5},"custo_com_imposto":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Custo Com Imposto","example":14.1},"custo_medio_sem_imposto":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Custo Medio Sem Imposto","example":12.3},"custo_medio_com_imposto":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Custo Medio Com Imposto","example":13.85},"preco_venda":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Preco Venda","example":18.9},"vigente_desde":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vigente Desde","description":"Data (YYYY-MM-DD) em que o seu sistema registrou essa mudança, se disponível.","example":"2026-09-10"},"origem_integracao":{"type":"string","maxLength":30,"minLength":1,"title":"Origem Integracao","description":"Identificador do seu sistema/conector — usado só para rastreio interno.","example":"MEU_ERP"}},"type":"object","required":["cdprod","loja","origem_integracao"],"title":"ItemProdutoPreco"},"ItemSupervisor":{"properties":{"codigo":{"type":"string","maxLength":50,"minLength":1,"pattern":"^\\d+$","title":"Codigo","description":"Código numérico do supervisor no ERP.","example":"010"},"nome":{"type":"string","minLength":1,"title":"Nome","example":"Ana Costa"}},"type":"object","required":["codigo","nome"],"title":"ItemSupervisor"},"LojaCadastroIn":{"properties":{"nome":{"type":"string","title":"Nome","example":"Loja Centro"},"codigo_loja":{"type":"string","title":"Codigo Loja","example":"001"},"cnpj":{"type":"string","title":"Cnpj","example":"12.345.678/0001-90"},"regime_tributario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regime Tributario","description":"simples_nacional | lucro_presumido | lucro_real | mei — opcional; obrigatório só ao ativar o Imendes. MEI não é gravado (domínio da Imendes não tem essa opção).","example":"simples_nacional"}},"type":"object","required":["nome","codigo_loja","cnpj"],"title":"LojaCadastroIn"},"MovimentoBancarioIn":{"properties":{"erp_id":{"type":"integer","title":"Erp Id"},"conta_codigo":{"type":"integer","title":"Conta Codigo"},"data_movimento":{"type":"string","format":"date","title":"Data Movimento"},"operacao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operacao"},"tipo_doc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Doc"},"nr_doc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nr Doc"},"historico_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Historico Id"},"historico_texto":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Historico Texto"},"valor":{"type":"number","title":"Valor","default":0},"nominal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nominal"},"transferencia":{"type":"boolean","title":"Transferencia","default":false},"cheque":{"type":"boolean","title":"Cheque","default":false},"conciliado":{"type":"boolean","title":"Conciliado","default":false},"data_conciliacao":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Data Conciliacao"},"tipodoc_origem":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipodoc Origem"},"nrdoc_origem":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Nrdoc Origem"},"desdobr_origem":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Desdobr Origem"},"emissao_origem":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Emissao Origem"},"destino":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Destino"},"tipo_registro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Registro"},"loja_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Loja Id"},"caixa_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Caixa Id"}},"type":"object","required":["erp_id","conta_codigo","data_movimento"],"title":"MovimentoBancarioIn","example":{"cheque":false,"conciliado":false,"conta_codigo":1,"data_movimento":"2026-08-19","erp_id":33021,"historico_id":5,"historico_texto":"Depósito de vendas do dia","loja_id":1,"nr_doc":"778812","operacao":"C","tipo_doc":"DEP","transferencia":false,"valor":2500.0}},"MovimentoTefIn":{"properties":{"erp_id":{"type":"integer","title":"Erp Id"},"data_movimento":{"type":"string","format":"date","title":"Data Movimento"},"loja_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Loja Id"},"caixa_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Caixa Id"},"cupom_numero":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cupom Numero"},"rede_nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rede Nome"},"bandeira_nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bandeira Nome"},"tipo_tef":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Tef"},"tipo_parcela":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Parcela"},"qtd_parcelas":{"type":"integer","title":"Qtd Parcelas","default":1},"nsu_tef":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nsu Tef"},"valor_total":{"type":"number","title":"Valor Total","default":0},"valor_parcela":{"type":"number","title":"Valor Parcela","default":0},"titulo_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Titulo Id"},"tipodoc_titulo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipodoc Titulo"},"desdobr_titulo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Desdobr Titulo"},"emissao_titulo":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Emissao Titulo"},"processado":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processado","default":"N"}},"type":"object","required":["erp_id","data_movimento"],"title":"MovimentoTefIn","example":{"bandeira_nome":"VISA","caixa_id":2,"cupom_numero":48213,"data_movimento":"2026-08-19","erp_id":900456,"loja_id":1,"nsu_tef":"004821312345","processado":"N","qtd_parcelas":3,"rede_nome":"CIELO","tipo_parcela":"P","tipo_tef":"CREDITO","valor_parcela":50.0,"valor_total":150.0}},"NotaEntradaIn":{"properties":{"fornecedor_id":{"type":"integer","title":"Fornecedor Id","description":"Código do fornecedor responsável.","example":1234},"numero_nota":{"type":"integer","title":"Numero Nota","description":"Número da nota fiscal.","example":123456},"serie":{"type":"string","title":"Serie","description":"Série da nota fiscal.","default":"","example":"1"},"tipo":{"type":"string","title":"Tipo","description":"Tipo da nota no ERP de origem. XML avulso costuma deixar vazio.","default":"","example":""},"chave_nfe":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chave Nfe","description":"Chave de acesso da NF-e (44 dígitos). Sempre presente quando a origem é XML/SEFAZ; usada como chave universal de dedup.","example":"35260712345678000199550010000001231000001235"},"loja":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Loja","description":"Número da loja destinatária da compra.","example":1},"numero_pedido":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Numero Pedido","description":"Número do pedido de compra vinculado a esta nota, se houver.","example":45001},"data_emissao":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Data Emissao","description":"Data e hora de emissão da nota (ISO 8601).","example":"2026-07-01T10:00:00"},"data_entrada":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Data Entrada","description":"Data de entrada/recebimento da mercadoria na loja.","example":"2026-07-02"},"protocolo_sefaz":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Protocolo Sefaz","description":"Protocolo de autorização da SEFAZ.","example":"135260000123456"},"recibo_sefaz":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recibo Sefaz","description":"Número do recibo de envio à SEFAZ.","example":"135260000123456"},"valor_nota":{"type":"number","title":"Valor Nota","description":"Valor total da nota.","default":0,"example":1234.56},"valor_ipi":{"type":"number","title":"Valor Ipi","description":"Valor total de IPI da nota.","default":0,"example":0.0},"valor_st":{"type":"number","title":"Valor St","description":"Valor total de ICMS-ST da nota.","default":0,"example":0.0},"valor_frete":{"type":"number","title":"Valor Frete","description":"Valor do frete da nota.","default":0,"example":50.0},"valor_seguro":{"type":"number","title":"Valor Seguro","description":"Valor do seguro da nota.","default":0,"example":0.0},"valor_outras_despesas":{"type":"number","title":"Valor Outras Despesas","description":"Valor de outras despesas acessórias da nota.","default":0,"example":0.0},"valor_desconto":{"type":"number","title":"Valor Desconto","description":"Valor de desconto total da nota.","default":0,"example":0.0},"origem_importacao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origem Importacao","description":"Canal de ingestão desta nota: `API_GZ` | `INTEGRADOR_<erp>` | `XML_UPLOAD` | `XML_SEFAZ`.","example":"API_GZ"},"protocolo_importacao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Protocolo Importacao","description":"Identificador do lote/protocolo de importação, para rastreabilidade.","example":"API_GZ_20260713_0001"},"dados_adicionais":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Dados Adicionais","description":"Campos extras específicos do ERP de origem, para rastreabilidade."},"status_processamento":{"type":"string","title":"Status Processamento","description":"Status de processamento da nota (ex.: 'recebida', 'auditada').","default":"recebida","example":"recebida"},"eh_devolucao":{"type":"boolean","title":"Eh Devolucao","description":"Nota é uma devolução ao fornecedor, não uma compra. 'True' = devolução e 'False' = compra normal. valor_nota e valor_produto continuam positivos; o volume comprado é descontado automaticamente.","default":false,"example":false},"itens":{"items":{"$ref":"#/components/schemas/NotaEntradaItemIn"},"type":"array","title":"Itens","description":"Itens da nota de entrada."}},"type":"object","required":["fornecedor_id","numero_nota"],"title":"NotaEntradaIn"},"NotaEntradaItemIn":{"properties":{"item":{"type":"integer","title":"Item","description":"Sequencial do item dentro da nota (1, 2, 3…)","example":1},"chave_nfe":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chave Nfe","description":"Chave de acesso da NF-e (44 dígitos). Dedup alternativo junto com item, quando a origem tiver (XML sempre tem; API de ERP legado pode não ter).","example":"35260712345678000199550010000001231000001235"},"cdprod":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cdprod","description":"Código do produto no ERP do lojista","example":"PRD001"},"ean":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ean","description":"Código de barras EAN/GTIN do produto","example":"7891234567890"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao","description":"Descrição do produto conforme veio na nota","example":"Refrigerante Cola 2L"},"codigo_produto_fornecedor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo Produto Fornecedor","description":"Código do produto no catálogo do fornecedor","example":"FORN-9988"},"numero_pedido":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Numero Pedido","description":"Número do pedido de compra vinculado a este item, se houver","example":45001},"item_pedido":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Item Pedido","description":"Sequencial do item dentro do pedido de compra vinculado","example":1},"quantidade":{"type":"number","title":"Quantidade","description":"Quantidade recebida do item","default":0,"example":24.0},"caixa":{"type":"number","title":"Caixa","description":"Quantidade de caixas/embalagens recebidas","default":0,"example":2.0},"custo_unitario":{"type":"number","title":"Custo Unitario","description":"Custo unitário de reposição do item (R$)","default":0,"example":4.8},"preco_venda_sugerido":{"type":"number","title":"Preco Venda Sugerido","description":"Preço de venda sugerido para o item (R$)","default":0,"example":7.99},"ncm":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ncm","description":"NCM do produto (8 dígitos)","example":"22021000"},"cfop":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cfop","description":"CFOP da operação já convertido para entrada (ex.: GZ Sistemas: nfitem.itemnat)","example":"1102"},"origem_icms":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origem Icms","description":"Origem da mercadoria (1º dígito do CST/CSOSN, tabela ICMS: 0=nacional, 1=estrangeira importação direta, etc.)","example":"0"},"cst_icms":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cst Icms","description":"CST de ICMS, regime normal, 2 dígitos. Vazio quando o produto usa CSOSN/Simples Nacional.","example":"00"},"csosn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Csosn","description":"CSOSN de ICMS, Simples Nacional. Vazio quando o produto usa CST/regime normal."},"base_icms":{"type":"number","title":"Base Icms","description":"Base de cálculo do ICMS do item (R$)","default":0,"example":100.0},"aliquota_icms":{"type":"number","title":"Aliquota Icms","description":"Alíquota de ICMS aplicada (%)","default":0,"example":18.0},"valor_icms":{"type":"number","title":"Valor Icms","description":"Valor de ICMS do item (R$)","default":0,"example":18.0},"cst_pis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cst Pis","description":"CST de PIS do item","example":"01"},"base_pis":{"type":"number","title":"Base Pis","description":"Base de cálculo do PIS do item (R$)","default":0,"example":100.0},"aliquota_pis":{"type":"number","title":"Aliquota Pis","description":"Alíquota de PIS aplicada (%)","default":0,"example":1.65},"valor_pis":{"type":"number","title":"Valor Pis","description":"Valor de PIS do item (R$)","default":0,"example":1.65},"cst_cofins":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cst Cofins","description":"CST de COFINS do item","example":"01"},"base_cofins":{"type":"number","title":"Base Cofins","description":"Base de cálculo do COFINS do item (R$)","default":0,"example":100.0},"aliquota_cofins":{"type":"number","title":"Aliquota Cofins","description":"Alíquota de COFINS aplicada (%)","default":0,"example":7.6},"valor_cofins":{"type":"number","title":"Valor Cofins","description":"Valor de COFINS do item (R$)","default":0,"example":7.6},"cst_ibs":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cst Ibs","description":"CST de IBS do item, Reforma Tributária, vigência 2026+"},"base_ibs_uf":{"type":"number","title":"Base Ibs Uf","description":"Base de cálculo do IBS (UF) do item (R$), Reforma Tributária","default":0,"example":0.0},"aliquota_ibs_uf":{"type":"number","title":"Aliquota Ibs Uf","description":"Alíquota de IBS (UF) aplicada (%), Reforma Tributária","default":0,"example":0.0},"valor_ibs_uf":{"type":"number","title":"Valor Ibs Uf","description":"Valor de IBS (UF) do item (R$), Reforma Tributária","default":0,"example":0.0},"cst_cbs":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cst Cbs","description":"CST de CBS do item, Reforma Tributária, vigência 2026+"},"base_cbs":{"type":"number","title":"Base Cbs","description":"Base de cálculo do CBS do item (R$), Reforma Tributária","default":0,"example":0.0},"aliquota_cbs":{"type":"number","title":"Aliquota Cbs","description":"Alíquota de CBS aplicada (%), Reforma Tributária","default":0,"example":0.0},"valor_cbs":{"type":"number","title":"Valor Cbs","description":"Valor de CBS do item (R$), Reforma Tributária","default":0,"example":0.0},"cst_is":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cst Is","description":"CST de IS (Imposto Seletivo) do item, Reforma Tributária, vigência 2027+"},"base_is":{"type":"number","title":"Base Is","description":"Base de cálculo do IS do item (R$), Reforma Tributária","default":0,"example":0.0},"aliquota_is":{"type":"number","title":"Aliquota Is","description":"Alíquota de IS aplicada (%), Reforma Tributária","default":0,"example":0.0},"valor_is":{"type":"number","title":"Valor Is","description":"Valor de IS do item (R$), Reforma Tributária","default":0,"example":0.0},"valor_produto":{"type":"number","title":"Valor Produto","description":"Valor do produto no item, antes de desconto/rateios (R$)","default":0,"example":100.0},"valor_desconto":{"type":"number","title":"Valor Desconto","description":"Valor de desconto aplicado ao item (R$)","default":0,"example":0.0},"valor_frete_rateado":{"type":"number","title":"Valor Frete Rateado","description":"Parcela do frete da nota rateada proporcionalmente para este item (R$)","default":0,"example":5.0},"valor_seguro_rateado":{"type":"number","title":"Valor Seguro Rateado","description":"Parcela do seguro da nota rateada proporcionalmente para este item (R$)","default":0,"example":0.0},"valor_outras_rateado":{"type":"number","title":"Valor Outras Rateado","description":"Parcela de outras despesas da nota rateada proporcionalmente para este item (R$)","default":0,"example":0.0},"valor_ipi_produto":{"type":"number","title":"Valor Ipi Produto","description":"Valor de IPI do item (R$)","default":0,"example":0.0},"valor_st_produto":{"type":"number","title":"Valor St Produto","description":"Valor de ICMS-ST do item (R$)","default":0,"example":0.0},"valor_total_produto":{"type":"number","title":"Valor Total Produto","description":"Valor total do item (custo pousado): produto - desconto + IPI + rateios de frete/seguro/outras (R$)","default":0,"example":105.0}},"type":"object","required":["item"],"title":"NotaEntradaItemIn","description":"Item da nota de entrada.\n\nCampos fiscais usam nomenclatura canônica alinhada à convenção da IMendes\n(ncm, cfop, cstIcms/origemIcms, csosn, PIS/COFINS/IBS/CBS/IS). Cada\nintegrador de ERP é responsável por traduzir seus próprios campos para\neste formato antes do envio."},"PagamentoCupom":{"properties":{"tipopagto":{"type":"integer","title":"Tipopagto","description":"Código da forma de pagamento","example":3},"valor":{"type":"number","title":"Valor","description":"Valor pago nesta forma (R$)","example":11.98},"bandeiratef":{"type":"string","title":"Bandeiratef","description":"Bandeira do cartão (ex: VISA, MASTER, PIX)","default":"","example":""},"instituicaotef":{"type":"string","title":"Instituicaotef","description":"Instituição financeira ou adquirente","default":"","example":""},"nsu":{"type":"string","title":"Nsu","description":"NSU ou código de autorização da transação","default":"","example":""},"parcelas":{"type":"integer","title":"Parcelas","description":"Número de parcelas (1 = à vista)","default":1,"example":1},"dados_extras":{"additionalProperties":true,"type":"object","title":"Dados Extras","description":"Campos adicionais do seu gateway ou adquirente, como codigo_autorizacao_gateway, id_transacao_adquirente ou terminal_id. Os campos do padrão (tipopagto, valortot, bandeiratef e outros) têm precedência.","example":{"codigo_autorizacao_gateway":"AUTH123456","terminal_id":"TID-01"}}},"type":"object","required":["tipopagto","valor"],"title":"PagamentoCupom","description":"Forma de pagamento utilizada no cupom.\n\nUse dados_extras para campos específicos do seu gateway ou adquirente."},"PedidoCompraIn":{"properties":{"numero_pedido":{"type":"integer","title":"Numero Pedido","description":"Número do pedido de compra.","example":45001},"loja":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Loja","description":"Número da loja.","example":1},"loja_destino":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Loja Destino","description":"Loja de destino do pedido."},"tipo_pedido":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Pedido","description":"Tipo/código do pedido no ERP de origem.","example":"N"},"comprador_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Comprador Id","description":"Código do comprador responsável.","example":10},"fornecedor_id":{"type":"integer","title":"Fornecedor Id","description":"Código do fornecedor responsável.","example":1234},"pedido_fornecedor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pedido Fornecedor","description":"Número do pedido identificado pelo fornecedor.","example":"PC-778899"},"data_pedido":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Data Pedido","description":"Data de emissão do pedido.","example":"2026-07-01"},"data_entrega_prevista":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Data Entrega Prevista","description":"Data prevista de entrega.","example":"2026-07-10"},"frete":{"type":"number","title":"Frete","description":"Valor do frete do pedido.","default":0,"example":150.0},"adicional":{"type":"number","title":"Adicional","description":"Valores adicionais do pedido.","default":0,"example":0.0},"desconto":{"type":"number","title":"Desconto","description":"Valores de desconto do pedido.","default":0,"example":0.0},"frete_por_conta":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Frete Por Conta","description":"Responsável pelo frete: código do ERP de origem (ex.: 'C'=CIF, 'F'=FOB)","example":"C"},"cancelado":{"type":"boolean","title":"Cancelado","description":"Pedido cancelado. 'True' = cancelado e 'False' = não cancelado.","default":false,"example":false},"data_cancelamento":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Data Cancelamento","description":"Data do cancelamento."},"efetivado":{"type":"boolean","title":"Efetivado","description":"Pedido efetivado/confirmado junto ao fornecedor","default":false,"example":true},"condicoes_pagamento_dias":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Condicoes Pagamento Dias","description":"Prazos de pagamento em dias. Exemplo: [30, 60, 90] para 3x(parcelas))","example":[30,60,90]},"data_faturamento":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Data Faturamento","description":"Data de faturamento do pedido pelo fornecedor.","example":"2026-07-01"},"itens":{"items":{"$ref":"#/components/schemas/PedidoCompraItemIn"},"type":"array","title":"Itens","description":"Itens do pedido de compra."}},"type":"object","required":["numero_pedido","fornecedor_id"],"title":"PedidoCompraIn"},"PedidoCompraItemIn":{"properties":{"item":{"type":"integer","title":"Item","description":"Sequencial do item dentro do pedido (1, 2, 3…)","example":1},"loja_destino":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Loja Destino","description":"Loja de destino do item, quando o pedido é cross-dock/distribuição para múltiplas lojas","example":1},"cdprod":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cdprod","description":"Código do produto no ERP do lojista","example":"PRD001"},"codigo_produto_fornecedor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo Produto Fornecedor","description":"Código do produto no catálogo do próprio fornecedor","example":"FORN-9988"},"quantidade":{"type":"number","title":"Quantidade","description":"Quantidade pedida","default":0,"example":100.0},"caixa":{"type":"number","title":"Caixa","description":"Quantidade de caixas/embalagens pedidas","default":0,"example":10.0},"preco_caixa":{"type":"number","title":"Preco Caixa","description":"Preço unitário da caixa/embalagem (R$)","default":0,"example":50.0},"preco_unitario":{"type":"number","title":"Preco Unitario","description":"Preço unitário do item (R$)","default":0,"example":5.0},"percentual_desconto":{"type":"number","title":"Percentual Desconto","description":"Percentual de desconto negociado no item (%)","default":0,"example":2.5},"ipi":{"type":"number","title":"Ipi","description":"Alíquota de IPI do item (%)","default":0,"example":0.0},"valor":{"type":"number","title":"Valor","description":"Valor total do item, sem desconto (R$)","default":0,"example":500.0},"valor_desconto":{"type":"number","title":"Valor Desconto","description":"Valor do desconto aplicado ao item (R$)","default":0,"example":12.5},"valor_ipi":{"type":"number","title":"Valor Ipi","description":"Valor de IPI do item (R$)","default":0,"example":0.0},"custo_unitario":{"type":"number","title":"Custo Unitario","description":"Custo unitário de reposição do item (R$)","default":0,"example":4.8},"venda_sugerida":{"type":"number","title":"Venda Sugerida","description":"Preço de venda sugerido pelo ERP para o item (R$)","default":0,"example":7.99},"quantidade_recebida":{"type":"number","title":"Quantidade Recebida","description":"Quantidade efetivamente recebida até o momento, usada no cálculo de aderência de fornecedor","default":0,"example":95.0},"data_recebimento":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Data Recebimento","description":"Data em que a quantidade recebida foi registrada, comparada com data_entrega_prevista para aderência","example":"2026-07-10"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Status do item no ERP de origem (código livre do ERP)","example":"A"},"pedido_origem":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pedido Origem","description":"Número do pedido de origem, quando este item veio de um desdobramento/complemento de outro pedido"},"quantidade_bonificacao":{"type":"number","title":"Quantidade Bonificacao","description":"Quantidade recebida como bonificação/brinde do fornecedor, fora do valor cobrado","default":0,"example":0.0},"percentual_adicional":{"type":"number","title":"Percentual Adicional","description":"Percentual de acréscimo aplicado ao item (%)","default":0,"example":0.0},"valor_adicional":{"type":"number","title":"Valor Adicional","description":"Valor de acréscimo aplicado ao item (R$)","default":0,"example":0.0},"complemento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Complemento","description":"Observação/complemento livre sobre o item"}},"type":"object","required":["item"],"title":"PedidoCompraItemIn"},"PerguntarIn":{"properties":{"email":{"type":"string","title":"Email","description":"E-mail do cliente final (usuário ativo do mesmo parceiro do token).","example":"cliente@empresa.com.br"},"whatsapp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Whatsapp","description":"Telefone do cliente final, com DDI (obrigatório quando canal='whatsapp').","example":"5511999999999"},"contexto":{"type":"string","minLength":1,"title":"Contexto","description":"Pergunta em texto livre do cliente final.","example":"Quanto vendi ontem?"},"canal":{"type":"string","title":"Canal","description":"'whatsapp' (dispara a resposta por WhatsApp) ou 'chat' (devolve o texto na resposta).","example":"chat"},"pdf_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pdf Base64","description":"Opcional: relatório em PDF, em base64 (sem o prefixo data:application/...). O texto é extraído e analisado junto com a pergunta. Precisa ser um PDF gerado por sistema (com texto de verdade) — PDF digitalizado/escaneado ainda não é aceito. Máximo 10 MB e 10 páginas."},"nova_conversa":{"type":"boolean","title":"Nova Conversa","description":"Quando true, descarta qualquer contexto de conversa anterior desse e-mail (histórico, pergunta de esclarecimento pendente, loja/grupo em foco) ANTES de processar esta pergunta — use no primeiro turno de uma nova aba/sessão do seu lado, pra garantir que não herde contexto de uma conversa anterior ainda dentro do TTL de 20 minutos (ver saas_iaas_conversa_sessao).","default":false},"idioma":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idioma","description":"Idioma das respostas prontas do modo ERP (negativa por permissão, limite): 'pt-BR' (padrão), 'en-US' ou 'es-ES'.","example":"pt-BR"},"empresa_cnpj":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Empresa Cnpj","description":"CNPJ da empresa do usuário no ERP (opcional). Identifica a empresa na cota mensal de quem ainda não tem contrato; sem ele, vale o domínio do e-mail (e-mail de provedor público não identifica empresa).","example":"00.000.000/0001-91"}},"type":"object","required":["email","contexto","canal"],"title":"PerguntarIn"},"PlanoContaIn":{"properties":{"codigo":{"type":"integer","title":"Codigo"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao"},"categoria_dre":{"type":"string","enum":["CMV","DESPESA_OPERACIONAL","DESPESA_FINANCEIRA","RECEITA","OUTRAS"],"title":"Categoria Dre","default":"OUTRAS"}},"type":"object","required":["codigo"],"title":"PlanoContaIn","example":{"categoria_dre":"CMV","codigo":12,"descricao":"Compra de mercadorias para revenda"}},"RecebimentoPdvIn":{"properties":{"erp_id":{"type":"integer","title":"Erp Id"},"data_movimento":{"type":"string","format":"date","title":"Data Movimento"},"loja_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Loja Id"},"caixa_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Caixa Id"},"operador_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Operador Id"},"cupom_numero":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cupom Numero"},"codfin":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codfin"},"rede_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rede Id"},"bin_cartao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bin Cartao"},"tipo_tef":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Tef"},"tipo_parcela":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Parcela"},"valor_pdv":{"type":"number","title":"Valor Pdv","default":0},"valor_operadora":{"type":"number","title":"Valor Operadora","default":0},"valor_sangria":{"type":"number","title":"Valor Sangria","default":0},"num_parcelas":{"type":"integer","title":"Num Parcelas","default":1},"data_vencto":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Data Vencto"},"cliente_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cliente Id"},"empresa_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Empresa Id"}},"type":"object","required":["erp_id","data_movimento"],"title":"RecebimentoPdvIn","example":{"bin_cartao":"516292","caixa_id":2,"codfin":3,"cupom_numero":48213,"data_movimento":"2026-08-19","data_vencto":"2026-09-19","erp_id":771234,"loja_id":1,"num_parcelas":3,"operador_id":15,"rede_id":7,"tipo_parcela":"P","tipo_tef":"CREDITO","valor_operadora":146.1,"valor_pdv":150.0,"valor_sangria":0}},"RespostaMovimentos":{"properties":{"protocolo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Protocolo","description":"Protocolo sequencial do lote (YYYYMMDD-{id:010d}). `null` quando `status='sem_dados'`.","example":"20260619-0000000001"},"status":{"type":"string","title":"Status","description":"`recebido` | `sem_dados`","example":"recebido"},"itens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Itens","description":"Quantidade de cupons aceitos e recebidos.","example":3},"mensagem":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mensagem","description":"Presente apenas quando `status='sem_dados'`."}},"type":"object","required":["status"],"title":"RespostaMovimentos","description":"Retorno do endpoint /bi/movimentos."},"TaxaCartaoIn":{"properties":{"erp_codigo":{"type":"integer","title":"Erp Codigo"},"num_parcelas":{"type":"integer","title":"Num Parcelas","default":1},"tipo":{"type":"string","title":"Tipo","default":""},"bandeira_id":{"type":"integer","title":"Bandeira Id","default":0},"administradora_id":{"type":"integer","title":"Administradora Id","default":0},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao"},"taxa_mdr_perc":{"type":"number","title":"Taxa Mdr Perc","default":0},"taxa_doc_perc":{"type":"number","title":"Taxa Doc Perc","default":0},"taxa_transacao_perc":{"type":"number","title":"Taxa Transacao Perc","default":0},"dias_liquidacao":{"type":"integer","title":"Dias Liquidacao","default":0},"fornecedor_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fornecedor Id"},"tipo_adm":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Adm"},"credenciadora_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credenciadora Id"}},"type":"object","required":["erp_codigo"],"title":"TaxaCartaoIn","example":{"administradora_id":1,"bandeira_id":2,"descricao":"Visa Crédito 3x","dias_liquidacao":30,"erp_codigo":1,"num_parcelas":3,"taxa_doc_perc":0,"taxa_mdr_perc":3.15,"taxa_transacao_perc":0.1,"tipo":"CREDITO","tipo_adm":"CIELO"}},"UsuarioAdminCadastroIn":{"properties":{"nome":{"type":"string","title":"Nome","example":"Roberto Santos"},"email":{"type":"string","title":"Email","example":"roberto.santos@redeexemplo.com.br"},"telefone_whatsapp":{"type":"string","title":"Telefone Whatsapp","example":"11999998888"}},"type":"object","required":["nome","email","telefone_whatsapp"],"title":"UsuarioAdminCadastroIn"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"BI Vendas","description":"Recepção de vendas (movimentos do PDV)."},{"name":"BI Financeiro","description":"Recepção de dados financeiros (contas a pagar/receber, movimentos bancários e TEF)."},{"name":"BI Compras","description":"Recepção de compras (fornecedores, pedidos e notas de entrada)."},{"name":"API","description":"Informações da API."},{"name":"WhatsApp","description":"Envio de mensagens via WhatsApp para parceiros externos. Autenticação via header `api-key`."},{"name":"IAaaS","description":"Análise de produto e inteligência de mercado para parceiros externos. Autenticação via header `api-key`."},{"name":"Coleta","description":"Pesquisa de satisfação disparada pelo PDV (QR code ou WhatsApp), respondida pelo cliente final. Autenticação via header `api-key` para criar/consultar; a resposta em si é pública."}]}