Dicionário de campos

Envie os registros para POST /ingestao-erp como JSON. O corpo tem sempre type (a carga) e data (um array de registros):

{
  "type": "vendas",
  "data": [{ "id_externo": "erp:venda:filial-1:cupom-123:item-1", "tipo": "Venda", "data_referencia": "2026-07-16" }]
}

type aceita vendas, contas, entradas ou cancelamento. O campo tipo dentro de cada registro de vendas classifica a linha como venda ou movimentação de estoque. Os campos chamados de obrigatórios abaixo incluem os necessários para a gravação no banco. Outros campos podem ser importantes para relatórios mesmo quando a API aceita sua ausência.

Use datas no formato YYYY-MM-DD, números JSON com ponto decimal (12.99) e códigos como texto para preservar zeros à esquerda. Não envie cliente_id, afiliado_id, sistema_operacional ou data_ultima_atualizacao: o servidor preenche esses campos. O backend descarta os nomes antigos setor e familia; use grupo e subgrupo.

Vendas e movimentações

Use type: "vendas". Um registro com tipo ausente ou "Venda" compõe as métricas financeiras. "Quebra", "Saída" e "Transferência" são gravados como movimentações de estoque. O valor de tipo aceita diferenças de maiúsculas e acentos, mas prefira a grafia mostrada aqui.

Campo	Formato	Uso
id_externo	Texto; obrigatório para vendas	Chave estável e única da linha no ERP. Reenvie a mesma chave para atualizar a linha sem duplicá-la. Use também nas movimentações para permitir reenvio seguro.
tipo	Venda, Quebra, Saída ou Transferência	Define o destino da linha. Omissão equivale a Venda.
codigo	Texto	Código interno do produto em linhas de venda.
codigo_produto	Texto	Código interno do produto em Quebra, Saída e Transferência. O processamento de movimentações lê este nome, não codigo.
descricao	Texto	Descrição comercial do produto ou da movimentação.
ean	Texto de 13 dígitos, quando disponível	Código de barras do produto. Veja EAN e códigos fiscais.
grupo, subgrupo	Texto	Classificação gerencial usada nas análises; envie ambos quando disponíveis no ERP.
embalagem	Texto	Unidade ou apresentação comercial, por exemplo UN.
promocao	Texto	Indicador de promoção vindo do ERP; não há lista fixa de valores na API.
data_referencia	Data YYYY-MM-DD	Data operacional da venda; para movimentações, data do registro em estoque.
quantidade	Número	Quantidade da linha. Em movimentações, o backend grava o valor absoluto; se ausente ou zero, usa 1.
preco_atual	Número	Valor de venda da linha.
cmv_atual	Número	Custo da mercadoria vendida da linha.
custo_contabil_atual, custo_aquisicao_atual	Número	Custos contábil e de aquisição da linha. Em movimentações, o primeiro valor disponível é usado como custo contábil.
markup_cmv_atual, markdown_atual	Número	Percentual de markup sobre CMV e redução ou desconto gerencial, conforme o ERP.
lucro_liquido	Número	Lucro líquido da linha, se calculado na origem. lucro_bruto é legado e não é gravado pela função.
codigo_nota_fiscal, codigo_cupom_fiscal	Texto com algarismos	Número fiscal para relacionar venda e cancelamento. O servidor o converte para número; evite letras e pontuação.
serie_nota_fiscal, serie_cupom_fiscal	Texto	Série do documento fiscal; preserve zeros à esquerda.
pagamentos	Array de objetos	Formas de pagamento da venda; veja a tabela seguinte.
motivo_observacao	Texto	Observação para Quebra, Saída ou Transferência.

Cada objeto de pagamentos

Campo	Formato	Uso
metodo	Texto	Forma de pagamento, por exemplo credito.
valor	Número não negativo	Valor atribuído a essa forma.
bandeira	Texto	Bandeira do cartão, quando houver.
taxa	Número não negativo	Taxa informada pelo ERP.
parcelas	Inteiro positivo	Número de parcelas.
operadora	Texto	Operadora do pagamento.
meio_de_captura	Texto	Origem da captura, como TEF.
nsu	Texto	Identificador da transação; preserve zeros à esquerda.

