eSocial — Eventos XML

O módulo eSocial (backend/src/esocial/) gera, persiste e transmite os eventos XML obrigatórios ao ambiente eSocial da Receita Federal, integrados com o módulo HR.

Visão Geral

Característica	Detalhe
Módulo backend	backend/src/esocial/
Schema de log	EsocialEvent — backend/src/esocial/esocial-event.schema.ts
Permissão	Admin ou Superadmin
Rota principal	/t/:slug/admin/esocial

Eventos Implementados

Código	Nome	Gatilho
S-2200	Admissão de Trabalhador	Cadastro de Employee (CLT)
S-1200	Remuneração Mensal	Aprovação de PayrollRun
S-2299	Desligamento	terminateEmployee()

Os tipos estão enumerados em EsocialEventType em esocial-event.schema.ts.

Schema EsocialEvent

Campo	Tipo	Descrição
tenant	ObjectId	Isolamento multi-tenant
employeeId	ObjectId	Referência ao Employee
eventType	S-2200 | S-1200 | S-2299
period	{ month, year }	Presente apenas em S-1200
xmlPayload	string	XML assinado completo — retido por 5 anos (obrigação RFB)
status	enum	pending → sent → authorized | rejected
protocoloRecibo	string	Número de protocolo retornado pelo WS eSocial em caso de sucesso
errorCode	string	Código de erro 4-dígitos em caso de rejected
errorMessage	string	Mensagem de erro legível
sentAt	Date	Timestamp do envio ao webservice

Índices compostos: (tenant, employeeId), (tenant, eventType, status), (tenant, period.year, period.month).

Ambiente (homologação vs. produção)

O campo environment aceito nos endpoints de envio controla o endpoint do webservice eSocial:

Valor	URL alvo
homologacao (default)	https://webwso2ihm.esocial.gov.br/servicos/
producao	https://webwso2.esocial.gov.br/servicos/

O valor padrão é sempre homologacao — o chamador deve passar explicitamente "environment": "producao" para transmissões reais. Isso evita envios acidentais ao ambiente produtivo durante desenvolvimento.

Serviços

Serviço	Responsabilidade	Arquivo
EsocialService	Orquestrador — carrega Employee/PayrollRun/Lines, chama builder, persiste EsocialEvent, despacha via transport	esocial.service.ts
EsocialEventService	Construtores XML — buildS2200(), buildS1200(), buildS2299()	esocial-event.service.ts
EsocialTransportService	HTTP POST ao webservice eSocial; retorna { protocoloRecibo }	esocial-transport.service.ts

Fluxo de envio

Controller
    ↓
EsocialService.send*()
    ↓ carrega Employee / PayrollRun / PayrollLines
EsocialEventService.build*()  → rawXml
    ↓
eventModel.create() com status = 'pending'
    ↓
EsocialTransportService.send()
    ↓ sucesso               ↓ falha
status = 'authorized'    status = 'rejected'
protocoloRecibo          errorCode + errorMessage

Em caso de falha no transporte, o evento permanece no banco com status: 'rejected' para reenvio manual. O erro é relançado ao chamador.

Endpoints

Método	Rota	Descrição
POST	/t/:slug/admin/esocial/send/admission/:employeeId	Gera e envia S-2200
POST	/t/:slug/admin/esocial/send/monthly/:payrollRunId	Gera e envia S-1200 para todas as linhas da folha
POST	/t/:slug/admin/esocial/send/termination/:employeeId	Gera e envia S-2299
GET	/t/:slug/admin/esocial/events	Lista eventos com filtros

Body de envio (S-2200 e S-2299)

{
  "cnpjEmpregador": "12345678000100",
  "environment": "homologacao"
}

Body de envio (S-1200)

{
  "cnpjEmpregador": "12345678000100",
  "environment": "homologacao"
}

O cnpjEmpregador deve ser o CNPJ da filial do funcionário (ou do tenant principal). O sistema não resolve o CNPJ automaticamente — o chamador deve passá-lo.

Body de desligamento (S-2299)

{
  "cnpjEmpregador": "12345678000100",
  "dtDeslig": "2026-05-31",
  "mtvDeslig": "01",
  "dtProjFimAPI": "2026-06-15",
  "pensaoAlim": "N",
  "environment": "homologacao"
}

Campo	Descrição
dtDeslig	Data do desligamento YYYY-MM-DD
mtvDeslig	Código do motivo (tabela eSocial: 01 = rescisão sem justa causa, 02 = pedido de demissão, etc.)
dtProjFimAPI	Data projetada fim do aviso prévio indenizado
pensaoAlim	S/N — indica se há pensão alimentícia

Query params (GET events)

Parâmetro	Descrição
employeeId	Filtrar por funcionário
eventType	S-2200 | S-1200 | S-2299
status	pending | sent | authorized | rejected
page	Página (default: 1)
limit	Itens por página (max: 100, default: 20)

Dados obrigatórios no Employee para eSocial

Campo	Por que é necessário
pisNit	Identificador do trabalhador no eSocial
cboCupation	Código Brasileiro de Ocupações
esocialCategory	Categoria do trabalhador (ex: 101 = empregado geral)
admissionDate	Data de admissão (S-2200)
cpf ou cpfEncrypted	CPF do trabalhador

Campos ausentes causam erro de validação no EsocialEventService ao tentar construir o XML.

Retenção dos XMLs

EsocialEvent.xmlPayload armazena o XML completo assinado. A Receita Federal / SEFAZ exige que o transmissor guarde os XMLs por 5 anos. Não exclua registros EsocialEvent — configure a RetentionPolicy em LGPD com retentionYears: 5 para esta coleção.

Relacionados

• HCM — Recursos Humanos — Módulo HR que fornece Employee e PayrollRun
• LGPD — Política de retenção de 5 anos para XMLs eSocial
• Security PII — CPF do trabalhador nos XMLs é decriptado sob demanda