BASE DE CONHECIMENTO

Documentação da API VendasPCP

Documentação da API

Referência geral da API REST do VendasPCP: autenticação, convenções e todos os endpoints disponíveis, organizados por assunto. Use o índice abaixo para ir direto ao endpoint desejado.

Visão geral

A API recebe e devolve JSON por HTTP, no endereço (URL base) informado na habilitação. Cada orçamento aprovado no CRM vira um pedido no VendasPCP, com a natureza de saída 2 – ORÇAMENTO. Esse tipo de pedido não baixa estoque e não gera contas a receber, então a integração não interfere no financeiro nem no estoque da empresa.

Localizar o clienteBusca por CPF/CNPJ em /cliente.
Cadastrar se não existir/cadcliente e depois buscar de novo para obter o código.
Localizar os produtos/produto devolve código, unidade e preço.
Enviar o orçamento/cadpedido com cabeçalho e itens. Retorna o id_venda.

Guarde o id_venda devolvido no passo 4 junto ao orçamento do CRM. Com ele é possível consultar o pedido depois e evitar envios em duplicidade.

Habilitação da integração

A empresa solicita a ativação da API à Querino Desenvolvimentos, informando o CNPJ da empresa que vai receber os pedidos.
A Querino habilita o CNPJ no servidor e envia, por canal privado:
- a URL base da API;
- o token de acesso;
- o código do usuário (id_usuario) e do vendedor (id_vendedor) que vão constar nos pedidos da integração.
A empresa faz os testes de envio e confere no VendasPCP os orçamentos gerados.
Com os testes aprovados, a integração é liberada para uso.

Guarde o token com segurança. Ele dá acesso aos dados da empresa no VendasPCP. Use-o apenas no servidor do CRM, nunca em aplicativos ou páginas abertas ao público, e avise a Querino caso ele seja exposto.

Autenticação

Toda requisição precisa destes cabeçalhos HTTP:

Cabeçalho	Valor
Authorization	`Bearer SEU_TOKEN`, com o token recebido na habilitação.
X-CNPJ	CNPJ da empresa habilitada. Identifica em qual base de dados o pedido será gravado.
Content-Type	`application/json; charset=utf-8`

Exemplo com cURL

curl -X POST "http://URL_BASE/cliente" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-CNPJ: 00000000000000" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"filtro": "12345678000199", "nivel": "0"}'

Convenções

Consultas também usam POST na maioria das rotas, com os filtros no corpo JSON. Envie sempre um JSON no corpo, mesmo que seja {}.
Exceção: leitura de imagem. GET /produto/{id}/imagem não usa corpo JSON e devolve o arquivo JPEG, não uma lista JSON.
Campos enviados usam snake_case (ex.: id_cliente).
Campos devolvidos nas consultas vêm em camelCase (ex.: idPessoa, nomeFantasia). As consultas devolvem sempre uma lista JSON, mesmo quando há um único resultado.
Códigos e valores marcados como número ou decimal vão como número JSON, sem aspas. Decimais usam ponto: 1250.50.
Datas enviadas como texto no formato dd/mm/aaaa.
Indicadores (flag_*) usam "S" para sim e "N" para não.
Mensagens de sucesso e de erro de algumas rotas de cadastro vêm como texto simples, não como JSON. Trate a resposta pelo código HTTP.

Exemplos demonstrativos. Os valores, códigos e dados dos exemplos desta documentação (como id_cliente, id_venda, idTipoPgto, nomes, totais e datas) servem apenas para ilustrar o formato. Eles variam de uma base para outra. Confirme sempre os códigos e os dados reais com uma consulta na própria requisição, usando as rotas de consulta e as tabelas de apoio da sua base.

Clientes

POST/cliente

Pesquisa clientes ativos. Devolve no máximo 50 registros.

Campo	Tipo	Descrição
filtro	string	Parte do nome ou razão social, código do cliente ou CPF/CNPJ (somente números). Vazio lista os primeiros 50.
niveluse “0”	string	Envie `"0"` para pesquisar em todos os clientes, sem restrição por vendedor.

Requisição

{
  "filtro": "12345678000199",
  "nivel": "0"
}

Resposta 200

[
  {
    "idPessoa": 1523,
    "nomeFantasia": "MERCADO BOA VISTA LTDA",
    "cpfCnpj": "12345678000199",
    "endereco": "RUA DAS FLORES, 120",
    "bairro": "CENTRO",
    "cidade": "SAO LUIS",
    "uf": "MA",
    "celular": "98999990000",
    "idTabelaPreco": 0,
    "idCondicoesPgto": 3,
    "idTipoPgto": 1,
    "flagVenda": "S"
  }
]

Outros campos devolvidos: idPessoaStr, numCasa, limiteCredito, diasBloqueio, descSituacao, telResidencial, telComercial, descricaoCondicoesPgto, flagRevenda, corCliente.

