Lançar contas vindas do seu ERP

O ERP, o sistema de vendas ou o de compras gera a obrigação; a TAI passa a acompanhá-la — parcelas, vencimentos, baixas, conciliação e fluxo de caixa. Cada conta vira um título com uma ou mais parcelas, ligado a uma contraparte (quem paga ou recebe) e a uma categoria.


Quando usar	Faturas de venda, pedidos de compra, contratos ou notas lançados em outro sistema precisam aparecer no financeiro da TAI
Porta	REST · Webhook (o caminho de volta) · Agente (MCP)
Você vai precisar	Módulo `FINANCEIRO`; permissão `FINANCEIRO` com nível de edição; token JWT de um usuário de integração

Como funciona

seu sistema ── GET /empresa ─────────────────────────▶ TAI   (descobre o empresaId)
seu sistema ── GET /financeiro/contraparte?search= ──▶ TAI   (acha o cliente/fornecedor pelo CNPJ)
            └─ POST /financeiro/contraparte ──────────▶ TAI   (cria, se não existir)
seu sistema ── GET /financeiro/titulo/page?search= ──▶ TAI   (a conta já foi lançada?)
seu sistema ── POST /financeiro/titulo ───────────────▶ TAI   (lança título + parcelas)
TAI ── evento TITULO_CRIADO ──▶ webhook e fluxos automatizados

Passo a passo

Descubra a empresa. O título pertence a um estabelecimento (CNPJ) da conta.
```
GET /empresa
Authorization: Bearer $TAI_TOKEN
```
Guarde o id da empresa: ele vai em empresaId.
Ache ou crie a contraparte. A busca cobre nome e CPF/CNPJ.
```
GET /financeiro/contraparte?search=12345678000190
```
Se a lista voltar vazia, crie:
```
POST /financeiro/contraparte
Content-Type: application/json

{
  "nome": "Papelaria Central Ltda",
  "tipo": "FORNECEDOR",
  "cpfCnpj": "12345678000190",
  "email": "financeiro@papelariacentral.com.br"
}
```
tipo aceita CLIENTE, FORNECEDOR, AMBOS, GOVERNO e OUTRO. O CPF/CNPJ é único na conta: um segundo cadastro com o mesmo documento é recusado com 400, dizendo qual contraparte já o usa. Guarde o id.
Escolha a categoria (opcional). O plano gerencial vem semeado na primeira leitura.
```
GET /financeiro/categoria/arvore
```
Conta a pagar pede categoria de DESPESA; a receber, de RECEITA. Sem categoria e com contraparte, a TAI usa a categoria da última conta daquela contraparte na mesma direção.
Confira se a conta já existe. Use o número do documento do seu sistema como chave.
```
GET /financeiro/titulo/page?empresaId=3&search=NF-004812&direcao=PAGAR
```
search procura na descrição e no número do documento por trecho; confirme a igualdade exata de numeroDocumento no resultado antes de decidir que já existe.

Lance o título com as parcelas.

POST /financeiro/titulo
Content-Type: application/json

{
  "empresaId": 3,
  "direcao": "PAGAR",
  "contraparteId": 88,
  "categoriaId": 412,
  "descricao": "Material de escritório — pedido 4812",
  "numeroDocumento": "NF-004812",
  "dataEmissao": "2026-10-01",
  "competencia": "2026-10",
  "parcelas": [
    { "dataVencimento": "2026-10-15", "valor": 600.00 },
    { "dataVencimento": "2026-11-15", "valor": 600.00 }
  ]
}

O valorTotal é a soma das parcelas, calculado no servidor. A resposta traz o título com id, status (ABERTO) e parcelas[] — cada uma com id, numero, dataVencimento, valor e saldo. Guarde o id do título e os id das parcelas ao lado do registro no seu sistema: são eles que você usa para registrar a baixa.

Campos do título

