Certificados

Validação

Não existe uma chamada separada de "validar certificado" -- a validação acontece dentro do próprio upload.

💡

O POST .../certificado-digital abre o arquivo com a senha informada na hora -- se a senha estiver errada ou o arquivo não for um PFX/P12 válido, você recebe 400 imediatamente, antes de qualquer coisa ser salva. Não há um estado intermediário "certificado enviado, aguardando validação".

Checagem além da senha/formato

O upload não faz validação de cadeia de certificação nem checa validade -- um certificado expirado é aceito e salvo normalmente (só falha depois, na hora de assinar de verdade). Pra confirmar que um certificado já cadastrado consegue assinar hoje, use o diagnóstico:

POST https://areacliente.centralfiscal.com.br/v1/diagnosticos/certificado-digital/assinatura

Assina um XML de teste (descartável) com o certificado ativo do contribuinte e confere a assinatura -- o jeito mais direto de saber "esse certificado funciona pra assinar agora", sem precisar emitir um documento fiscal real pra descobrir.

⚠️

Só funciona com API key de homologação -- com chave de produção, 403. Use-o em homologação pra validar o mesmo certificado antes de subir pra produção (o certificado A1 do cliente é o mesmo nos dois ambientes, ver Ambientes).

Corpo da requisição

Campo	Obrigatório	Observação
`contribuinte_id`	Um dos dois	UUID do contribuinte.
`emitente_documento`	Um dos dois	CNPJ/CPF do contribuinte -- alternativa ao `contribuinte_id`.

{
  "ambiente": "HOMOLOGATION",
  "status": "OK",
  "mensagem": "Certificado A1 aberto, XML de diagnostico assinado e assinatura verificada localmente.",
  "certificado": {
    "certificado_digital_id": "7b1e...",
    "tipo": "A1",
    "titular": "CN=CENTRAL FISCAL COMERCIO LTDA:12345678000190, ...",
    "numero_serie": "4F3A9C1B...",
    "valido_de": "2026-02-10T00:00:00-03:00",
    "valido_ate": "2027-02-10T00:00:00-03:00",
    "status": "ACTIVE"
  },
  "contribuinte": {"contribuinte_id": "3d390cff-...", "documento": "12345678000190", "razao_social": "Central Fiscal Comercio Ltda"},
  "assinatura": {
    "algoritmo": "rsa-sha256",
    "digest_sha256": "a1b2c3...",
    "referencia": "diag-...",
    "xml_teste_assinado": true,
    "assinatura_verificada": true,
    "tamanho_xml_assinado": 1842,
    "emitido_em": "2026-08-07T10:00:00-03:00"
  },
  "alertas": [
    "Diagnostico tecnico de homologacao; nao transmite para autorizador.",
    "Nao retorna arquivo, senha, chave privada nem XML assinado."
  ]
}

✅

409 se o contribuinte não tiver certificado ativo -- o mesmo sinal que você já vê na emissão real (*_CERTIFICADO_A1_AUSENTE), só que sem gastar um documento fiscal pra descobrir.