Pular para o conteúdo
notemnotemDocumentação

Referência da API › Certificado

Enviar certificado

Envia ou troca o certificado digital A1 que a empresa usa para assinar as notas.

POST/api/v1/empresas/{id}/certificado

O certificado é necessário para emitir e cancelar notas. Envie o arquivo .pfx ou .p12 (até 100 KB) em base64, com a senha. O CNPJ do certificado precisa ser o da empresa.

O certificado anterior continua valendo até o novo ser aceito, então uma troca recusada não interrompe as emissões. Quando o arquivo é recusado, a resposta 422 diz o motivo: senha errada, certificado vencido, sem chave privada ou de outro CNPJ.

O arquivo e a senha nunca são devolvidos nem registrados.

Parâmetros

idtextono caminhoobrigatório
Empresa da organização da chave (de outra organização → 404). UUID (RFC 9562); fora do padrão → 400 REQUISICAO_INVALIDA com campo id. · UUID
Idempotency-Keytextono cabeçalho
Chave de idempotência (até 100 caracteres) aceita em POST, PATCH, PUT e DELETE; vale 24 h por integração e ambiente, exceto emissão, cancelamento, análise e substituição de notas (associação duradoura ao pedido). Mesmo conteúdo devolve a mesma resposta (cabeçalho Idempotent-Replayed true); conteúdo diferente devolve 409 IDEMPOTENCIA_CONFLITO. Obrigatória em emissão, cancelamento e substituição. · até 100 caracteres

Corpo da requisição

arquivo_base64textoobrigatório
.pfx/.p12 de até 100 KB em base64
senhatextoobrigatório

Respostas

200 Certificado aceito

Campos da resposta
titulartexto
cnpjtexto
CNPJ de 14 posições, numérico ou alfanumérico (12 posições 0-9/A-Z + 2 dígitos verificadores). Na entrada, máscara e minúsculas são aceitas e normalizadas; nas respostas vem sempre com 14 caracteres maiúsculos, sem máscara. · até 18 caracteres
emissortexto
numero_serietexto
valido_detexto
data e hora ISO 8601
valido_atetexto
data e hora ISO 8601
situacaotexto
Valores: valido, vencendo, vencido
dias_para_vencerinteiro

400 Erro no formato padrão

404 Erro no formato padrão

422 CERTIFICADO_SENHA_OU_ARQUIVO_INVALIDO, CERTIFICADO_SEM_CHAVE_PRIVADA, CERTIFICADO_VENCIDO, CERTIFICADO_AINDA_NAO_VALIDO, CERTIFICADO_CNPJ_NAO_ENCONTRADO ou CERTIFICADO_CNPJ_DIVERGENTE

Limites

Esta operação: 3 a cada 10 minutos por chave e 10 por dia por empresa. Valem também os limites gerais da chave. Veja Limites de uso.