Certificados digitais (certificates)

client.certificates envia o certificado digital A1 de uma empresa e lista os certificados cadastrados. Usa https://api.nfse.io com a api_key.

Métodos

certificates.upload(company_id, file, password, *, filename=None, options=None) -> Certificate
certificates.list(company_id, *, options=None) -> list[Certificate]

Enviar

file aceita o caminho do arquivo, os bytes ou um arquivo aberto em modo binário:

from pathlib import Path

from nfeio import NfeClient

client = NfeClient()
company_id = "ID_DA_EMPRESA"

cert = client.certificates.upload(company_id, Path("certificado.pfx"), "senha-do-certificado")
print(cert.thumbprint, cert.status, cert.expires_on)

# ou com um arquivo aberto:
with open("certificado.pfx", "rb") as arquivo:
    client.certificates.upload(company_id, arquivo, "senha-do-certificado")

• O arquivo precisa ter entre 1 byte e 1 MiB, e a senha não pode ser vazia. As duas regras são conferidas antes do envio (InvalidParameterError).
• A senha nunca aparece em log, repr ou mensagem de erro, mesmo se a API a ecoar.
• O upload é um POST: não é repetido automaticamente depois de enviado.
• Um arquivo que não é um PFX válido foi recusado pela API com 500, não 400, nos testes do SDK. O erro chega como ServerError e, por ser um POST, com outcome_unknown=True. Confira o arquivo e a senha antes de reenviar e, na dúvida, veja em certificates.list se o certificado entrou.

Consultar validade

from datetime import datetime, timedelta, timezone

from nfeio import NfeClient

client = NfeClient()

daqui_a_30_dias = datetime.now(timezone.utc) + timedelta(days=30)
for cert in client.certificates.list("ID_DA_EMPRESA"):
    if cert.is_expired():
        print(cert.thumbprint, "vencido")
    elif cert.is_expired(at=daqui_a_30_dias):
        print(cert.thumbprint, "vence em menos de 30 dias:", cert.expires_on)
    else:
        print(cert.thumbprint, "válido até", cert.expires_on)

list devolve uma list comum (vazia quando não há certificado). Propriedades de Certificate: thumbprint, tax_id (CNPJ ou CPF do titular, como str), status, provider_type, expires_on (datetime com fuso) e modified_on. is_expired(at=None) compara a validade com o momento informado (agora, em UTC, por padrão); um certificado sem data legível conta como vencido.

Veja também

• Empresas.
• API de certificados digitais e upload do certificado pelo painel.