Académique Documents
Professionnel Documents
Culture Documents
Verso 1.1
Junho de 2015
Histrico de verses
Data Verso Descrio
19/12/2014 1.0 Verso inicial
- Alterao do protocolo de segurana da camada de transporte de
SSL para TLS.
- Alterao da verso do SOAP de 1.2 para 1.1.
- Excluso da tag hash dos retornos dos WebServices.
- Alterao do nome das tags "tpInscricao" e "nrInscricao" para
"tpInsc" e "nrInsc" para compatibilizar com o nome utilizado nos
Schemas dos eventos.
26/06/2015 1.1 - Alterao do nome do atributo "id" para "Id" para compatibilizar
com o nome utilizado nos Schemas dos eventos.
- Alterao dos namespaces dos Schemas dos XMLs de
comunicao.
- Melhoria da descrio da seo 4.1 - Padro de Documento XML.
(Esclarecer o cenrio de uso dos caracteres de escape).
- Melhoria da descrio da seo 6.5 - Estrutura do retorno de
processamento do evento. (Incluso da referncia ao arquivo
RetornoEvento-v1_1_0.xsd.)
2
ndice
1. INTRODUO ......................................................................................................... 5
2. CONSIDERAES INICIAIS .............................................................................. 5
2.1. OBJETIVOS DO PROJETO ........................................................................................... 5
2.2. CONCEITO DE EVENTO ............................................................................................. 6
3. ARQUITETURA DE COMUNICAO ........................................................... 7
3.1. MODELO OPERACIONAL ........................................................................................... 7
3.2. NVEIS DE VALIDAO ............................................................................................ 8
3.3. AMBIENTES DE RECEPO....................................................................................... 9
3.4. ETAPAS DO PROCESSO IDEAL ................................................................................. 10
3.5. PROCEDIMENTOS DE CONTINGNCIA ..................................................................... 12
3.5.1. Indisponibilidade dos servidores ......................................................... 12
4. PADRES TCNICOS ......................................................................................... 13
4.1. PADRO DE DOCUMENTO XML............................................................................. 13
4.1.1.1. Declarao namespace.......................................................................... 14
4.2. SCHEMA XML....................................................................................................... 14
4.3. PADRO DE COMUNICAO .................................................................................. 15
4.4. PADRO DE CERTIFICADO DIGITAL ........................................................................ 16
4.5. PADRO DE ASSINATURA DIGITAL ......................................................................... 17
4.6. PROCESSO DE VALIDAO DE ASSINATURA DIGITAL.............................................. 19
4.7. RESUMO DOS PADRES TCNICOS .......................................................................... 20
5. WEBSERVICES ...................................................................................................... 22
5.1. PADRO DE MENSAGENS DOS WEBSERVICES ........................................................ 22
5.2. VALIDAO DA ESTRUTURA DA MENSAGEM NO WEBSERVICE ............................. 22
5.3. VALIDAO DO CERTIFICADO DIGITAL ................................................................. 23
5.4. WEBSERVICE DE ENVIO DE LOTE DE EVENTOS ...................................................... 24
5.4.1. Dados para a chamada ao Webservice .............................................. 25
5.4.2. Fluxo de Envio de Lote de Eventos ..................................................... 26
5.4.3. Leiaute Mensagem de Entrada ............................................................. 27
5.4.4. Leiaute Mensagem de Retorno do Envio do Lote ............................ 31
5.4.5. Validaes aplicadas .............................................................................. 38
5.5. WEBSERVICE DE CONSULTA AO RESULTADO DO PROCESSAMENTO DE UM LOTE DE
EVENTOS ........................................................................................................................... 39
5.5.1. Dados para a chamada ao Webservice .............................................. 39
5.5.2. Fluxo de consulta ao resultado do processamento do lote de
eventos 40
5.5.3. Leiaute da Mensagem de Entrada ....................................................... 41
5.5.4. Leiaute Mensagem de Retorno do Processamento do Lote .......... 43
5.5.5. Validaes aplicadas .............................................................................. 52
5.6. RECOMENDAES E BOAS PRTICAS ..................................................................... 53
5.6.1. Evitar o envio de eventos de outros grupos durante o envio dos eventos
peridicos ..................................................................................................................... 53
3
5.6.2. Tempo de espera para busca do resultado do processamento..... 53
5.6.3. Otimizao na montagem do arquivo................................................. 54
5.6.4.
Validao de Schema.................................................................................... 54
6. EVENTOS ................................................................................................................. 55
6.1. ESTRUTURA DO EVENTO ........................................................................................ 55
6.2. IDENTIFICAO DO EVENTO................................................................................... 59
6.3. ASSINATURA DO EVENTO ....................................................................................... 60
6.4. VERSIONAMENTO DOS LEIAUTES DOS EVENTOS ..................................................... 60
6.5. ESTRUTURA DO RETORNO DE PROCESSAMENTO DO EVENTO .................................. 62
6.6. CDIGOS DE REPOSTA DE PROCESSAMENTO DO EVENTO ........................................ 68
4
1. Introduo
2. Consideraes iniciais
5
2.2. Conceito de evento
6
3. Arquitetura de comunicao
Este arquivo eletrnico dever ser transmitido pela Internet para o Ambiente
Nacional em agrupamentos denominados lote de eventos, que so arquivos eletrnicos que
encapsulam um conjunto de eventos. No Ambiente Nacional, os eventos sero extrados
dos lotes, e submetidos a validaes quanto ao contedo e quanto aos outros eventos
recebidos anteriormente, garantindo a qualidade da informao.
7
O segundo Webservice, cujo propsito a consulta ao resultado do processamento
de um lote de eventos, ter como retorno o andamento/resultado do processamento, assim
como os erros gerados, caso estes existam, e o recibo de entrega de cada um dos eventos
pertencentes ao lote.
8
O andamento/resultado do processamento dos eventos, bem como os erros gerados
pela m formao destes ou pelo processamento dos mesmos, somente podero ser
recuperados pelo responsvel pela solicitao de processamento, ou seja, aquele que enviou
a solicitao de processamento do lote. A recuperao destes dados deve ocorrer atravs de
uma solicitao de consulta ao resultado do processamento de um lote.
9
3.4. Etapas do processo ideal
10
2) O balanceador de carga do eSocial define se o lote ser enviado para o ambiente do
Serpro ou da Caixa;
7) O sistema eSocial valida cada um dos eventos contidos no lote. Os eventos que so
considerados vlidos pelo eSocial so armazenados e um recibo emitido;
11
3.5. Procedimentos de contingncia
12
4. Padres Tcnicos
Cada arquivo XML somente poder ter uma nica declarao <?xml version="1.0"
encoding="UTF-8"?>. Nas situaes em que um documento XML pode conter outros
documentos XML, como ocorre com o documento XML de servios que recebem lote de
eventos, deve-se tomar cuidado para que exista uma nica declarao no incio do
documento.
Caractere Escape
13
(aspas duplas) "
Cada evento XML dever ter uma nica declarao de namespace no elemento raiz
do documento com o seguinte padro:
<eSocial xmlns="http://www.esocial.gov.br/schema/evt">
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<.../>
</Signature>
</eSocial>
14
contedo e de obrigatoriedade de cada elemento ou grupo de informao. Este Schema
XML representado, fisicamente, por um arquivo de extenso XSD.
<soap:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
15
<soap:Header></soap:Header>
</soap:Envelope>
O certificado digital utilizado no sistema eSocial dever ser emitido por Autoridade
Certificadora credenciada pela Infraestrutura de Chaves Pblicas Brasileira ICP-Brasil.
Este dever pertencer srie A. Existem duas sries as quais os certificados podem
pertencer, a srie A e a S. A srie A rene os certificados de assinatura digital utilizados na
confirmao de identidade na Web, em e-mails, em redes privadas virtuais (VPN) e em
documentos eletrnicos com verificao da integridade de suas informaes. A srie S
rene os certificados de sigilo que so utilizados na codificao de documentos, de bases de
dados, de mensagens e de outras informaes eletrnicas sigilosas.
16
2. Assinatura de documentos: para garantir o no repdio e a integridade das
informaes os documentos eletrnicos enviados para o eSocial so assinados
digitalmente seguindo a especificao descrita em 4.5 - Padro de assinatura digital
e as orientaes estabelecidas no "Manual de Orientao do eSocial".
17
8.1. Enveloped (http://www.w3.org/2000/09/xmldsig#enveloped-signature)
<eSocial xmlns="http://www.esocial.gov.br/schema/evt">
<!-- Xml do Evento -->
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-
20010315" />
<SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
<Reference URI="">
<Transforms>
<Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-
signature" />
<Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
<DigestValue>7ZFzmAV6TKTa4fzbAJlFDAL6BZI=</DigestValue>
</Reference>
</SignedInfo>
<SignatureValue>k/.......+FKpYamLYxA==</SignatureValue>
<KeyInfo>
<X509Data>
<X509Certificate>MIIHdzCCBVk......3DP8d2TOROQw==</X509Certificate>
</X509Data>
</KeyInfo>
</Signature>
</eSocial>
18
4.6. Processo de validao de assinatura digital
6) adotar as regras definidas pelo RFC 3280 para as LCR e cadeia de confiana;
19
4.7. Resumo dos padres tcnicos
Caracterstica Descrio
Meio lgico de
Webservice (s) disponibilizado (s) pelo sistema eSocial
comunicao
Meio fsico de
INTERNET
comunicao
Padro de troca de
SOAP verso 1.1
mensagens
20
XML Digital Signature, Enveloped, com certificado digital X.509
verso 3, com chave privada de tamanho varivel, conforme o
Padro de assinatura
padro da ICP-Brasil (1024, 2048, ou mais bits), com padres de
digital
criptografia assimtrica RSA, algoritmo message digest SHA-1 e
utilizao das transformaes Enveloped e C14N.
21
5. Webservices
22
Assim, os aplicativos que fazem solicitaes ao sistema eSocial devem estar
preparados para gerar lotes de eventos no formato definido pelo XSD em vigor.
Namespace:
http://www.esocial.gov.br/schema/lote/eventos/envio/v1_0_0
Nome arquivo:
Os certificados digitais podem ser utilizados tanto nas conexes TLS de transmisso
dos lotes de eventos para o eSocial, quanto para a assinatura dos eventos. Neste caso, os
efeitos da validao podem se dar para todo o lote (no caso do erro ser gerado a partir do
certificado de transmisso) como para um evento especfico (no caso do erro ser gerado a
partir de uma assinatura de um documento XML, enviado ao eSocial, que representa o
evento).
23
Os Certificados Digitais utilizados no acesso aos servios disponibilizados pelo
sistema eSocial e na assinatura dos arquivos XML enviados a este devero atender aos
seguintes critrios:
Rejeio do lote
O certificado no poder estar revogado. MS0150
ou do evento
Rejeio do lote
O certificado no foi encontrado. MS0004
ou do evento
Rejeio do lote
Falha ao acessar a lista de certificados revogados. MS0011
ou do evento
24
Neste Webservice sero as executadas as validaes de nvel 1, conforme descrito
na seo 3.2 - Nveis de Validao.
Cada evento enviado, atravs do lote de eventos, deve ser assinado individualmente
dentro do lote. Alm disso, o lote somente poder conter eventos de um nico empregador
e do mesmo grupo. Caso existam eventos pertencentes a um grupo diferente do informado
no lote, o sistema eSocial ir considera-los rejeitados e no ir processa-los. Os grupos dos
eventos, e os eventos que compem estes, esto listados no "Manual de Orientao do
eSocial".
Sim.
URL A DEFINIR
25
5.4.2. Fluxo de Envio de Lote de Eventos
26
5.4.3. Leiaute Mensagem de Entrada
tag: eSocial
obrigatrio? Sim
ocorrncia nica
27
grupo obrigatrio 1 1 - Eventos Iniciais e de Define o grupo dos
Tabelas eventos contidos no
lote. Durante o
2 - Eventos No Peridicos
processamento
3 - Eventos Peridicos
verificado se o evento
pertence ao grupo
informado no lote, e
caso no seja, o evento
rejeitado.
tag: envioLoteEventos
obrigatrio? Sim
ocorrncia nica
tag: ideEmpregador
obrigatrio? Sim
ocorrncia nica
28
do empregador.
Observaes:
tag: ideTransmissor
obrigatrio? Sim
ocorrncia nica
Observaes:
tag: eventos
29
obrigatrio? Sim
ocorrncia nica
tag: evento
obrigatrio? Sim
ocorrncia 1 .. 50
Observaes:
O contedo do campo evento, deve ser o XML do evento a ser enviado para processamento
no sistema eSocial. Este campo pode ser repetido at 50 vezes, isto quer dizer que o lote de
eventos pode ser composto, no mximo, por 50 eventos.
Existem diferentes estruturas XML, leiautes, para a representao dos eventos recebidos
pelo sistema eSocial. Mais informaes a respeito podem ser obtidas na Seo 6 - Eventos.
30
5.4.4. Leiaute Mensagem de Retorno do Envio do Lote
tag: eSocial
31
obrigatrio? Sim
ocorrncia nica
retornoEnvio/v1_1_0
tag: retornoEnvioLoteEventos
obrigatrio? Sim
ocorrncia nica
tag: ideEmpregador
obrigatrio? No
ocorrncia nica
32
nrInsc obrigatrio 1 - Contm o nmero de inscrio
do empregador.
Observaes:
Esta tag ser preenchida somente quando o lote no apresentar erros de Schema.
tag: ideTransmissor
obrigatrio? No
ocorrncia nica
Observaes:
Esta tag ser preenchida somente quando o lote no apresentar erros de Schema.
33
tag: status
obrigatrio? Sim
ocorrncia nica
34
tag: ocorrencias
obrigatrio? No
ocorrncia nica
tag: ocorrencia
descrio: Contm cada uma das ocorrncias encontradas no lote quando o cdigo
de resposta contido na tag status for diferente de sucesso (cdigo: 201).
ocorrncia 1..*
35
localizacao facultativo 1 - Contm o caminho da tag ou
atributo em que ocorreu o
erro.
tag: dadosRecepcaoLote
descrio: Contm os dados relativos a um lote recebido com sucesso. nesta tag
que est localizado o Protocolo de Envio.
obrigatrio? No
ocorrncia nica
36
formao deste Protocolo:
A.B.NNNNNNNN....N
A = Agente de recepo:
Serpro=1 ou Caixa=2
B = Ambiente de recepo:
1=Produo;
2=Pr-produo - dados reais;
3=Pr-produo - dados
fictcios;
6=Homologao;
7=Validao;
8=Testes;
9=Desenvolvimento;
Observaes:
Esta tag ser preenchida somente quando o lote for recebido com sucesso.
37
5.4.5. Validaes aplicadas
38
5.5. Webservice de Consulta ao Resultado do Processamento de um
Lote de Eventos
Sim.
Observao: Somente quem transmitiu a solicitao de
Requer Certificado de processamento tem acesso ao resultado do processamento.
Cliente? Portanto, necessrio utilizar o mesmo certificado (certificado
com o mesmo nmero de inscrio) da transmisso para acessar o
resultado do processamento do lote.
URL A DEFINIR
39
5.5.2. Fluxo de consulta ao resultado do processamento do lote de eventos
40
5.5.3. Leiaute da Mensagem de Entrada
tag: eSocial
obrigatrio? Sim
ocorrncia nica
tag: consultaLoteEventos
obrigatrio? Sim
ocorrncia nica
41
campo obrigatoriedade ocorrncia valores vlidos descrio
42
5.5.4. Leiaute Mensagem de Retorno do Processamento do Lote
43
tag: eSocial
obrigatrio? Sim
ocorrncia nica
tag: retornoProcessamentoLoteEventos
obrigatrio? Sim
ocorrncia nica
tag: ideEmpregador
obrigatrio? No
ocorrncia nica
44
campo obrigatoriedade ocorrncia valores vlidos descrio
Observaes:
Esta tag somente no ser preenchida quando houver um erro no servidor que impossibilite
a obteno do lote sob consulta.
tag: ideTransmissor
obrigatrio? No
ocorrncia nica
Observaes:
Esta tag somente no ser preenchida quando houver um erro no servidor que impossibilite
a obteno do lote sob consulta.
45
tag: status
obrigatrio? Sim
ocorrncia nica
501 - Solicitao de
Consulta Incorreta -
46
Erro Preenchimento.
502 - Solicitao de
Consulta Incorreta -
Schema Invlido.
503 - Solicitao de
Consulta Incorreta -
Verso do Schema
No Permitida.
504 - Solicitao de
Consulta Incorreta -
Erro Certificado.
505 - Solicitao de
Consulta Incorreta -
Consulta nula ou
vazia.
47
tag: ocorrencias
obrigatrio? No
ocorrncia nica
tag: ocorrencia
descrio: Contm cada uma das ocorrncias encontradas no lote quando o cdigo
de resposta contido na tag status indicar que foram encontrados erros
ou advertncias no lote.
ocorrncia 1..*
48
2 - Advertncia ocorrncia.
tag: dadosRecepcaoLote
obrigatrio? No
ocorrncia nica
Observaes:
Esta tag ser preenchida somente quando a consulta ao lote for realizada com sucesso.
tag: dadosProcessamentoLote
obrigatrio? No
49
ocorrncia nica
Observaes:
Esta tag ser preenchida somente quando a consulta ao lote for realizada com sucesso.
tag: retornoEventos
obrigatrio? No
ocorrncia nica
Observaes:
Esta tag somente ser preenchida quando o campo <cdRespota> contido na tag <status>
contiver o valor maior que 200 e menor que 300.
tag: evento
obrigatrio? No
ocorrncia 1 .. 50
50
campo obrigatoriedade ocorrncia valores vlidos descrio
51
5.5.5. Validaes aplicadas
Rejeio da
Foi identificado um erro na estrutura da solicitao. MS0606
consulta
52
5.6. Recomendaes e boas prticas
53
5.6.3. Otimizao na montagem do arquivo
No dever ser includa a tag de campo com contedo zero (para campos tipo
numrico) ou vazio (para campos tipo caractere) na gerao do arquivo XML para servir de
insumo e de resposta para os servios disponibilizados pelo eSocial. Exceto para os campos
identificados como obrigatrios no modelo, neste caso, dever constar a tag com o valor
correspondente (mesmo que este seja zero ou vazio) e, para os demais campos, devero ser
eliminadas as tags.
Para reduzir o tamanho final do arquivo XML a ser transportado alguns cuidados de
programao devero ser assumidos:
54
6. Eventos
Ex. http://www.esocial.gov.br/schema/evt/evtInfoEmpregador/v1_0_0
55
tag: eSocial
obrigatrio? Sim
ocorrncia nica
56
tag: evtXXX
descrio: Tag que identifica o tipo do evento (O nome dessa tag est presente tambm
no namespace do Xsd da estrutura do evento).
obrigatrio? Sim
ocorrncia nica
tag: ideEvento
obrigatrio? Sim
ocorrncia nica
3=Pr-produo -
dados fictcios;
6=Homologao;
57
7=Validao;
8=Testes;
9=Desenvolvimento;
2 - Aplicativo Web
do ESocial
tag: ideEmpregador
obrigatrio? Sim
ocorrncia nica
tag: infoXXX
58
obrigatrio? Sim
ocorrncia nica
tag: Signature
obrigatrio? Obrigatrio
ocorrncia nica
Observaes:
Cada evento do eSocial possui uma identificao nica, gerada pelo empregador,
conforme o padro abaixo:
59
2 (pos) 1 (pos) 14 (pos) 14 (pos) 5 (pos)
Obs.: O nmero de inscrio deve ser informado com CNPJ completo quando a
natureza jurdica do empregador for igual a 1015, 1040, 1074 e 1163, para as demais
naturezas jurdicas deve ser informado o CNPJ base (8 primeiras posies do CNPJ).
O documento Xml do Evento dever ser assinado com um certificado digital do tipo
e-CPF (e-PF) ou e-CNPJ (e-PJ)., conforme a especificao definida em 4.5 - Padro de
assinatura digital e os critrios estabelecidos no "Manual de Orientao do eSocial".
A assinatura do evento dever ser realizada sobre todo documento Xml e inserida no
local estabelecido no Schema (XSD) de cada tipo de evento, ou seja, no elemento
"Signature".
O versionamento dos leiautes dos eventos ser por tipo de evento. Assim, a
alterao do leiaute de um determinado tipo de evento no afeta a verso dos demais tipos
de eventos.
60
seu perodo de vigncia. A alterao dos valores vlidos ou do conjunto de
regras de um leiaute, sem alterao de sua estrutura, ser realizada atravs da
atualizao do "Manual de Orientao do eSocial", ou seja, no haver alterao
da verso do leiaute.
Para cada tipo de evento haver apenas uma verso de leiaute vigente em um
determinado perodo.
Onde:
61
6.5. Estrutura do retorno de processamento do evento
Para cada evento enviado, o Sistema eSocial gera um documento Xml com
informaes referentes ao processamento do evento. Se o Sistema eSocial no identificar
nenhum erro no evento durante o seu processamento, o evento ser aceito e um nmero de
recibo de entrega ser gerado. O documento de retorno de processamento somente ser
assinado digitalmente se o evento for validado sem erros e aceito pelo eSocial.
62
tag: eSocial
obrigatrio? Sim
ocorrncia nica
tag: retornoEvento
obrigatrio? Sim
ocorrncia nica
tag: ideEmpregador
63
obrigatrio? Sim
ocorrncia nica
tag: recepcao
obrigatrio? Sim
ocorrncia nica
3=Pr-produo -
dados fictcios;
6=Homologao;
7=Validao;
8=Testes;
9=Desenvolvimento;
64
versaoApp obrigatrio 1 - Verso do aplicativo de
recepo do evento.
Recepcao
tag: processamento
obrigatrio? Sim
ocorrncia nica
tag: ocorrencias
65
descrio: Contm as ocorrncias encontradas no evento.
obrigatrio? no
ocorrncia nica
Observaes:
Somente poder existir ocorrncia se o campo cdResposta da Tag status for diferente de
Sucesso (Cdigo 201).
tag: ocorrencia
ocorrncia 1..*
66
tag: recibo
obrigatrio? Facultativo
ocorrncia nica
A.B.CC.NNNNNNNN....N
A = Agente de processamento:
Serpro=1
B = Ambiente de recepo:
1=Produo;
2=Pr-produo - dados reais;
3=Pr-produo - dados
fictcios;
6=Homologao;
7=Validao;
8=Testes;
9=Desenvolvimento;
C = Partio do Empregador
N = Nmero sequencial (19
posies)
Observaes:
A tag recibo somente ser preenchida se o evento estiver vlido para o Sistema eSocial.
67
tag: Signature
obrigatrio? Facultativo
ocorrncia nica
Observaes:
O retorno do evento somente ser assinado caso o Evento esteja vlido para o Sistema
eSocial. O padro de assinatura do documento de retorno est descrito em "Padro de
Assinatura Digital".
Cdigo Descrio
201 Sucesso.
Sucesso
202 Sucesso com advertncia.
Erro 301 Erro Servidor
eSocial
401 Erro no contedo do evento.
402 Schema invlido.
403 Leiaute invlido.
Erro Erro do certificado digital da
404
cliente assinatura do evento.
405 Erro na assinatura evento
Evento no pertence ao grupo
406
especificado no lote de eventos
68