O código usado nos pedidos é o idPessoa. Quando flagVenda vier "N", a situação do cliente não permite vendas.

POST/cadcliente

Cadastra um novo cliente. Se o CPF/CNPJ já existir, o cadastro é recusado com o código 409.

Campo	Tipo	Descrição
flag_juridicaobrigatório	“S” \| “N”	`"S"` para pessoa jurídica (CNPJ), `"N"` para pessoa física (CPF).
cpf_cnpjobrigatório	string	CPF ou CNPJ, somente números.
razao_socialobrigatório	string	Razão social ou nome completo.
nome_fantasia	string	Nome fantasia.
ins_estadual	string	Inscrição estadual.
endereco	string	Logradouro.
num_casa	string	Número.
bairro	string	Bairro.
cep	string	CEP.
id_cidadeobrigatório	número	Código da cidade, obtido em `/cidades`.
celular	string	Celular.
tel_comercial	string	Telefone comercial.
tel_residencial	string	Telefone residencial.
email	string	E-mail.
id_pessoa_vendedor	número	Vendedor responsável pelo cliente (`/vendedor`).
id_grupo_cli	número	Grupo de clientes, se a empresa utilizar.
obs	string	Observações.

Requisição

{
  "flag_juridica": "S",
  "cpf_cnpj": "12345678000199",
  "razao_social": "MERCADO BOA VISTA LTDA",
  "nome_fantasia": "MERCADO BOA VISTA",
  "ins_estadual": "123456789",
  "endereco": "RUA DAS FLORES",
  "num_casa": "120",
  "bairro": "CENTRO",
  "cep": "65000000",
  "id_cidade": 2105,
  "celular": "98999990000",
  "email": "compras@boavista.com.br",
  "id_pessoa_vendedor": 7
}

Retorno	Corpo (texto)
200	`Cadastro Realizado com Sucesso`
409	`CNPJ ja cadastrado para o cliente MERCADO BOA VISTA LTDA.`
500	`Erro ao gravar CadCliente: …`

O cadastro não devolve o código do cliente. Depois do retorno 200, pesquise o CPF/CNPJ em /cliente para obter o idPessoa. No retorno 409, o cliente já existe: faça a mesma pesquisa e siga com o pedido.

POST/cidades

Lista as cidades cadastradas, opcionalmente filtradas por UF. Use para obter o id_cidade do cadastro de cliente.

Requisição

{ "UF": "MA" }

Resposta 200

[
  { "idCidade": 2105, "descricao": "SAO LUIS", "uf": "MA" }
]

Produtos

POST/produto

Pesquisa produtos ativos com preço, unidade e estoque. Devolve no máximo 100 registros, ordenados pela descrição.

Campo	Tipo	Descrição
filtro	string	Parte da descrição (espaços funcionam como curinga), referência, código do produto (até 8 dígitos) ou código de barras (10 dígitos ou mais).
LocalizaProdutouse true	boolean	Envie `true` para a pesquisa padrão.
id_tabela_preco	número	Tabela de preço a aplicar. `0` usa o preço de venda padrão do produto.

Requisição

{
  "filtro": "cimento",
  "LocalizaProduto": true,
  "id_tabela_preco": 0
}

Resposta 200

[
  {
    "idProduto": 101,
    "descricao": "CIMENTO CP II 50KG",
    "codBarras": "7891234567890",
    "referencia": "CIM50",
    "idUnidade": 1,
    "unidade": "SC",
    "precoVenda": 100.00,
    "precoPrazo": 105.00,
    "qtdeEstoque": 320.00,
    "ncm": "25232910"
  }
]

Outros campos devolvidos: precoPromocao, qtdeMinimaPromocao, promoData, promoSemana, percDesconto, controlarEstoque, flagPermiteComplementarNome, flagPermiteAlterarPrecoVend e os dados fiscais (percIpi, ipiCst, percIcms, icmsCst, icmsCsosn, icmsOrig, cfcod, percPis, percCofins, flagIsentoSt, cbenef, cest).

Para os itens do pedido, use idProduto e idUnidade deste retorno.

POST/cadproduto

Cadastra um produto. Use somente se o CRM também for responsável pelo cadastro de produtos. O código de barras, quando informado, não pode se repetir.

Campo	Tipo	Descrição
descricaoobrigatório	string	Descrição do produto.
id_grupoobrigatório	número	Grupo do produto (`/grupoprodutos`).
id_unidadeobrigatório	número	Unidade de medida (`/unidade`).
id_empresaobrigatório	número	Código da empresa no VendasPCP, informado na habilitação.
id_marca	número	Marca (`/marca`).
cod_barras	string	Código de barras (EAN).
ncm	string	NCM.
preco_venda	decimal	Preço de venda.
preco_custo	decimal	Preço de custo.
controlar_estoque	“S” \| “N”	Padrão `"S"`.
qtde_estoque	decimal	Estoque inicial.
estoque_minimo	decimal	Estoque mínimo.
obs	string	Observações.
imagem_base64	string	Foto em JPEG codificada em Base64, até 128 KB.

