API de Certificados (Certificates)

Gerencie certificados digitais ICP-Brasil das empresas

Navegação

• ← Voltar para Visão Geral
• Empresas →
• Inscrições Estaduais →
• Inscrições Municipais →

---

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

Autenticação

Todos os endpoints exigem autenticação via API Key: Authorization: <sua_api_key>

→ Saiba como obter sua API Key

---

Upload de Certificado

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

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

{
  "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

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

Exemplo cURL

curl -X POST https://api.nfse.io/v2/companies/company_abc123/certificates \
  -H "Authorization: sk_live_xxx" \
  -F "[email protected]" \
  -F "Password=senha123"

Exemplo 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.

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

{
  "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

{
  "Certificates": []
}

Respostas de Erro

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

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

Exemplo cURL

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.

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

{
  "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

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

Exemplo cURL

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.

Atenção

Este processo é irreversível. A empresa não poderá emitir documentos fiscais até que um novo certificado seja vinculado.

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

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
2. Crie uma Inscrição Municipal para emitir NFS-e → Ver documentação

---

Veja também:

• API de Empresas - Gerenciamento de empresas
• Inscrições Estaduais - Configuração para NF-e/NFC-e
• Inscrições Municipais - Configuração para NFS-e