Skip to content
API/
Notas fiscais
/
/
Retornar notas fiscais de...

Notas fiscais (v1)

A API de Notas Fiscais (v1) tem como objetivo permitir a consulta de documentos fiscais de forma programática. No momento, o suporte disponível é apenas para consulta de notas de produto NF-e emitidas no ERP, permitindo que sistemas externos recuperem informações fiscais, validem dados e integrem essas notas aos seus próprios fluxos.

Essa API possibilita acessar detalhes das notas já emitidas, acompanhar informações essenciais para controle fiscal e garantir maior eficiência na integração entre sistemas.

Se desejar aprofundar o entendimento das regras de negócio aplicadas pelo ERP, recomendamos, de forma opcional a consulta à nossa Central de Ajuda:

https://ajuda.contaazul.com/hc/pt-br/articles/4424707438605-Como-acessar-notas-fiscais-emitidas-na-Conta-Azul

Download OpenAPI description
open-api-invoice.json
open-api-invoice.yaml
Overview
Languages
Servers
https://api-v2.contaazul.com
Mock server
https://developers.contaazul.com/_mock/open-api-docs/open-api-invoice

v1

Operações relacionadas a notas fiscais

Operations

Retornar as notas fiscais por filtro

Request

Permite consultar todas as notas fiscais de produto (NFe) já emitidas no ERP, com suporte a filtros como data, número da nota, id da venda.. Este endpoint retorna somente NFe com status EMITIDA e CORRIGIDA COM SUCESSO (outros status em construção). Essa funcionalidade facilita o monitoramento fiscal, exportação para relatórios ou integração com contabilidade.

Security
BearerAuth
Query
data_inicialstringrequired

Data inicial no formato YYYY-MM-DD

data_finalstringrequired

Data final no formato YYYY-MM-DD

paginainteger

Página

Default 1
tamanho_paginainteger

Tamanho da página

Default 10
Enum102050100
documento_tomadorstring

Documento do tomador

Example: documento_tomador=12345678900
numero_notastring

Número da nota fiscal

Example: numero_nota=1234
id_vendastring

ID da venda

Example: id_venda=550e8400-e29b-41d4-a716-446655440000
curl -i -X GET \
  'https://api-v2.contaazul.com/v1/notas-fiscais?data_inicial=string&data_final=string&pagina=1&tamanho_pagina=10&documento_tomador=12345678900&numero_nota=1234&id_venda=550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
itensArray of objects(NotaFiscal)

Lista de notas fiscais

paginacaoobject

Paginação

Response
application/json
{
  "itens": [
    { … }
  ],
  "paginacao": {
    "pagina_atual": 1,
    "tamanho_pagina": 10,
    "total_itens": 50,
    "total_paginas": 5
  }
}

Retornar notas fiscais de serviço por filtros

Request

Permite consultar todas as notas fiscais de serviço (NFS-e) já emitidas no ERP, com uso de filtros como data, número da nota, id da venda.. Este endpoint retorna NFS-e com todos os status possíveis a partir da emissão. Essa funcionalidade facilita o monitoramento fiscal, exportação para relatórios ou integração com contabilidade.

Security
BearerAuth
Query
paginainteger>= 1

Número da página

Default 1
tamanho_paginainteger

Tamanho da página (valores válidos: 10, 20, 50, 100)

Default 10
Enum102050100
data_competencia_destringrequired

Data de emissão inicial no formato YYYY-MM-DD (range máximo: 15 dias)

Example: data_competencia_de=2024-01-01
data_competencia_atestringrequired

Data de emissão final no formato YYYY-MM-DD (range máximo: 15 dias)

Example: data_competencia_ate=2024-01-15
idsArray of strings

Lista de UUIDs das notas fiscais de serviço

id_clienteArray of strings

Lista de IDs de clientes (UUIDs)

numero_vendainteger(int64)

Número da venda

Example: numero_venda=1001
numero_nfse_inicialinteger(int64)

Número inicial da NFS-e

Example: numero_nfse_inicial=100
numero_nfse_finalinteger(int64)

Número final da NFS-e

Example: numero_nfse_final=200
numero_rps_inicialinteger(int64)

Número inicial do RPS

Example: numero_rps_inicial=1000
numero_rps_finalinteger(int64)

Número final do RPS

Example: numero_rps_final=2000
statusArray of strings

Status da nota fiscal

Items Enum"PENDENTE""PRONTA_ENVIO""AGUARDANDO_RETORNO""EM_ESPERA""EMITINDO""EMITIDA""CANCELADA""FALHA""FALHA_CANCELAMENTO""CORRIGIDA_SUCESSO"
tipo_negociacaostring

Tipo de negociação

Enum"VENDA""CONTRATO"
curl -i -X GET \
  'https://api-v2.contaazul.com/v1/notas-fiscais-servico?pagina=1&tamanho_pagina=10&data_competencia_de=2024-01-01&data_competencia_ate=2024-01-15&ids=string&id_cliente=string&numero_venda=1001&numero_nfse_inicial=100&numero_nfse_final=200&numero_rps_inicial=1000&numero_rps_final=2000&status=PENDENTE&tipo_negociacao=VENDA' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
itensArray of objects(NotaFiscalServico)
paginacaoobject(Pagina_o)

Modelo de resposta para paginação dos resultados

Response
application/json
{
  "itens": [
    { … }
  ],
  "paginacao": {
    "pagina_atual": 1,
    "tamanho_pagina": 10,
    "total_itens": 50,
    "total_paginas": 5
  }
}

Vincular nota fiscal a mdfe

Request

Permite associar uma ou mais notas fiscais (identificadas pelas chaves de acesso) a um MDF-e (Manifesto Eletrônico de Documento Fiscal). É possível também informar o status do vínculo (ex: "AUTORIZADO", "ENCERRADO", "CANCELADO"). Apoio no controle logístico e fiscal.

Security
BearerAuth
Bodyapplication/jsonrequired

Dados para vincular nota fiscal a mdfe

chaves_acessoArray of stringsrequired

Chaves de acesso das notas fiscais vinculadas ao MDF-e

Example: ["42250323643586000108550010000001151606401726","42250323643586000108550010000001141054498495"]
identificadorstringrequired

Identificador do MDF-e

Example: "345345"
statusstring

Status do MDF-e

Enum"AUTORIZADO""ENCERRADO""CANCELADO"
Example: "ENCERRADO"
curl -i -X POST \
  https://api-v2.contaazul.com/v1/notas-fiscais/vinculo-mdfe \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "chaves_acesso": [
      "42250323643586000108550010000001151606401726",
      "42250323643586000108550010000001141054498495"
    ],
    "identificador": "345345",
    "status": "ENCERRADO"
  }'

Responses

No Content

Response
No content

Retornar a nota fiscal por chave

Request

Permite consultar dados de uma nota fiscal específica, buscando pela sua chave de acesso

Security
BearerAuth
Path
chavestringrequired

Chave da nota fiscal

curl -i -X GET \
  'https://api-v2.contaazul.com/v1/notas-fiscais/{chave}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/xml
string
Response
application/xml
<root>string</root>