Lançar notas fiscais e boletos

O documento já diz quase tudo: a NF-e traz emitente, destinatário, valor e duplicatas; o boleto traz valor, vencimento e beneficiário. Em vez de digitar, o seu sistema (ou uma caixa de e-mail de notas, um robô de download da SEFAZ, um scanner) envia o arquivo e a TAI lança a conta — depois de uma prévia que não grava nada.

Quando usar	Notas de compra e de venda chegam em XML; boletos de fornecedores chegam em PDF, foto ou como linha digitável
Porta	REST (upload multipart/form-data) · Agente (MCP, só a leitura da linha digitável)
Você vai precisar	Módulo FINANCEIRO; permissão FINANCEIRO com nível de edição; token JWT

Como funciona

XML ou .zip ── POST /financeiro/nfe/previa ──▶ TAI  (nota a nota: entra, já lançada ou erro)
            ── POST /financeiro/nfe ─────────▶ TAI  (lança contas + contrapartes novas)

boleto      ── GET  /financeiro/boleto/ler?linha= ─────────▶ valor e vencimento (não grava)
PDF / foto  ── POST /financeiro/titulo/documento/previa ──▶ TAI  (lê e confere, não grava)
            ── POST /financeiro/titulo/documento ────────▶ TAI  (lança só leitura conferida)

cada conta lançada ── evento TITULO_CRIADO ──▶ webhook e fluxos automatizados

NF-e (XML)

1. Faça a prévia. Envie um XML ou um .zip com vários (até 200 notas por envio).

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

   A resposta resume totalLinhas, importadosComSucesso, ignorados e erros, e traz em resultados[] uma linha por nota, com nome (o número da nota), status e mensagem:

   status	Significado
   SUCESSO	A nota entraria — a mensagem diz direção, contraparte, valor e parcelas
   IGNORADO	A mesma nota (mesma chave de acesso) já foi lançada
   ERRO	Não é de nenhuma empresa da conta, não tem valor, não é NF-e

2. Importe. Mesmo arquivo, mesmos parâmetros, na rota sem /previa:

   curl -X POST "https://api.taitecnologia.com/financeiro/nfe?empresaId=3&categoriaId=412" \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -F "arquivo=@notas-outubro.zip"

   Em SUCESSO, a mensagem traz o id da conta criada.

Como a nota vira conta

• Direção pelo CNPJ: nota em que a empresa é a destinatária vira conta a pagar ao emitente; em que é a emitente, conta a receber do destinatário. Sem empresaId, a TAI procura entre todas as empresas da conta; com ele, só naquela.
• Parcelas: as duplicatas da nota viram as parcelas. Sem duplicata, uma parcela à vista na data de emissão (a mensagem avisa — ajuste o vencimento se preciso). Duplicatas que não somam o total da nota: entra a soma das duplicatas, com aviso.
• Contraparte: procurada pelo CNPJ; se não existe, é criada (fornecedor ou cliente).
• Categoria: a de categoriaId, se informada; senão, a da última conta daquela contraparte na mesma direção.
• Campos: numeroDocumento recebe número/série da nota, competencia o mês da emissão, e a chave de acesso fica na observação.
• Sem duplicidade: a chave de acesso identifica a nota — reimportar o mesmo arquivo não lança de novo. Você pode reenviar com segurança.

Boleto

Linha digitável

Quando o seu sistema já tem a linha digitável (ou o código de barras), leia antes de lançar:

GET /financeiro/boleto/ler?linha=23793381286000000012345600112233491230000059000
Authorization: Bearer $TAI_TOKEN

Aceita a linha de 47 números do boleto bancário (com ou sem pontos e espaços), o código de barras de 44 e a linha de 48 de conta de consumo e tributo. A resposta traz valida, banco, valor, vencimento e codigoBarras; com dígito verificador errado, valida vem false e falha diz qual parte não confere — não lance nesse caso. A linha de 48 traz o valor, mas não o vencimento. Com a leitura válida, crie a conta a pagar como em Lançar contas vindas do seu ERP.

PDF ou foto

Com o boleto em arquivo (PDF, PNG, JPG ou WebP, até 10 MB), a TAI lê a linha digitável por regra, completa com IA só o que falta (beneficiário, CNPJ, número do documento) e confere tudo — dígitos verificadores, valor e vencimento da linha contra os impressos, CNPJ válido, conta já lançada.

curl -X POST "https://api.taitecnologia.com/financeiro/titulo/documento/previa?empresaId=3" \
  -H "Authorization: Bearer $TAI_TOKEN" \
  -F "arquivo=@boleto-energia.pdf"

A prévia e o lançamento (POST /financeiro/titulo/documento) respondem no mesmo formato da NF-e (resultados[] com status e mensagem). Só leitura conferida entra: se algo não bate, o resultado é ERRO com o motivo, e o boleto deve ser conferido e lançado à mão. A conta nasce a pagar, com uma parcela no vencimento do boleto; o fornecedor que não existe é criado pelo CNPJ; o mesmo boleto (mesma linha digitável) não entra duas vezes. Sem empresaId, a conta precisa ter uma única empresa.

POST /financeiro/titulo/documento/ler devolve só a leitura e as conferências, sem montar a conta.

Automatize

Cada nota ou boleto lançado publica TITULO_CRIADO, como qualquer conta. Um webhook assinando Uma conta a pagar ou a receber é lançada leva a conta ao seu ERP (tituloId, direcao, descricao, valorTotal, contraparte; o título inteiro com Enviar também o registro completo). Um fluxo automatizado pode, por exemplo, abrir um card de aprovação num quadro de Processos — veja Avisar a cobrança e o CRM.

Pelo seu agente de IA

“Leia este boleto: 23793.38128 60000.000123 45600.112233 4 91230000059000. Qual o valor e o vencimento?”

O agente lê a linha digitável e responde, sem gravar nada; com escopo de escrita, pode criar a conta com os valores lidos. O envio de arquivos (XML, PDF, foto) é upload e não passa pelo MCP — use a API, a tela ou a Tali, que aceita o arquivo anexado na conversa.

Cuidados

• Sempre a prévia primeiro em cargas novas: ela mostra nota a nota o que vai acontecer.
• Conta lançada por documento é editável como qualquer conta manual; cancelar exige motivo.
• Até 200 notas por envio e 50 MB descompactados por .zip; outros arquivos dentro do .zip são ignorados.
• XML com declaração DOCTYPE é recusado por segurança — o XML da NF-e não usa.
• Uploads seguem os limites de arquivo.