Retorno	Corpo (texto)
200	`Cadastro Realizado com Sucesso`
400	Campo obrigatório ausente ou imagem inválida. Ex.: `Grupo do produto não informado.`
409	`Código de barras já cadastrado no produto 101.`

O cadastro não devolve o código do produto. Pesquise pelo código de barras ou pela descrição em /produto para obter o idProduto. Para ler a foto cadastrada, use GET /produto/{id}/imagem.

GET/produto/{id}/imagem

Devolve a foto do produto em JPEG. Use o idProduto obtido em /produto. A rota não recebe corpo e devolve o arquivo da imagem, não JSON.

Parâmetro	Tipo	Descrição
idobrigatório	número (na URL)	Código do produto (`idProduto`).

Exemplo com cURL

curl -X GET "https://URL_BASE/produto/101/imagem" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-CNPJ: 00000000000000" \
  -o foto.jpg

Retorno	Corpo
200	Imagem JPEG (`Content-Type: image/jpeg`). A resposta traz `Cache-Control: private, max-age=3600`, então o CRM pode guardar a imagem por até uma hora.
400	`Id do produto inválido.`
404	`Produto sem imagem.` (texto simples).
500	Erro ao consultar a imagem. A mensagem vem em texto.

Nem todo produto tem foto. A imagem é gravada no cadastro, pelo campo imagem_base64 de /cadproduto. Quando não houver imagem, a rota responde 404.

Pedidos e orçamentos

POST/cadpedido

Grava o pedido de venda com todos os itens em uma única transação. Se qualquer item falhar, nada é gravado.

Natureza fixa: ORÇAMENTO. Envie "id_tipo_saida": 2 no cabeçalho e em cada item, com "flag_gera_creceber": "N" e "flag_saida_estoque": "N". Assim o pedido entra como orçamento, sem baixar estoque e sem gerar contas a receber.

Cabeçalho do pedido

Campo	Tipo	Descrição
id_tipo_saidafixo 2	número	Natureza do pedido. Sempre `2` (ORÇAMENTO).
id_clienteobrigatório	número	`idPessoa` obtido em `/cliente`.
id_vendedorobrigatório	número	Vendedor do pedido (`/vendedor`) ou o informado na habilitação.
id_usuarioobrigatório	número	Usuário da integração, informado na habilitação.
total_sem_descontoobrigatório	decimal	Soma de `qtde × valor_unit` de todos os itens.
valor_desconto	decimal	Desconto total do pedido. Padrão `0`.
total_vendaobrigatório	decimal	`total_sem_desconto − valor_desconto`.
flag_gera_creceberfixo “N”	“N”	Orçamento não gera contas a receber.
flag_venda_vista	“S” \| “N”	Venda à vista.
id_condicao_pgto	número	Condição de pagamento combinada (`/condpgto`).
id_tipo_pgto	número	Forma de pagamento (`/tipopgto`).
id_tabela_preco	número	Tabela de preço usada, se houver.
id_status_pedido	número	Status inicial (`/status`), se a empresa utilizar.
obs	string	Observação do pedido. Recomendamos incluir o número do orçamento no CRM.
itensobrigatório	lista	Itens do pedido (tabela abaixo). Ao menos um item.

Itens do pedido

Campo	Tipo	Descrição
id_produtoobrigatório	número	`idProduto` obtido em `/produto`.
id_unidadeobrigatório	número	`idUnidade` do produto.
qtdeobrigatório	decimal	Quantidade.
valor_unitobrigatório	decimal	Preço unitário negociado.
valor_desconto	decimal	Desconto do item em reais. Padrão `0`.
valor_totalobrigatório	decimal	`qtde × valor_unit − valor_desconto`.
id_tipo_saidafixo 2	número	Mesmo valor do cabeçalho: `2`.
flag_saida_estoquefixo “N”	“N”	Orçamento não baixa estoque.
descricao_complementar	string	Texto que substitui a descrição do produto no pedido (ex.: cor, medida).

Os campos fiscais do item (ICMS_CST, PERC_ICMS, ipiCST, PERC_IPI etc.) são opcionais e podem ser omitidos em orçamentos. Quando omitidos, são gravados com zero.

Os totais não são recalculados pela API. O VendasPCP grava os valores exatamente como enviados. Confira as contas antes do envio: a soma de valor_total dos itens deve ser igual a total_venda.

Requisição: orçamento com 2 itens

