Documentação da API · v1

Mande o JSON.
O eSocial fica com a gente.

Você manda cada evento em JSON. O enviaeSocial gera o XML do leiaute, assina com o seu certificado A1, transmite ao governo e devolve o recibo por consulta ou webhook.

Atualizada a cada nota técnica do eSocial. Leiaute S-1.3, NT 07/2026, conferida em 21/10/2026. O que mudou

Do zero ao primeiro recibo Chave de teste, certificado, empregador, envio e recibo, tudo na Produção Restrita. Autenticação A chave e o ambiente Os 40 eventos Campo a campo Erros O campo exato e o motivo

Recursos da API

Certificados O A1 que assina os eventos

POST /v1/certificates
GET /v1/certificates
GET /v1/certificates/{uuid}
DELETE /v1/certificates/{uuid}

Empregadores Para quem você transmite

POST /v1/employers
GET /v1/employers
GET /v1/employers/{uuid}
PUT /v1/employers/{uuid}

Envio de eventos Enviar, acompanhar e baixar

POST /v1/events
POST /v1/events/batch
GET /v1/events/{uuid}
GET /v1/events

Webhooks O recibo chega sozinho

POST sua URL
evt event.processed
evt event.failed

O essencial

Uma chave, um ambiente es_test_ vai para a Produção Restrita; es_live_, para a produção.

Assíncrono 202 na hora; o recibo chega por consulta ou webhook.

Reenvio seguro O mesmo client_reference com o mesmo conteúdo volta 200, sem duplicar.

Nomes do leiaute cpftrab ou cpfTrab: as duas grafias valem, e recomendamos minúsculas.

curl -X POST "https://integration.enviaesocial.com.br/v1/events" \ -H "Authorization: Bearer $ENVIAESOCIAL_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "S-2200", "employer_document": "11.222.333/0001-81", "layout": "S-1.3", "client_reference": "admissao-0042", "data": { "indretif": 1, "cpftrab": "41872634036", "nmtrab": "Mariana Alves Peixoto", "sexo": "F", "racacor": 3, "estciv": 1, "grauinstr": "09", "dtnascto": "1994-03-12", "paisnascto": "105", "paisnac": "105", "endereco": { "brasil": { "tplograd": "R", "dsclograd": "das Acácias", "nrlograd": "215", "complemento": "Apto 92", "bairro": "Jardim das Flores", "cep": "01000000", "codmunic": "3550308", "uf": "SP" } }, "dependente": [ { "tpdep": "03", "nmdep": "Helena Alves Peixoto", "dtnascto": "2019-07-08", "cpfdep": "73624918087", "depirrf": "S", "depsf": "S", "inctrab": "N" } ], "contato": { "foneprinc": "11900000000", "emailprinc": "[email protected]" }, "vinculo": { "matricula": "0042", "tpregtrab": 1, "tpregprev": 1, "cadini": "N", "infoceletista": { "dtadm": "2026-10-19", "tpadmissao": 1, "indadmissao": 1, "tpregjor": 1, "natatividade": 1, "cnpjsindcategprof": "34781526000178" }, "infocontrato": { "nmcargo": "Analista de Departamento Pessoal", "cbocargo": "413105", "codcateg": 101, "remuneracao": { "vrsalfx": 4850, "undsalfixo": 5 }, "duracao": { "tpcontr": 1 }, "localtrabgeral": { "tpinsc": "1", "nrinsc": "11222333000181" }, "horcontratual": { "qtdhrssem": 44, "tpjornada": 2, "tmpparc": 0, "hornoturno": "N", "dscjorn": "Segunda a sexta, das 8h às 17h48, com 1h de intervalo" } } } } }'

