Notas Fiscais (NF-e)

Nas respostas de leitura, contato.tipo_pessoa e contato.contribuinte podem estar ausentes. O OpenAPI do Bling marca tipoPessoa e contribuinte como writeOnly: sua obrigatoriedade aplica-se à requisição, conforme a especificação OpenAPI 3.0. O SDK usa NotasFiscaisContatoResponseDTO nessas respostas, preserva os valores quando presentes e representa a ausência como None. to_json_object() omite esses campos ausentes; não preenche valores fiscais por conta própria.

Essa distinção também vale para a listagem, a paginação e as leituras de NFC-e que reutilizam o mesmo schema. NotasFiscaisContatoDTO e os modelos de criação e alteração continuam exigindo ambos os campos. Os métodos públicos e seus aliases mantêm as assinaturas; o tipo do contato retornado passa a ser a variante de resposta. nome e numero_documento continuam obrigatórios, e os aliases e a rejeição de chaves conflitantes permanecem ativos.

A geração faz essa projeção numa cópia temporária do OpenAPI, sem alterar specs/bling-openapi-reference.json. A revisão de campos writeOnly obrigatórios do schema versionado identificou somente esses dois campos; os demais campos writeOnly já eram opcionais nas respostas. Contratos de outros recursos e todos os request bodies são preservados por testes de regressão.

A projeção também percorre schemas inline aninhados (composições, itens de arrays e propriedades), componentes reutilizáveis de resposta e respostas de callbacks. As exigências são removidas somente no objeto que declara o campo; os objetos pais, exemplos e componentes requestBodies permanecem intactos.

bling_erp_api.resources.nfe.NfeResource

NfeResource(transport: Transport)

Bases: BaseResource

Operações de notas fiscais eletrônicas (NF-e).

Este recurso mapeia os endpoints /nfe. Os métodos canônicos usam português para acompanhar a documentação oficial; os métodos em inglês continuam disponíveis como aliases de compatibilidade.

Para NFC-e use NfceResource (client.notas_fiscais_consumidor).

Source code in src/bling_erp_api/resources/base.py

def __init__(self, transport: Transport) -> None:
    """Create a resource bound to a transport."""
    self._transport = transport

listar

listar(
    *,
    pagina: int | None = None,
    limite: int | None = None,
    numero_loja: int | None = None,
    id_transportador: int | None = None,
    chave_acesso: str | None = None,
    numero: str | None = None,
    serie: str | None = None,
    situacao: int | None = None,
    tipo: int | None = None,
    data_emissao_inicial: str | None = None,
    data_emissao_final: str | None = None,
) -> NfeGetResponse200

Lista notas fiscais eletrônicas (NF-e).

Endpoint: GET /nfe

Obtém lista paginada de NF-e.

Parameters:

Name	Type	Description	Default
pagina	int | None	N° da página (Bling: pagina, integer, opcional)	None
limite	int | None	Registros por página (Bling: limite, integer, opcional)	None
numero_loja	int | None	N° da loja (Bling: numeroLoja, integer, opcional)	None
id_transportador	int | None	ID do transportador (Bling: idTransportador, integer, opcional)	None
chave_acesso	str | None	Chave de acesso da NF-e (Bling: chaveAcesso, string, opcional)	None
numero	str | None	N° da nota fiscal (Bling: numero, string, opcional)	None
serie	str | None	Série da nota fiscal (Bling: serie, string, opcional)	None
situacao	int | None	Situação (Bling: situacao, integer, opcional)	None
tipo	int | None	Tipo (Bling: tipo, integer, opcional)	None
data_emissao_inicial	str | None	Data de emissão inicial (Bling: dataEmissaoInicial, string, opcional)	None
data_emissao_final	str | None	Data de emissão final (Bling: dataEmissaoFinal, string, opcional)	None

Returns:

Type	Description
NfeGetResponse200	Bling API response. Response schemas: 200: NotasFiscaisDadosBaseDTO; 404: ErrorResponse

Source code in src/bling_erp_api/resources/nfe.py

