Cliente

class pynfse_nacional.client.NFSeClient

Bases: object

Client for NFSe Nacional API with mTLS support.

Uses PKCS12 (.pfx/.p12) certificates for mutual TLS authentication with the NFSe Nacional SEFIN API.

__init__(cert_path, cert_password, ambiente='homologacao', timeout=30.0)

Initialize NFSe client.

Parameters:

  • cert_path (str) – Path to PKCS12 certificate file (.pfx/.p12)

  • cert_password (str) – Certificate password

  • ambiente (str) – API environment (‘homologacao’ or ‘producao’)

  • timeout (float) – HTTP request timeout in seconds

submit_dps(dps)

Submit DPS and receive NFSe.

Parameters:

dps (DPS)

Return type:

NFSeResponse

query_nfse(chave_acesso)

Query NFSe by access key.

Parameters:

chave_acesso (str)

Return type:

NFSeQueryResult

query_nfse_by_dps(id_dps)

Recover an NFSe by DPS identifier, then fetch the full invoice.

Parameters:

id_dps (str)

Return type:

NFSeQueryResult

has_nfse_by_dps(id_dps)

Check whether an NFSe exists for a DPS identifier.

Parameters:

id_dps (str)

Return type:

bool

recover_nfse_by_dps(id_dps)

Recover an NFSe by DPS identifier when submit may have already succeeded.

High-level helper that combines has_nfse_by_dps() and query_nfse_by_dps() for the duplicate / lost-chave_acesso recovery path. Use after submit_dps failed or raised, when SEFIN may still have processed the DPS. Swallows NFSeError failures from the lookup path and wraps XML parse failures into status="error".

See RecoveryOutcome for the possible statuses.

Parameters:

id_dps (str)

Return type:

RecoveryOutcome

download_danfse(chave_acesso)

Download DANFSe PDF from official API.

Note: The official DANFSE API at adn.nfse.gov.br may not be available or may return errors (501, 502, 429). As an alternative, use the local PDF generator helper from pynfse_nacional.pdf_generator when the submit response includes nfse_xml_gzip_b64. That path requires the optional pynfse-nacional[pdf] extra.

Parameters:

chave_acesso (str)

Return type:

bytes

substitute_nfse(chave_acesso_original, new_dps, motivo, codigo_motivo=99)

Substitute an existing NFSe with a new one.

This operation cancels the original NFSe and creates a new one with the updated information. The new NFSe will be linked to the original as a substitution.

Parameters:

  • chave_acesso_original (str) – Access key of the NFSe to be substituted (50 digits)

  • new_dps (DPS) – New DPS with updated information (do not set substituicao field)

  • motivo (str) – Reason for substitution (15-255 characters)

  • codigo_motivo (int) – Reason code (1-99, default 99 for “outros”)

Returns:

NFSeResponse with the new NFSe data

Raises:

  • NFSeAPIError – If the API returns an error

  • ValueError – If the original NFSe cannot be substituted

Return type:

NFSeResponse

Note

  • Substitution must be done within 35 days of the original emission

  • Cannot substitute NFSe where tomador was not identified

  • Cannot change the tomador to a different person/company

cancel_nfse(chave_acesso, reason, codigo_motivo=1, cnpj_prestador='')

Cancel NFSe by access key.

Parameters:

  • chave_acesso (str) – 50-digit NFSe access key.

  • reason (str) – Free-text cancellation reason (max 255 chars).

  • codigo_motivo (int) – Cancellation reason code (1=erro na emissão, 2=serviço não prestado, 4=duplicidade). Default 1.

  • cnpj_prestador (str) – CNPJ of the service provider (14 digits, digits only). Required by SEFIN to identify the cancellation author. Without this, SEFIN returns 404 on the /eventos endpoint.

Returns:

EventResponse with protocolo on success.

Return type:

EventResponse

query_convenio_municipal(codigo_municipio)

Consulta se um municipio tem convenio com o sistema nacional.

Parameters:

codigo_municipio (int) – Codigo IBGE do municipio (7 digitos)

Returns:

ConvenioMunicipal com informacoes do convenio

Raises:

NFSeAPIError – Se ocorrer erro na consulta

Return type:

ConvenioMunicipal

class pynfse_nacional.client.RecoveryOutcome

Bases: object

Outcome of attempting NFSe recovery by DPS identifier.

Returned by NFSeClient.recover_nfse_by_dps() when a DPS submission may have already been processed by SEFIN but the caller did not persist the chave_acesso (e.g. duplicate e0014 response, or a transport failure after SEFIN accepted the DPS).

  • status="success": the NFSe exists remotely; result holds the full invoice data and the caller should persist it.

  • status="processing": the DPS was received but the NFSe has not been emitted yet (SEFIN returned 202 / 404 / 409 on the lookup). The caller should keep the issuance retryable rather than marking it failed.

  • status="error": the lookup itself failed (transport, API, or certificate error); error holds the NFSeError. The caller should surface the original submit error.

property recovered: bool

True when recovery succeeded and result is populated.

__init__(status, result=None, error=None)
Parameters:
Return type:

None