Layout Klingo
Endpoints da WebApiAlcance para o layout de um relatório Klingo: o de-para entre as colunas do relatório e os campos do lançamento contábil. Cobrem o CRUD do layout e o fluxo de importação que o usa: descobrir as colunas, prever os lançamentos e confirmar a criação.
Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.
Base path
/api/v1/klingo-layoutEscopos necessários
klingo_layout:read- listagem e detalhe do layout (rotasGET).klingo_layout:write- criação, atualização, exclusão, descoberta, preview e confirmação (POST,PUT,DELETE).
O escopo é derivado do prefixo público da rota: /klingo-layout vira o recurso klingo_layout (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/PATCH/DELETE). Por isso descobrir e preview, mesmo sem gravar nada, exigem klingo_layout:write. Este escopo é distinto de klingo:*, usado pelos relatórios Klingo.
Envelope de resposta
Toda resposta segue o envelope padrão da WebApi:
{
"status": "success",
"message": "Mensagem em PT-BR",
"data": {}
}Erros de negócio retornam { "message": ... } com o status HTTP correspondente. Falhas de validação retornam 422 com { "detail": [...] }.
Fluxo de importação
A importação de um relatório Klingo para lançamentos contábeis segue quatro passos:
- Sincronizar o relatório do período com
POST /klingo/relatorio/sync/(ver Klingo: Relatórios). Oiddo registro devolvido é a execução (id_klingo_relatorio) usada nos passos 3 e 4. - Descobrir as colunas com
POST /klingo-layout/descobrir/. A resposta traz a lista de colunas e ohash_colunasdo conjunto. Nada é gravado. - Salvar o layout com
POST /klingo-layout/, enviando todas as colunas descobertas (as não usadas compapel: "ignorar") e ohash_colunasrecebido no passo 2. Faça isso uma vez por relatório; nas importações seguintes reaproveite o layout. - Prever com
POST /klingo-layout/preview/e, depois de conferir total, soma e amostra, confirmar comPOST /klingo-layout/confirmar/. Os dois recebem o mesmo corpo e aplicam a mesma derivação, então o que o preview mostra é o que a confirmação grava.
Endpoints
POST /klingo-layout/descobrir/
Lê a definição das colunas de um relatório Klingo para montar o de-para. Não grava nada.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo (ver KlingoDescobrirColunasInput).
Request
{
"id_cliente": 123,
"id_relatorio_klingo": 5612,
"periodo": "l",
"data_inicio": "2026-07-01",
"data_fim": "2026-07-31"
}Response 200 OK
{
"status": "success",
"message": "Colunas do relatorio Klingo obtidas com sucesso",
"data": {
"id_relatorio_klingo": 5612,
"titulo": "Recebimentos por convênio",
"colunas": [
{ "name": "col0", "title": "Data", "type": "timestamp" },
{ "name": "col1", "title": "Convênio", "type": "string" },
{ "name": "col2", "title": "Valor", "type": "value", "format": 2 }
],
"total_linhas": 63,
"hash_colunas": "b1946ac92492d2347c6235b4d2611184..."
}
}total_linhas = 0 indica que o período não teve movimento: as colunas vêm, mas sem dados para conferir. Prefira o período mais curto que ainda traga linhas.
Erros: 409 cliente sem credencial Klingo utilizável; 413 resposta acima do limite; 422 período inválido ou regra de negócio da Klingo; 502 token rejeitado ou falha de comunicação com a Klingo.
Escopo: klingo_layout:write
POST /klingo-layout/
Cria um layout. Um mesmo relatório pode ter mais de um layout por cliente.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo (ver KlingoLayoutCreate).
Request
{
"id_cliente": 123,
"id_relatorio_klingo": 5612,
"nome": "Recebimentos por convênio",
"origem_data": "coluna",
"hash_colunas": "b1946ac92492d2347c6235b4d2611184...",
"colunas": [
{ "nome_coluna": "col0", "titulo_esperado": "Data", "tipo_esperado": "timestamp", "papel": "data", "ordem": 0 },
{ "nome_coluna": "col1", "titulo_esperado": "Convênio", "tipo_esperado": "string", "papel": "historico", "campo_regra": true, "ordem": 1 },
{ "nome_coluna": "col2", "titulo_esperado": "Valor", "tipo_esperado": "value", "formato_esperado": "2", "papel": "valor", "gera_lancamento": true, "ordem": 2 }
]
}Response 200 OK
{
"status": "success",
"message": "Layout Klingo criado com sucesso",
"data": {
"id": 8,
"id_usuario_created": 7,
"id_cliente": 123,
"id_relatorio_klingo": 5612,
"nome": "Recebimentos por convênio",
"origem_data": "coluna",
"hash_colunas": "b1946ac92492d2347c6235b4d2611184...",
"ativo": true,
"colunas": [
{
"id": 21,
"id_layout": 8,
"nome_coluna": "col2",
"titulo_esperado": "Valor",
"tipo_esperado": "value",
"formato_esperado": "2",
"papel": "valor",
"gera_lancamento": true,
"campo_regra": false,
"rotulo": null,
"ordem": 2
}
],
"avisos": []
}
}avisos lista, em frases, as colunas geradoras de lançamento que outro layout ativo do mesmo cliente e relatório também gera. É um aviso, não um bloqueio.
Regras de coerência do layout
O corpo é recusado com 422 quando:
- há nomes de coluna repetidos;
gera_lancamentoestá marcado em coluna cujopapelnão évalor;- um papel exclusivo (
data,numero_documento,campo_auxiliar_1,campo_auxiliar_2,campo_auxiliar_3) é atribuído a mais de uma coluna; origem_data = "coluna"sem coluna de papeldata, ouorigem_datadiferente decolunacom coluna de papeldatamapeada;- nenhuma coluna tem
gera_lancamento; - mais de 10 colunas têm
campo_regra.
Escopo: klingo_layout:write
GET /klingo-layout/
Lista os layouts, com filtros e paginação por skip e limit.
Parâmetros de query
| Parâmetro | Tipo | Default | Observações |
|---|---|---|---|
id_cliente | int (≥ 1) | - | Filtra por cliente. |
apenas_ativos | bool | false | Quando true, omite layouts inativos. |
skip | int (≥ 0) | 0 | Itens a pular. |
limit | int (1-200) | 50 | Itens por página. |
Request
GET /api/v1/klingo-layout/?id_cliente=123&apenas_ativos=true&skip=0&limit=50Response 200 OK
{
"status": "success",
"message": "Layouts Klingo listados com sucesso",
"data": {
"total": 1,
"items": [
{
"id": 8,
"id_usuario_created": 7,
"id_cliente": 123,
"id_relatorio_klingo": 5612,
"nome": "Recebimentos por convênio",
"origem_data": "coluna",
"hash_colunas": "b1946ac92492d2347c6235b4d2611184...",
"ativo": true,
"colunas": [],
"avisos": []
}
]
}
}Cada item segue KlingoLayoutRead; avisos vem sempre vazio na listagem.
Escopo: klingo_layout:read
POST /klingo-layout/preview/
Aplica um layout sobre uma execução já sincronizada e devolve os lançamentos que seriam criados, sem criar nenhum. Pode ser repetido quantas vezes for necessário, sem nova chamada à Klingo.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo (ver KlingoPreviewInput).
Request
{
"id_klingo_relatorio": 340,
"id_layout": 8,
"id_banco": 3,
"data_informada": null
}Response 200 OK
{
"status": "success",
"message": "Preview gerado com sucesso",
"data": {
"id_klingo_relatorio": 340,
"id_layout": 8,
"id_cliente": 123,
"id_banco": 3,
"origem_data": "coluna",
"drift": {
"hash_salvo": "b1946ac9...",
"hash_atual": "b1946ac9...",
"mudou": false,
"bloqueia": false,
"ausentes": [],
"tipo_alterado": [],
"titulo_alterado": [],
"novas": []
},
"total_candidatos": 63,
"soma_candidatos": "12450.00",
"qtd_com_regra": 60,
"qtd_regra_pendente": 3,
"qtd_conflito": 0,
"qtd_fallback": 4,
"conflitos": [],
"conflitos_truncado": false,
"qtd_ignorados": 0,
"ignorados": [],
"ignorados_sem_valor": 12,
"erros": [],
"amostra_limite": 500,
"amostra_truncada": false,
"candidatos": [
{
"indice_linha": 0,
"nome_coluna": "col2",
"rotulo": null,
"data_registro": "2026-07-03",
"valor": "150.00",
"historico_contabil": "Operadora Exemplo",
"numero_documento": null,
"campo_auxiliar_1": null,
"campo_auxiliar_2": null,
"campo_auxiliar_3": null,
"colunas_regra": { "col1": "Operadora Exemplo" },
"regras_aplicadas": ["Recebimento convênio"],
"classificado": true,
"conflitos": [],
"usou_fallback": false
}
]
}
}Como ler o resultado:
total_candidatosesoma_candidatos(string decimal) cobrem todos os lançamentos que a confirmação gravaria, já descontados os descartados por regra de ignorar. Só a listacandidatosé cortada emamostra_limiteitens;amostra_truncadaindica quando houve corte.qtd_com_regra(nasceriam com contas definidas) eqtd_regra_pendente(sem classificação completa) somamtotal_candidatos.qtd_conflitoconta os que ficariam pendentes por disputa entre regras;qtd_fallback, os classificados por regras gerais por não haver regra específica do layout.conflitoslista, separadamente da amostra, os candidatos com disputa entre regras (cortada emamostra_limite;conflitos_truncadoindica corte). É o que precisa ser resolvido antes de confirmar.ignoradoslista os descartados por regra de ignorar (indice_linha,nome_coluna,regra_id,regra_nome), cortada emamostra_limite;qtd_ignoradosé o total.ignorados_sem_valorconta os pares linha x coluna descartados por serem zero ou nulos. Não é erro.erroslista linhas que não puderam ser lidas (linha,coluna,motivo).
Drift das colunas
drift compara o layout salvo com as colunas atuais da execução. Quando bloqueia = true (coluna mapeada ausente ou com tipo alterado), candidatos vem vazio e erros traz o motivo; revise o layout antes de importar. Renomeações de título (titulo_alterado) e colunas novas são apenas avisos. mudou é null quando o layout não tem hash_colunas salvo.
Erros: 404 execução, layout (inexistente ou de outro cliente) ou id_banco não encontrados; 409 execução sem cliente identificado (sincronize novamente), layout inativo ou nenhum layout mapeado para o relatório; 422 layout de outro relatório, dois ou mais layouts ativos sem id_layout, ou data_informada ausente quando o layout usa origem_data = "informada".
Escopo: klingo_layout:write
POST /klingo-layout/confirmar/
Deriva e grava a importação (tipo = "klingo") e os lançamentos contábeis, com a mesma derivação e classificação do preview. A gravação é única: se falhar, nada fica gravado.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo (mesmo KlingoPreviewInput do preview).
Request
{
"id_klingo_relatorio": 340,
"id_layout": 8,
"id_banco": 3,
"data_informada": null
}Response 200 OK
{
"status": "success",
"message": "Lancamentos criados a partir do relatorio Klingo",
"data": {
"id_importacao": 912,
"status": "success",
"qtd_lancamentos_criados": 63,
"qtd_com_regra": 60,
"qtd_regra_pendente": 3,
"qtd_conflito": 0,
"qtd_fallback": 4,
"qtd_ignorados": 0,
"ignorados_sem_valor": 12,
"qtd_linhas_erro": 0,
"erros": [],
"qtd_lucros_gerados": 0,
"lucros_por_conta": null
}
}status da importação: success (tudo gravado), partial (gravou, mas houve linhas com erro) ou error (nada gravado). qtd_lucros_gerados e lucros_por_conta seguem o mesmo significado do ConfirmarResponse das importações; lucros_por_conta é null quando não há resumo a informar.
Uma importação por execução
Cada execução (id_klingo_relatorio) só pode virar lançamentos uma vez. Uma nova confirmação retorna 409 com o corpo { "message": { "message": "...", "importacao_existente": { "importacao_id_existente", "status_existente", "data_hora_criacao" } } }. Para refazer, exclua a importação anterior e confirme de novo. Para importar com outro layout, sincronize uma nova execução.
Erros: os mesmos do preview, mais 409 quando o drift bloqueia a importação (as colunas mudaram na Klingo desde que o layout foi salvo) e 422 quando não há nenhum lançamento a criar (todas as linhas sem valor, ignoradas por regra ou com erro).
Escopo: klingo_layout:write
GET /klingo-layout/{layout_id}
Detalha um layout, com suas colunas.
Parâmetros
| Parâmetro | Local | Tipo | Obrigatório | Observações |
|---|---|---|---|---|
layout_id | rota | int | sim | ID do layout. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Layout Klingo obtido com sucesso",
"data": {
"id": 8,
"id_usuario_created": 7,
"id_cliente": 123,
"id_relatorio_klingo": 5612,
"nome": "Recebimentos por convênio",
"origem_data": "coluna",
"hash_colunas": "b1946ac92492d2347c6235b4d2611184...",
"ativo": true,
"colunas": [],
"avisos": []
}
}O data segue KlingoLayoutRead. ID inexistente retorna 404 Not Found.
Escopo: klingo_layout:read
PUT /klingo-layout/{layout_id}
Atualiza um layout. Todos os campos são opcionais.
Parâmetros
| Parâmetro | Local | Tipo | Obrigatório | Observações |
|---|---|---|---|---|
layout_id | rota | int | sim | ID do layout. |
Request
{
"nome": "Recebimentos por convênio (v2)",
"ativo": true
}Quando colunas é enviado, ele substitui o conjunto inteiro de colunas - não há atualização parcial de colunas. A coerência (mesmas regras da criação) é verificada sobre o estado resultante: por exemplo, enviar só origem_data: "data_importacao" a um layout que tem coluna de papel data é recusado com 422.
Response 200 OK
{
"status": "success",
"message": "Layout Klingo atualizado com sucesso",
"data": {
"id": 8,
"id_usuario_created": 7,
"id_cliente": 123,
"id_relatorio_klingo": 5612,
"nome": "Recebimentos por convênio (v2)",
"origem_data": "coluna",
"hash_colunas": "b1946ac92492d2347c6235b4d2611184...",
"ativo": true,
"colunas": [],
"avisos": []
}
}O data segue KlingoLayoutRead, com avisos preenchido como na criação. ID inexistente retorna 404. Retorna 409 quando a edição deixaria uma regra de lançamento vinculada ao layout apontando para uma coluna que deixou de ser campo_regra; remova ou altere a condição da regra antes.
Escopo: klingo_layout:write
DELETE /klingo-layout/{layout_id}
Exclui um layout.
Parâmetros
| Parâmetro | Local | Tipo | Obrigatório | Observações |
|---|---|---|---|---|
layout_id | rota | int | sim | ID do layout. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Layout Klingo excluido com sucesso",
"data": { "id": 8 }
}ID inexistente retorna 404. Retorna 409 enquanto houver regra de lançamento vinculada ao layout; remova ou desvincule as regras antes de excluir.
Escopo: klingo_layout:write
Schemas
KlingoDescobrirColunasInput
Corpo de POST /klingo-layout/descobrir/.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_cliente | int (≥ 1) | sim | Cliente cuja credencial Klingo é usada. |
id_relatorio_klingo | int (≥ 1) | sim | ID do relatório na Klingo. |
periodo | str (≤ 20) | não | Default l (intervalo livre). Aceita letras, números, _ e -. Outros valores são presets (ex.: u3). |
data_inicio | date | null | condicional | Obrigatório com periodo = "l"; proibido com preset. |
data_fim | date | null | condicional | Obrigatório com periodo = "l"; proibido com preset; não pode ser anterior a data_inicio. |
KlingoLayoutCreate
Corpo de POST /klingo-layout/.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_cliente | int (≥ 1) | sim | Cliente dono do layout. |
id_relatorio_klingo | int (≥ 1) | sim | Relatório Klingo mapeado. |
nome | str (1-150) | sim | Espaços nas pontas são removidos. |
origem_data | "coluna" | "data_importacao" | "informada" | não | Default coluna. Ver Origem da data. |
hash_colunas | str (≤ 64) | null | não | Valor devolvido por descobrir. Sem ele, a comparação por hash não roda. |
colunas | List[KlingoLayoutColunaCreate] | sim | Mínimo 1. Envie todas as colunas descobertas. |
KlingoLayoutColunaCreate
Item de colunas na criação e na atualização.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
nome_coluna | str (≤ 50) | sim | Identificador estável da coluna na Klingo (ex.: col2). É a chave do casamento. |
titulo_esperado | str | null | não | Título da coluna quando o layout foi salvo (≤ 255). Usado no diagnóstico de drift. |
tipo_esperado | str | null | não | Tipo da coluna (≤ 50). Usado no diagnóstico de drift. |
formato_esperado | str | null | não | Formato da coluna (≤ 50). Usado no diagnóstico de drift. |
papel | str (enum) | sim | Ver Papéis de coluna. |
gera_lancamento | bool | não | Default false. Só vale com papel = "valor". |
campo_regra | bool | não | Default false. Expõe o valor da coluna às regras de lançamento, com qualquer papel (inclusive ignorar). |
rotulo | str | null | não | Rótulo livre (≤ 100). |
ordem | int | não | Default 0. Define a ordem de concatenação das colunas de historico. |
KlingoLayoutUpdate
Corpo de PUT /klingo-layout/{layout_id}. Todos os campos são opcionais.
| Campo | Tipo | Observações |
|---|---|---|
nome | str (1-150) | Novo nome. |
origem_data | "coluna" | "data_importacao" | "informada" | Nova origem da data. |
hash_colunas | str (≤ 64) | Novo hash do conjunto de colunas. |
ativo | bool | Ativa ou inativa o layout. Layout inativo não é usado na importação. |
colunas | List[KlingoLayoutColunaCreate] | Mínimo 1. Substitui todas as colunas. |
KlingoLayoutRead
Layout nas respostas de criação, listagem, detalhe e atualização.
| Campo | Tipo | Observações |
|---|---|---|
id | int | ID do layout. |
id_usuario_created | int | Usuário que criou o layout. |
id_cliente | int | Cliente dono. |
id_relatorio_klingo | int | Relatório Klingo mapeado. |
nome | str | Nome do layout. |
origem_data | str | coluna, data_importacao ou informada. |
hash_colunas | str | null | Hash do conjunto de colunas no momento do salvamento. |
ativo | bool | Se o layout está ativo. |
colunas | List[KlingoLayoutColunaRead] | Colunas mapeadas: os campos de KlingoLayoutColunaCreate mais id e id_layout. |
avisos | List[str] | Preenchido apenas em criação e atualização. |
KlingoPreviewInput
Corpo de POST /klingo-layout/preview/ e POST /klingo-layout/confirmar/.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_klingo_relatorio | int (≥ 1) | sim | ID da execução sincronizada. |
id_layout | int | null | não | Layout a aplicar. Deve ser ativo, do mesmo cliente e do mesmo relatório da execução. Sem ele, usa o único layout ativo do relatório; com 2 ou mais, responde 422. |
data_informada | date | null | condicional | Obrigatória quando o layout tem origem_data = "informada". Ignorada nos demais casos. |
id_banco | int (≥ 1) | null | não | Banco cujos padrões de regras ativos do cliente são aplicados antes das regras do cliente. Deve existir (404). |
Papéis de coluna
Valores de papel e seu destino no lançamento:
papel | Destino | Quantidade por layout |
|---|---|---|
data | Data do lançamento (origem_data = "coluna"). | no máximo 1 |
valor | Valor. Gera lançamento apenas se gera_lancamento = true. | várias |
numero_documento | Número do documento. | no máximo 1 |
historico | Histórico contábil. Várias colunas são concatenadas na ordem de ordem. | várias |
campo_auxiliar_1 | Campo auxiliar 1. | no máximo 1 |
campo_auxiliar_2 | Campo auxiliar 2. | no máximo 1 |
campo_auxiliar_3 | Campo auxiliar 3. | no máximo 1 |
ignorar | Não vai para o lançamento (a coluna pode ainda ser campo_regra). | várias |
Origem da data
origem_data | Data do lançamento |
|---|---|
coluna | Vem da coluna com papel data. |
data_importacao | O relatório não traz data; usa o dia da importação (fuso de São Paulo). |
informada | O relatório não traz data; o consumidor envia data_informada no preview e na confirmação. |
Notas
- O preview não grava nada e pode ser repetido; só
confirmarcria a importação e os lançamentos. - Colunas monetárias derivadas de outras (por exemplo, bruto = líquido + taxas) não devem ser todas marcadas com
gera_lancamento, ou o mesmo valor é lançado duas vezes. - A comparação de drift usa o identificador estável da coluna (
nome_coluna), não o título. - Sem
id_layout, preview e confirmação nunca escolhem um layout por conta própria quando há mais de um ativo.