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/relatorioEscopos necessários
klingo:read- listagem paginada e leitura individual de relatórios persistidosklingo: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):
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_cliente | int | sim | Cliente cuja credencial Klingo busca o dado. Mínimo 1. |
id | int | sim | ID do relatório na Klingo. Mínimo 1. |
periodo | str | não | Modo do período. Default l (intervalo livre). Máx. 20 caracteres, só letras, números, _ e -. |
data_inicio | date | condicional | YYYY-MM-DD. Obrigatório com periodo = "l"; proibido com preset. |
data_fim | date | condicional | YYYY-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â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. |
id_relatorio_klingo | int >= 1 | query | não | Filtra pelo ID do relatório na Klingo. |
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
{
"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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
relatorio_id | int | path | sim | ID 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.
| Campo | Tipo | Notas |
|---|---|---|
id | int | ID interno do registro persistido. |
id_usuario_created | int | Usuário que executou a sincronização (autoria). |
id_cliente | int? | Cliente cuja credencial Klingo buscou o dado. |
id_relatorio_klingo | int | ID do relatório na Klingo. |
titulo | str? | Título do relatório. |
params_enviados | Any? | Request enviado à Klingo (enviado) e período que a Klingo diz ter aplicado (periodo_aplicado, null se não ecoou). |
total_linhas | int? | Quantidade de linhas do dataset. |
inputs | Any? | Inputs associados à execução. |
klingo_status_code | int? | Status HTTP retornado pela Klingo. |
klingo_msg | str? | Mensagem retornada pela Klingo. |
executado_em | datetime | Momento da execução (fuso America/Sao_Paulo). |
data_hora_criacao | datetime | Momento da criação do registro (fuso America/Sao_Paulo). |
colunas | List[Coluna] | Definição das colunas (ver abaixo). Default []. |
KlingoRelatorioRead
Projeção completa, usada em POST /sync/ e GET /{relatorio_id}. Estende KlingoRelatorioReadSemDados acrescentando:
| Campo | Tipo | Notas |
|---|---|---|
linhas | List[Linha] | Linhas do dataset (ver abaixo). Default []. |
KlingoRelatorioColunaRead
| Campo | Tipo | Notas |
|---|---|---|
indice | int | Índice/posição da coluna. |
nome | str | Nome interno da coluna. |
titulo | str? | Rótulo exibido no cabeçalho. |
tipo | str? | Tipo do dado da coluna. |
formato | str? | Formato de exibição. |
align | str? | Alinhamento (left/right/etc.). |
definicao_bruta | Any | Definição bruta da coluna. |
KlingoRelatorioLinhaRead
| Campo | Tipo | Notas |
|---|---|---|
indice | int | Índice da linha no dataset. |
col0 … col9 | str? | Até 10 colunas achatadas para consulta. |
dados_linha_json | Any | Linha 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 como422com{ "detail": [...] }). - Ordem de rotas (FastAPI). As rotas estáticas
POST /sync/eGET /são declaradas antes da rota dinâmicaGET /{relatorio_id}, para que o FastAPI não interpretesynccomo umrelatorio_id. - Os campos
executado_emedata_hora_criacaosão localizados no fusoAmerica/Sao_Paulona serialização. GET /{relatorio_id}usa o ID interno do registro persistido - diferente doid_relatorio_klingo(o ID do relatório na plataforma Klingo).- O escopo
klingoé compartilhado com Klingo: Despesas e Klingo: Consumos.