Compras e Estoque

Endpoints da WebApiAlcance para gerenciar registros de compras vinculadas ao estoque - dados de notas fiscais de entrada, fornecedores, contas a pagar e valores originados do Klingo ERP. Cobrem criação, listagem com filtros e paginação, detalhamento por ID, atualização parcial e exclusão.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/compras-estoque

Escopos necessários

compras_estoque:read - listagem e detalhamento
compras_estoque:write - criação, atualização e exclusão

O escopo é derivado da rota: o prefixo /compras-estoque vira o recurso compras_estoque (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

`POST /compras-estoque/`

Cria um novo registro de compras/estoque. O id e o data_hora_criacao são gerados pelo servidor - não são aceitos no body.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ComprasEstoqueCreate), com todos os campos opcionais que descrevem a nota fiscal de entrada, o fornecedor, a conta a pagar e os valores.

Request

{
  "cnpj": "12345678000199",
  "cfg_emp": "ACME SERVICOS LTDA",
  "cct_descr": "Fornecedores nacionais",
  "nfe_serie": 1,
  "nfe_num": 45678,
  "nfe_fne_cod": 320,
  "nfe_dt_entrada": "2026-06-30",
  "fne_nome_fantasia": "Distribuidora Beta",
  "cpg_serie": 1,
  "cpg_num": 8890,
  "gcc_descr": "Mercadorias para revenda",
  "desconto": 0,
  "frete": 1500,
  "despesas": 0,
  "valor": 128000
}

Response 201 Created

{
  "success": true,
  "message": "Registro de compras/estoque criado com sucesso",
  "data": {
    "id": 501,
    "cnpj": "12345678000199",
    "cfg_emp": "ACME SERVICOS LTDA",
    "cct_descr": "Fornecedores nacionais",
    "nfe_serie": 1,
    "nfe_num": 45678,
    "nfe_fne_cod": 320,
    "nfe_dt_entrada": "2026-06-30",
    "fne_nome_fantasia": "Distribuidora Beta",
    "cpg_serie": 1,
    "cpg_num": 8890,
    "gcc_descr": "Mercadorias para revenda",
    "desconto": 0,
    "frete": 1500,
    "despesas": 0,
    "valor": 128000,
    "data_hora_criacao": "2026-06-30T14:22:05"
  }
}

Em caso de dados inválidos, retorna 422 Unprocessable Entity com o detail do erro de validação. Escopo: compras_estoque:write

`GET /compras-estoque/`

Lista os registros de compras/estoque, com filtros opcionais e paginação. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum registro de compras/estoque encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cfg_emp`	`str`	query	não	Filtra por empresa (`cfg_emp`).
`gcc_descr`	`str`	query	não	Filtra por grupo de conta contábil.
`limit`	`int` (1..500)	query	não	Limite de itens por página. Default `100`.
`offset`	`int` (>= 0)	query	não	Offset de paginação. Default `0`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registros de compras/estoque recuperados com sucesso",
  "data": [
    {
      "id": 501,
      "cnpj": "12345678000199",
      "cfg_emp": "ACME SERVICOS LTDA",
      "cct_descr": "Fornecedores nacionais",
      "nfe_serie": 1,
      "nfe_num": 45678,
      "nfe_fne_cod": 320,
      "nfe_dt_entrada": "2026-06-30",
      "fne_nome_fantasia": "Distribuidora Beta",
      "cpg_serie": 1,
      "cpg_num": 8890,
      "gcc_descr": "Mercadorias para revenda",
      "desconto": 0,
      "frete": 1500,
      "despesas": 0,
      "valor": 128000,
      "data_hora_criacao": "2026-06-30T14:22:05"
    }
  ]
}

Escopo: compras_estoque:read

`GET /compras-estoque/{compra_id}`

Detalha um registro de compras/estoque pelo ID inteiro. Quando não encontrado, retorna 404 Not Found com o detail do erro.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`compra_id`	`int`	path	sim	ID interno do registro.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro de compras/estoque recuperado com sucesso",
  "data": {
    "id": 501,
    "cnpj": "12345678000199",
    "cfg_emp": "ACME SERVICOS LTDA",
    "cct_descr": "Fornecedores nacionais",
    "nfe_serie": 1,
    "nfe_num": 45678,
    "nfe_fne_cod": 320,
    "nfe_dt_entrada": "2026-06-30",
    "fne_nome_fantasia": "Distribuidora Beta",
    "cpg_serie": 1,
    "cpg_num": 8890,
    "gcc_descr": "Mercadorias para revenda",
    "desconto": 0,
    "frete": 1500,
    "despesas": 0,
    "valor": 128000,
    "data_hora_criacao": "2026-06-30T14:22:05"
  }
}

Escopo: compras_estoque:read

`PUT /compras-estoque/{compra_id}`

Atualiza um registro existente. O body é um ComprasEstoqueUpdate com campos parciais - somente o que vier preenchido é alterado. Os campos cnpj e cfg_emp não podem ser alterados (são definidos apenas na criação).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`compra_id`	`int`	path	sim	ID do registro.

Request (ComprasEstoqueUpdate - todos os campos opcionais)

{
  "gcc_descr": "Material de uso e consumo",
  "frete": 2000,
  "valor": 130000
}

Response 200 OK

{
  "success": true,
  "message": "Registro de compras/estoque atualizado com sucesso",
  "data": {
    "id": 501,
    "cnpj": "12345678000199",
    "cfg_emp": "ACME SERVICOS LTDA",
    "cct_descr": "Fornecedores nacionais",
    "nfe_serie": 1,
    "nfe_num": 45678,
    "nfe_fne_cod": 320,
    "nfe_dt_entrada": "2026-06-30",
    "fne_nome_fantasia": "Distribuidora Beta",
    "cpg_serie": 1,
    "cpg_num": 8890,
    "gcc_descr": "Material de uso e consumo",
    "desconto": 0,
    "frete": 2000,
    "despesas": 0,
    "valor": 130000,
    "data_hora_criacao": "2026-06-30T14:22:05"
  }
}

Se o registro não existir, retorna 404 Not Found; outros erros de validação retornam 422 Unprocessable Entity. Escopo: compras_estoque:write

`DELETE /compras-estoque/{compra_id}`

Remove um registro de compras/estoque pelo ID. Quando o registro não existe, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`compra_id`	`int`	path	sim	ID do registro.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro de compras/estoque removido com sucesso",
  "data": null
}

Escopo: compras_estoque:write

Schemas

`ComprasEstoqueCreate`

Herda todos os campos de ComprasEstoqueBase. Todos são opcionais.

Campo	Tipo	Obrigatório	Observações
`cnpj`	`str`	não	CNPJ relacionado. Máx. 30 caracteres.
`cfg_emp`	`str`	não	Empresa (configuração). Máx. 300 caracteres.
`cct_descr`	`str`	não	Descrição da conta contábil. Máx. 300 caracteres.
`nfe_serie`	`int`	não	Série da nota fiscal de entrada.
`nfe_num`	`int`	não	Número da nota fiscal de entrada.
`nfe_fne_cod`	`int`	não	Código do fornecedor da NF-e.
`nfe_dt_entrada`	`str`	não	Data de entrada da NF-e. Máx. 30 caracteres.
`fne_nome_fantasia`	`str`	não	Nome fantasia do fornecedor. Máx. 300 caracteres.
`cpg_serie`	`int`	não	Série da conta a pagar.
`cpg_num`	`int`	não	Número da conta a pagar.
`gcc_descr`	`str`	não	Grupo de conta contábil. Máx. 300 caracteres.
`desconto`	`int`	não	Valor de desconto.
`frete`	`int`	não	Valor de frete.
`despesas`	`int`	não	Outras despesas.
`valor`	`int`	não	Valor total do registro.

`ComprasEstoqueUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Note que não inclui os campos cnpj nem cfg_emp (esses são definidos apenas na criação).

