---
title: "API de Certificados Digitais ICP-Brasil | NFE.io | Docs"
description: "Guia completo para gerenciamento de certificados digitais ICP-Brasil (e-CNPJ A1 e NF-e A1) para emissão de documentos fiscais eletrônicos."
source_url: https://nfe.io/docs/documentacao/gerenciamento-empresas/api-certificados
last_updated: 2026-02-06
---

# API de Certificados (Certificates)

## Gerencie certificados digitais ICP-Brasil das empresas

> **Navegação**
> - [← Voltar para Visão Geral](./gerenciamento-empresas-resumo.md)
> - [Empresas →](./gerenciamento-empresas.md)
> - [Inscrições Estaduais →](./gerenciamento-inscricao-estadual.md)
> - [Inscrições Municipais →](./gerenciamento-inscricao-municipal.md)

---

## Visão Geral

O **Certificado Digital ICP-Brasil** funciona como uma identidade eletrônica para empresas, permitindo a identificação segura e inequívoca do autor de uma transação feita em meios eletrônicos.

Para emitir Documentos Fiscais Eletrônicos (NF-e, NFC-e, NFS-e), é **obrigatório** vincular um certificado digital válido à empresa emissora.

---

## Anatomia de um Certificado

### Conceitos Fundamentais

Ao fazer upload de um certificado, você precisa fornecer:

| Conceito | Campos na API | Descrição |
|----------|---------------|-----------|
| **Arquivo** | `File` | Certificado em formato `.pfx` ou `.p12` |
| **Credencial** | `Password` | Senha do certificado para validação |

### Requisitos do Certificado

| Requisito | Descrição |
|-----------|-----------|
| **Tipo** | e-CNPJ A1 ou NF-e A1 (certificados A3 não são suportados) |
| **Formato** | Arquivo `.pfx` ou `.p12` |
| **CNPJ** | Deve corresponder ao `FederalTaxNumber` da empresa |
| **Validade** | Não pode estar expirado |
| **Senha** | Obrigatória para upload e validação |

### Tipos de Certificado

| Tipo | Descrição | Suporte |
|------|-----------|---------|
| **e-CNPJ A1** | Certificado de pessoa jurídica em arquivo | ✅ Suportado |
| **NF-e A1** | Certificado específico para NF-e em arquivo | ✅ Suportado |
| **e-CPF A1** | Certificado de pessoa física | ❌ Não suportado |
| **A3** | Certificado em hardware (token/cartão) | ❌ Não suportado |

### Campos Gerenciados pelo Sistema

Após o upload, o sistema extrai e mantém automaticamente:

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `TaxPayerId` | string | ID da empresa vinculada |
| `Thumbprint` | string | Impressão digital única do certificado |
| `TaxId` | string | CNPJ extraído do certificado |
| `Subject` | string | Nome do certificado (Distinguished Name) |
| `ValidUntil` | datetime | Data de expiração |
| `Status` | enum | Status atual do certificado |
| `ModifiedOn` | datetime | Data da última modificação |

### Referência Completa de Propriedades

### 📋 Expandir tabela completa

| Propriedade | Tipo | Descrição |
|-------------|------|-----------|
| `TaxPayerId` | string | Identificador da empresa (company_id) |
| `Thumbprint` | string | Impressão digital única (hash SHA-1) |
| `TaxId` | string | CNPJ do certificado (somente dígitos) |
| `Subject` | string | Distinguished Name completo do certificado |
| `ValidUntil` | datetime | Data e hora de expiração (UTC) |
| `ModifiedOn` | datetime | Data e hora da última modificação (UTC) |
| `Status` | enum | Status atual: `Active`, `Overdue`, `Inactive`, `Pending`, `None` |

---

## Endpoints

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| `POST` | `/v2/companies/{company_id}/certificates` | Upload de certificado |
| `GET` | `/v2/companies/{company_id}/certificates` | Listar certificados |
| `GET` | `/v2/companies/{company_id}/certificates/{thumbprint}` | Consultar certificado |
| `DELETE` | `/v2/companies/{company_id}/certificates/{thumbprint}` | Excluir certificado |

:::info[Autenticação]
Todos os endpoints exigem autenticação via API Key: `Authorization: <sua_api_key>`

