Caixa Cartão

Endpoints da WebApiAlcance para registrar e consultar movimentações de caixa via cartão - lançamentos de crédito/débito, saldos e conciliação originados da integração com o Klingo ERP. Cobrem criação, listagem com filtros (CNPJ, tipo) 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/caixa-cartao

Escopos necessários

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

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

Endpoints

`POST /caixa-cartao/`

Cria um novo registro de caixa cartão a partir dos dados de movimentação (integração Klingo ERP).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (CaixaCartaoCreate), cujos campos são todos opcionais. Veja o Schema CaixaCartaoCreate.

Request

{
  "cnpj": "12345678000199",
  "mcc_cnv": 1500.0,
  "mcc_lote": 3021,
  "mcc_dt": "2026-07-03T10:15:00",
  "saldo": 1500.0,
  "tipo": "CREDITO"
}

Response 201 Created

{
  "success": true,
  "message": "Caixa Cartão criado com sucesso",
  "data": {
    "id": 42,
    "cnpj": "12345678000199",
    "mcc_cnv": 1500.0,
    "mcc_lote": 3021,
    "mcc_dt": "2026-07-03T10:15:00",
    "saldo": 1500.0,
    "tipo": "CREDITO",
    "data_hora_criacao": "2026-07-03T10:15:02"
  }
}

Em caso de dados inválidos, retorna 422 Unprocessable Entity com detail descritivo. Escopo: caixa_cartao:write

`GET /caixa-cartao/`

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

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cnpj`	`str`	query	não	Filtra pelo CNPJ.
`tipo`	`str`	query	não	Filtra pelo tipo de movimentação.
`limit`	`int 1..500`	query	não	Limite de itens por página. Default `100`.
`offset`	`int >= 0`	query	não	Deslocamento de paginação. Default `0`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Caixas Cartão recuperados com sucesso",
  "data": [
    { "id": 42, "cnpj": "12345678000199", "tipo": "CREDITO", "saldo": 1500.0 },
    { "id": 43, "cnpj": "12345678000199", "tipo": "DEBITO", "saldo": -320.5 }
  ]
}

Escopo: caixa_cartao:read

`GET /caixa-cartao/{caixa_cartao_id}`

Detalha um registro de caixa cartão pelo ID inteiro. Quando não encontrado, retorna 404 Not Found com detail descritivo.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Caixa Cartão recuperado com sucesso",
  "data": {
    "id": 42,
    "cnpj": "12345678000199",
    "mcc_lote": 3021,
    "saldo": 1500.0,
    "tipo": "CREDITO",
    "data_hora_criacao": "2026-07-03T10:15:02"
  }
}

Escopo: caixa_cartao:read

`PUT /caixa-cartao/{caixa_cartao_id}`

Atualiza um registro existente. O body é um CaixaCartaoUpdate com campos parciais - somente o que vier preenchido é alterado. O cnpj não é alterável via update.

Parâmetros

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

O corpo segue o Schema CaixaCartaoUpdate, com todos os campos opcionais.

Request (CaixaCartaoUpdate - todos os campos opcionais)

{
  "saldo": 1750.0,
  "tipo": "CREDITO"
}

Response 200 OK

{
  "success": true,
  "message": "Caixa Cartão atualizado com sucesso",
  "data": {
    "id": 42,
    "cnpj": "12345678000199",
    "mcc_lote": 3021,
    "saldo": 1750.0,
    "tipo": "CREDITO",
    "data_hora_criacao": "2026-07-03T10:15:02"
  }
}

Quando não encontrado, retorna 404 Not Found; para valores inválidos, 422 Unprocessable Entity. Escopo: caixa_cartao:write

`DELETE /caixa-cartao/{caixa_cartao_id}`

Remove um registro de caixa cartão pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Caixa Cartão removido com sucesso",
  "data": null
}

Escopo: caixa_cartao:write

Schemas

`CaixaCartaoCreate`

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

Campo	Tipo	Obrigatório	Observações
`cnpj`	`str`	não	CNPJ associado. Máx. 30 caracteres.
`mcc_cnv`	`float`	não	Valor do convênio.
`mcc_lote`	`int`	não	Número do lote da movimentação.
`mcc_dt`	`datetime`	não	Data/hora da movimentação.
`saldo`	`float`	não	Saldo da movimentação.
`co_mcc_cre`	`float`	não	Valor de crédito.
`co_mcc_deb`	`float`	não	Valor de débito.
`cfo_nome`	`str`	não	Nome relacionado. Máx. 500 caracteres.
`mcc_obs`	`str`	não	Observação. Máx. 500 caracteres.
`mcc_doc`	`str`	não	Documento. Máx. 100 caracteres.
`saldo_fim`	`float`	não	Saldo final.
`saldo_conc`	`float`	não	Saldo conciliado.
`saldo_nao_conc`	`float`	não	Saldo não conciliado.
`tot_disp`	`float`	não	Total disponível.
`ccr_ccr_sini`	`float`	não	Valor de sinistro/CCR.
`tot_rec`	`float`	não	Total recebido.
`tipo`	`str`	não	Tipo de movimentação. Máx. 200 caracteres.
`saldo_ini_grupo`	`float`	não	Saldo inicial do grupo.
`saldo_subtotal`	`float`	não	Subtotal do saldo.

`CaixaCartaoUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Contém os mesmos campos de CaixaCartaoBase exceto cnpj (o CNPJ não é alterável via update).

Campo	Tipo	Observações
`mcc_cnv`	`float`	Valor do convênio.
`mcc_lote`	`int`	Número do lote.
`mcc_dt`	`datetime`	Data/hora da movimentação.
`saldo`	`float`	Saldo da movimentação.
`co_mcc_cre`	`float`	Valor de crédito.
`co_mcc_deb`	`float`	Valor de débito.
`cfo_nome`	`str`	Nome relacionado. Máx. 500 caracteres.
`mcc_obs`	`str`	Observação. Máx. 500 caracteres.
`mcc_doc`	`str`	Documento. Máx. 100 caracteres.
`saldo_fim`	`float`	Saldo final.
`saldo_conc`	`float`	Saldo conciliado.
`saldo_nao_conc`	`float`	Saldo não conciliado.
`tot_disp`	`float`	Total disponível.
`ccr_ccr_sini`	`float`	Valor de sinistro/CCR.
`tot_rec`	`float`	Total recebido.
`tipo`	`str`	Tipo de movimentação. Máx. 200 caracteres.
`saldo_ini_grupo`	`float`	Saldo inicial do grupo.
`saldo_subtotal`	`float`	Subtotal do saldo.

`CaixaCartaoRead`

Estende CaixaCartaoBase com os campos de identificação e auditoria.

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

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 caixa cartão originam-se da integração com o Klingo ERP; os prefixos mcc_ referem-se à movimentação de caixa por cartão.
GET /caixa-cartao/ sempre retorna 200 OK mesmo sem resultados - verifique data: [] em vez de tratar como erro.
A rota estática GET /caixa-cartao/ é declarada antes da rota dinâmica GET /caixa-cartao/{caixa_cartao_id}, evitando conflito de roteamento no FastAPI.