Acompanhar o eSocial

A TAI monta os eventos do eSocial a partir do cadastro e da folha — tabelas, vínculos, remuneração e pagamentos —, transmite em lotes e lê o retorno do governo evento a evento. Esta página mostra o que é automático, o que exige um gesto e o que um sistema externo (um painel de conformidade, o sistema do escritório contábil) consulta pela API.


Quando usar	Acompanhar de fora a situação do eSocial — recusas, lotes pendentes, competência fechada — ou conduzir geração e transmissão por um orquestrador seu
Porta	REST · Webhook (os avisos) · Agente (MCP, leitura)
Você vai precisar	Módulo `FOLHA_PAGAMENTO`; `FOLHA` para consultar; `FOLHA_PROCESSAR` para gerar eventos e consultar o retorno; `FOLHA_APROVAR` para transmitir e fechar; `FOLHA_CADASTRO` para configuração e certificado; usuário de integração com token JWT

Como funciona

cadastro e folha ─► gerar eventos ─► fila (GERADO)
                                        │  transmitir (exige transmissão habilitada)
                                        ▼
                              lote ENVIADO ─► AGUARDANDO_RETORNO
                                        │  esocial-consulta-retorno, a cada 10 minutos
                                        ▼
               cada evento: SUCESSO · SUCESSO_COM_ALERTA · ERRO (com as ocorrências do governo)
                                        │
                     fechamento da competência (S-1299) ─► totalizadores ─► confronto TAI × governo

As famílias têm ordem: os eventos de tabela (S-1000, S-1005, S-1010, S-1020) vêm primeiro; os eventos do vínculo (S-2200, S-2205, S-2206, S-2230, S-2299) só saem depois do S-2200 aceito; os periódicos (S-1200, S-1210 e os S-3000 do que sumiu da folha) são gerados por competência. A geração compara o cadastro com o que o eSocial já aceitou e cria só o que mudou — rodar de novo sem mudança não gera nada.

O que é automático e o que é gesto

O quê	Como acontece
Consultar o retorno dos lotes	Automático: `esocial-consulta-retorno`, a cada 10 minutos (ligada)
Avisar recusa por e-mail aos donos da conta	Automático com `esocial-aviso-recusa` ligada (começa desligada)
Avisar certificado perto de vencer	Automático com `esocial-alerta-certificado` ligada (começa desligada)
Gerar os periódicos da competência	Automático ao pagar a folha, com `gerarEsocialAoPagar` na configuração da folha da empresa; senão, gesto
Reabrir a competência no eSocial (S-1298)	Automático ao reabrir uma folha cuja competência já estava fechada lá: o evento entra na fila para a próxima transmissão
Transmitir	Sempre um gesto — na tela, pela Tali ou pela API — e só com a transmissão habilitada
Fechar a competência (S-1299)	Sempre um gesto

As rotinas se ligam em Processos › Central de Automações. Na plataforma, a transmissão fica em Departamento Pessoal › Folha de Pagamento › Folha do Mês, etapa Declarar ao governo (eSocial).

Consultar pela API

Resumo por situação — o número que um painel mostra:

curl https://api.taitecnologia.com/esocial/evento/resumo/3 \
  -H "Authorization: Bearer $TAI_TOKEN"

{ "GERADO": 4, "EM_LOTE": 0, "ENVIADO": 0, "SUCESSO": 212, "SUCESSO_COM_ALERTA": 3, "ERRO": 2, "EXCLUIDO": 0 }

Os recusados, com o motivo. Liste por situação e abra cada um:
```
GET /esocial/evento?empresaId=3&status=ERRO&page=0&size=50
GET /esocial/evento/{id}
```
O detalhe traz o tipo (S-2200, S-1200…), a chaveNegocio, o nrRecibo quando aceito e as ocorrencias devolvidas pelo governo — cada uma com codigo, descricao e a localizacao (a tag onde a validação falhou). GET /esocial/evento/{id}/xml devolve o XML assinado, quando o gateway o devolveu, ou o gerado.

Os lotes.

GET /esocial/lote?empresaId=3
GET /esocial/lote/{id}/eventos
POST /esocial/lote/{id}/consultar        ← antecipa a consulta do retorno

status do lote: MONTADO, ENVIADO, AGUARDANDO_RETORNO, CONCLUIDO, ERRO_COMUNICACAO (reenviavel) ou ERRO_LAYOUT.

O fechamento da competência.
```
GET /esocial/fechamento/3?perApur=2026-10
GET /esocial/fechamento/3/confronto?perApur=2026-10
```
O primeiro diz se a competência está fechada, o recibo do fechamento e os impedimentos, um a um. O confronto compara, trabalhador a trabalhador, o que a TAI calculou com o que o governo apurou nos totalizadores (S-5001/S-5002); quem ainda não tem totalizador aparece em semTotalizador. O recorte é a raiz do CNPJ: matriz e filiais fecham juntas.
Antes de tudo, a prontidão. GET /esocial/prontidao/{empresaId} lista o que falta no cadastro (empresa, cargos, colaboradores, rubricas) para transmitir.