{
  "id_tipo_saida": 2,
  "id_cliente": 1523,
  "id_vendedor": 7,
  "id_usuario": 7,
  "id_condicao_pgto": 3,
  "id_tipo_pgto": 1,
  "flag_venda_vista": "N",
  "flag_gera_creceber": "N",
  "total_sem_desconto": 1250.00,
  "valor_desconto": 50.00,
  "total_venda": 1200.00,
  "obs": "Orçamento CRM nº 4587",
  "itens": [
    {
      "id_produto": 101,
      "id_unidade": 1,
      "qtde": 10,
      "valor_unit": 100.00,
      "valor_desconto": 50.00,
      "valor_total": 950.00,
      "id_tipo_saida": 2,
      "flag_saida_estoque": "N"
    },
    {
      "id_produto": 205,
      "id_unidade": 1,
      "qtde": 5,
      "valor_unit": 50.00,
      "valor_desconto": 0,
      "valor_total": 250.00,
      "id_tipo_saida": 2,
      "flag_saida_estoque": "N",
      "descricao_complementar": "ARGAMASSA AC-II CINZA 20KG"
    }
  ]
}

Resposta 200

{
  "id_venda": 58231,
  "msg": "Cadastro Realizado com Sucesso"
}

Resposta 500 (texto)

Erro ao gravar Itens do Pedido: …

O id_venda é o número do pedido no VendasPCP. A data do pedido é a data e hora do servidor no momento do envio.

Evite reenvio automático após erro de rede. Se a conexão cair antes da resposta, o pedido pode ter sido gravado. Antes de reenviar, consulte os orçamentos do dia em /pedidos filtrando pelo cliente e compare o valor total.

Consultar pedidos

POST/pedidos

Lista os pedidos não cancelados de uma natureza em uma data ou período.

Campo	Tipo	Descrição
naturezaobrigatório	string	Natureza dos pedidos. Use `"2"` para orçamentos.
datainiobrigatório	string	Data inicial, `dd/mm/aaaa`.
datafim	string	Data final, `dd/mm/aaaa`. Sem ela, a consulta é só do dia `dataini`.
cliente	string	Código do cliente. `"0"` para todos.
niveluse “0”	string	`"0"` lista pedidos de todos os vendedores.

Requisição: orçamentos do dia

{
  "natureza": "2",
  "dataini": "02/10/2026",
  "cliente": "0",
  "nivel": "0"
}

Resposta 200 (trecho)

[
  {
    "idVenda": 58231,
    "dataVendaStr": "02/10/2026",
    "totalVenda": 1200.00,
    "cpfCnpj": "12345678000199",
    "cliente": "MERCADO BOA VISTA LTDA",
    "flagVendaViaApp": "S",
    "statusPedido": ""
  }
]

Com datafim informado, a resposta é resumida: idVenda, dataVenda, dataVendaStr, valorTotal e valorRecebido.

POST/mostravenda

Devolve o cabeçalho completo de um pedido: cliente, natureza, forma e condição de pagamento, totais e dados da empresa.

Requisição

{ "id_venda": 58231 }

Resposta 200 (trecho)

[
  {
    "idVenda": 58231,
    "dataVenda": "2026-10-02",
    "descTipoSaida": "ORÇAMENTO",
    "razaoSocial": "MERCADO BOA VISTA LTDA",
    "descCondPgto": "30/60 DIAS",
    "totalSemDesconto": 1250.00,
    "valorDesconto": 50.00,
    "totalVenda": 1200.00
  }
]

Quando o pedido não existe, a resposta é uma lista vazia: [].

POST/mostraitens

Devolve os itens de um pedido.

Requisição

{ "id_venda": 58231 }

Resposta 200

[
  {
    "produto": "CIMENTO CP II 50KG",
    "valorUnit": 100.00,
    "qtde": 10,
    "valorTotal": 950.00,
    "idVenda": 58231
  }
]

Retorna 404 com o texto Busca sem retorno! quando o pedido não tem itens.

POST/vendaanexo

Anexa uma foto JPEG a uma venda (também grava como imagem do orçamento).

Campo	Tipo	Descrição
id_vendaobrigatório	número	Venda existente.
descricaoobrigatório	string	Descrição, de 1 a 60 caracteres.
imagem_base64obrigatório	string	Imagem JPEG em base64 puro, sem o prefixo `data:`, de até 128 KB.

Requisição

{
  "id_venda": 58231,
  "descricao": "Foto do pedido",
  "imagem_base64": "/9j/4AAQSkZJRg..."
}

Sucesso: 201 com o texto Anexo salvo.. Erros: 400 dado inválido ou imagem fora do limite, 404 pedido não encontrado.

Financeiro

Contas a receber, contas a pagar, cheques e caixa. Nas consultas por período as datas seguem dd/mm/aaaa, salvo onde indicado.

POST/baixacreceber

Registra o recebimento (baixa) de um título de contas a receber. Não altera juros nem desconto: grava somente o valor recebido.

