Pular para o conteúdo

Certificado digital A1

Toda NF-e, NFC-e, CT-e, MDF-e e boa parte das NFS-e saem assinadas com o certificado digital da empresa. Com estas rotas, o seu sistema instala o certificado A1 (o arquivo .pfx ou .p12) e acompanha a validade dele, sem ninguém abrir a tela de configuração do FazNota. É útil para cadastrar empresas em lote e para trocar o certificado antes do vencimento.

Desde a versão 3.20.0.

Endpoints

OperaçãoEndpoint
Consultar situação e validade do certificadoGET /certificado
Instalar (ou trocar) o certificado A1POST /certificado/a1

As duas rotas respondem na hora: não há recibo nem polling. A autenticação é a mesma de todas as rotas da v3 (Authorization: Token <chave>). A empresa vem da chave: o certificado é sempre o da empresa dona da chave, e o corpo não aceita CNPJ nem id de empresa.

  1. Converter o arquivo para base64

    O .pfx é binário; a API recebe o conteúdo em base64, no campo arquivo.

    Terminal window
    # Linux
    ARQUIVO=$(base64 -w0 certificado.pfx)
    # macOS
    ARQUIVO=$(base64 -i certificado.pfx | tr -d '\n')

    Aceitamos também o formato data:application/x-pkcs12;base64,... e base64 com quebras de linha.

  2. Instalar

    A senha vem de uma variável de ambiente (não digite na linha de comando: ela fica no histórico do shell). O jq monta o JSON, o que resolve senha com aspas ou barra, e o curl lê o corpo da entrada padrão, sem expor arquivo e senha na lista de processos:

    Terminal window
    read -rs MYSE_PFX_SENHA && export MYSE_PFX_SENHA # digita sem eco
    jq -n --arg arquivo "$ARQUIVO" --arg senha "$MYSE_PFX_SENHA" '{arquivo: $arquivo, senha: $senha}' \
    | curl -X POST $BASE/certificado/a1 \
    -H "Authorization: Token $TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @-

    Resposta:

    {
    "status": "001",
    "descricao": "Certificado A1 instalado. As próximas emissões já saem assinadas com ele.",
    "data": {
    "tipo": "A1",
    "titular": "EMPRESA EXEMPLO LTDA",
    "documento": "12.345.678/0001-99",
    "tipo-documento": "CNPJ",
    "valido-ate": "2027-11-10",
    "dias-para-vencer": 360,
    "situacao": "VALIDO",
    "dt-vencimento-gravada": "2027-11-10",
    "dt-validade": "2027-11-10"
    }
    }

    Com 001, o certificado já está em uso: a próxima emissão sai assinada com ele. A validade vem em valido-ate e também em dt-validade, a mesma chave da consulta.

  3. Consultar quando quiser

    Terminal window
    curl $BASE/certificado -H "Authorization: Token $TOKEN"
    {
    "status": "005",
    "descricao": "Situação do certificado digital da empresa.",
    "data": {
    "tipo": "A1",
    "titular": "EMPRESA EXEMPLO LTDA",
    "cnpj": "12345678000199",
    "dt-validade": "2027-11-10",
    "dias-para-vencer": 360,
    "situacao": "VALIDO",
    "instalado": true
    }
    }

Corpo do POST /certificado/a1

CampoTipoObrigatórioDescrição
arquivostringSimConteúdo do .pfx/.p12 em base64. Até 50 KB de arquivo (um A1 tem de 3 a 15 KB).
senhastringSimA senha do arquivo .pfx. Até 128 caracteres.

Qualquer outro campo é recusado com 400.

O que é conferido antes de gravar

Nada é gravado antes de todas estas travas passarem. São as mesmas regras da tela de upload do FazNota:

  1. O arquivo abre com a senha e tem chave privada e uso de assinatura digital.
  2. O certificado é ICP-Brasil (cadeia até a raiz da ICP-Brasil, não autoassinado).
  3. Está dentro da validade: não venceu e já começou a valer.
  4. O titular é a empresa da chave: CNPJ com a mesma raiz (matriz e filiais usam o mesmo e-CNPJ) ou, para produtor rural e profissional autônomo, o mesmo CPF do cadastro.
  5. Não troca um certificado válido por um que vence antes. Se a empresa já tem um certificado válido até 2027 e você envia um que vence em 2026 (o arquivo antigo, por engano), o atual é mantido e a resposta é 400 explicando as duas datas.

Passando tudo, o FazNota converte o arquivo, grava com segurança, atualiza a data de vencimento (que alimenta os avisos de renovação) e já passa a usar o certificado novo nas emissões.

Situação do certificado

data.situacao no GET /certificado (e no retorno da instalação):

SituaçãoSignificado
VALIDOInstalado e com mais de 30 dias de validade.
A_VENCERInstalado, vence em até 30 dias. Hora de renovar com a certificadora.
VENCIDOPassou da validade (dias-para-vencer negativo). As emissões são recusadas.
NAO_INSTALADOA empresa não tem certificado instalado.
INDISPONIVELInstalado, mas sem data de validade conhecida (caso raro, típico de A3 sem validade registrada). Para um A1, reenvie o arquivo pelo POST /certificado/a1.

tipo é A1 ou A3. O A3 (token ou cartão) não é instalado pela API: ele fica no computador da empresa. A consulta informa a validade dele mesmo assim, quando conhecida. titular e cnpj da consulta são os do cadastro da empresa.

Códigos de status

CódigoCenário
005GET /certificado: consulta feita.
001POST /certificado/a1: certificado instalado e em uso.
400Campo ausente ou inválido (data.campo: arquivo ou senha), senha errada, arquivo que não é um A1 ICP-Brasil, certificado vencido, de outro CNPJ/CPF ou que vence antes do atual. A descricao diz o motivo.
999Falha interna ao falar com o módulo de certificado, ou limite de instalações por minuto atingido (a descricao diz qual). Tente de novo em instantes.

Segurança

  • A senha, a chave privada e o arquivo nunca aparecem na resposta, nos logs nem nas mensagens de erro do FazNota. O registro de uso da API guarda só que houve uma instalação, sem o conteúdo.
  • O certificado só pode ser instalado na empresa da chave, e só se for dela (titular conferido).
  • Não há Idempotency-Key nesta rota: reenviar o mesmo certificado é inofensivo (ele é regravado com a mesma validade).

Boas práticas

  • Monitore a validade. Consulte GET /certificado uma vez por dia e avise o cliente quando situacao virar A_VENCER. Um certificado vencido faz todas as emissões serem recusadas.
  • Troque antes de vencer. Com o certificado novo em mãos, envie pelo POST /certificado/a1: a troca é imediata e o antigo deixa de ser usado.
  • Erro de senha? A descricao diz quando o arquivo não abre com a senha. Peça a senha de novo ao cliente; o arquivo não é gravado.