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 e a leitura individual de um registro com o dataset completo (colunas + linhas).

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.

Escopo compartilhado

O recurso é derivado do 1º segmento após /api/v1/, que é klingo. Portanto os escopos são klingo:read / klingo:write - não klingo_relatorio. Esse escopo klingo é compartilhado com Klingo: Despesas e Klingo: Consumos: uma API Key com klingo:read enxerga a leitura dos três domínios.

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 grava dados)

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/

Busca o relatório na API da Klingo para o período informado, persiste o resultado no banco e devolve o registro recém-criado (com colunas e linhas inline). Não é idempotente (grava dados e chama a API externa a cada requisição), por isso é POST; está sujeito a limite de tentativas; ao exceder, 429 com Retry-After.

Mudança incompatível: o campo parametros foi removido

O campo parametros não existe mais no corpo. A busca é sempre por período explícito (periodo, com data_inicio e data_fim quando livre). Clientes que ainda enviam parametros devem migrar para periodo/data_inicio/data_fim.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (KlingoRelatorioSyncInput):

CampoTipoObrigatórioObservações
id_clienteintsimCliente cuja credencial Klingo busca o dado. Mínimo 1.
idintsimID do relatório na Klingo. Mínimo 1.
periodostrnãoModo do período. Default l (intervalo livre). Máx. 20 caracteres, só letras, números, _ e -.
data_iniciodatecondicionalYYYY-MM-DD. Obrigatório com periodo = "l"; proibido com preset.
data_fimdatecondicionalYYYY-MM-DD, inclusivo e não anterior a data_inicio. Obrigatório com periodo = "l"; proibido com preset.

Valores de periodo: l (livre, usa as datas) ou um preset da Klingo, como h (hoje), o (ontem), s (essa semana), m (mês atual), ma (mês anterior), a (ano atual), aa (ano anterior), u3, u6 e u9 (últimos 30, 60 e 90 dias - atenção: não são u30, u60 e u90). Os presets disponíveis variam por relatório.

Request

{
  "id_cliente": 154,
  "id": 20,
  "periodo": "l",
  "data_inicio": "2026-06-01",
  "data_fim": "2026-06-30"
}

Com preset:

{ "id_cliente": 154, "id": 20, "periodo": "u9" }

Response 200 OK

{
  "status": "success",
  "message": "Relatório Klingo sincronizado com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "id_cliente": 154,
    "id_relatorio_klingo": 20,
    "titulo": "Faturamento por convênio",
    "params_enviados": {
      "enviado": { "id": 20, ":periodo0": "l", ":periodo0-from": "2026-06-01", ":periodo0-to": "2026-06-30" },
      "periodo_aplicado": "l"
    },
    "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": "Operadora Exemplo", "col1": "12.450,00" }
    ]
  }
}

Erros: 422 combinação inválida de período (preset com datas, periodo = "l" sem as duas datas, data_fim anterior a data_inicio), preset rejeitado pela Klingo ou regra de negócio da Klingo; 409 cliente sem credencial Klingo utilizável; 413 resposta acima do limite; 502 token rejeitado ou falha de comunicação com a Klingo. Período válido sem movimento não é erro: retorna 200 com zero linhas. Escopo: klingo:write

GET /klingo/relatorio/

Lista, de forma paginada, os relatórios persistidos, em ordem decrescente de executado_em. A visão é compartilhada entre os usuários internos do escritório (id_usuario_created indica só a autoria). Retorna KlingoRelatorioReadSemDados (mãe + colunas, sem linhas); para o dataset completo, busque pelo GET /{relatorio_id}.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
skipint >= 0querynãoOffset para paginação. Default 0.
limitint 1..200querynãoTamanho da página. Default 50.
id_relatorio_klingoint >= 1querynãoFiltra pelo ID do relatório na Klingo.
executado_em_iniciodatetimequerynãoFiltra por executado_em >= valor (ISO 8601).
executado_em_fimdatetimequerynãoFiltra 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

{
  "status": "success",
  "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. Qualquer usuário autenticado pode ler qualquer execução. Retorna o dataset completo (KlingoRelatorioRead: mãe + colunas + linhas).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
relatorio_idintpathsimID interno do relatório persistido (não é o ID da Klingo).

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Relatório Klingo encontrado com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "id_relatorio_klingo": 20,
    "titulo": "Faturamento por convênio",
    "id_cliente": 154,
    "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": "Operadora Exemplo", "col1": "12.450,00" }
    ]
  }
}

Quando não encontrado, retorna 404 Not Found. Escopo: klingo:read

Schemas

KlingoRelatorioSyncInput

Campos descritos em POST /klingo/relatorio/sync/: id_cliente, id, periodo, data_inicio e data_fim.

KlingoRelatorioReadSemDados

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

CampoTipoNotas
idintID interno do registro persistido.
id_usuario_createdintUsuário que executou a sincronização (autoria).
id_clienteint?Cliente cuja credencial Klingo buscou o dado.
id_relatorio_klingointID do relatório na Klingo.
titulostr?Título do relatório.
params_enviadosAny?Request enviado à Klingo (enviado) e período que a Klingo diz ter aplicado (periodo_aplicado, null se não ecoou).
total_linhasint?Quantidade de linhas do dataset.
inputsAny?Inputs associados à execução.
klingo_status_codeint?Status HTTP retornado pela Klingo.
klingo_msgstr?Mensagem retornada pela Klingo.
executado_emdatetimeMomento da execução (fuso America/Sao_Paulo).
data_hora_criacaodatetimeMomento da criação do registro (fuso America/Sao_Paulo).
colunasList[Coluna]Definição das colunas (ver abaixo). Default [].

KlingoRelatorioRead

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

CampoTipoNotas
linhasList[Linha]Linhas do dataset (ver abaixo). Default [].

KlingoRelatorioColunaRead

CampoTipoNotas
indiceintÍndice/posição da coluna.
nomestrNome interno da coluna.
titulostr?Rótulo exibido no cabeçalho.
tipostr?Tipo do dado da coluna.
formatostr?Formato de exibição.
alignstr?Alinhamento (left/right/etc.).
definicao_brutaAnyDefinição bruta da coluna.

KlingoRelatorioLinhaRead

CampoTipoNotas
indiceintÍndice da linha no dataset.
col0 … col9str?Até 10 colunas achatadas para consulta.
dados_linha_jsonAnyLinha completa em JSON (todos os campos).

Notas

  • Toda resposta segue o envelope { status, message, data } (erros de negócio vêm como { "message": ... } e a validação de entrada como 422 com { "detail": [...] }).
  • 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.