$http = new GuzzleHttp\Client([ 'base_uri' => 'https://integration.enviaesocial.com.br/v1/', 'headers' => ['Authorization' => 'Bearer ' . getenv('ENVIAESOCIAL_KEY')],]); $response = $http->post('events', ['json' => [ 'type' => 'S-2200', 'employer_document' => '11.222.333/0001-81', 'layout' => 'S-1.3', 'client_reference' => 'admissao-0042', 'data' => [ 'indretif' => 1, 'cpftrab' => '41872634036', 'nmtrab' => 'Mariana Alves Peixoto', 'sexo' => 'F', 'racacor' => 3, 'estciv' => 1, 'grauinstr' => '09', 'dtnascto' => '1994-03-12', 'paisnascto' => '105', 'paisnac' => '105', 'endereco' => [ 'brasil' => [ 'tplograd' => 'R', 'dsclograd' => 'das Acácias', 'nrlograd' => '215', 'complemento' => 'Apto 92', 'bairro' => 'Jardim das Flores', 'cep' => '01000000', 'codmunic' => '3550308', 'uf' => 'SP', ], ], 'dependente' => [ [ 'tpdep' => '03', 'nmdep' => 'Helena Alves Peixoto', 'dtnascto' => '2019-07-08', 'cpfdep' => '73624918087', 'depirrf' => 'S', 'depsf' => 'S', 'inctrab' => 'N', ] ], 'contato' => [ 'foneprinc' => '11900000000', 'emailprinc' => '[email protected]', ], 'vinculo' => [ 'matricula' => '0042', 'tpregtrab' => 1, 'tpregprev' => 1, 'cadini' => 'N', 'infoceletista' => [ 'dtadm' => '2026-10-19', 'tpadmissao' => 1, 'indadmissao' => 1, 'tpregjor' => 1, 'natatividade' => 1, 'cnpjsindcategprof' => '34781526000178', ], 'infocontrato' => [ 'nmcargo' => 'Analista de Departamento Pessoal', 'cbocargo' => '413105', 'codcateg' => 101, 'remuneracao' => [ 'vrsalfx' => 4850, 'undsalfixo' => 5, ], 'duracao' => [ 'tpcontr' => 1, ], 'localtrabgeral' => [ 'tpinsc' => '1', 'nrinsc' => '11222333000181', ], 'horcontratual' => [ 'qtdhrssem' => 44, 'tpjornada' => 2, 'tmpparc' => 0, 'hornoturno' => 'N', 'dscjorn' => 'Segunda a sexta, das 8h às 17h48, com 1h de intervalo', ], ], ], ],]]); $result = json_decode($response->getBody(), true);