def listar(  # noqa: PLR0913
    self,
    *,
    pagina: int | None = None,
    limite: int | None = None,
    numero_loja: int | None = None,
    id_transportador: int | None = None,
    chave_acesso: str | None = None,
    numero: str | None = None,
    serie: str | None = None,
    situacao: int | None = None,
    tipo: int | None = None,
    data_emissao_inicial: str | None = None,
    data_emissao_final: str | None = None,
) -> NfeGetResponse200:
    """Lista notas fiscais eletrônicas (NF-e).

    Endpoint: GET /nfe

    Obtém lista paginada de NF-e.

    Args:
        pagina: N° da página (Bling: ``pagina``, integer, opcional)
        limite: Registros por página (Bling: ``limite``, integer, opcional)
        numero_loja: N° da loja (Bling: ``numeroLoja``, integer, opcional)
        id_transportador: ID do transportador (Bling: ``idTransportador``, integer, opcional)
        chave_acesso: Chave de acesso da NF-e (Bling: ``chaveAcesso``, string, opcional)
        numero: N° da nota fiscal (Bling: ``numero``, string, opcional)
        serie: Série da nota fiscal (Bling: ``serie``, string, opcional)
        situacao: Situação (Bling: ``situacao``, integer, opcional)
        tipo: Tipo (Bling: ``tipo``, integer, opcional)
        data_emissao_inicial: Data de emissão inicial (Bling: ``dataEmissaoInicial``, string, opcional)
        data_emissao_final: Data de emissão final (Bling: ``dataEmissaoFinal``, string, opcional)

    Returns:
        Bling API response. Response schemas: 200: NotasFiscaisDadosBaseDTO; 404: ErrorResponse
    """
    raw = self._get(
        "/nfe",
        params=_nfe_list_params(
            pagina=pagina,
            limite=limite,
            numero_loja=numero_loja,
            id_transportador=id_transportador,
            chave_acesso=chave_acesso,
            numero=numero,
            serie=serie,
            situacao=situacao,
            tipo=tipo,
            data_emissao_inicial=data_emissao_inicial,
            data_emissao_final=data_emissao_final,
        ),
    )
    return self._validate_response(NfeGetResponse200, raw)

iterar

iterar(
    *,
    pagina: int | None = None,
    limite: int | None = None,
    numero_loja: int | None = None,
    id_transportador: int | None = None,
    chave_acesso: str | None = None,
    numero: str | None = None,
    serie: str | None = None,
    situacao: int | None = None,
    tipo: int | None = None,
    data_emissao_inicial: str | None = None,
    data_emissao_final: str | None = None,
) -> Iterator[JsonObject]

Itera pelas NF-e página a página.

Endpoint: GET /nfe (via paginação automática)

Aceita os mesmos filtros de listar() e busca novas páginas enquanto o Bling retornar registros no envelope data.

Parameters:

Name	Type	Description	Default
pagina	int | None	N° da página (Bling: pagina, integer, opcional)	None
limite	int | None	Registros por página (Bling: limite, integer, opcional)	None
numero_loja	int | None	N° da loja (Bling: numeroLoja, integer, opcional)	None
id_transportador	int | None	ID do transportador (Bling: idTransportador, integer, opcional)	None
chave_acesso	str | None	Chave de acesso da NF-e (Bling: chaveAcesso, string, opcional)	None
numero	str | None	N° da nota fiscal (Bling: numero, string, opcional)	None
serie	str | None	Série da nota fiscal (Bling: serie, string, opcional)	None
situacao	int | None	Situação (Bling: situacao, integer, opcional)	None
tipo	int | None	Tipo (Bling: tipo, integer, opcional)	None
data_emissao_inicial	str | None	Data de emissão inicial (Bling: dataEmissaoInicial, string, opcional)	None
data_emissao_final	str | None	Data de emissão final (Bling: dataEmissaoFinal, string, opcional)	None

Returns:

Type	Description
Iterator[JsonObject]	Iterator sobre os itens da resposta.

Source code in src/bling_erp_api/resources/nfe.py

