Caixa Espécie

Endpoints da WebApiAlcance para gerenciar movimentações de caixa em espécie originadas do Klingo ERP. Cada registro representa um lançamento de caixa (crédito/débito, saldos e conciliação) vinculado ao CNPJ do cliente. Cobrem criação, listagem geral (com filtro opcional por CNPJ e paginação), listagem por cliente, 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/caixa-especie

Escopos necessários

caixa_especie:read - listagem geral, listagem por cliente e detalhamento
caixa_especie:write - criação, atualização e exclusão

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

Endpoints

`POST /caixa-especie/`

Cria um novo registro de caixa em espécie. Os dados vão no corpo da requisição (CaixaEspecieCreate); o campo mais relevante é o cnpj, que vincula o lançamento ao cliente.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (CaixaEspecieCreate). Todos os campos são opcionais.

Request

{
  "cnpj": "12345678000199",
  "mcc_lote": "2026-000123",
  "mcc_dt": "2026-07-03T00:00:00",
  "saldo": "1500.00",
  "co_mcc_cre": "1200.00",
  "co_mcc_deb": "300.00",
  "cfo_nome": "Recebimento de vendas à vista",
  "mcc_obs": "Movimento diário do caixa",
  "mcc_doc": "REC-4521",
  "saldo_fim": "1500.00"
}

Response 201 Created

{
  "success": true,
  "message": "Registro de caixa espécie criado com sucesso",
  "data": {
    "id": 87,
    "cnpj": "12345678000199",
    "mcc_lote": "2026-000123",
    "mcc_dt": "2026-07-03T00:00:00",
    "saldo": "1500.00",
    "co_mcc_cre": "1200.00",
    "co_mcc_deb": "300.00",
    "cfo_nome": "Recebimento de vendas à vista",
    "mcc_obs": "Movimento diário do caixa",
    "mcc_doc": "REC-4521",
    "saldo_fim": "1500.00",
    "data_hora_criacao": "2026-07-03T10:22:41"
  }
}

Erros de validação de regra de negócio retornam 422 Unprocessable Entity com detail descrevendo o problema. Escopo: caixa_especie:write

`GET /caixa-especie/`

Lista registros de caixa em espécie, com filtro opcional por CNPJ e paginação. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum registro de caixa espécie encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cnpj`	`str`	query	não	Filtra os registros pelo CNPJ.
`limit`	`int`	query	não	Itens por página (`1..500`, default `100`).
`offset`	`int`	query	não	Deslocamento de paginação (`>= 0`, default `0`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registros de caixa espécie recuperados com sucesso",
  "data": [
    {
      "id": 87,
      "cnpj": "12345678000199",
      "mcc_lote": "2026-000123",
      "mcc_dt": "2026-07-03T00:00:00",
      "saldo": "1500.00",
      "co_mcc_cre": "1200.00",
      "co_mcc_deb": "300.00",
      "cfo_nome": "Recebimento de vendas à vista",
      "mcc_obs": "Movimento diário do caixa",
      "mcc_doc": "REC-4521",
      "saldo_fim": "1500.00",
      "data_hora_criacao": "2026-07-03T10:22:41"
    }
  ]
}

Escopo: caixa_especie:read

`GET /caixa-especie/cliente/{cnpj}`

Lista os registros de caixa em espécie de um cliente específico, identificado pelo CNPJ no path, com paginação. Lista vazia é um estado válido - retorna 200 OK com data: [].

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cnpj`	`str`	path	sim	CNPJ do cliente.
`limit`	`int`	query	não	Itens por página (`1..500`, default `100`).
`offset`	`int`	query	não	Deslocamento de paginação (`>= 0`, default `0`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registros de caixa espécie recuperados com sucesso",
  "data": [
    {
      "id": 87,
      "cnpj": "12345678000199",
      "mcc_lote": "2026-000123",
      "mcc_dt": "2026-07-03T00:00:00",
      "saldo": "1500.00",
      "co_mcc_cre": "1200.00",
      "co_mcc_deb": "300.00",
      "cfo_nome": "Recebimento de vendas à vista",
      "mcc_obs": "Movimento diário do caixa",
      "mcc_doc": "REC-4521",
      "saldo_fim": "1500.00",
      "data_hora_criacao": "2026-07-03T10:22:41"
    }
  ]
}

Escopo: caixa_especie:read

`GET /caixa-especie/{caixa_id}`

Detalha um registro de caixa em espécie pelo ID inteiro. Quando não encontrado, retorna 404 Not Found com detail descrevendo a ausência do registro.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro de caixa espécie recuperado com sucesso",
  "data": {
    "id": 87,
    "cnpj": "12345678000199",
    "mcc_lote": "2026-000123",
    "mcc_dt": "2026-07-03T00:00:00",
    "saldo": "1500.00",
    "co_mcc_cre": "1200.00",
    "co_mcc_deb": "300.00",
    "cfo_nome": "Recebimento de vendas à vista",
    "mcc_obs": "Movimento diário do caixa",
    "mcc_doc": "REC-4521",
    "saldo_fim": "1500.00",
    "data_hora_criacao": "2026-07-03T10:22:41"
  }
}

Escopo: caixa_especie:read

`PUT /caixa-especie/{caixa_id}`

Atualiza um registro existente. O body é um CaixaEspecieUpdate com campos parciais - somente o que vier preenchido é alterado.

