Começar · cinco chamadas

Primeiros passos

Do zero ao primeiro recibo do governo, em cinco chamadas, na Produção Restrita: o ambiente de testes do eSocial. Nada daqui chega à produção.

Antes de começar

Uma conta no portal Para criar a chave de teste.
O certificado A1 O arquivo .pfx e a senha dele.
Um CNPJ ou CPF O empregador que vai aparecer nos testes.

Passo 1 de 5 Crie a chave de teste

No portal, abra Integração e crie uma chave. A de teste começa com es_test_ e manda tudo para a Produção Restrita. Guarde numa variável de ambiente e faça o ping para conferir.
Confira na resposta
- environment RESTRICTED: a chave é de teste.
- company.name A sua empresa no enviaeSocial.
Se der erro
- 401 invalid_api_key A chave está errada, incompleta ou foi revogada.
A chave é de servidor para servidor: nunca coloque no navegador nem no app.

Ver a rota completa
Mande o arquivo .pfx e a senha em multipart/form-data. Ele fica cifrado e a senha não é guardada em texto.
Confira na resposta
- certificate.uuid Guarde: ele vai no próximo passo.
- certificate.valid_until Até quando o certificado vale.
Se der erro
- invalid_certificate_password A senha não abre o arquivo.
- certificate_not_icp_brasil O certificado não é da ICP-Brasil.
Um certificado serve para quantos empregadores você precisar.

Ver a rota completa
Diga o CNPJ ou CPF, o nome e o uuid do certificado que assina por ele.
Confira na resposta
- employer.link_type OWN se o certificado é do empregador; PROXY se é seu.
- employer.uuid O identificador do empregador.
Se der erro
- invalid_document CNPJ ou CPF inválido.
- certificate_not_found O uuid do certificado está errado ou ele foi revogado.
Com PROXY, a procuração do empregador precisa existir no eSocial.

Ver a rota completa
Mande o envelope de cinco campos com o data da admissão. O 202 diz que o JSON passou na conferência e entrou na fila de transmissão.
Confira na resposta
- event.uuid Guarde: é por ele que você acompanha.
- event.status VALIDATED: conferido e na fila.
Se der erro
- 422 validation_error O field de cada erro diz o campo exato do data.
- employer_not_found O employer_document não foi cadastrado.
Use um client_reference seu, como admissao-0042: o reenvio com ele nunca duplica.

Ver a rota completa
Consulte o evento pelo uuid até o governo responder, ou deixe o webhook avisar.
Confira na resposta
- event.status PROCESSED_SUCCESS: o governo aceitou.
- event.receipt O número do recibo do eSocial.
Se der erro
- PROCESSED_ERROR O governo recusou: o motivo está em occurrences.
Em vez de consultar, cadastre um webhook e receba event.processed.

Ver a rota completa

Recibo na mão

Agora é com você

Na produção é igual: troque a chave por uma es_live_. Daqui, os próximos caminhos:

Webhooks Receba o recibo sozinho Catálogo Os campos de cada evento Erros Cada código e como resolver