Ir para o conteúdo
MadNotas
Documentação

Certificado digital

Homologação e produção exigem o certificado e-CNPJ A1 (arquivo .pfx ou .p12) do emitente. Ele assina o XML e abre a conexão segura com a SEFAZ.

Qual certificado

  • A1: arquivo com senha, válido por 1 ano. É o único tipo aceito, porque a emissão acontece no servidor.
  • A3 (token ou cartão) não funciona em emissão por API: a chave privada não sai do dispositivo.
  • O CNPJ do certificado precisa ter a mesma raiz (8 primeiros dígitos) do emitente. Certificado da matriz serve para as filiais.

Pelo painel

Em Notas fiscais › Emitentes, abra o emitente, envie o arquivo e a senha. Ao salvar, a MadNotas lê o certificado e mostra titular, CNPJ e validade. Depois, use Testar conexão para conferir a comunicação com a SEFAZ da UF.

Pela API (software house)

Para cadastrar o certificado dos seus clientes sem passar pelo painel, envie o arquivo em base64. O {id} é o número inteiro do emitente, o mesmo id que POST /emitentes e GET /emitentes devolvem (no exemplo, 45):

PUT /emitentes/{id}/certificado
curl -X PUT "$MADNOTAS_URL/emitentes/45/certificado" \
  -H "Authorization: Bearer $MADNOTAS_CHAVE" \
  -H "Content-Type: application/json" \
  -d "{\"arquivo_base64\": \"$(base64 < certificado.pfx | tr -d '\n')\", \"senha\": \"$PFX_SENHA\"}"

A resposta traz o que foi lido do certificado (titular, CNPJ, validade). Senha errada, CNPJ de outra raiz ou certificado vencido voltam 422 com o motivo. Os nomes exatos dos campos estão na referência de Emitentes.

Depois do certificado, POST /emitentes/{id}/testar-conexao roda um checklist (certificado, cadeia, conexão com o autorizador, status do serviço) e GET /emitentes/{id}/prontidao diz o que ainda falta para emitir em cada ambiente.

Sem certificado válido, nada é gasto. Com chave mn_hom_ ou mn_prod_ e o emitente sem A1 válido (ausente, vencido ou ilegível), a emissão volta 422 certificado_indisponivel antes de reservar número: a numeração da série não anda. POST /nfe/validar já avisa o mesmo. A simulação não usa certificado.

Excluir um emitente (DELETE /emitentes/{id}) responde 200 com o emitente em "ativo": false. Ele não é apagado: deixa de emitir, e as notas, os XMLs e os eventos continuam disponíveis para consulta.

Como o certificado é guardado

  • O arquivo e a senha são criptografados (AES-256-GCM) antes de gravar e só são abertos no momento de assinar ou transmitir.
  • Nunca aparecem em log, resposta da API ou tela: o painel mostra apenas titular, CNPJ, validade e número de série.
  • Ao trocar o certificado, o anterior deixa de ser usado na hora.

Vencimento

A MadNotas avisa por e-mail e pelo webhook emitente.certificado_vencendo 30, 15, 7 e 1 dia antes do vencimento. Com o certificado vencido, a SEFAZ recusa a conexão e a emissão daquele emitente para.

CSC da NFC-e

Para NFC-e, além do certificado, cadastre o CSC (código de segurança do contribuinte) e o seu identificador, obtidos no portal da SEFAZ da UF. Veja o guia da NFC-e.