Enviar lançamentos variáveis

A comissão sai do CRM, o desconto de convênio do sistema da farmácia, o prêmio da planilha da diretoria. Todo mês essas verbas precisam entrar na folha antes do cálculo. Esta jornada envia cada uma como lançamento variável da competência: o lançamento passa pela aprovação e, aprovado, entra no próximo cálculo da folha.


Quando usar	Verbas variáveis da competência nascem em outro sistema e precisam chegar à folha da TAI
Porta	REST · Webhook (o retorno) · Agente (MCP)
Você vai precisar	Módulo `FOLHA_PAGAMENTO`; permissão `FOLHA_PROCESSAR` com nível de edição; leitura de colaboradores para casar as pessoas; usuário de integração com token JWT

Como funciona

seu sistema ──► POST /folha/lancamento/importar   (planilha .xlsx, uma linha por variável)
            ou  POST /folha/lancamento            (um lançamento por chamada, com ids da TAI)
                        │
                        ▼
        lançamento PENDENTE  ──► aprovação (tela, Tali ou POST …/aprovar)
        ou APROVADO, se a empresa aprova lançamentos automaticamente
                        │
                        ▼
        cálculo da folha da competência consome os APROVADOS
        (folha-automatica recalcula quando entram variáveis aprovadas)

Há dois caminhos. A planilha é o mais simples quando o outro sistema já exporta as variáveis do mês: a TAI casa as pessoas pelo CPF e as rubricas pelo código ou nome, e não lança em dobro. O lançamento a lançamento dá controle total e devolve o id de cada lançamento.

Pela planilha

Monte o .xlsx. Uma linha por variável, com as colunas CPF (ou Colaborador, pelo nome completo), Rubrica (o código, como 002, ou o nome, como Comissões) e pelo menos uma entre Quantidade, Percentual e Valor. Competência (AAAA-MM) e Observação são opcionais. O cabeçalho é reconhecido pelo nome e não precisa estar na primeira linha.

Confira antes de gravar. A prévia roda as mesmas validações e não grava nada:

curl -X POST "https://api.taitecnologia.com/folha/lancamento/importar/previa?competencia=2026-10" \
  -H "Authorization: Bearer $TAI_TOKEN" \
  -F "arquivo=@variaveis-outubro.xlsx"

{
  "totalLinhas": 48, "importadosComSucesso": 45, "ignorados": 2, "erros": 1,
  "resultados": [
    { "linha": 7, "nome": "Ana Ribeiro", "status": "…", "mensagem": "…" }
  ],
  "avisos": [], "colunasIgnoradas": [], "colunasAmbiguas": []
}

Cada linha de resultados diz o que entraria, o que seria ignorado (a mesma pessoa, rubrica e competência já lançadas, ou repetida na planilha) e o que tem erro, com a mensagem. Sem a coluna Competência, vale o parâmetro competencia (ou o mês corrente).

Importe. Mesma chamada, sem /previa:
Terminal window
```
curl -X POST "https://api.taitecnologia.com/folha/lancamento/importar?competencia=2026-10" \
  -H "Authorization: Bearer $TAI_TOKEN" \
  -F "arquivo=@variaveis-outubro.xlsx"
```
Cada linha válida vira um lançamento, como se fosse digitado na tela — na fila de aprovação ou já aprovado, conforme a empresa. Linhas com erro não abortam as demais. Reimportar a mesma planilha não duplica: o que já foi lançado na competência é ignorado.

Lançamento a lançamento

Mapeie as rubricas. Rubrica é a verba da folha — “Comissões”, “Prêmio”, “Desconto de convênio”. Liste uma vez e guarde a correspondência entre o seu código e o id da TAI:

curl https://api.taitecnologia.com/folha/rubrica \
  -H "Authorization: Bearer $TAI_TOKEN"

Cada rubrica traz codigo, nome, tipo (PROVENTO, DESCONTO, INFORMATIVA) e tipoCalculo, que diz qual número do lançamento conta:

`tipoCalculo` da rubrica	Envie no lançamento
`VALOR_FIXO`	`valor` (em reais)
`PERCENTUAL_SALARIO`, `PERCENTUAL_BASE`	`percentual`
`QUANTIDADE_X_VALOR`	`quantidade` (e `valor` unitário, se a rubrica não tiver valor padrão)
`HORAS`, `DIAS`	`quantidade`

Case as pessoas. O lançamento usa o colaboradorId da TAI. Busque pelo CPF ou pela matrícula (codigoFuncionario) e guarde a correspondência — o padrão está no guia de Pessoas.

Veja o que já foi lançado na competência, para não lançar duas vezes:

curl https://api.taitecnologia.com/folha/lancamento/competencia/2026-10 \
  -H "Authorization: Bearer $TAI_TOKEN"

Envie os lançamentos. Um por chamada:

curl -X POST https://api.taitecnologia.com/folha/lancamento \
  -H "Authorization: Bearer $TAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "colaboradorId": 812,
    "rubricaId": 57,
    "competencia": "2026-10",
    "valor": 1850.40,
    "observacao": "Comissão de vendas — pedido 4471",
    "loteImportacao": "crm-2026-10"
  }'

ou vários de uma vez, com uma lista no corpo:

POST /folha/lancamento/batch

[
  { "colaboradorId": 812, "rubricaId": 57, "competencia": "2026-10", "valor": 1850.40, "loteImportacao": "crm-2026-10" },
  { "colaboradorId": 815, "rubricaId": 57, "competencia": "2026-10", "valor": 920.00, "loteImportacao": "crm-2026-10" }
]

Guarde o id de cada lançamento ao lado do registro de origem. loteImportacao é um texto livre seu, devolvido em cada lançamento — use-o para achar, depois, tudo o que uma remessa enviou.

Confira o status. O lançamento nasce APROVADO quando a empresa aprova lançamentos automaticamente (autoAprovarLancamentos em GET /folha/config/empresa/{empresaId}) e PENDENTE quando não. Pendentes são aprovados ou rejeitados na tela ou pela API:
```
POST /folha/lancamento/9031/aprovar

POST /folha/lancamento/9032/rejeitar
{ "motivo": "Comissão duplicada" }
```

Corrigir e cancelar

Enquanto a folha da competência não consumiu o lançamento, ele pode ser corrigido com PATCH /folha/lancamento (o id e os campos que mudam) ou excluído com DELETE /folha/lancamento/{id}. Depois que uma folha calculada o consumiu (processamentoId preenchido), edição e exclusão respondem 400.

Automatize

folha-automatica (ligada por empresa em folhaAutomatica) recalcula de madrugada a folha mensal ainda aberta ou calculada quando entram variáveis aprovadas. A pessoa encontra a folha pronta para conferir de manhã.
Retorno da aprovação. Um webhook assinando Um lançamento da folha é aprovado (LANCAMENTO_FOLHA_APROVADO) e Um lançamento da folha é recusado (LANCAMENTO_FOLHA_REJEITADO) devolve ao seu sistema o destino de cada lançamento — case pelo lancamentoId que você guardou:
```
{
  "id": "evt_50112",
  "tipo": "LANCAMENTO_FOLHA_REJEITADO",
  "descricao": "Um lançamento da folha é recusado",
  "versao": 1,
  "ocorridoEm": "2026-10-28T13:41:07.004Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": { "lancamentoId": 9032, "colaboradorId": 815, "rubricaId": 57, "competencia": "2026-10" }
}
```
O valor da verba não vem em dados; com Enviar também o registro completo, o lançamento chega em registro como GET /folha/lancamento/{id} o devolve.
Cálculo feito. A folha é calculada (FOLHA_CALCULADA) traz processamentoId, competencia, tipo e holeritesComErro: o seu sistema sabe que as variáveis aprovadas já estão no cálculo.

Se o seu sistema dispara o envio, um bom gatilho é o fim do período de apuração dele (o fechamento de vendas do mês, por exemplo), antes do dia em que a folha automática começa a calcular.

Pelo seu agente de IA

“Lance uma comissão de R$ 1.850,40 para a Ana Ribeiro na folha de outubro.”

Com escopo de escrita, o agente acha a pessoa e a rubrica e cria o lançamento — o seu cliente de IA pede sua aprovação antes. Aprovar e rejeitar lançamentos são de confirmação forte e não saem pelo MCP (Escrita e segurança). Para perguntas como “o que foi lançado em outubro e o que falta aprovar?”, o agente só lê.

Cuidados

Só lançamento APROVADO entra na folha. Um pendente na hora do cálculo simplesmente não é considerado — sem erro nenhum. Confira o status depois de enviar.
Não envie status. Deixe a regra da empresa decidir entre PENDENTE e APROVADO.
Valores positivos. O sinal vem da rubrica: uma rubrica de DESCONTO desconta. Valor zero ou negativo é ignorado no cálculo.
O lote não é atômico. POST /folha/lancamento/batch grava um por um: se um item falha, os anteriores já foram gravados. Releia a competência (passo 3) antes de reenviar.
Só a planilha deduplica. A importação ignora o que já foi lançado; POST /folha/lancamento e /batch não — reenviar o mesmo lançamento cria outro. Nesse caminho, a chave de correspondência é sua: pessoa, rubrica e competência, mais o id que você guardou.
8 KB por corpo, exceto a planilha. Em /folha/lancamento e /batch, um corpo grande é recusado pelo firewall com 403 sem JSON; divida em lotes de 20 a 30 lançamentos. A importação por planilha é rota de upload e aceita arquivos maiores — veja Limites.
Envie antes da aprovação da folha. Aprovada a folha, ela não recalcula: um lançamento novo só entra se a folha for reaberta e calculada de novo.
Competência é AAAA-MM; valores em reais, com ponto decimal (Datas e formatos).

Referência gerada do contrato da API em 30 de outubro de 2026. taitecnologia.com · Termos de uso · Privacidade