Campo	Tipo	Observações
`cct_descr`	`str`	Descrição da conta contábil. Máx. 300 caracteres.
`nfe_serie`	`int`	Série da nota fiscal de entrada.
`nfe_num`	`int`	Número da nota fiscal de entrada.
`nfe_fne_cod`	`int`	Código do fornecedor da NF-e.
`nfe_dt_entrada`	`str`	Data de entrada da NF-e. Máx. 30 caracteres.
`fne_nome_fantasia`	`str`	Nome fantasia do fornecedor. Máx. 300 caracteres.
`cpg_serie`	`int`	Série da conta a pagar.
`cpg_num`	`int`	Número da conta a pagar.
`gcc_descr`	`str`	Grupo de conta contábil. Máx. 300 caracteres.
`desconto`	`int`	Valor de desconto.
`frete`	`int`	Valor de frete.
`despesas`	`int`	Outras despesas.
`valor`	`int`	Valor total do registro.

`ComprasEstoqueRead`

Estende ComprasEstoqueBase com os campos gerados pelo servidor.

Campo	Tipo	Notas
`id`	`int`	Identificador do registro.
`data_hora_criacao`	`datetime`	Data e hora de criação do registro.
`cnpj`	`str`	CNPJ relacionado.
`cfg_emp`	`str`	Empresa (configuração).
`cct_descr`	`str`	Descrição da conta contábil.
`nfe_serie`	`int`	Série da NF-e.
`nfe_num`	`int`	Número da NF-e.
`nfe_fne_cod`	`int`	Código do fornecedor da NF-e.
`nfe_dt_entrada`	`str`	Data de entrada da NF-e.
`fne_nome_fantasia`	`str`	Nome fantasia do fornecedor.
`cpg_serie`	`int`	Série da conta a pagar.
`cpg_num`	`int`	Número da conta a pagar.
`gcc_descr`	`str`	Grupo de conta contábil.
`desconto`	`int`	Valor de desconto.
`frete`	`int`	Valor de frete.
`despesas`	`int`	Outras despesas.
`valor`	`int`	Valor total do registro.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro). Códigos HTTP refletem semântica REST padrão.
Os dados de compras/estoque são originados do Klingo ERP e refletem notas fiscais de entrada, fornecedores e contas a pagar.
GET /compras-estoque/ sempre retorna 200 OK, mesmo sem resultados - nesse caso data é [] e a mensagem indica que nenhum registro foi encontrado.
Os campos de valor (desconto, frete, despesas, valor) são inteiros; confirme com a integração se representam centavos ou unidades monetárias inteiras antes de exibir ao usuário final.
O schema ComprasEstoqueUpdate não permite alterar cnpj nem cfg_emp - para corrigir esses campos, recrie o registro.