Campo	Obrigatório	Observação
`empresaId`	Sim	Estabelecimento dono da conta
`direcao`	Sim	`PAGAR` ou `RECEBER`. Não muda depois de criado
`descricao`	Sim	Pelo menos 2 caracteres
`parcelas[]`	Sim	Ao menos uma; cada uma com `dataVencimento` e `valor` maior que zero
`contraparteId`, `categoriaId`	Não	Ids da própria conta
`numeroDocumento`	Não	Número da nota, fatura ou pedido no seu sistema
`competencia`	Não	`AAAA-MM`. Decide em que mês a conta entra na contabilização
`dataEmissao`, `observacao`	Não

Alterar e cancelar

PATCH /financeiro/titulo/{id} muda só os campos enviados. Enviar parcelas refaz todas as parcelas — e só é aceito enquanto a conta não tem pagamento registrado.
POST /financeiro/titulo/{id}/cancelar com {"motivo": "Pedido cancelado no ERP"} cancela a conta. Conta com pagamento registrado precisa ter as baixas estornadas antes. Cancelada, ela continua na lista, vale zero nos totais e o motivo fica na trilha (GET /financeiro/titulo/{id}/eventos).
Conta recorrente (aluguel, mensalidade) não precisa ser empurrada todo mês: cadastre uma recorrência em POST /financeiro/recorrencia e a TAI gera o título de cada competência.

Automatize

Cada conta lançada publica o evento TITULO_CRIADO — também as que nascem fora do seu ERP: na tela, pela Tali, pela conciliação do extrato ou importadas de NF-e. Para o ERP receber essas contas, crie um webhook assinando Uma conta a pagar ou a receber é lançada:

{
  "id": "evt_59410",
  "tipo": "TITULO_CRIADO",
  "descricao": "Uma conta a pagar ou a receber é lançada",
  "versao": 1,
  "ocorridoEm": "2026-10-09T11:20:37.845Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "tituloId": 1290,
    "direcao": "RECEBER",
    "descricao": "Pedido 4471",
    "valorTotal": 1200.0,
    "contraparte": "Mercado Sol"
  }
}

As contas que o próprio ERP lançou também voltam por esse webhook: descarte-as pelo tituloId que você guardou na criação. Com Enviar também o registro completo, o título chega inteiro, com as parcelas, em registro. Para manter o cadastro de clientes e fornecedores em dia nos dois lados, assine também CONTRAPARTE_CADASTRADO, CONTRAPARTE_ALTERADO e CONTRAPARTE_EXCLUIDO.

Dentro da TAI, o mesmo evento pode abrir um card de aprovação num fluxo de Processos ou avisar alguém — veja Financeiro: o que a TAI avisa e Avisar a cobrança e o CRM.

Pelo seu agente de IA

“Lance uma conta a pagar de R$ 1.200 para a Papelaria Central, em duas parcelas de 15/10 e 15/11, categoria Material de escritório.”

Com escopo de escrita, o agente acha a contraparte e a categoria e cria o título — seu cliente de IA pede aprovação antes. Com credencial somente leitura, ele só consulta. Veja Escrita e segurança.

Cuidados

Duplicidade é responsabilidade de quem envia. O POST /financeiro/titulo não recusa um numeroDocumento repetido. Guarde o id da TAI no seu sistema ou consulte antes de lançar (passo 4). Ao repetir uma chamada que falhou por rede, consulte primeiro.
Datas civis: dataVencimento e dataEmissao como yyyy-MM-dd; competencia como AAAA-MM. Veja Datas e formatos.
Valores em reais com ponto decimal (600.00).
Origem: contas lançadas pela API nascem com origem MANUAL e são editáveis. As que vêm do escritório contábil (ESCRITORIO) ou da folha (FOLHA) são somente leitura.
Carga grande: um título por requisição, e corpos acima de 8 KB são barrados pelo firewall — veja Limites. Espalhe cargas de milhares de contas ao longo do tempo.
Empresa errada responde 404 Empresa não encontrada; categoria da direção oposta responde 400 dizendo qual tipo é esperado.

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