Trabalhar com o escritório contábil

Empresa e escritório de contabilidade trocam duas coisas todo mês: as guias que o contador apura (que a empresa precisa pagar) e o movimento da empresa (que o contador precisa escriturar). Na TAI, o vínculo contábil liga as duas contas com consentimento registrado, e a contabilização gera os lançamentos no leiaute do sistema contábil do escritório.

Quando usar	O escritório atende a empresa pela TAI, ou o sistema contábil do escritório precisa receber os lançamentos da folha e do financeiro
Porta	REST · Página pública (aceite do convite)
Você vai precisar	Empresa: permissão VINCULO_CONTADOR (módulo CORE) para o vínculo; módulo FOLHA_PAGAMENTO com permissão FOLHA para ler e exportar e FOLHA_PROCESSAR para gerar lotes. Escritório: módulo FSC com permissão FSC

Como funciona

escritório ── POST /vinculo/escritorio/convidar ──▶ TAI ── e-mail com link ──▶ empresa
empresa ── aceita (painel ou link público), consentindo os escopos ──▶ vínculo ATIVO
escritório apura o DAS ──▶ conta a pagar na empresa (origem ESCRITORIO)       [escopo OBRIGACOES]
empresa ── POST /contabil/lote/preparar-mes ──▶ lotes da folha e do financeiro
        ── GET  /contabil/lote/{id}/exportar?layoutId= ──▶ arquivo para o sistema contábil

O vínculo

O escritório propõe os escopos; a empresa consente no aceite. Cada escopo é uma travessia:

Escopo	O que atravessa
OBRIGACOES	A guia do Simples (DAS) apurada pelo escritório vira conta a pagar no Financeiro da empresa, com a origem ESCRITORIO. Reapurar ou reemitir atualiza a mesma conta
NOTAS	As notas fiscais da empresa chegam à apuração do escritório

Lado da empresa

Quem é o contador hoje, convites pendentes e o histórico:

GET /vinculo/empresa/meu-contador
Authorization: Bearer $TAI_TOKEN

Para aceitar um convite pendente — pelo token do link do e-mail ou pelo vinculoId que aparece em convitesPendentes, nunca os dois —, informe qual empresa da conta será vinculada:

POST /vinculo/empresa/aceitar
Content-Type: application/json

{ "vinculoId": 57, "empresaId": 3, "aceitouTermo": true }

A raiz do CNPJ da empresa precisa bater com a do convite (matriz e filiais aceitam o mesmo convite). Para cortar o acesso do escritório na hora:

POST /vinculo/empresa/57/encerrar

{ "motivo": "Troca de escritório contábil" }

A trilha de cada vínculo, com autor, data e lado, sai em GET /vinculo/empresa/{id}/eventos.

Lado do escritório

O cliente precisa existir na carteira do escritório, com CNPJ válido.

POST /vinculo/escritorio/convidar
Content-Type: application/json

{
  "clienteId": 214,
  "email": "financeiro@suaempresa.com.br",
  "escopos": ["OBRIGACOES", "NOTAS"],
  "mensagem": "Vamos ligar sua conta TAI ao escritório para as guias chegarem sozinhas."
}

A resposta traz emailEnviado e caminhoConvite — o link para mandar por outro canal se o e-mail não chegar. O convite vale 15 dias. POST /vinculo/escritorio/{id}/reenviar gera um link novo e invalida o anterior; /cancelar desiste antes do aceite; /encerrar termina um vínculo ativo. A carteira inteira, com o estado de cada um, sai em GET /vinculo/escritorio.

Empresa que ainda não usa a TAI

O link do convite abre uma página pública. Ela lê o convite em GET /public/vinculo/{token} e, no aceite, POST /public/vinculo/{token}/aceitar cria a conta e a empresa com o CNPJ do convite e ativa o vínculo. POST /public/vinculo/{token}/recusar recusa sem criar nada.

Os estados do vínculo são CONVIDADO, ATIVO, RECUSADO (a empresa disse não), CANCELADO (o escritório desistiu antes do aceite) e ENCERRADO (existiu e acabou). Uma empresa tem no máximo um contador ativo.

Exportar os lançamentos contábeis

A contabilização mora no módulo Folha de Pagamento e cobre a folha e o Financeiro no mesmo esquema contábil. O plano de contas, o esquema e o vínculo das categorias e contas bancárias às contas contábeis são configurados na tela Departamento Pessoal › Folha de Pagamento › Contabilidade da empresa.

1. Veja o que falta mapear. A prévia do financeiro lista o que entraria e cada pendência — categoria sem regra, conta bancária sem conta contábil —, com o valor que ficaria de fora.

   GET /contabil/lote/previa-financeiro?empresaId=3&competencia=2026-10

2. Gere os lotes do mês. Num gesto, um lote por folha aprovada sem lote e o lote do Financeiro:

   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. Só o financeiro: POST /contabil/lote/gerar-financeiro?empresaId=3&competencia=2026-10.

3. Escolha o leiaute. Os leiautes da conta descrevem o arquivo do sistema contábil (delimitado ou posicional, campos e ordem):

   GET /contabil/layout/listar

   Sem nenhum, POST /contabil/layout/padrao cria um CSV genérico para conferir numa planilha.

4. Baixe o arquivo.

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

   Exportar marca o lote como EXPORTADO. Para só olhar o arquivo sem mudar o status, use marcar=false. Os lotes de uma competência saem em GET /contabil/lote?empresaId=3&competencia=2026-10; os lançamentos de um lote, linha a linha (contas de débito e crédito, valor, histórico, centro de custo, origem), em GET /contabil/lote/{id}/lancamentos.

Pelo seu agente de IA

“Quem é o contador da empresa e desde quando ele tem acesso? O lote do financeiro de outubro já foi exportado?”

O agente lê o vínculo e os lotes. Aceitar um convite não passa por agente: o consentimento é dado por uma pessoa, na tela ou pela API. Encerrar o vínculo e cancelar um lote são atos de confirmação forte, recusados pelo MCP — veja Escrita e segurança.

Cuidados

• Conta vinda do escritório é somente leitura na empresa: editar ou cancelar é recusado. Quem emitiu atualiza. Registrar o pagamento é normal.
• Um lote vivo do Financeiro por competência. Conta lançada ou baixa estornada depois do lote aparece como diferença; o caminho é cancelar o lote (POST /contabil/lote/{id}/cancelar) e gerar de novo. Competência fechada recusa lote novo e cancelamento.
• Contas de origem FOLHA ficam fora do lote do Financeiro: a despesa entra pelo lote da folha.
• Lote cancelado depois de exportado não desfaz o arquivo que já saiu — o sistema contábil precisa ser corrigido também.
• Competência em AAAA-MM. Veja Datas e formatos.