def iterar(  # noqa: PLR0913
    self,
    *,
    pagina: int | None = None,
    limite: int | None = None,
    numero_loja: int | None = None,
    id_transportador: int | None = None,
    chave_acesso: str | None = None,
    numero: str | None = None,
    serie: str | None = None,
    situacao: int | None = None,
    tipo: int | None = None,
    data_emissao_inicial: str | None = None,
    data_emissao_final: str | None = None,
) -> Iterator[JsonObject]:
    """Itera pelas NF-e página a página.

    Endpoint: GET /nfe (via paginação automática)

    Aceita os mesmos filtros de ``listar()`` e busca novas páginas enquanto
    o Bling retornar registros no envelope ``data``.

    Args:
        pagina: N° da página (Bling: ``pagina``, integer, opcional)
        limite: Registros por página (Bling: ``limite``, integer, opcional)
        numero_loja: N° da loja (Bling: ``numeroLoja``, integer, opcional)
        id_transportador: ID do transportador (Bling: ``idTransportador``, integer, opcional)
        chave_acesso: Chave de acesso da NF-e (Bling: ``chaveAcesso``, string, opcional)
        numero: N° da nota fiscal (Bling: ``numero``, string, opcional)
        serie: Série da nota fiscal (Bling: ``serie``, string, opcional)
        situacao: Situação (Bling: ``situacao``, integer, opcional)
        tipo: Tipo (Bling: ``tipo``, integer, opcional)
        data_emissao_inicial: Data de emissão inicial (Bling: ``dataEmissaoInicial``, string, opcional)
        data_emissao_final: Data de emissão final (Bling: ``dataEmissaoFinal``, string, opcional)

    Returns:
        Iterator sobre os itens da resposta.
    """
    params = _nfe_list_params(
        pagina=pagina,
        limite=limite,
        numero_loja=numero_loja,
        id_transportador=id_transportador,
        chave_acesso=chave_acesso,
        numero=numero,
        serie=serie,
        situacao=situacao,
        tipo=tipo,
        data_emissao_inicial=data_emissao_inicial,
        data_emissao_final=data_emissao_final,
    )
    return self._iterate("/nfe", page=pagina or 1, limit=limite or 100, params=params)

obter

obter(id_nota_fiscal: int) -> NfeIdNotaFiscalGetResponse200

Obtém uma NF-e.

Endpoint: GET /nfe/{idNotaFiscal}

Obtém uma nota fiscal eletrônica pelo ID.

Parameters:

Name	Type	Description	Default
id_nota_fiscal	int	ID da nota fiscal (Bling: idNotaFiscal, integer, obrigatório)	required

Returns:

Type	Description
NfeIdNotaFiscalGetResponse200	Bling API response. Response schemas: 200: NotasFiscaisDadosGetDTO; 404: ErrorResponse

Source code in src/bling_erp_api/resources/nfe.py

def obter(self, id_nota_fiscal: int) -> NfeIdNotaFiscalGetResponse200:
    """Obtém uma NF-e.

    Endpoint: GET /nfe/{idNotaFiscal}

    Obtém uma nota fiscal eletrônica pelo ID.

    Args:
        id_nota_fiscal: ID da nota fiscal (Bling: ``idNotaFiscal``, integer, obrigatório)

    Returns:
        Bling API response. Response schemas: 200: NotasFiscaisDadosGetDTO; 404: ErrorResponse
    """
    raw = self._get(f"/nfe/{id_nota_fiscal}")
    return self._validate_response(NfeIdNotaFiscalGetResponse200, raw)

criar

criar(dados: NfePostRequest) -> NfePostResponse201

Cria uma NF-e.

Endpoint: POST /nfe

Cria uma nova nota fiscal eletrônica.

Parameters:

Name	Type	Description	Default
dados	NfePostRequest	Dados da NF-e. Request body schema: NotasFiscaisDadosPostDTO	required

Returns:

Type	Description
NfePostResponse201	Bling API response. Response schemas: 201: BasePostResponse; 400: ErrorResponse

Source code in src/bling_erp_api/resources/nfe.py

def criar(self, dados: NfePostRequest) -> NfePostResponse201:
    """Cria uma NF-e.

    Endpoint: POST /nfe

    Cria uma nova nota fiscal eletrônica.

    Args:
        dados: Dados da NF-e. Request body schema: NotasFiscaisDadosPostDTO

    Returns:
        Bling API response. Response schemas: 201: BasePostResponse; 400: ErrorResponse
    """
    raw = self._post("/nfe", json=to_json_object(dados))
    return self._validate_response(NfePostResponse201, raw)

