Registrar pagamentos e conciliar o extrato

Há dois caminhos para a TAI saber que uma conta foi paga ou recebida: o seu sistema registra a baixa parcela a parcela (quando ele é a fonte do pagamento — um gateway, um PDV, o ERP), ou o extrato do banco é importado e cada lançamento casa com a parcela certa. Os dois criam a mesma baixa, com a mesma trilha.

Quando usar	O pagamento acontece fora da TAI e precisa aparecer como baixa; ou o extrato do banco é a prova de que o dinheiro entrou e saiu
Porta	REST · Webhook (os avisos) · Agente (MCP, só consulta)
Você vai precisar	Módulo FINANCEIRO; permissão FINANCEIRO_PAGAR para baixar, conciliar e estornar; FINANCEIRO para importar e consultar; token JWT

Como funciona

Baixa direta
  seu sistema ── POST /financeiro/titulo/parcela/{parcelaId}/pagar ──▶ TAI
  TAI recompõe o status (PARCIAL / LIQUIDADO) ── evento PARCELA_BAIXADA

Conciliação
  arquivo OFX/PDF ── POST /financeiro/extrato/previa ──▶ TAI (confere, não grava)
                  ── POST /financeiro/extrato ────────▶ TAI (importa e sugere)
  seu sistema ── GET  /financeiro/extrato/{id}/linha?status=SUGERIDA
              ── POST /financeiro/extrato/linha/{linhaId}/pagar ──▶ baixa criada

Baixa direta

1. Tenha o id da parcela. Ele vem na resposta da criação do título (parcelas[].id) ou no detalhe:

   GET /financeiro/titulo/1290
   Authorization: Bearer $TAI_TOKEN

   Sem o id guardado, liste as parcelas em aberto com saldo — até 100 por chamada, refine com search:

   GET /financeiro/titulo/parcela/abertas?empresaId=3&direcao=RECEBER&search=Mercado%20Sol

2. Descubra a conta bancária (opcional). A baixa pode apontar a conta por onde o dinheiro passou:

   GET /financeiro/extrato/contas?empresaId=3

3. Registre o pagamento.

   POST /financeiro/titulo/parcela/5521/pagar
   Content-Type: application/json
   
   {
     "dataBaixa": "2026-10-16",
     "valorPrincipal": 600.00,
     "juros": 4.20,
     "multa": 12.00,
     "desconto": 0,
     "forma": "PIX",
     "contaBancariaId": 7,
     "observacao": "Recebido via gateway, transação 88123"
   }

   A resposta é o título atualizado: a parcela fica LIQUIDADA ou PARCIAL e o título passa a PARCIAL ou LIQUIDADO.

Como os valores se somam

• Principal + desconto amortizam o valor de face da parcela. A parcela liquida quando eles alcançam o saldo; abaixo disso, fica PARCIAL e aceita outra baixa.
• Juros e multa são acréscimos: entram no caixa, mas não amortizam. Principal + desconto acima do saldo é recusado com 400 — o excedente vai em juros ou multa.
• O valor que atravessou o caixa é principal + juros + multa. O desconto não passa pelo caixa.
• forma aceita PIX, TED, BOLETO, DINHEIRO, CARTAO_CREDITO, CARTAO_DEBITO, DEBITO_AUTOMATICO, TRANSFERENCIA e OUTRO.

Estornar

Pagamento registrado por engano não se apaga: estorna-se. O id da baixa aparece no detalhe do título (GET /financeiro/titulo/{id}).

POST /financeiro/titulo/baixa/9034/cancelar
Content-Type: application/json

{ "motivo": "Pagamento devolvido pelo gateway" }

A baixa fica marcada como estornada, a parcela reabre e o motivo vai para a trilha.

Conciliação pelo extrato

1. Confira o arquivo antes de gravar. A prévia lê o OFX (ou o PDF do internet banking), mostra período e totais e confere se a soma dos lançamentos fecha com os saldos. Sem contaBancariaId, ela identifica a conta pelo banco, agência e conta que o arquivo declara.

   curl -X POST "https://api.taitecnologia.com/financeiro/extrato/previa?empresaId=3" \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -F "arquivo=@extrato-outubro.ofx"

   Olhe contaDetectadaId, podeImportar, bloqueioPrevisto, jaImportados e avisos. No primeiro extrato de uma conta, informe saldoInicial; nos seguintes, ele vem do fechamento do extrato anterior. Conta que ainda não existe se cria com POST /financeiro/extrato/contas (descrição, banco, agência e conta).

2. Importe.

   curl -X POST "https://api.taitecnologia.com/financeiro/extrato?empresaId=3&contaBancariaId=7" \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -F "arquivo=@extrato-outubro.ofx"

   A resposta é o lote, com status e as filas: pendentes, sugeridas, conciliadas, ignoradas. Lote cuja soma não fecha com os saldos nasce BLOQUEADO: as linhas ficam visíveis, mas nada concilia. Exclua o lote (DELETE /financeiro/extrato/{id}) e reimporte com o saldo certo.

3. Confirme as sugestões. O casador procura a parcela pela direção, pelo valor exato (ou pela soma das parcelas em aberto de um título), pela janela de vencimento e pela contraparte lida no histórico — e explica o porquê em sugestaoJustificativa, com sugestaoConfianca ALTA ou MEDIA.

   GET /financeiro/extrato/412/linha?status=SUGERIDA

   Para confirmar uma linha, envie o corpo vazio:

   POST /financeiro/extrato/linha/80117/pagar
   Content-Type: application/json
   
   {}

   Para confirmar todas as sugeridas de uma vez, POST /financeiro/extrato/412/pagar-sugeridas. A linha que falhar não derruba as outras: a resposta traz conciliadas e falhas[] com o motivo de cada uma.