→ **[Saiba como obter sua API Key](https://nfe.io/docs/documentacao/nossa-plataforma/chaves-de-autenticacao/)**
:::

---

## Upload de Certificado

Faz upload de um certificado ICP-Brasil e vincula à empresa.

```http
POST /v2/companies/{company_id}/certificates
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Content-Type` | `multipart/form-data` |
| `Authorization` | `<sua_api_key>` |

### Corpo da Requisição (Form Data)

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `File` | file | ✅ | Arquivo do certificado (.pfx ou .p12) |
| `Password` | string | ✅ | Senha do certificado |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Certificate": {
    "TaxPayerId": "company_abc123",
    "Thumbprint": "A1B2C3D4E5F6789012345678901234567890ABCD",
    "TaxId": "12345678000199",
    "Subject": "CN=ACME TECNOLOGIA LTDA:12345678000199, OU=Secretaria da Receita Federal do Brasil - RFB, O=ICP-Brasil, C=BR",
    "ValidUntil": "2025-06-15T23:59:59Z",
    "ModifiedOn": "2024-01-15T10:30:00Z",
    "Status": "Active"
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Dados inválidos |
| `404 Not Found` | Empresa não encontrada |
| `422 Unprocessable Entity` | Certificado expirado |

```json
{
  "Errors": [
    {
      "Code": 40034,
      "Message": "password is null or empty"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X POST https://api.nfse.io/v2/companies/company_abc123/certificates \
  -H "Authorization: sk_live_xxx" \
  -F "File=@certificado.pfx" \
  -F "Password=senha123"
```

### Exemplo PowerShell

```powershell
$headers = @{ Authorization = "sk_live_xxx" }
$form = @{
    File = Get-Item -Path ".\certificado.pfx"
    Password = "senha123"
}

Invoke-RestMethod -Uri "https://api.nfse.io/v2/companies/company_abc123/certificates" `
    -Method Post -Headers $headers -Form $form
```

---

## Listar Certificados

Lista os certificados vinculados à empresa.

```http
GET /v2/companies/{company_id}/certificates
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Certificates": [
    {
      "TaxPayerId": "company_abc123",
      "Thumbprint": "A1B2C3D4E5F6789012345678901234567890ABCD",
      "TaxId": "12345678000199",
      "Subject": "CN=ACME TECNOLOGIA LTDA:12345678000199, OU=RFB, O=ICP-Brasil, C=BR",
      "ValidUntil": "2025-06-15T23:59:59Z",
      "ModifiedOn": "2024-01-15T10:30:00Z",
      "Status": "Active"
    }
  ]
}
```

### Resposta Quando Não Há Certificado

**Status:** `200 OK`

```json
{
  "Certificates": []
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | company_id inválido |

```json
{
  "Errors": [
    {
      "Message": "company_id is null or empty"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X GET https://api.nfse.io/v2/companies/company_abc123/certificates \
  -H "Authorization: sk_live_xxx"
```

---

## Consultar Certificado por Thumbprint

Retorna os detalhes de um certificado específico.

```http
GET /v2/companies/{company_id}/certificates/{certificate_thumbprint}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `certificate_thumbprint` | string | Impressão digital do certificado |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Certificate": {
    "TaxPayerId": "company_abc123",
    "Thumbprint": "A1B2C3D4E5F6789012345678901234567890ABCD",
    "TaxId": "12345678000199",
    "Subject": "CN=ACME TECNOLOGIA LTDA:12345678000199, OU=RFB, O=ICP-Brasil, C=BR",
    "ValidUntil": "2025-06-15T23:59:59Z",
    "ModifiedOn": "2024-01-15T10:30:00Z",
    "Status": "Active"
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Parâmetros inválidos |
| `404 Not Found` | Certificado não encontrado |

```json
{
  "Errors": [
    {
      "Message": "Certificate not found"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X GET https://api.nfse.io/v2/companies/company_abc123/certificates/A1B2C3D4E5F6789012345678901234567890ABCD \
  -H "Authorization: sk_live_xxx"
```

---

## Excluir Certificado

Exclui um certificado e desvincula da empresa.

:::warning[Atenção]
Este processo é **irreversível**. A empresa não poderá emitir documentos fiscais até que um novo certificado seja vinculado.
:::

```http
DELETE /v2/companies/{company_id}/certificates/{certificate_thumbprint}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `certificate_thumbprint` | string | Impressão digital do certificado |

### Headers

| Header | Valor |
|--------|-------|
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `204 No Content`

(Sem corpo na resposta)

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Parâmetros inválidos |
| `404 Not Found` | Certificado não encontrado |

### Exemplo cURL

```bash
curl -X DELETE https://api.nfse.io/v2/companies/company_abc123/certificates/A1B2C3D4E5F6789012345678901234567890ABCD \
  -H "Authorization: sk_live_xxx"
```

---

## Regras de Validação

O sistema aplica as seguintes regras de validação ao fazer upload de um certificado:

### Validação do Arquivo

| Campo | Regra | Mensagem de Erro |
|-------|-------|------------------|
| `File` | Obrigatório | File is null |
| `File` | Extensão deve ser .pfx ou .p12 | File extension is not valid (.pfx or .p12) |
| `Password` | Obrigatória | password is null or empty |
| `Password` | Deve ser válida para o certificado | Certificate password is invalid |

### Validação do Certificado

| Regra | Mensagem de Erro |
|-------|------------------|
| Dados devem ser válidos | Certificate data is invalid |
| Tipo deve ser e-CNPJ (não e-CPF) | Certificate type is invalid |
| Não pode estar expirado | Certificate expired |
| CNPJ deve corresponder ao da empresa | Certificate or company federal tax number is invalid |

### Validação da Empresa

| Regra | Código | Mensagem de Erro |
|-------|--------|------------------|
| Empresa deve existir | — | companyId not found |
| Empresa deve estar ativa | 40019 | company is not active |
| Empresa deve ter CNPJ cadastrado | 40031 | FederalTaxNumber is null |

---

## Códigos de Erro

### Validação de Arquivo e Certificado

| Mensagem | Descrição |
|----------|-----------|
| File is null | Arquivo não enviado |
| File extension is not valid (.pfx or .p12) | Extensão de arquivo inválida |
| Certificate password is invalid | Senha do certificado incorreta |
| Certificate data is invalid | Dados do certificado inválidos |
| Certificate type is invalid | Tipo não suportado (deve ser e-CNPJ) |
| Certificate expired | Certificado expirado |
| Certificate not found | Certificado não encontrado |
| Certificate or company federal tax number is invalid | CNPJ não corresponde |

### Validação de Empresa

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| — | company_id is null or empty | ID da empresa não informado |
| — | companyId not found | Empresa não encontrada |
| 40019 | company is not active | Empresa inativa |
| 40031 | FederalTaxNumber is null | Empresa sem CNPJ cadastrado |
| 40034 | password is null or empty | Senha não informada |

---

## Enums

### CertificateStatus (Status do Certificado)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Inactive` | -3 | Certificado inativo/excluído |
| `Overdue` | -2 | Certificado vencido |
| `Pending` | -1 | Certificado pendente de validação |
| `None` | 0 | Status não definido |
| `Active` | 1 | Certificado ativo e válido |

### IcpBrasilCertificateType (Tipo de Certificado)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `None` | 0 | Tipo não identificado |
| `eCPF` | 1 | Certificado de Pessoa Física (não suportado) |
| `eCNPJ` | 2 | Certificado de Pessoa Jurídica |

---

## Boas Práticas

### Preparação do Certificado

- Verifique se o tipo é **e-CNPJ A1** ou **NF-e A1**
- Verifique se a validade não está expirada
- Confirme que o CNPJ do certificado corresponde ao da empresa
- Mantenha a senha original em local seguro

### Renovação de Certificado

- Monitore a data de expiração (`ValidUntil`)
- Faça o upload do novo certificado **antes** do vencimento
- O sistema sobrescreve automaticamente o certificado anterior

### Segurança

- Nunca exponha a senha do certificado em logs ou URLs
- Use HTTPS em todas as requisições
- Armazene certificados em local seguro antes do upload
- Não compartilhe o arquivo do certificado

### Monitoramento

Verifique periodicamente o status do certificado:

| Status | Ação Recomendada |
|--------|------------------|
| `Active` | Nenhuma ação necessária |
| `Overdue` | Renovar imediatamente - emissões bloqueadas |
| `Inactive` | Fazer upload de novo certificado |
| `Pending` | Aguardar processamento |

---

## Próximos Passos

Após configurar o certificado:

1. **Crie uma Inscrição Estadual** para emitir NF-e/NFC-e → [Ver documentação](./gerenciamento-inscricao-estadual.md)
2. **Crie uma Inscrição Municipal** para emitir NFS-e → [Ver documentação](./gerenciamento-inscricao-municipal.md)

---

## Veja também:

- [API de Empresas](./gerenciamento-empresas.md) - Gerenciamento de empresas
- [Inscrições Estaduais](./gerenciamento-inscricao-estadual.md) - Configuração para NF-e/NFC-e
- [Inscrições Municipais](./gerenciamento-inscricao-municipal.md) - Configuração para NFS-e