Parâmetros

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

O campo cnpj não faz parte do CaixaEspecieUpdate - foi removido de propósito para evitar mass-assignment (trocar o dono do registro via PUT). O vínculo com o cliente é definido apenas na criação.

Request (CaixaEspecieUpdate - todos os campos opcionais)

{
  "saldo": "1800.00",
  "saldo_fim": "1800.00",
  "mcc_obs": "Ajuste de saldo após conferência"
}

Response 200 OK

{
  "success": true,
  "message": "Registro de caixa espécie atualizado com sucesso",
  "data": {
    "id": 87,
    "cnpj": "12345678000199",
    "mcc_lote": "2026-000123",
    "mcc_dt": "2026-07-03T00:00:00",
    "saldo": "1800.00",
    "co_mcc_cre": "1200.00",
    "co_mcc_deb": "300.00",
    "cfo_nome": "Recebimento de vendas à vista",
    "mcc_obs": "Ajuste de saldo após conferência",
    "mcc_doc": "REC-4521",
    "saldo_fim": "1800.00",
    "data_hora_criacao": "2026-07-03T10:22:41"
  }
}

Retorna 404 Not Found quando o registro não existe e 422 Unprocessable Entity em erro de validação. Escopo: caixa_especie:write

`DELETE /caixa-especie/{caixa_id}`

Remove um registro de caixa em espécie pelo ID.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro de caixa espécie removido com sucesso",
  "data": null
}

Retorna 404 Not Found quando o registro não existe. Escopo: caixa_especie:write

Schemas

`CaixaEspecieCreate`

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

Campo	Tipo	Obrigatório	Observações
`cnpj`	`str`	não	CNPJ do cliente. Máx. 30 caracteres.
`mcc_lote`	`str`	não	Identificador do lote de movimento. Máx. 30.
`mcc_dt`	`datetime`	não	Data do movimento de caixa.
`saldo`	`str`	não	Saldo do movimento. Máx. 30.
`co_mcc_cre`	`str`	não	Valor de crédito. Máx. 30.
`co_mcc_deb`	`str`	não	Valor de débito. Máx. 30.
`cfo_nome`	`str`	não	Nome/descrição da operação de caixa. Máx. 300.
`mcc_obs`	`str`	não	Observação do movimento. Máx. 300.
`mcc_doc`	`str`	não	Documento associado ao movimento. Máx. 30.
`saldo_fim`	`str`	não	Saldo final. Máx. 30.
`saldo_conc`	`str`	não	Saldo conciliado. Máx. 30.
`saldo_nao_conc`	`str`	não	Saldo não conciliado. Máx. 30.
`tot_disp`	`str`	não	Total disponível. Máx. 30.
`ccr_ccr_sini`	`str`	não	Campo auxiliar de conciliação. Máx. 30.
`tot_rec`	`str`	não	Total de recebimentos. Máx. 30.
`saldo_ini_grupo`	`str`	não	Saldo inicial do grupo. Máx. 30.
`saldo_subtotal`	`str`	não	Subtotal de saldo. Máx. 30.

`CaixaEspecieUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Não inclui cnpj (ver aviso em PUT).

Campo	Tipo	Observações
`mcc_lote`	`str`	Identificador do lote de movimento. Máx. 30.
`mcc_dt`	`datetime`	Data do movimento de caixa.
`saldo`	`str`	Saldo do movimento. Máx. 30.
`co_mcc_cre`	`str`	Valor de crédito. Máx. 30.
`co_mcc_deb`	`str`	Valor de débito. Máx. 30.
`cfo_nome`	`str`	Nome/descrição da operação. Máx. 300.
`mcc_obs`	`str`	Observação do movimento. Máx. 300.
`mcc_doc`	`str`	Documento associado. Máx. 30.
`saldo_fim`	`str`	Saldo final. Máx. 30.
`saldo_conc`	`str`	Saldo conciliado. Máx. 30.
`saldo_nao_conc`	`str`	Saldo não conciliado. Máx. 30.
`tot_disp`	`str`	Total disponível. Máx. 30.
`ccr_ccr_sini`	`str`	Campo auxiliar de conciliação. Máx. 30.
`tot_rec`	`str`	Total de recebimentos. Máx. 30.
`saldo_ini_grupo`	`str`	Saldo inicial do grupo. Máx. 30.
`saldo_subtotal`	`str`	Subtotal de saldo. Máx. 30.

`CaixaEspecieRead`

Estende CaixaEspecieBase com os campos gerados pelo servidor.

Campo	Tipo	Notas
`id`	`int`	Identificador do registro.
`data_hora_criacao`	`datetime`	Momento de criação do registro.
(demais campos)	-	Todos os campos de `CaixaEspecieBase` acima.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
Os campos monetários (saldo, co_mcc_cre, co_mcc_deb, saldo_fim etc.) são strings de até 30 caracteres - preservam a formatação de origem do Klingo ERP e não são normalizados para número pela API.
A rota GET /caixa-especie/cliente/{cnpj} é declarada antes da rota dinâmica GET /caixa-especie/{caixa_id}, então o prefixo cliente/ é resolvido corretamente e não é interpretado como um caixa_id.
Paginação: use limit (1..500) e offset (>= 0) nas listagens; o default é limit=100, offset=0.