Levar a contabilização da folha para o ERP

A folha aprovada vira partidas contábeis: salários, descontos, encargos, FGTS e provisões, cada um na sua conta e centro de custo. Esta jornada gera o lote contábil da folha, confere com o que a folha sustenta e entrega ao ERP contábil — como arquivo no leiaute dele ou como JSON para uma integração direta.

Quando usar	A contabilidade roda num ERP ou no sistema do escritório contábil e precisa receber a folha do mês
Porta	REST · Automação/webhook (o gatilho) · Agente (MCP, leitura)
Você vai precisar	Módulo FOLHA_PAGAMENTO; FOLHA para ler e exportar; FOLHA_PROCESSAR para gerar e cancelar lotes; FOLHA_CADASTRO para plano de contas, esquema e leiaute; usuário de integração com token JWT

Como funciona

uma vez:   plano de contas ─► esquema contábil (rubrica → conta) ─► leiaute do arquivo do ERP

todo mês:  folha APROVADA ─► prévia ─► lote contábil (GERADO) ─► conferência
                                              │
                         exportar no leiaute (EXPORTADO) ─► arquivo para o ERP
                         ou  GET …/lancamentos ─► JSON para a sua integração

O esquema decide para onde cada valor vai; o lote é o resultado do esquema sobre uma folha; o leiaute só formata o arquivo. Existe um lote vivo por processamento — dois lotes não cancelados duplicariam a folha no razão.

Preparar (uma vez)

Peça	Chamadas	Na plataforma
Plano de contas	POST /contabil/conta/plano-padrao cria o plano mínimo de folha; /contabil/conta para o resto; GET /contabil/conta/plano lê inteiro	Departamento Pessoal › Folha de Pagamento › Contabilidade da empresa › Mais › Plano de contas
Esquema contábil	POST /contabil/esquema/sugerir/{empresaId} monta um rascunho a partir do plano e das rubricas; POST /contabil/esquema/regra ajusta; POST /contabil/esquema/{id}/publicar publica	idem, Mais › Esquema contábil
Leiaute do arquivo	POST /contabil/layout/padrao cria um CSV genérico; /contabil/layout e POST /contabil/layout/campo montam o do seu ERP; GET /contabil/layout/campos-disponiveis lista os campos	idem, Mais › Leiautes de exportação

O leiaute é declarativo: formato delimitado ou posicional, agrupamento (ANALITICO, POR_CONTA, POR_CONTA_CENTRO_CUSTO), delimitador, encoding, separador decimal, cabeçalho — tudo configurável, sem desenvolvimento. Detalhes na referência de Contabilização.

Passo a passo (todo mês)

1. Veja a prévia do que sairia da folha:

   curl https://api.taitecnologia.com/contabil/lote/previa/118 \
     -H "Authorization: Bearer $TAI_TOKEN"

   podeGerar diz se está tudo mapeado. Se não, impedimentos e pendencias mostram, item a item, o que falta mapear no esquema e o valor que ficaria fora do razão. loteExistenteId aparece se a folha já tem lote vivo.

2. Gere o lote. A folha precisa estar aprovada (ou além):

   POST /contabil/lote/gerar/118

   Ou gere tudo o que a competência ainda deve ao razão — um lote por folha aprovada sem lote e o lote do financeiro — num gesto só:

   POST /contabil/lote/preparar-mes?empresaId=3&competencia=2026-10

   A resposta diz, alvo a alvo, o que foi gerado, o que já existia e o que não gerou, com o motivo.

3. Confira.

   GET /contabil/lote/{id}/conferencia

   balanceado (débito = crédito) é verdade por construção; o que prova algo é confere e as linhas que confrontam a folha com o contábil — a mais reveladora é o saldo da conta de contrapartida contra o líquido da folha.

4. Entregue ao ERP.

   Arquivo no leiaute

   curl "https://api.taitecnologia.com/contabil/lote/731/exportar?layoutId=4" \
     -H "Authorization: Bearer $TAI_TOKEN" -o folha-2026-10.csv

   Baixar marca o lote como EXPORTADO. Passe marcar=false para só espiar o arquivo sem mudar o status. Os leiautes da conta estão em GET /contabil/layout/listar.

   JSON, linha a linha

   GET /contabil/lote/731/lancamentos

   Cada lançamento traz dataLancamento, contaDebitoCodigo, contaCreditoCodigo, valor, historico, centroCustoCodigo, a origem (RUBRICA, ENCARGO, PROVISAO…) e, quando se aplica, rubricaCodigo e colaboradorMatricula. Essa leitura não muda o status do lote.

Automatize

• Contabilização automática. Com contabilizarAutomatico ligado na configuração da folha da empresa (PUT /folha/config/empresa/{empresaId}), a TAI prepara de madrugada a contabilidade do mês anterior — o mesmo preparar-mes do passo 2. Ela gera, nunca exporta: os lotes ficam GERADO esperando o seu sistema.

• Busca pelo seu sistema. Uma rotina sua lista os lotes da competência (GET /contabil/lote?empresaId=3&competencia=2026-10) e exporta os que estão GERADO.

• Aviso na hora. Para contabilizar assim que a folha é aprovada, crie um webhook assinando A folha é aprovada (FOLHA_APROVADA). Chega:

  {
    "id": "evt_51877",
    "tipo": "FOLHA_APROVADA",
    "descricao": "A folha é aprovada",
    "versao": 1,
    "ocorridoEm": "2026-11-03T18:22:10.512Z",
    "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
    "dados": { "processamentoId": 118, "empresaId": 3, "competencia": "2026-10", "tipo": "MENSAL" }
  }

  Com o processamentoId recebido, o seu sistema faz os passos 1 a 4. Assine também Uma folha é reaberta (FOLHA_PROCESSAMENTO_REABERTO): a folha reaberta será recalculada, e o lote gerado antes precisa ser cancelado (veja Cuidados).

Pelo seu agente de IA

“A folha de outubro já pode ser contabilizada? O que falta mapear?”

O agente lê a prévia e a conferência e explica as pendências — só leitura. Cancelar um lote é de confirmação forte e não sai pelo MCP (Escrita e segurança).

Cuidados

• Folha recalculada depois do lote? Cancele o lote antigo (POST /contabil/lote/{id}/cancelar) e gere de novo. O cancelamento tira os lançamentos de toda soma, mas não desfaz um arquivo já importado no ERP — estorne lá também.
• Idempotência pelo status. Exporte só lotes GERADO e guarde o id do lote importado. Um lote EXPORTADO já saiu uma vez.
• Linhas informativas sem regra são ignoradas de propósito (não movimentam dinheiro); a prévia as conta em qtdInformativasIgnoradas e valorInformativasIgnoradas.
• Leiaute agrupado não aceita campos de colaborador nem de rubrica — uma linha agrupada representa vários lançamentos. A exportação recusa a combinação.
• Encoding. Leiautes nascem em ISO-8859-1, o padrão dos ERPs contábeis brasileiros; ajuste se o seu ERP espera UTF-8.