Klingo: Relatórios

Endpoints da WebApiAlcance para trabalhar com relatórios do sistema Klingo - a plataforma de gestão de clínicas médicas integrada à Alcance. Cobrem a sincronização sob demanda (dispara a chamada na API da Klingo, persiste o resultado no banco), a listagem paginada dos relatórios já executados pelo usuário e a leitura individual de um registro com o dataset completo (colunas + linhas).

Base path

/api/v1/klingo/relatorio

Escopos necessários

• klingo:read - listagem paginada e leitura individual de relatórios persistidos
• klingo:write - sincronização (dispara a API externa e escreve no banco)

O escopo vem do primeiro segmento da rota (klingo) e o método HTTP define a ação (read para GET, write para POST). Como o escopo klingo é compartilhado entre Relatórios, Despesas e Consumos, emita API Keys com o menor escopo necessário - preferencialmente klingo:read.

Endpoints

POST /klingo/relatorio/sync/

Dispara a chamada GET /relatorio na API da Klingo, persiste o resultado no banco e devolve o registro recém-criado (com colunas e linhas inline). Não é idempotente (escreve no banco e chama a API externa a cada requisição), por isso é POST; está sujeito a rate limit no bucket klingo_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 (KlingoRelatorioSyncInput): id (obrigatório, ID do relatório na Klingo) e parametros (opcional, string crua de parâmetros).

Request

{
  "id": 20,
  "parametros": "data_inicio=2026-06-01&data_fim=2026-06-30"
}

Response 200 OK

{
  "success": true,
  "message": "Relatório Klingo sincronizado com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "id_relatorio_klingo": 20,
    "titulo": "Faturamento por convênio",
    "parametros_enviados": "data_inicio=2026-06-01&data_fim=2026-06-30",
    "total_linhas": 128,
    "klingo_status_code": 200,
    "klingo_msg": "OK",
    "executado_em": "2026-07-03T10:15:00-03:00",
    "data_hora_criacao": "2026-07-03T10:15:00-03:00",
    "colunas": [
      { "indice": 0, "nome": "convenio", "titulo": "Convênio", "tipo": "string" }
    ],
    "linhas": [
      { "indice": 0, "col0": "Unimed", "col1": "12.450,00" }
    ],
    "payload_bruto": {}
  }
}

Erros possíveis: 422 (regra de negócio da Klingo), 413 (payload excede o limite), 502 (token rejeitado, falha de transporte/parse ou 404 do gateway Klingo). Escopo: klingo:write

GET /klingo/relatorio/

Lista, de forma paginada, os relatórios persistidos do usuário autenticado, em ordem decrescente de executado_em. Sempre filtra por id_usuario_created = usuário logado (RLS por dono). Retorna KlingoRelatorioReadSemDados (mãe + colunas, sem linhas e sem payload_bruto); para o dataset completo, busque pelo GET /{relatorio_id}.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Relatórios Klingo recuperados com sucesso",
  "data": {
    "items": [
      {
        "id": 42,
        "id_usuario_created": 7,
        "id_relatorio_klingo": 20,
        "titulo": "Faturamento por convênio",
        "total_linhas": 128,
        "executado_em": "2026-07-03T10:15:00-03:00",
        "data_hora_criacao": "2026-07-03T10:15:00-03:00",
        "colunas": []
      }
    ],
    "total": 1
  }
}

Quando não há registros, retorna data: [] com a mensagem "Nenhum relatório Klingo encontrado.". Escopo: klingo:read

GET /klingo/relatorio/{relatorio_id}

Busca um registro persistido pelo ID interno (klingo_relatorios.id), validando o ownership (id_usuario_created = usuário logado). Retorna o dataset completo (KlingoRelatorioRead: mãe + colunas + linhas + payload_bruto), com eager load para evitar N+1 na serialização.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Relatório Klingo encontrado com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "id_relatorio_klingo": 20,
    "titulo": "Faturamento por convênio",
    "parametros_enviados": "data_inicio=2026-06-01&data_fim=2026-06-30",
    "total_linhas": 128,
    "klingo_status_code": 200,
    "klingo_msg": "OK",
    "executado_em": "2026-07-03T10:15:00-03:00",
    "data_hora_criacao": "2026-07-03T10:15:00-03:00",
    "colunas": [
      { "indice": 0, "nome": "convenio", "titulo": "Convênio", "tipo": "string" }
    ],
    "linhas": [
      { "indice": 0, "col0": "Unimed", "col1": "12.450,00" }
    ],
    "payload_bruto": {}
  }
}

Quando não encontrado (ou de outro dono), retorna 404 Not Found com detail: "Relatório Klingo não encontrado.". Escopo: klingo:read

Schemas

KlingoRelatorioSyncInput

KlingoRelatorioReadSemDados

Projeção usada na listagem paginada. Herda os campos-base; não inclui linhas nem payload_bruto.

KlingoRelatorioRead

Projeção completa, usada em POST /sync/ e GET /{relatorio_id}. Estende KlingoRelatorioReadSemDados acrescentando:

KlingoRelatorioColunaRead

KlingoRelatorioLinhaRead

Notas

• Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
• Ordem de rotas (FastAPI). As rotas estáticas POST /sync/ e GET / são declaradas antes da rota dinâmica GET /{relatorio_id}, para que o FastAPI não interprete sync como um relatorio_id.
• Os campos executado_em e data_hora_criacao são localizados no fuso America/Sao_Paulo na serialização.
• GET /{relatorio_id} usa o ID interno do registro persistido - diferente do id_relatorio_klingo (o ID do relatório na plataforma Klingo).
• O escopo klingo é compartilhado com Klingo: Despesas e Klingo: Consumos.