Campo	Tipo	Descrição
id_contas_receberobrigatório	número	Código do título a baixar.
id_tipo_pgtoobrigatório	número	Tipo de pagamento ativo. Lista em `GET /tipopgto`.
id_usuarioobrigatório	número	Usuário que está registrando a baixa.
valorobrigatório	decimal	Valor recebido, maior que zero e até o saldo em aberto. Decimal com ponto.
data_pgtoobrigatório	string	Data do pagamento, `dd/mm/aaaa`.
id_bandeira	número	Bandeira do cartão. Lista em `GET /bandeira`.
id_conta_caixa	número	Conta caixa ativa. Sem ela, usa a conta do tipo de pagamento ou a primeira do usuário.
obs	string	Observação livre.

Requisição

{
  "id_contas_receber": 48120,
  "id_tipo_pgto": 3,
  "id_usuario": 7,
  "valor": "450.00",
  "data_pgto": "22/10/2026",
  "obs": "Recebido via PIX"
}

Resposta 201

{
  "ok": true,
  "id_baixa_creceber": 9021,
  "saldo_restante": 750
}

Erros vêm em texto: 400 dado inválido ou valor maior que o saldo, 403 usuário sem permissão para alterar a data de pagamento, 404 título não encontrado ou indisponível para baixa, 409 data com caixa fechado.

Atenção. A rota não é idempotente: repetir a chamada grava uma nova baixa até esgotar o saldo do título. Guarde o id_baixa_creceber devolvido.

GET/contasreceber

Lista os títulos em aberto, sem nenhuma baixa, que vencem de dois meses atrás até um mês à frente. Não recebe corpo nem filtros.

Resposta 200 (trecho)

[
  {
    "dataVcto": "2026-10-25T00:00:00.000Z",
    "valor": 1200,
    "cpfCnpj": "12345678000199",
    "razaoSocial": "MERCADO BOA VISTA LTDA",
    "celular": "11999990000",
    "email": "financeiro@boavista.com.br",
    "linhadigitavel": "00190.00009 ..."
  }
]

Campos devolvidos: dataVcto, valor, cpfCnpj, razaoSocial, celular, email e linhadigitavel. Esta rota não devolve o código do título.

POST/consultacontasreceber

Consulta títulos de contas a receber em um período.

Campo	Tipo	Descrição
tipoperiodo	string	`"0"` por emissão (padrão) ou `"1"` por vencimento.
datainiobrigatório	string	Data inicial, `dd/mm/aaaa`.
datafimobrigatório	string	Data final, `dd/mm/aaaa`.
mostrar	string	`"0"` todas, `"1"` pendentes, `"2"` vencidas, `"3"` recebidas.
cliente	string	Código do cliente. `"0"` para todos.

Requisição

{
  "tipoperiodo": "1",
  "dataini": "01/10/2026",
  "datafim": "31/10/2026",
  "mostrar": "1",
  "cliente": "0"
}

Resposta 200 (trecho)

[
  {
    "data": "2026-10-02",
    "dataStr": "02/10/2026",
    "idContasReceber": 48120,
    "idCliente": 310,
    "valor": 1200,
    "valorRecebido": 0,
    "dataVcto": "2026-10-30",
    "dataVctoStr": "30/10/2026",
    "nomeFantasia": "BOA VISTA"
  }
]

Sem resultado, responde 500 com o texto Busca sem retorno!.

POST/consultacontasapagar

Consulta parcelas de contas a pagar em um período.

Campo	Tipo	Descrição
tipoperiodo	string	`"0"` por emissão (padrão) ou `"1"` por vencimento.
datainiobrigatório	string	Data inicial, `dd/mm/aaaa`.
datafimobrigatório	string	Data final, `dd/mm/aaaa`.
fornecedor	string	Código do fornecedor. `"0"` para todos.

Requisição

{
  "tipoperiodo": "1",
  "dataini": "01/10/2026",
  "datafim": "31/10/2026",
  "fornecedor": "0"
}

Resposta 200 (trecho)

[
  {
    "data": "2026-10-05",
    "dataStr": "05/10/2026",
    "valor": 850,
    "valorPago": 0,
    "nomeFantasia": "DISTRIBUIDORA SUL",
    "codBarras": ""
  }
]

POST/consultadebitocliente

Lista os títulos vencidos de clientes com saldo devedor (até 100 linhas, vencidos nos últimos 500 dias), ordenados pelo nome.

Campo	Tipo	Descrição
niveluse “0”	string	Envie `"0"`.
id_usuario	string	Envie `"0"`.
id_cliente	string	Código do cliente. `"0"` para todos.

Requisição

{
  "nivel": "0",
  "id_usuario": "0",
  "id_cliente": "310"
}

Resposta 200 (trecho)

[
  {
    "valorPendente": 1200,
    "idCliente": 310,
    "razaoSocial": "BOA VISTA",
    "dataVcto": "2026-09-10",
    "dataVctoStr": "10/09/2026"
  }
]

