Recursos da API

Certificados

O certificado A1 assina cada evento. Envie uma vez: ele fica cifrado e serve a quantos empregadores você precisar.

Rotas

POST

Enviar o certificado A1 /v1/certificates

Envia o certificado A1 que vai assinar os eventos.

GET

Listar certificados /v1/certificates

Lista os certificados da empresa, com paginação, dos que vencem por último aos que vencem primeiro.

GET

Ver um certificado /v1/certificates/{uuid}

Um certificado com a validade, os dias que faltam para vencer e quantos empregadores o usam.

DELETE

Revogar um certificado /v1/certificates/{uuid}

Apaga o arquivo e a senha.

O objeto

uuid texto

O identificador, usado ao cadastrar o empregador.

holder objeto

O titular: name, document e document_type (CNPJ ou CPF).

issuer · fingerprint texto

A autoridade certificadora e a impressão digital.

valid_from · valid_until data

A validade, em ISO 8601 com fuso.

expires_in_days número

Quantos dias faltam para vencer; negativo depois de vencido.

status texto

ACTIVE ou REVOKED; revoked_at diz quando.

replaced sim/não

true quando outro certificado ativo do mesmo titular vale até depois.

last_used_at · employers_count data · número

Última assinatura e quantos empregadores o usam.

created_at data

Quando foi enviado.

$http = new GuzzleHttp\Client([ 'base_uri' => 'https://integration.enviaesocial.com.br/v1/', 'headers' => ['Authorization' => 'Bearer ' . getenv('ENVIAESOCIAL_KEY')],]); $response = $http->post('certificates', ['multipart' => [ ['name' => 'pfx', 'contents' => fopen('certificado-a1.pfx', 'r')], ['name' => 'password', 'contents' => getenv('CERT_PASSWORD')],]]);

import { openAsBlob } from 'node:fs'; const form = new FormData();form.append('pfx', await openAsBlob('certificado-a1.pfx'), 'certificado-a1.pfx');form.append('password', process.env.CERT_PASSWORD); const res = await fetch('https://integration.enviaesocial.com.br/v1/certificates', { method: 'POST', headers: { Authorization: `Bearer ${process.env.ENVIAESOCIAL_KEY}` }, body: form,});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/certificates", headers=auth, files={"pfx": open("certificado-a1.pfx", "rb")}, data={"password": os.environ["CERT_PASSWORD"]},)data = res.json()["data"]

using var http = new HttpClient { BaseAddress = new Uri("https://integration.enviaesocial.com.br/v1/") };http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("ENVIAESOCIAL_KEY")); using var form = new MultipartFormDataContent();form.Add(new ByteArrayContent(File.ReadAllBytes("certificado-a1.pfx")), "pfx", "certificado-a1.pfx");form.Add(new StringContent(Environment.GetEnvironmentVariable("CERT_PASSWORD")), "password"); var res = await http.PostAsync("certificates", form);var json = await res.Content.ReadAsStringAsync();

{ "status": "success", "message": "certificate_uploaded", "data": { "certificate": { "uuid": "3f2b9c1e-6a47-4d0b-8e15-2c9a7f3b1d60", "holder": { "name": "CONTABIL HORIZONTE LTDA", "document": "11222444000198", "document_type": "CNPJ" }, "issuer": "AC EXEMPLO v5", "fingerprint": "9C:41:7E:0B:22:D8:5F:A3:61:4C:9E:07:B2:13:F8:6D:3A:C5:90:11", "valid_from": "2026-08-14T10:22:31-03:00", "valid_until": "2027-08-14T10:22:31-03:00", "expires_in_days": 301, "status": "ACTIVE", "replaced": false, "revoked_at": null, "last_used_at": null, "employers_count": 0, "created_at": "2026-10-17T14:10:12-03:00" }, "replaced_certificates": [], "relinked_employers_count": 0 }}

{ "status": "error", "message": "validation_error", "data": { "errors": [ { "field": "pfx", "code": "require", "detail": "Envie o arquivo do certificado (.pfx ou .p12)." } ] }}

{ "status": "error", "message": "file_too_large", "data": { "errors": [ { "field": "pfx", "code": "file_too_large", "detail": "O arquivo pode ter até 100 KB." } ] }}

{ "status": "error", "message": "invalid_certificate_file", "data": { "errors": [ { "field": "pfx", "code": "invalid_certificate_file", "detail": "O arquivo não é um certificado A1 (.pfx ou .p12)." } ] }}

{ "status": "error", "message": "invalid_certificate_password", "data": { "errors": [ { "field": "password", "code": "invalid_certificate_password", "detail": "A senha não abre o certificado." } ] }}

{ "status": "error", "message": "certificate_expired", "data": { "errors": [ { "field": null, "code": "certificate_expired", "detail": "O certificado está vencido." } ] }}

{ "status": "error", "message": "certificate_not_yet_valid", "data": { "errors": [ { "field": null, "code": "certificate_not_yet_valid", "detail": "O certificado ainda não começou a valer." } ] }}

{ "status": "error", "message": "certificate_without_document", "data": { "errors": [ { "field": null, "code": "certificate_without_document", "detail": "O certificado não traz CNPJ nem CPF da ICP-Brasil." } ] }}

{ "status": "error", "message": "certificate_not_icp_brasil", "data": { "errors": [ { "field": null, "code": "certificate_not_icp_brasil", "detail": "O certificado não é da ICP-Brasil." } ] }}

{ "status": "error", "message": "certificate_already_exists", "data": { "errors": [ { "field": "pfx", "code": "certificate_already_exists", "detail": "Este certificado já foi enviado." } ] }}

{ "status": "error", "message": "storage_unavailable", "data": { "errors": [ { "field": null, "code": "storage_unavailable", "detail": "O armazenamento está fora do ar: tente de novo em instantes." } ] }}

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