4. Resolva as pendentes. Linha PENDENTE é a que não casou ou empatou — o casador não chuta.

   Apontar a parcela

   POST /financeiro/extrato/linha/80121/pagar
   
   { "parcelaId": 5530, "lembrarContraparte": true }

   Com lembrarContraparte, os lançamentos daquela contraparte chegam sugeridos com confiança alta nos próximos extratos.

   Criar a conta na hora

   POST /financeiro/extrato/linha/80122/criar-titulo
   
   { "descricao": "Tarifa de pacote de serviços", "categoriaId": 455 }

   Tarifa, compra avulsa: a conta nasce com origem EXTRATO, uma parcela na data da linha, já liquidada.

   Ignorar

   POST /financeiro/extrato/linha/80125/ignorar
   
   { "motivo": "Transferência entre contas próprias" }

   Reversível com POST /financeiro/extrato/linha/{linhaId}/retomar.

   Depois de cadastrar contas ou contrapartes que faltavam, POST /financeiro/extrato/{id}/sugerir roda o casador de novo. O lote fica CONCILIADO quando não sobra linha pendente nem sugerida.

Envio do arquivo

A prévia e a importação são multipart/form-data, com o arquivo no campo arquivo, dentro dos limites de upload. A tela Financeiro › Banco importa o mesmo arquivo, e a conciliação continua disponível pela API.

Automatize

Cada passo publica um evento, que um webhook leva ao seu sistema:

Evento	Quando	Campos (dados)
PARCELA_BAIXADA	Cada baixa — direta ou pela conciliação	tituloId, parcelaId, direcao, valor, statusTitulo
PARCELA_ESTORNADA	Um estorno desfaz uma baixa	tituloId, parcelaId, baixaId, direcao, valor, motivo, statusTitulo
EXTRATO_IMPORTADO	Um extrato foi importado e as sugestões calculadas	loteId, empresaId, contaBancariaId, linhas, sugestoes, status
PARCELA_PAGAMENTO_APROVADO	Alguém autorizou o pagamento de uma parcela a pagar (veja abaixo)	tituloId, parcelaId, valor, vencimento, aprovadoPorId

Um estorno chega assim:

{
  "id": "evt_60877",
  "tipo": "PARCELA_ESTORNADA",
  "descricao": "O pagamento de uma parcela é estornado",
  "versao": 1,
  "ocorridoEm": "2026-10-18T15:02:44.120Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "tituloId": 1290,
    "parcelaId": 5521,
    "baixaId": 9034,
    "direcao": "RECEBER",
    "valor": 616.2,
    "motivo": "Pagamento devolvido pelo gateway",
    "statusTitulo": "ABERTO"
  }
}

EXTRATO_IMPORTADO é o gatilho para um sistema seu confirmar as sugeridas (GET /financeiro/extrato/{loteId}/linha?status=SUGERIDA) logo depois da importação. Para avisar o CRM ou a cobrança quando um cliente paga, veja Avisar a cobrança e o CRM.

Decisões na Caixa

Duas chaves da empresa, desligadas por padrão, levam o Financeiro para a Caixa de decisões dos donos da conta. Elas são lidas em GET /financeiro/config e ligadas com PUT /financeiro/config (campos nulos mantêm o gravado):

PUT /financeiro/config
Content-Type: application/json

{ "aprovacaoPagamentoCaixa": true, "conciliacaoCaixa": true }

• conciliacaoCaixa — um extrato importado com linhas sugeridas vira a decisão “Conciliar N linhas”, que executa o mesmo pagar-sugeridas.
• aprovacaoPagamentoCaixa — cada conta a pagar lançada vira “Aprovar pagamento” por parcela, até o vencimento. A aprovação também tem rota própria, POST /financeiro/titulo/parcela/{parcelaId}/aprovar-pagamento (permissão FINANCEIRO_PAGAR): ela registra quem autorizou, na trilha da conta. Sem banco integrado, aprovar não paga e não dá baixa — a resposta diz, em mensagem, como pagar à mão; a baixa entra depois pela conciliação do extrato.

Pelo seu agente de IA

“Quais linhas do extrato de outubro da conta Itaú ainda estão pendentes, e com que conta cada uma parece casar?”

O agente lê o lote, as linhas e as parcelas em aberto e responde. Registrar pagamento, conciliar e estornar não rodam por agente externo: são atos de confirmação forte, recusados pelo MCP com STRONG_CONFIRMATION_REQUIRED. Faça-os pela API, pela tela ou pela Tali. Veja Escrita e segurança.

Cuidados

• Uma baixa por pagamento. Repetir a chamada registra duas baixas; o servidor só recusa quando a soma passa do saldo. Guarde o id da transação do seu sistema em observacao e confira o detalhe antes de reenviar.
• Reimportar o mesmo extrato é recusado pelos identificadores dos lançamentos (FITID do OFX). permitirDuplicados=true força, quando a reimportação é intencional.
• Lote bloqueado não desbloqueia: exclua e reimporte. Lote com baixa conciliada ativa só se exclui depois de estornar.
• Conta cancelada não recebe pagamento; parcela liquidada também não — estorne antes se o pagamento não aconteceu.
• dataBaixa é data civil: envie yyyy-MM-dd. Veja Datas e formatos.