POST/contaspendentes

Lista os títulos pendentes de um cliente ligados a vendas, ordenados por vencimento.

Campo	Tipo	Descrição
id_clienteobrigatório	string	Código do cliente.

Requisição

{
  "id_cliente": "310"
}

Resposta 200 (trecho)

[
  {
    "dataVcto": "2026-09-10",
    "idVenda": 58100,
    "valor": 1200,
    "diasVcto": 42
  }
]

valor é o total da venda, não o do título. diasVcto positivo indica dias em atraso; negativo, dias a vencer.

POST/saldocredito

Calcula o saldo de crédito do cliente: limite de crédito menos títulos sem baixa e cheques pendentes.

Campo	Tipo	Descrição
id_clienteobrigatório	string	Código do cliente.

Requisição

{
  "id_cliente": "310"
}

Resposta 200 (trecho)

[
  {
    "saldo": 3800
  }
]

Cliente inexistente devolve lista vazia.

POST/consultacheque

Consulta cheques recebidos em um período.

Campo	Tipo	Descrição
tipoperiodo	string	`"0"` emissão (padrão), `"1"` bom para, `"2"` lançamento, `"3"` compensação.
datainiobrigatório	string	Data inicial, `dd/mm/aaaa`.
datafimobrigatório	string	Data final, `dd/mm/aaaa`.
mostrar	string	`"0"` todos, `"1"` pendentes, `"2"` compensados, `"3"` devolvidos, `"4"` devolvidos pendentes.

Requisição

{
  "tipoperiodo": "1",
  "dataini": "01/10/2026",
  "datafim": "31/10/2026",
  "mostrar": "1"
}

Resposta 200 (trecho)

[
  {
    "dataPre": "2026-10-15",
    "dataPreStr": "15/10/2026",
    "valor": 600,
    "dataEmissao": "2026-09-15",
    "dataEmissaoStr": "15/09/2026",
    "razaoSocial": "BOA VISTA"
  }
]

POST/imprimicreceber

Devolve as parcelas de uma venda com a situação de pagamento, ordenadas por vencimento.

Campo	Tipo	Descrição
id_vendaobrigatório	número	Código da venda.

Requisição

{
  "id_venda": 58231
}

Resposta 200 (trecho)

[
  {
    "dataVcto": "2026-10-30",
    "valor": 600,
    "dataPgto": "2026-10-28",
    "valorRecebido": 600,
    "descTipoPgto": "PIX"
  }
]

POST/movcaixa/filtros

Lista as contas caixa ativas que o usuário pode consultar.

Campo	Tipo	Descrição
id_usuarioobrigatório	número	Usuário logado.

Requisição

{
  "id_usuario": 7
}

Resposta 200 (trecho)

{
  "contas_caixa": [
    {
      "idContaCaixa": 1,
      "descricao": "CAIXA GERAL",
      "numero": ""
    }
  ]
}

Se o usuário tem contas restritas, vêm só as dele; senão, todas as ativas.

POST/movcaixa/consultar

Movimento de caixa paginado, com resumo de entradas, saídas e saldo.

Campo	Tipo	Descrição
id_usuarioobrigatório	número	Usuário logado. Define as contas permitidas.
data_ini	string	Data inicial, `aaaa-mm-dd`. Padrão: hoje.
data_fim	string	Data final, `aaaa-mm-dd`, inclusive. Padrão: hoje.
ids_conta_caixa	lista	Códigos de contas caixa. Vazio: todas as permitidas.
pagina	número	Página, a partir de 1. Padrão 1.
itens_por_pagina	número	De 1 a 100. Padrão 50.
id_empresa	número	Empresa de referência para as configurações. Padrão 0 (primeira).

Requisição

{
  "id_usuario": 7,
  "data_ini": "2026-10-01",
  "data_fim": "2026-10-22",
  "pagina": 1,
  "itens_por_pagina": 50
}

Resposta 200 (trecho)

{
  "resumo": {
    "saldo_anterior": 0,
    "entradas": 5400,
    "saidas": 1800,
    "saldo_atual": 3600
  },
  "paginacao": {
    "pagina": 1,
    "itens_por_pagina": 50,
    "tem_mais": false
  },
  "movimentacoes": [
    {
      "dataMovimento": "2026-10-22",
      "valor": 450,
      "idContaCaixa": 1,
      "descContaCaixa": "CAIXA GERAL",
      "tipo": "R",
      "sinal": "+",
      "descricao": "VENDA 58231",
      "descTipoPgto": "PIX",
      "origem": "CONTAS_RECEBER"
    }
  ]
}

origem: CONTAS_RECEBER, CONTAS_PAGAR, LIVRO_CAIXA, TRANSFERENCIA, CHEQUE ou CREDITO_CLIENTE. tipo: R receber, P pagar, E cheque, X crédito de cliente. Nesta rota as datas usam aaaa-mm-dd.

