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-layout

Escopos necessários

  • klingo_layout:read - listagem e detalhe do layout (rotas GET).
  • 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:

  1. Sincronizar o relatório do período com POST /klingo/relatorio/sync/ (ver Klingo: Relatórios). O id do registro devolvido é a execução (id_klingo_relatorio) usada nos passos 3 e 4.
  2. Descobrir as colunas com POST /klingo-layout/descobrir/. A resposta traz a lista de colunas e o hash_colunas do conjunto. Nada é gravado.
  3. Salvar o layout com POST /klingo-layout/, enviando todas as colunas descobertas (as não usadas com papel: "ignorar") e o hash_colunas recebido no passo 2. Faça isso uma vez por relatório; nas importações seguintes reaproveite o layout.
  4. Prever com POST /klingo-layout/preview/ e, depois de conferir total, soma e amostra, confirmar com POST /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_lancamento está marcado em coluna cujo papel nã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 papel data, ou origem_data diferente de coluna com coluna de papel data mapeada;
  • 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âmetroTipoDefaultObservações
id_clienteint (≥ 1)-Filtra por cliente.
apenas_ativosboolfalseQuando true, omite layouts inativos.
skipint (≥ 0)0Itens a pular.
limitint (1-200)50Itens por página.

Request

GET /api/v1/klingo-layout/?id_cliente=123&apenas_ativos=true&skip=0&limit=50

Response 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_candidatos e soma_candidatos (string decimal) cobrem todos os lançamentos que a confirmação gravaria, já descontados os descartados por regra de ignorar. Só a lista candidatos é cortada em amostra_limite itens; amostra_truncada indica quando houve corte.
  • qtd_com_regra (nasceriam com contas definidas) e qtd_regra_pendente (sem classificação completa) somam total_candidatos. qtd_conflito conta os que ficariam pendentes por disputa entre regras; qtd_fallback, os classificados por regras gerais por não haver regra específica do layout.
  • conflitos lista, separadamente da amostra, os candidatos com disputa entre regras (cortada em amostra_limite; conflitos_truncado indica corte). É o que precisa ser resolvido antes de confirmar.
  • ignorados lista os descartados por regra de ignorar (indice_linha, nome_coluna, regra_id, regra_nome), cortada em amostra_limite; qtd_ignorados é o total.
  • ignorados_sem_valor conta os pares linha x coluna descartados por serem zero ou nulos. Não é erro.
  • erros lista 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âmetroLocalTipoObrigatórioObservações
layout_idrotaintsimID 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âmetroLocalTipoObrigatórioObservações
layout_idrotaintsimID 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âmetroLocalTipoObrigatórioObservações
layout_idrotaintsimID 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/.

CampoTipoObrigatórioObservações
id_clienteint (≥ 1)simCliente cuja credencial Klingo é usada.
id_relatorio_klingoint (≥ 1)simID do relatório na Klingo.
periodostr (≤ 20)nãoDefault l (intervalo livre). Aceita letras, números, _ e -. Outros valores são presets (ex.: u3).
data_iniciodate | nullcondicionalObrigatório com periodo = "l"; proibido com preset.
data_fimdate | nullcondicionalObrigatório com periodo = "l"; proibido com preset; não pode ser anterior a data_inicio.

KlingoLayoutCreate

Corpo de POST /klingo-layout/.

CampoTipoObrigatórioObservações
id_clienteint (≥ 1)simCliente dono do layout.
id_relatorio_klingoint (≥ 1)simRelatório Klingo mapeado.
nomestr (1-150)simEspaços nas pontas são removidos.
origem_data"coluna" | "data_importacao" | "informada"nãoDefault coluna. Ver Origem da data.
hash_colunasstr (≤ 64) | nullnãoValor devolvido por descobrir. Sem ele, a comparação por hash não roda.
colunasList[KlingoLayoutColunaCreate]simMínimo 1. Envie todas as colunas descobertas.

KlingoLayoutColunaCreate

Item de colunas na criação e na atualização.

CampoTipoObrigatórioObservações
nome_colunastr (≤ 50)simIdentificador estável da coluna na Klingo (ex.: col2). É a chave do casamento.
titulo_esperadostr | nullnãoTítulo da coluna quando o layout foi salvo (≤ 255). Usado no diagnóstico de drift.
tipo_esperadostr | nullnãoTipo da coluna (≤ 50). Usado no diagnóstico de drift.
formato_esperadostr | nullnãoFormato da coluna (≤ 50). Usado no diagnóstico de drift.
papelstr (enum)simVer Papéis de coluna.
gera_lancamentoboolnãoDefault false. Só vale com papel = "valor".
campo_regraboolnãoDefault false. Expõe o valor da coluna às regras de lançamento, com qualquer papel (inclusive ignorar).
rotulostr | nullnãoRótulo livre (≤ 100).
ordemintnãoDefault 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.

CampoTipoObservações
nomestr (1-150)Novo nome.
origem_data"coluna" | "data_importacao" | "informada"Nova origem da data.
hash_colunasstr (≤ 64)Novo hash do conjunto de colunas.
ativoboolAtiva ou inativa o layout. Layout inativo não é usado na importação.
colunasList[KlingoLayoutColunaCreate]Mínimo 1. Substitui todas as colunas.

KlingoLayoutRead

Layout nas respostas de criação, listagem, detalhe e atualização.

CampoTipoObservações
idintID do layout.
id_usuario_createdintUsuário que criou o layout.
id_clienteintCliente dono.
id_relatorio_klingointRelatório Klingo mapeado.
nomestrNome do layout.
origem_datastrcoluna, data_importacao ou informada.
hash_colunasstr | nullHash do conjunto de colunas no momento do salvamento.
ativoboolSe o layout está ativo.
colunasList[KlingoLayoutColunaRead]Colunas mapeadas: os campos de KlingoLayoutColunaCreate mais id e id_layout.
avisosList[str]Preenchido apenas em criação e atualização.

KlingoPreviewInput

Corpo de POST /klingo-layout/preview/ e POST /klingo-layout/confirmar/.

CampoTipoObrigatórioObservações
id_klingo_relatorioint (≥ 1)simID da execução sincronizada.
id_layoutint | nullnãoLayout 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_informadadate | nullcondicionalObrigatória quando o layout tem origem_data = "informada". Ignorada nos demais casos.
id_bancoint (≥ 1) | nullnãoBanco 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:

papelDestinoQuantidade por layout
dataData do lançamento (origem_data = "coluna").no máximo 1
valorValor. Gera lançamento apenas se gera_lancamento = true.várias
numero_documentoNúmero do documento.no máximo 1
historicoHistórico contábil. Várias colunas são concatenadas na ordem de ordem.várias
campo_auxiliar_1Campo auxiliar 1.no máximo 1
campo_auxiliar_2Campo auxiliar 2.no máximo 1
campo_auxiliar_3Campo auxiliar 3.no máximo 1
ignorarNão vai para o lançamento (a coluna pode ainda ser campo_regra).várias

Origem da data

origem_dataData do lançamento
colunaVem da coluna com papel data.
data_importacaoO relatório não traz data; usa o dia da importação (fuso de São Paulo).
informadaO 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ó confirmar cria 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.