Conduzir pela API

Para um orquestrador que faz o ciclo inteiro, na ordem:

POST /esocial/evento/gerar/3                                  ← tabelas
POST /esocial/evento/gerar-vinculos/3                         ← admissões, alterações, afastamentos, desligamentos
POST /esocial/evento/gerar-periodicos/3?competencia=2026-10   ← remuneração e pagamentos
POST /esocial/lote/transmitir/3                               ← monta lotes de até 50 e envia
POST /esocial/fechamento/3/fechar?perApur=2026-10             ← S-1299, quando não houver impedimento

Cada geração devolve gerados, semMudanca, bloqueados e os itens com o detalhe do que bloqueou. Nada é transmitido sem transmissaoHabilitada em GET /esocial/config/{empresaId}. O fechamento do 13º é separado: indApuracao=2 e perApur com o ano (2026).

Certificado digital

O certificado A1 da empresa é enviado ao gateway do eSocial e descartado: nem o arquivo nem a senha ficam na TAI.

curl -X POST "https://api.taitecnologia.com/esocial/certificado/3?senha=…" \
  -H "Authorization: Bearer $TAI_TOKEN" \
  -F "arquivo=@certificado.pfx"

A TAI confere a titularidade contra o CNPJ da empresa. GET /esocial/certificado/{empresaId} lista os certificados enviados com validadeFim, vigente e diasParaVencer — um bom item para o seu painel vigiar. Na renovação, envie o arquivo novo.

Automatize

Cada passo do eSocial publica um evento. Para levar recusas e recibos a outro sistema — um painel de conformidade, o sistema do escritório contábil —, crie um webhook assinando os que interessam:

Evento	Quando
`ESOCIAL_LOTE_TRANSMITIDO`	Um lote foi transmitido e recebeu `protocolo`; o retorno chega depois
`ESOCIAL_EVENTO_ACEITO`	O governo aceitou um evento e devolveu o `nrRecibo`
`ESOCIAL_EVENTO_RECUSADO`	O governo recusou um evento; ele precisa ser corrigido e gerado de novo
`ESOCIAL_EVENTO_INVALIDO_ESQUEMA`	A conferência contra o esquema XSD oficial barrou um evento antes da transmissão; ele fica fora do lote até ser corrigido
`ESOCIAL_COMPETENCIA_FECHADA`	O fechamento da competência (S-1299) foi gerado
`ESOCIAL_COMPETENCIA_REABERTA`	A reabertura (S-1298) foi gerada — pela pessoa ou porque a folha foi reaberta

Uma recusa chega assim:

{
  "id": "evt_52310",
  "tipo": "ESOCIAL_EVENTO_RECUSADO",
  "descricao": "O eSocial recusa um envio",
  "versao": 1,
  "ocorridoEm": "2026-11-06T14:10:02.918Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "esocialEventoId": 4471,
    "tipoEsocial": "S_1200",
    "operacao": "INCLUSAO",
    "empresaId": 3,
    "perApur": "2026-10",
    "loteId": 312,
    "nrRecibo": null
  }
}

As ocorrências apontadas pelo governo não vêm em dados: com Enviar também o registro completo, o evento chega com o registro; sem ele, leia GET /esocial/evento/{esocialEventoId} (passo 2 acima). Para só avisar alguém — o escritório num canal do Slack, por exemplo —, use um fluxo automatizado com o bloco Chamar outro sistema e um Corpo (JSON) próprio (Da TAI para o seu sistema).

Como as novas tentativas cobrem horas, não dias, um painel que precisa estar sempre em dia também consulta GET /esocial/evento/resumo/{empresaId} de tempos em tempos (reconciliação). Para avisar pessoas por e-mail, ligue esocial-aviso-recusa e esocial-alerta-certificado.

Pelo seu agente de IA

“Tem evento do eSocial recusado na empresa matriz? O que o governo apontou?”

O agente lê o resumo, os eventos recusados e as ocorrências — só leitura. Transmitir e fechar são de confirmação forte e não saem pelo MCP (Escrita e segurança).

Cuidados

Comece em produção restrita. ambiente PRODUCAO_RESTRITA é o ambiente de homologação, sem efeito legal; em PRODUCAO, os eventos valem.
Evento recusado não é reaproveitado. Corrija o cadastro e gere de novo; o recusado fica como registro da tentativa.
SUCESSO_COM_ALERTA vale como aceite, mas leia a ocorrência: é onde o governo avisa o que vai deixar de aceitar.
Transmissão desligada não perde nada. Os eventos continuam sendo gerados e ficam na fila.
O S-1200 é um por trabalhador e competência, com todas as folhas do mês dentro: uma folha nova na mesma competência vira retificação do evento já aceito.
A senha do certificado vai como parâmetro. Chame essa rota só de um servidor seu, nunca de um navegador, e não registre a URL em logs.

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