Klingo: Despesas

Endpoints da WebApiAlcance para as despesas do sistema Klingo. Cada execução representa uma sincronização de um mês: a API dispara a chamada à Klingo (GET /despesas?mes=YYYY-MM), persiste o resultado (a execução-mãe e seus lançamentos individuais) e devolve o registro criado. Além do disparo, há listagem paginada das execuções do usuário autenticado e busca de uma execução específica por ID.

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.

Escopo compartilhado do recurso klingo

O escopo é derivado do 1º segmento da rota (klingo), não de despesas. Portanto os escopos são klingo:read e klingo:write - os mesmos usados por Klingo: Relatórios e Klingo: Consumos. Uma API Key com klingo:read / klingo:write alcança todos os subrecursos klingo/*. Emita chaves com esse escopo apenas quando o consumidor realmente precisar de todo o domínio Klingo.

Base path

/api/v1/klingo/despesas

Escopos necessários

klingo:read - listagem das execuções e busca por ID
klingo:write - sincronização (dispara a chamada à Klingo e persiste)

O recurso é o primeiro segmento da rota (klingo), compartilhado por todos os subrecursos do domínio Klingo (Despesas, Relatórios, Consumos). O método HTTP define a ação: read para GET, write para POST.

Endpoints

`POST /klingo/despesas/sync/`

Dispara GET /despesas?mes=YYYY-MM na Klingo, persiste o resultado (execução-mãe + lançamentos) e devolve o registro recém-criado, já com os lancamentos inline.

Rate limit

Bucket klingo_despesas_sync: 10 requisições/min. A infra atual aplica o limite por IP (migração para por-usuário planejada).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (KlingoDespesaSyncInput): mes (obrigatório), no formato YYYY-MM (regex ^\d{4}-(0[1-9]\|1[0-2])$), ex.: 2026-05.

Request

{
  "mes": "2026-05"
}

Response 200 OK

{
  "success": true,
  "message": "Despesas Klingo sincronizadas com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "mes": "2026-05",
    "total_lancamentos": 128,
    "executado_em": "2026-05-31T09:12:00-03:00",
    "data_hora_criacao": "2026-05-31T09:12:00-03:00",
    "payload_bruto": {},
    "lancamentos": [
      {
        "id": 1001,
        "id_lancamento_klingo": 55012,
        "descricao": "Aluguel unidade centro",
        "emissao": "2026-05-05",
        "venc": "2026-05-10",
        "valor": "3500.00",
        "categoria_nome": "Despesas fixas",
        "data_hora_criacao": "2026-05-31T09:12:00-03:00"
      }
    ]
  }
}

O service mapeia ValueError para o status HTTP: 422 (regra de negócio), 502 (token rejeitado, falha de transporte/HTTP/parse ou 404 do gateway Klingo), 413 (payload da Klingo excede o limite) e 404 (registro não encontrado por RLS). Escopo: klingo:write

`GET /klingo/despesas/`

Lista, de forma paginada, as execuções persistidas do usuário autenticado, em ordem decrescente de executado_em. Sempre filtra por id_usuario_created = usuário logado. Retorna a projeção enxuta KlingoDespesaExecucaoReadSemDados - sem lancamentos e sem payload_bruto; use GET /{execucao_id} para o dataset completo.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`skip`	`int >= 0`	query	não	Offset para paginação. Default `0`.
`limit`	`int 1..200`	query	não	Tamanho da página. Default `50`.
`mes`	`str`	query	não	Filtra por mês no formato `YYYY-MM` (regex `^\d{4}-(0[1-9]\|1[0-2])$`).
`executado_em_inicio`	`datetime`	query	não	Filtra por `executado_em >= valor` (ISO 8601).
`executado_em_fim`	`datetime`	query	não	Filtra por `executado_em <= valor` (ISO 8601). Hora `00:00:00` é expandida para o fim do dia.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Execucoes de despesas Klingo recuperadas com sucesso",
  "data": {
    "items": [
      {
        "id": 42,
        "id_usuario_created": 7,
        "mes": "2026-05",
        "total_lancamentos": 128,
        "executado_em": "2026-05-31T09:12:00-03:00",
        "data_hora_criacao": "2026-05-31T09:12:00-03:00"
      }
    ],
    "total": 1
  }
}

Quando não há registros, data é [] com a mensagem "Nenhuma execucao de despesas Klingo encontrada.". Escopo: klingo:read

`GET /klingo/despesas/{execucao_id}`

Busca uma execução persistida pelo ID interno (klingo_despesas_execucoes.id), validando ownership (RLS por id_usuario_created). Retorna KlingoDespesaExecucaoRead - mãe + lancamentos (com eager load para evitar N+1).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`execucao_id`	`int`	path	sim	ID interno da execução persistida.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Execucao de despesas Klingo encontrada com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "mes": "2026-05",
    "total_lancamentos": 128,
    "executado_em": "2026-05-31T09:12:00-03:00",
    "data_hora_criacao": "2026-05-31T09:12:00-03:00",
    "payload_bruto": {},
    "lancamentos": [
      {
        "id": 1001,
        "id_lancamento_klingo": 55012,
        "descricao": "Aluguel unidade centro",
        "emissao": "2026-05-05",
        "venc": "2026-05-10",
        "valor": "3500.00",
        "categoria_nome": "Despesas fixas",
        "data_hora_criacao": "2026-05-31T09:12:00-03:00"
      }
    ]
  }
}

Quando não encontrado (ou de outro usuário), retorna 404 Not Found. Escopo: klingo:read

Schemas

`KlingoDespesaSyncInput`

Body do POST /sync/. O período vai no body (write não idempotente), nunca na query string.

Campo	Tipo	Obrigatório	Observações
`mes`	`str`	sim	Formato `YYYY-MM`, validado por regex. Ex.: `2026-05`.

`KlingoDespesaExecucaoReadSemDados`

Projeção enxuta para a listagem paginada - sem lancamentos e sem payload_bruto.

Campo	Tipo	Notas
`id`	`int`	Identificador da execução.
`id_usuario_created`	`int`	Usuário que criou a execução (base do RLS).
`mes`	`str`	Mês sincronizado (`YYYY-MM`).
`total_lancamentos`	`int?`	Quantidade de lançamentos da execução.
`executado_em`	`datetime`	Momento da execução (America/Sao_Paulo).
`data_hora_criacao`	`datetime`	Criação do registro (America/Sao_Paulo).

`KlingoDespesaExecucaoRead`

Projeção completa (usada em POST /sync/ e GET /{id}). Estende a projeção enxuta com os campos pesados.

Campo	Tipo	Notas
(todos acima)	-	Mesmos campos de `KlingoDespesaExecucaoReadSemDados`.
`payload_bruto`	`Any`	Payload bruto retornado pela Klingo. Default `null`.
`lancamentos`	`List[KlingoDespesaLancamentoRead]`	Lançamentos individuais da execução. Default `[]`.

`KlingoDespesaList`

Página de execuções devolvida por GET /klingo/despesas/.

Campo	Tipo	Notas
`items`	`List[KlingoDespesaExecucaoReadSemDados]`	Execuções da página (projeção enxuta).
`total`	`int`	Total absoluto de execuções (sem paginação).

`KlingoDespesaLancamentoRead`

Lançamento individual persistido em klingo_despesas_lancamentos (aparece dentro de lancamentos).

Campo	Tipo	Notas
`id`	`int`	Identificador interno do lançamento.
`id_lancamento_klingo`	`int?`	ID do lançamento na Klingo.
`id_unidade_operacao`	`int?`	Unidade de operação.
`id_centro_custo`	`int?`	Centro de custo.
`id_fornecedor`	`int?`	Fornecedor.
`id_categoria`	`int?`	Categoria.
`emissao`	`date?`	Data de emissão.
`venc`	`date?`	Data de vencimento.
`doc`	`str?`	Documento.
`descricao`	`str?`	Descrição do lançamento.
`mes`	`str?`	Mês de referência.
`valor_bruto`	`Decimal?`	Valor bruto.
`valor_adiantado`	`Decimal?`	Valor adiantado.
`valor`	`Decimal?`	Valor final.
`categoria_nome`	`str?`	Nome da categoria.
`categoria_natureza`	`str?`	Natureza da categoria.
`centro_nome`	`str?`	Nome do centro de custo.
`unidade_nome`	`str?`	Nome da unidade.
`unidade_sigla`	`str?`	Sigla da unidade.
`fornecedor_nome_fantasia`	`str?`	Nome fantasia do fornecedor.
`fornecedor_cpf_cnpj`	`str?`	CPF/CNPJ do fornecedor.
`payload_bruto_lancamento`	`Any`	Payload bruto do lançamento vindo da Klingo.
`data_hora_criacao`	`datetime`	Criação do registro (America/Sao_Paulo).

Notas

Armadilha de roteamento FastAPI

As rotas estáticas POST /sync/ e GET / são declaradas antes da rota dinâmica GET /{execucao_id}, para que o FastAPI não interprete sync como um execucao_id. Ao chamar a sincronização, use a barra final: /klingo/despesas/sync/.

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
A listagem (GET /) devolve a projeção enxuta (sem lancamentos nem payload_bruto) por questão de volume e segurança; busque pelo GET /{id} quando precisar do dataset completo.
Todo acesso é restrito ao usuário autenticado (id_usuario_created): a listagem filtra e a busca por ID valida ownership (RLS), retornando 404 para execuções de outros usuários.
Datas/horas são normalizadas para o fuso America/Sao_Paulo na serialização.
Recurso compartilha os escopos klingo:read / klingo:write com Klingo: Relatórios e Klingo: Consumos.