const res = await fetch('https://integration.enviaesocial.com.br/v1/events', { method: 'POST', headers: { Authorization: `Bearer ${process.env.ENVIAESOCIAL_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ type: "S-2200", employer_document: "11.222.333/0001-81", layout: "S-1.3", client_reference: "admissao-0042", data: { indretif: 1, cpftrab: "41872634036", nmtrab: "Mariana Alves Peixoto", sexo: "F", racacor: 3, estciv: 1, grauinstr: "09", dtnascto: "1994-03-12", paisnascto: "105", paisnac: "105", endereco: { brasil: { tplograd: "R", dsclograd: "das Acácias", nrlograd: "215", complemento: "Apto 92", bairro: "Jardim das Flores", cep: "01000000", codmunic: "3550308", uf: "SP", }, }, dependente: [ { tpdep: "03", nmdep: "Helena Alves Peixoto", dtnascto: "2019-07-08", cpfdep: "73624918087", depirrf: "S", depsf: "S", inctrab: "N", } ], contato: { foneprinc: "11900000000", emailprinc: "[email protected]", }, vinculo: { matricula: "0042", tpregtrab: 1, tpregprev: 1, cadini: "N", infoceletista: { dtadm: "2026-10-19", tpadmissao: 1, indadmissao: 1, tpregjor: 1, natatividade: 1, cnpjsindcategprof: "34781526000178", }, infocontrato: { nmcargo: "Analista de Departamento Pessoal", cbocargo: "413105", codcateg: 101, remuneracao: { vrsalfx: 4850, undsalfixo: 5, }, duracao: { tpcontr: 1, }, localtrabgeral: { tpinsc: "1", nrinsc: "11222333000181", }, horcontratual: { qtdhrssem: 44, tpjornada: 2, tmpparc: 0, hornoturno: "N", dscjorn: "Segunda a sexta, das 8h às 17h48, com 1h de intervalo", }, }, }, }, }),});const { data } = await res.json();

import osimport requests auth = {"Authorization": f"Bearer {os.environ['ENVIAESOCIAL_KEY']}"} res = requests.post( "https://integration.enviaesocial.com.br/v1/events", headers=auth, json={ "type": "S-2200", "employer_document": "11.222.333/0001-81", "layout": "S-1.3", "client_reference": "admissao-0042", "data": { "indretif": 1, "cpftrab": "41872634036", "nmtrab": "Mariana Alves Peixoto", "sexo": "F", "racacor": 3, "estciv": 1, "grauinstr": "09", "dtnascto": "1994-03-12", "paisnascto": "105", "paisnac": "105", "endereco": { "brasil": { "tplograd": "R", "dsclograd": "das Acácias", "nrlograd": "215", "complemento": "Apto 92", "bairro": "Jardim das Flores", "cep": "01000000", "codmunic": "3550308", "uf": "SP", }, }, "dependente": [ { "tpdep": "03", "nmdep": "Helena Alves Peixoto", "dtnascto": "2019-07-08", "cpfdep": "73624918087", "depirrf": "S", "depsf": "S", "inctrab": "N", } ], "contato": { "foneprinc": "11900000000", "emailprinc": "[email protected]", }, "vinculo": { "matricula": "0042", "tpregtrab": 1, "tpregprev": 1, "cadini": "N", "infoceletista": { "dtadm": "2026-10-19", "tpadmissao": 1, "indadmissao": 1, "tpregjor": 1, "natatividade": 1, "cnpjsindcategprof": "34781526000178", }, "infocontrato": { "nmcargo": "Analista de Departamento Pessoal", "cbocargo": "413105", "codcateg": 101, "remuneracao": { "vrsalfx": 4850, "undsalfixo": 5, }, "duracao": { "tpcontr": 1, }, "localtrabgeral": { "tpinsc": "1", "nrinsc": "11222333000181", }, "horcontratual": { "qtdhrssem": 44, "tpjornada": 2, "tmpparc": 0, "hornoturno": "N", "dscjorn": "Segunda a sexta, das 8h às 17h48, com 1h de intervalo", }, }, }, }, },)data = res.json()["data"]

using System.Text; using var http = new HttpClient { BaseAddress = new Uri("https://integration.enviaesocial.com.br/v1/") };http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("ENVIAESOCIAL_KEY")); var body = """{ "type": "S-2200", "employer_document": "11.222.333/0001-81", "layout": "S-1.3", "client_reference": "admissao-0042", "data": { "indretif": 1, "cpftrab": "41872634036", "nmtrab": "Mariana Alves Peixoto", "sexo": "F", "racacor": 3, "estciv": 1, "grauinstr": "09", "dtnascto": "1994-03-12", "paisnascto": "105", "paisnac": "105", "endereco": { "brasil": { "tplograd": "R", "dsclograd": "das Acácias", "nrlograd": "215", "complemento": "Apto 92", "bairro": "Jardim das Flores", "cep": "01000000", "codmunic": "3550308", "uf": "SP" } }, "dependente": [ { "tpdep": "03", "nmdep": "Helena Alves Peixoto", "dtnascto": "2019-07-08", "cpfdep": "73624918087", "depirrf": "S", "depsf": "S", "inctrab": "N" } ], "contato": { "foneprinc": "11900000000", "emailprinc": "[email protected]" }, "vinculo": { "matricula": "0042", "tpregtrab": 1, "tpregprev": 1, "cadini": "N", "infoceletista": { "dtadm": "2026-10-19", "tpadmissao": 1, "indadmissao": 1, "tpregjor": 1, "natatividade": 1, "cnpjsindcategprof": "34781526000178" }, "infocontrato": { "nmcargo": "Analista de Departamento Pessoal", "cbocargo": "413105", "codcateg": 101, "remuneracao": { "vrsalfx": 4850, "undsalfixo": 5 }, "duracao": { "tpcontr": 1 }, "localtrabgeral": { "tpinsc": "1", "nrinsc": "11222333000181" }, "horcontratual": { "qtdhrssem": 44, "tpjornada": 2, "tmpparc": 0, "hornoturno": "N", "dscjorn": "Segunda a sexta, das 8h às 17h48, com 1h de intervalo" } } } }}"""; var res = await http.PostAsync("events", new StringContent(body, Encoding.UTF8, "application/json"));var json = await res.Content.ReadAsStringAsync();

{ "status": "success", "message": "event_accepted", "data": { "event": { "uuid": "7c1e4f9a-3b2d-4e8f-9a61-0d5c2b8e4f17", "type": "S-2200", "layout": "S-1.3", "client_reference": "admissao-0042", "employer_document": "11222333000181", "status": "VALIDATED", "response_code": null, "protocol": null, "receipt": null, "occurrences": [], "esocial_id": null, "period": null, "worker_cpf": "41872634036", "totalizers": [], "created_at": "2026-10-17T14:32:08-03:00", "updated_at": "2026-10-17T14:32:08-03:00", "processed_at": null } }}

{ "status": "success", "message": "event_already_received", "data": { "event": { "uuid": "7c1e4f9a-3b2d-4e8f-9a61-0d5c2b8e4f17", "type": "S-2200", "layout": "S-1.3", "client_reference": "admissao-0042", "employer_document": "11222333000181", "status": "PROCESSED_SUCCESS", "response_code": "201", "protocol": "1.2.202610.0000000004817233", "receipt": "1.2.0000000048172331", "occurrences": [], "esocial_id": "ID1112223330000002026101714320800001", "period": null, "worker_cpf": "41872634036", "totalizers": [], "created_at": "2026-10-17T14:32:08-03:00", "updated_at": "2026-10-17T14:33:41-03:00", "processed_at": "2026-10-17T14:33:41-03:00" } }}

{ "status": "error", "message": "validation_error", "data": { "errors": [ { "field": "data.cpftrab", "code": "pattern", "detail": "Não corresponde ao padrão ^[0-9]{11}$" }, { "field": "data.vinculo.matricula", "code": "required", "detail": "A propriedade matricula é obrigatória" } ] }}

{ "status": "error", "message": "unsupported_event", "data": { "errors": [ { "field": "type", "code": "unsupported_event", "detail": "Tipo de evento não aceito." } ] }}

{ "status": "error", "message": "unsupported_layout", "data": { "errors": [ { "field": "layout", "code": "unsupported_layout", "detail": "Leiaute não aceito: use S-1.3." } ] }}

{ "status": "error", "message": "employer_not_found", "data": { "errors": [ { "field": "employer_document", "code": "employer_not_found", "detail": "Empregador não cadastrado na empresa." } ] }}

{ "status": "error", "message": "employer_without_certificate", "data": { "errors": [ { "field": null, "code": "employer_without_certificate", "detail": "O empregador não tem certificado válido." } ] }}

{ "status": "error", "message": "client_reference_conflict", "data": { "errors": [ { "field": "client_reference", "code": "client_reference_conflict", "detail": "Este client_reference já foi usado com outro conteúdo." } ] }}

{ "status": "error", "message": "payment_overdue", "data": { "errors": [ { "field": null, "code": "payment_overdue", "detail": "Há uma fatura vencida há 10 dias ou mais: regularize o pagamento para enviar em produção." } ] }}

{ "status": "error", "message": "subscribe_required", "data": { "errors": [ { "field": null, "code": "subscribe_required", "detail": "Você não tem plano ativo e não há mais envios do bônus. Assine um plano para enviar em produção." } ] }}

{ "status": "error", "message": "invalid_api_key", "data": { "errors": [ { "field": null, "code": "invalid_api_key", "detail": "Chave de API ausente, inválida ou revogada." } ] }}