alterar

alterar(
    id_nota_fiscal: int, dados: NfeIdNotaFiscalPutRequest
) -> NfeIdNotaFiscalPutResponse200

Altera uma NF-e.

Endpoint: PUT /nfe/{idNotaFiscal}

Altera uma nota fiscal eletrônica pelo ID.

Parameters:

Name	Type	Description	Default
id_nota_fiscal	int	ID da nota fiscal (Bling: idNotaFiscal, integer, obrigatório)	required
dados	NfeIdNotaFiscalPutRequest	Dados da NF-e para atualização. Request body schema: NotasFiscaisDadosPostDTO	required

Returns:

Type	Description
NfeIdNotaFiscalPutResponse200	Bling API response. Response schemas: 200: NotasFiscaisDadosGetDTO; 400: ErrorResponse; 404: ErrorResponse

Source code in src/bling_erp_api/resources/nfe.py

def alterar(
    self, id_nota_fiscal: int, dados: NfeIdNotaFiscalPutRequest
) -> NfeIdNotaFiscalPutResponse200:
    """Altera uma NF-e.

    Endpoint: PUT /nfe/{idNotaFiscal}

    Altera uma nota fiscal eletrônica pelo ID.

    Args:
        id_nota_fiscal: ID da nota fiscal (Bling: ``idNotaFiscal``, integer, obrigatório)
        dados: Dados da NF-e para atualização. Request body schema: NotasFiscaisDadosPostDTO

    Returns:
        Bling API response. Response schemas: 200: NotasFiscaisDadosGetDTO; 400: ErrorResponse; 404: ErrorResponse
    """
    raw = self._put(f"/nfe/{id_nota_fiscal}", json=to_json_object(dados))
    return self._validate_response(NfeIdNotaFiscalPutResponse200, raw)

remover_varios

remover_varios(ids_notas: Sequence[int]) -> NfeDeleteResponse200

Remove múltiplas NF-e.

Endpoint: DELETE /nfe

Remove múltiplas notas fiscais eletrônicas pelos IDs.

Parameters:

Name	Type	Description	Default
ids_notas	Sequence[int]	IDs das notas fiscais (Bling: idsNotas[], array, obrigatório)	required

Returns:

Type	Description
NfeDeleteResponse200	Bling API response. Response schemas: 200: NotasFiscaisExclusaoDTO; 204: NoContent; 400: ErrorResponse

Source code in src/bling_erp_api/resources/nfe.py

def remover_varios(self, ids_notas: Sequence[int]) -> NfeDeleteResponse200:
    """Remove múltiplas NF-e.

    Endpoint: DELETE /nfe

    Remove múltiplas notas fiscais eletrônicas pelos IDs.

    Args:
        ids_notas: IDs das notas fiscais (Bling: ``idsNotas[]``, array, obrigatório)

    Returns:
        Bling API response. Response schemas: 200: NotasFiscaisExclusaoDTO; 204: NoContent; 400: ErrorResponse
    """
    raw = self._delete("/nfe", params={"idsNotas[]": list(ids_notas)})
    return self._validate_response(NfeDeleteResponse200, raw)

autorizar

autorizar(
    id_nota_fiscal: int, *, enviar_email: bool | None = None
) -> NfeIdNotaFiscalEnviarPostResponse200

Autoriza (envia para a SEFAZ) uma NF-e.

Endpoint: POST /nfe/{idNotaFiscal}/enviar

Envia uma NF-e para autorização da SEFAZ.

Parameters:

Name	Type	Description	Default
id_nota_fiscal	int	ID da nota fiscal (Bling: idNotaFiscal, integer, obrigatório)	required
enviar_email	bool | None	Enviar e-mail após autorização (Bling: enviarEmail, boolean, opcional)	None

Returns:

Type	Description
NfeIdNotaFiscalEnviarPostResponse200	Bling API response. Response schemas: 200: NotasFiscaisDadosGetDTO; 400: ErrorResponse; 404: ErrorResponse

Source code in src/bling_erp_api/resources/nfe.py