POST/contaspagar/incluir

Cadastra uma conta a pagar com as suas parcelas em uma única chamada. A gravação é feita em uma transação: se qualquer parte falhar, nada é gravado.

Campo	Tipo	Descrição
id_empresaobrigatório	número	Código da empresa cadastrada no sistema.
id_fornecedorobrigatório	número	Código do fornecedor (pessoa marcada como fornecedor).
id_tipo_despesaobrigatório	número	Código de um tipo de despesa ativo.
id_usuarioobrigatório	número	Usuário que está realizando o lançamento.
data_compraobrigatório	data	Data da compra, no formato `dd/mm/aaaa`.
valor_contaobrigatório	decimal	Valor total da conta, maior que zero. Ponto como separador decimal.
parcelasobrigatório	lista	Ao menos uma parcela. A soma dos valores deve ser igual a `valor_conta`.
parcelas[].data_vctoobrigatório	data	Vencimento da parcela, no formato `dd/mm/aaaa`.
parcelas[].valor_parcelaobrigatório	decimal	Valor da parcela, maior que zero.
parcelas[].obs	string	Observação da parcela.
parcelas[].data_pgto	data	Data do pagamento, no formato `dd/mm/aaaa`. Informe junto com `id_conta_caixa` e `valor_pago` para lançar a parcela já paga.
parcelas[].id_conta_caixa	número	Conta caixa ativa e liberada para lançamento, de onde saiu o pagamento.
parcelas[].valor_pago	decimal	Valor pago, maior que zero e não maior que `valor_parcela`. Valor menor deixa saldo em aberto na parcela.
parcelas[].id_tipo_pgto	número	Tipo de pagamento ativo (opcional). Só vale em parcela paga.
numero_nf	número	Número da nota fiscal. Quando informado, cada parcela recebe o documento `número-parcela` (ex.: `9876-1`).
modelo_nf	string	Modelo da nota fiscal (até 2 caracteres).
serie_nf	string	Série da nota fiscal.
obs	string	Observação da conta.

Requisição

{
  "id_empresa": 1,
  "id_fornecedor": 3,
  "id_tipo_despesa": 2,
  "id_usuario": 1,
  "data_compra": "27/10/2026",
  "valor_conta": 1500.00,
  "numero_nf": 9876,
  "obs": "Compra de materiais",
  "parcelas": [
    { "data_vcto": "27/10/2026", "valor_parcela": 750.00,
      "data_pgto": "27/10/2026", "id_conta_caixa": 3, "valor_pago": 750.00 },
    { "data_vcto": "27/12/2026", "valor_parcela": 750.00 }
  ]
}

Resposta 201

{
  "ok": true,
  "id_contas_pagar": 343,
  "parcelas": [510, 511]
}

Erros vêm em texto: 400 dado inválido (soma das parcelas diferente do valor da conta, parcela sem valor, data inválida, empresa, fornecedor, tipo de despesa ou usuário inexistentes, lista de parcelas vazia, valor pago inválido, conta caixa inválida, inativa ou bloqueada para lançamento, tipo de pagamento inválido, baixa informada pela metade) 409 data de pagamento com caixa fechado e 500 falha ao gravar. Em caso de erro nada é gravado.

Atenção. As parcelas são numeradas na ordem de vencimento. A rota não é idempotente: repetir a mesma chamada cria uma nova conta. Guarde o id_contas_pagar devolvido. Para lançar uma parcela já paga, informe data_pgto, id_conta_caixa e valor_pago juntos; parcela sem esses campos fica em aberto.

Estoque

Acerto de estoque e balanço (inventário).

POST/acertoestoque

Registra um acerto de estoque para um produto, com log de usuário e motivo.

Campo	Tipo	Descrição
ID_USUARIOobrigatório	número	Usuário. Chaves em MAIÚSCULAS.
ID_PRODUTOobrigatório	número	Produto.
QTDEobrigatório	decimal	Quantidade do acerto.
QTDE_ATUAL	decimal	Saldo antes do acerto.
QTDE_ETQ_AJUSTADA	decimal	Quantidade ajustada.
QTDE_ETQ_MOVIMENTADA	decimal	Quantidade movimentada.
MOTIVO	string	Motivo do acerto.
FLUXO	string	Sentido do acerto (entrada ou saída).
OBS	string	Observação.

Requisição

{
  "ID_USUARIO": 7,
  "ID_PRODUTO": 1520,
  "QTDE": 10,
  "QTDE_ATUAL": 40,
  "MOTIVO": "INVENTARIO",
  "FLUXO": "ENTRADA",
  "OBS": ""
}

Sucesso: 200 com o texto Acerto de Estoque Realizado com Sucesso. Falha: 500 com corpo vazio.

Atenção. Nesta rota os nomes dos campos são em maiúsculas e a rota não valida produto nem quantidade.

POST/balanco