O servidor remove propriedades desconhecidas de cada objeto de pagamento e descarta valores negativos ou inválidos de valor e taxa. parcelas é convertido para inteiro positivo. Envie somente dados que você conhece; a API não define uma lista fechada de métodos ou bandeiras.

Contas a pagar

Use type: "contas". A mesma combinação de cliente e id_externo atualiza um título já enviado.

Campo	Formato	Uso
id_externo	Texto; obrigatório para reenvio seguro	Chave estável do título no ERP.
nome_conta	Texto; obrigatório para gravação	Nome do fornecedor, favorecido ou descrição da despesa.
categoria	Texto	Classificação financeira do título.
valor	Número	Valor atualizado.
metodo_pagamento	Texto	Forma de pagamento prevista ou realizada.
validacao_pagamento	Booleano (true ou false)	Indica baixa confirmada.
data_entrada	Data YYYY-MM-DD; obrigatória para gravação	Data de emissão, lançamento ou entrada do título.
data_prevista	Data YYYY-MM-DD	Vencimento previsto.
data_efetiva	Data YYYY-MM-DD ou null	Data de pagamento ou baixa.

Em um reenvio, omitir data_efetiva ou validacao_pagamento, ou enviar null, não apaga o valor já gravado. data_ultima_atualizacao é gerada pelo servidor e não deve ser enviada.

Entradas de produtos

Use type: "entradas". A mesma combinação de cliente e id_externo atualiza o item de entrada.

Campo	Formato	Uso
id_externo	Texto; obrigatório para reenvio seguro	Chave estável da entrada ou do item no ERP.
descricao_produto	Texto; obrigatório para gravação	Nome do produto recebido.
codigo_produto	Texto	Código interno do produto no ERP.
ean	Texto de 13 dígitos, quando disponível	Código de barras do produto.
grupo, subgrupo	Texto	Classificação gerencial usada nas análises; envie ambos quando disponíveis.
quantidade	Número	Quantidade recebida.
custo, custo_contabil	Número	Custos unitários de compra e contábil.
data_referencia	Data YYYY-MM-DD; obrigatória para gravação	Data da nota, compra ou entrada.
ncm, cest	Texto com algarismos	Classificações fiscais, quando aplicáveis. Preserve zeros à esquerda.

Cancelamentos

Use type: "cancelamento". Envie o número da nota fiscal ou do cupom fiscal da venda original. Envie também a série correspondente para que a correspondência seja precisa. Cancelamentos são eventos novos; não usam o id_externo para upsert.

Campo	Formato	Uso
codigo_nota_fiscal	Texto com algarismos ou número	Número da nota cancelada, quando o cancelamento for por nota.
serie_nota_fiscal	Texto	Série da nota; deve coincidir com a série enviada na venda.
codigo_cupom_fiscal	Texto com algarismos ou número	Número do cupom cancelado, quando o cancelamento for por cupom.
serie_cupom_fiscal	Texto	Série do cupom; deve coincidir com a série enviada na venda.
motivo_cancelamento	Texto	Motivo, quando disponível.
data_cancelamento	Texto de data e hora	Horário do evento; exemplo: 2026-07-16 14:30:00. Não há validação explícita de um formato único na função.

O banco exige pelo menos um dos dois números fiscais. O processamento pode concluir sem encontrar uma venda correspondente se número e série não coincidirem; registre e acompanhe esse resultado no seu processo de integração.

EAN e códigos fiscais

Envie ean como texto para preservar zeros à esquerda. O backend mantém códigos com 13 dígitos. Um valor com letras vira o marcador 9999999999999; um código curto ou com pontuação vira 8888888888888. Para códigos com mais de 13 dígitos, ele tenta remover zeros iniciais. Não há conferência do dígito verificador; valide o GTIN no ERP antes de enviar. Se não houver EAN, omita o campo ou envie null.

Números de nota e cupom são convertidos em números pelo servidor. As séries permanecem texto e participam da localização de cancelamentos. Não envie pontuação nem caracteres não numéricos nos números fiscais.

Consulte a API Reference para os esquemas técnicos e respostas HTTP.