Klingo: Consumos

Endpoints da WebApiAlcance para os consumos do sistema Klingo. Cada execução dispara a chamada GET /consumos?mes=YYYY-MM na API Klingo, persiste o resultado (a execução-mãe mais os lançamentos de estoque/centro de custo) e permite consultá-lo depois. Cobrem a sincronização mensal, a listagem paginada das execuções do usuário autenticado e a busca de uma execução por ID (com lançamentos e payload bruto inline).

Base path

/api/v1/klingo/consumos

Escopos necessários

• klingo:read - listagem paginada e busca por ID
• klingo:write - sincronização (POST /sync/, escreve no banco e chama a API externa)

O escopo é derivado da rota: o primeiro segmento /klingo vira o recurso klingo (compartilhado com Relatórios e Despesas), e o método HTTP define a ação (read para GET, write para POST).

Endpoints

POST /klingo/consumos/sync/

Dispara GET /consumos?mes=YYYY-MM na API Klingo, persiste o resultado (execução-mãe mais os lançamentos) e devolve o registro recém-criado com os lancamentos inline. Operação de escrita não idempotente - escreve no banco e chama a API externa. Sujeita a rate limit (bucket klingo_consumos_sync, 10 requisições/min por IP).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (KlingoConsumoSyncInput): mes (obrigatório, formato YYYY-MM, mês entre 01 e 12).

Request

{
  "mes": "2026-06"
}

Response 200 OK

{
  "success": true,
  "message": "Consumos Klingo sincronizados com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "mes": "2026-06",
    "total_lancamentos": 128,
    "executado_em": "2026-06-30T18:05:11-03:00",
    "data_hora_criacao": "2026-06-30T18:05:11-03:00",
    "payload_bruto": {},
    "lancamentos": [
      {
        "id": 1001,
        "dt_movimentacao": "2026-06-15T10:22:00-03:00",
        "qtd": 3,
        "valor": 149.9,
        "item_nome": "Consulta cardiologia",
        "centro_nome": "Unidade Centro"
      }
    ]
  }
}

Payload da Klingo acima do limite retorna 413 Request Entity Too Large; regra de negócio da Klingo retorna 422 Unprocessable Entity; token rejeitado, falha de transporte/parse ou 404 do gateway retornam 502 Bad Gateway. Escopo: klingo:write

GET /klingo/consumos/

Lista, de forma paginada, as execuções de consumos do usuário autenticado, em ordem decrescente de executado_em. Sempre filtra por id_usuario_created = usuário logado. Lista vazia é um estado válido - retorna 200 OK com data: [] e a mensagem "Nenhuma execucao de consumos Klingo encontrada.".

Parâmetros

Retorna KlingoConsumoExecucaoReadSemDados - a projeção sem lancamentos e sem payload_bruto (a leitura completa fica em GET /{execucao_id}).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Execucoes de consumos Klingo recuperadas com sucesso",
  "data": {
    "items": [
      {
        "id": 42,
        "id_usuario_created": 7,
        "mes": "2026-06",
        "total_lancamentos": 128,
        "executado_em": "2026-06-30T18:05:11-03:00",
        "data_hora_criacao": "2026-06-30T18:05:11-03:00"
      }
    ],
    "total": 1
  }
}

Escopo: klingo:read

GET /klingo/consumos/{execucao_id}

Busca uma execução persistida pelo ID interno (klingo_consumos_execucoes.id), validando ownership (RLS por id_usuario_created). Retorna KlingoConsumoExecucaoRead (execução-mãe + payload_bruto + lancamentos) com eager load para evitar N+1 na serialização. Quando não encontrado (ou de outro usuário), retorna 404 Not Found com detail: "Execucao de consumos Klingo nao encontrada.".

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Execucao de consumos Klingo encontrada com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "mes": "2026-06",
    "total_lancamentos": 128,
    "executado_em": "2026-06-30T18:05:11-03:00",
    "data_hora_criacao": "2026-06-30T18:05:11-03:00",
    "payload_bruto": {},
    "lancamentos": [
      {
        "id": 1001,
        "dt_movimentacao": "2026-06-15T10:22:00-03:00",
        "qtd": 3,
        "valor": 149.9,
        "item_nome": "Consulta cardiologia",
        "centro_nome": "Unidade Centro"
      }
    ]
  }
}

Escopo: klingo:read

Schemas

KlingoConsumoSyncInput

Body de entrada de POST /klingo/consumos/sync/.

KlingoConsumoExecucaoReadSemDados

Projeção usada na listagem paginada. Sem lancamentos e sem payload_bruto (evita devolver MBs por item e dados brutos da Klingo sem filtro).

KlingoConsumoExecucaoRead

Projeção completa, usada em POST /sync/ e GET /{execucao_id}. Estende KlingoConsumoExecucaoReadSemDados (todos os campos acima) e acrescenta:

KlingoConsumoLancamentoRead

Cada lançamento persistido em klingo_consumos_lancamentos.

KlingoConsumoList

Envelope de paginação retornado por GET /klingo/consumos/.

Notas

• Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
• As rotas estáticas (POST /sync/ e GET /) são declaradas antes da rota dinâmica GET /{execucao_id}, evitando que o FastAPI faça pattern-match em "sync" como um execucao_id.
• Datas são normalizadas para o fuso America/Sao_Paulo na serialização quando chegam sem timezone.
• A listagem intencionalmente omite lancamentos e payload_bruto - para o dado completo, consulte a execução por ID.
• O POST /sync/ é uma operação de escrita não idempotente e sujeita a rate limit; não deve ser usado para leitura repetida.