def autorizar(
    self, id_nota_fiscal: int, *, enviar_email: bool | None = None
) -> NfeIdNotaFiscalEnviarPostResponse200:
    """Autoriza (envia para a SEFAZ) uma NF-e.

    Endpoint: POST /nfe/{idNotaFiscal}/enviar

    Envia uma NF-e para autorização da SEFAZ.

    Args:
        id_nota_fiscal: ID da nota fiscal (Bling: ``idNotaFiscal``, integer, obrigatório)
        enviar_email: Enviar e-mail após autorização (Bling: ``enviarEmail``, boolean, opcional)

    Returns:
        Bling API response. Response schemas: 200: NotasFiscaisDadosGetDTO; 400: ErrorResponse; 404: ErrorResponse
    """
    params = compact_params({"enviarEmail": enviar_email})
    raw = self._post(f"/nfe/{id_nota_fiscal}/enviar", params=params)
    return self._validate_response(NfeIdNotaFiscalEnviarPostResponse200, raw)

lancar_contas

lancar_contas(id_nota_fiscal: int) -> JsonObject

Lança as contas de uma NF-e.

Endpoint: POST /nfe/{idNotaFiscal}/lancar-contas

Lança as contas a pagar/receber geradas a partir de uma NF-e.

Parameters:

Name	Type	Description	Default
id_nota_fiscal	int	ID da nota fiscal (Bling: idNotaFiscal, integer, obrigatório)	required

Returns:

Type	Description
JsonObject	Bling API response. Response schemas: 204: NoContent; 400: ErrorResponse; 404: ErrorResponse

Source code in src/bling_erp_api/resources/nfe.py

def lancar_contas(self, id_nota_fiscal: int) -> JsonObject:
    """Lança as contas de uma NF-e.

    Endpoint: POST /nfe/{idNotaFiscal}/lancar-contas

    Lança as contas a pagar/receber geradas a partir de uma NF-e.

    Args:
        id_nota_fiscal: ID da nota fiscal (Bling: ``idNotaFiscal``, integer, obrigatório)

    Returns:
        Bling API response. Response schemas: 204: NoContent; 400: ErrorResponse; 404: ErrorResponse
    """
    return self._post(f"/nfe/{id_nota_fiscal}/lancar-contas")

estornar_contas

estornar_contas(id_nota_fiscal: int) -> JsonObject

Estorna as contas de uma NF-e.

Endpoint: POST /nfe/{idNotaFiscal}/estornar-contas

Estorna as contas a pagar/receber vinculadas a uma NF-e.

Parameters:

Name	Type	Description	Default
id_nota_fiscal	int	ID da nota fiscal (Bling: idNotaFiscal, integer, obrigatório)	required

Returns:

Type	Description
JsonObject	Bling API response. Response schemas: 204: NoContent; 400: ErrorResponse; 404: ErrorResponse

Source code in src/bling_erp_api/resources/nfe.py

def estornar_contas(self, id_nota_fiscal: int) -> JsonObject:
    """Estorna as contas de uma NF-e.

    Endpoint: POST /nfe/{idNotaFiscal}/estornar-contas

    Estorna as contas a pagar/receber vinculadas a uma NF-e.

    Args:
        id_nota_fiscal: ID da nota fiscal (Bling: ``idNotaFiscal``, integer, obrigatório)

    Returns:
        Bling API response. Response schemas: 204: NoContent; 400: ErrorResponse; 404: ErrorResponse
    """
    return self._post(f"/nfe/{id_nota_fiscal}/estornar-contas")

lancar_estoque

lancar_estoque(
    id_nota_fiscal: int, *, id_deposito: int | None = None
) -> JsonObject

Lança o estoque de uma NF-e.

Endpoint: POST /nfe/{idNotaFiscal}/lancar-estoque[/{idDeposito}]

Lança o estoque de uma NF-e, opcionalmente em um depósito específico.

Parameters:

Name	Type	Description	Default
id_nota_fiscal	int	ID da nota fiscal (Bling: idNotaFiscal, integer, obrigatório)	required
id_deposito	int | None	ID do depósito (Bling: idDeposito, integer, opcional). Se omitido, usa o depósito padrão.	None

Returns:

Type	Description
JsonObject	Bling API response. Response schemas: 204: NoContent; 400: ErrorResponse; 404: ErrorResponse

Source code in src/bling_erp_api/resources/nfe.py

def lancar_estoque(self, id_nota_fiscal: int, *, id_deposito: int | None = None) -> JsonObject:
    """Lança o estoque de uma NF-e.

    Endpoint: POST /nfe/{idNotaFiscal}/lancar-estoque[/{idDeposito}]

    Lança o estoque de uma NF-e, opcionalmente em um depósito específico.

    Args:
        id_nota_fiscal: ID da nota fiscal (Bling: ``idNotaFiscal``, integer, obrigatório)
        id_deposito: ID do depósito (Bling: ``idDeposito``, integer, opcional). Se
            omitido, usa o depósito padrão.

    Returns:
        Bling API response. Response schemas: 204: NoContent; 400: ErrorResponse; 404: ErrorResponse
    """
    if id_deposito is not None:
        return self._post(f"/nfe/{id_nota_fiscal}/lancar-estoque/{id_deposito}")
    return self._post(f"/nfe/{id_nota_fiscal}/lancar-estoque")

estornar_estoque

estornar_estoque(id_nota_fiscal: int) -> JsonObject

Estorna o estoque de uma NF-e.

Endpoint: POST /nfe/{idNotaFiscal}/estornar-estoque

Estorna o estoque lançado de uma NF-e.

Parameters:

Name	Type	Description	Default
id_nota_fiscal	int	ID da nota fiscal (Bling: idNotaFiscal, integer, obrigatório)	required

Returns:

Type	Description
JsonObject	Bling API response. Response schemas: 204: NoContent; 404: ErrorResponse

Source code in src/bling_erp_api/resources/nfe.py

def estornar_estoque(self, id_nota_fiscal: int) -> JsonObject:
    """Estorna o estoque de uma NF-e.

    Endpoint: POST /nfe/{idNotaFiscal}/estornar-estoque

    Estorna o estoque lançado de uma NF-e.

    Args:
        id_nota_fiscal: ID da nota fiscal (Bling: ``idNotaFiscal``, integer, obrigatório)

    Returns:
        Bling API response. Response schemas: 204: NoContent; 404: ErrorResponse
    """
    return self._post(f"/nfe/{id_nota_fiscal}/estornar-estoque")

obter_documento_nota_fiscal

obter_documento_nota_fiscal(
    chave_acesso: str, *, formato: str | None = None
) -> NfeDocumentoChaveAcessoGetResponse200

Obtém o documento (XML/DANFE) de uma NF-e.

Endpoint: GET /nfe/documento/{chaveAcesso}

Obtém o documento de uma NF-e pela chave de acesso.

Parameters:

Name	Type	Description	Default
chave_acesso	str	Chave de acesso da NF-e (Bling: chaveAcesso, string, obrigatório)	required
formato	str | None	Formato do documento: pdf ou xml (Bling: formato, string, opcional)	None

Returns:

Type	Description
NfeDocumentoChaveAcessoGetResponse200	Bling API response. Response schemas: 200: NotasFiscaisDocumentoDTO; 400: ErrorResponse; 404: ErrorResponse

Source code in src/bling_erp_api/resources/nfe.py

def obter_documento_nota_fiscal(
    self, chave_acesso: str, *, formato: str | None = None
) -> NfeDocumentoChaveAcessoGetResponse200:
    """Obtém o documento (XML/DANFE) de uma NF-e.

    Endpoint: GET /nfe/documento/{chaveAcesso}

    Obtém o documento de uma NF-e pela chave de acesso.

    Args:
        chave_acesso: Chave de acesso da NF-e (Bling: ``chaveAcesso``, string, obrigatório)
        formato: Formato do documento: pdf ou xml (Bling: ``formato``, string, opcional)

    Returns:
        Bling API response. Response schemas: 200: NotasFiscaisDocumentoDTO; 400: ErrorResponse; 404: ErrorResponse
    """
    params = compact_params({"formato": formato})
    raw = self._get(f"/nfe/documento/{chave_acesso}", params=params)
    return self._validate_response(NfeDocumentoChaveAcessoGetResponse200, raw)