Lança uma contagem de balanço para um produto.

Campo	Tipo	Descrição
dataobrigatório	string	Data do balanço, `dd/mm/aaaa`.
id_produtoobrigatório	número	Produto.
qtdeobrigatório	número	Quantidade contada, número inteiro maior que zero.
id_usuarioobrigatório	número	Usuário.
id_empresaobrigatório	número	Empresa.

Requisição

{
  "data": "22/10/2026",
  "id_produto": 1520,
  "qtde": 48,
  "id_usuario": 7,
  "id_empresa": 1
}

Sucesso: 200 com o texto Balanço inserido com sucesso.. Erros: 400 data ou dados inválidos, 500 falha ao gravar. Vários lançamentos do mesmo produto no dia são permitidos.

POST/balanco/listar

Lista os lançamentos de balanço de uma data e empresa.

Campo	Tipo	Descrição
dataobrigatório	string	Data, `dd/mm/aaaa`.
id_empresaobrigatório	número	Empresa.

Requisição

{
  "data": "22/10/2026",
  "id_empresa": 1
}

Resposta 200 (trecho)

[
  {
    "idBalanco": 331,
    "data": "2026-10-22",
    "idProduto": 1520,
    "descricao": "CIMENTO CP II 50KG",
    "codBarras": "7891234567890",
    "qtde": 48,
    "flagEfetivado": "N"
  }
]

DELETE/balanco/:id_balanco

Exclui um lançamento de balanço. O código vai na URL.

Sucesso: 200 com o texto Balanço excluído com sucesso.. A rota não confere se o lançamento já foi efetivado nem se o código existe, então só exclua lançamentos pendentes.

Relatórios e indicadores

Totais por mês e indicadores gerenciais. Todas as rotas recebem o período no corpo e devolvem uma lista.

POST/vendames

Vendas por mês, das naturezas que geram contas a receber.

Campo	Tipo	Descrição
datainiobrigatório	string	Data inicial, `dd/mm/aaaa`.
datafimobrigatório	string	Data final, `dd/mm/aaaa`.

Requisição

{
  "dataini": "01/01/2026",
  "datafim": "31/10/2026"
}

Resposta 200 (trecho)

[
  {
    "mesano": "10/2026",
    "mes": 10,
    "totalVenda": 98500,
    "valorPendente": 21000,
    "ticketmedio": 1450
  }
]

A chave ticketmedio vem toda em minúsculas.

POST/receitames

Total recebido por mês (baixas de contas a receber).

Campo	Tipo	Descrição
datainiobrigatório	string	Data inicial, `dd/mm/aaaa`.
datafimobrigatório	string	Data final, `dd/mm/aaaa`.

Requisição

{
  "dataini": "01/01/2026",
  "datafim": "31/10/2026"
}

Resposta 200 (trecho)

[
  {
    "mesano": "10/2026",
    "mes": 10,
    "valorRecebido": 77500
  }
]

POST/contaspagar

Total pago por mês (contas a pagar e saídas do livro caixa). É um resumo mensal, não uma lista de títulos.

Campo	Tipo	Descrição
datainiobrigatório	string	Data inicial, `dd/mm/aaaa`.
datafimobrigatório	string	Data final, `dd/mm/aaaa`.

Requisição

{
  "dataini": "01/01/2026",
  "datafim": "31/10/2026"
}

Resposta 200 (trecho)

[
  {
    "mesano": "10/2026",
    "mes": 10,
    "valorPago": 31200
  }
]

POST/resumotipopgto

Total recebido por tipo de pagamento, do maior para o menor.

Campo	Tipo	Descrição
datainiobrigatório	string	Data inicial, `dd/mm/aaaa`.
datafimobrigatório	string	Data final, `dd/mm/aaaa`.

Requisição

{
  "dataini": "01/10/2026",
  "datafim": "31/10/2026"
}

Resposta 200 (trecho)

[
  {
    "descricao": "PIX",
    "valor": 42000
  }
]

POST/dashboard/totais

Totais do período: vendas, quantidades, novos clientes, contas pagas e receitas. Os /dashboard/* recebem o mesmo corpo.

Campo	Tipo	Descrição
datainiobrigatório	string	Data inicial, `dd/mm/aaaa`.
datafimobrigatório	string	Data final, `dd/mm/aaaa`.
niveluse “0”	string	`"0"` para todos os vendedores.
usuario	string	Código do usuário. Use `"0"` com `nivel` `"0"`.

Requisição

{
  "dataini": "01/10/2026",
  "datafim": "22/10/2026",
  "nivel": "0",
  "usuario": "0"
}

Resposta 200 (trecho)

[
  {
    "vlrVendas": 98500,
    "qtdeVendas": 68,
    "qtdeItens": 410,
    "qtdeNovosClientes": 5,
    "contasPagas": 31200,
    "receitas": 77500
  }
]