--- title: "Listar notas" method: GET path: "/v1/notas" tags: ["Notas"] --- # Listar notas `GET /v1/notas` ## Request - Base URL: `https://api.notaguard.com.br` - URL: `https://api.notaguard.com.br/v1/notas` - Auth: HTTP bearer Lista NF-e, NFC-e e NFS-e da empresa, com filtros e paginação por cursor. Ordenação padrão: `criada_em` decrescente. `incluir=cfop` adiciona a cada item a lista de CFOPs distintos do documento. ## Query parameters - `tipo` string: Filtra por tipo. Aceita múltiplos separados por vírgula: `tipo=NFe,NFCe`. Valores aceitos: NFe, NFCe, NFSe. - `status` string: Filtra por situação. Múltiplos separados por vírgula. Valores aceitos: autorizada, resumida, cancelada, denegada, desconhecido. - `vinculo` string: Filtra pelo vínculo da sua empresa com o documento. Múltiplos separados por vírgula. `indefinido` retorna os documentos cujo vínculo ainda não foi determinado. Valores aceitos: emissor, receptor, transportador, terceiro, indefinido. - `manifestacao` string: Filtra pela manifestação registrada. Múltiplos separados por vírgula. Valores aceitos: ciencia, confirmacao, desconhecimento, nao_realizada. - `data_ref_de` string: Data de referência a partir de (AAAA-MM-DD ou ISO 8601). A data de referência é a mesma da coluna "Data" do painel: emissão em NF-e e NFC-e, competência em NFS-e. Atenção: documentos sem essa data (só resumo) são excluídos quando este filtro é usado. - `data_ref_ate` string: Data de referência até, **inclusive o dia inteiro**. AAAA-MM-DD ou ISO 8601. - `data_emissao_de` string: Data de emissão a partir de (AAAA-MM-DD ou ISO 8601). Atenção: documentos sem data de emissão (só resumo) são excluídos quando este filtro é usado. - `data_emissao_ate` string: Data de emissão até, **inclusive o dia inteiro**. AAAA-MM-DD ou ISO 8601. - `data_criacao_de` string: Filtra por quando o documento entrou no NotaGuard (`criada_em`), a partir de. AAAA-MM-DD ou ISO 8601. - `data_criacao_ate` string: Filtra por quando o documento entrou no NotaGuard (`criada_em`), até, **inclusive o dia inteiro**. AAAA-MM-DD ou ISO 8601. - `data_atualizacao_apos` string: Retorna apenas documentos alterados depois deste instante (AAAA-MM-DD ou ISO 8601). É o parâmetro recomendado para sincronização incremental: guarde o maior `atualizada_em` recebido e mande de volta na próxima chamada. - `valor_min` number: Valor mínimo. Documentos sem valor conhecido são excluídos quando este filtro é usado. - `valor_max` number: Valor máximo. Documentos sem valor conhecido são excluídos quando este filtro é usado. - `chave` string: Busca exata por chave de acesso. - `numero` integer: Busca exata pelo número do documento. - `documento_emissor` string: CNPJ ou CPF do emissor, somente dígitos. - `busca` string: Busca textual em nome do emissor, chave e número. Use para consulta livre; para filtro exato prefira os parâmetros dedicados. - `xml_completo_disponivel` 'true' | 'false': `true` retorna apenas documentos com XML completo disponível; `false`, apenas os que têm só o resumo. - `etiqueta` string: Filtra por etiqueta aplicada no painel. `etiqueta=centro-custo` retorna notas que têm a etiqueta com qualquer valor; `etiqueta=centro-custo:matriz` filtra pelo valor (aceita o `valor` ou o `rotulo` da opção; em booleanas use `true`/`false`; em data use AAAA-MM-DD). Os slugs vêm de `GET /v1/etiquetas`. - `sem_etiqueta` string: Inverso de `etiqueta`, mesmo formato. `sem_etiqueta=centro-custo` retorna as notas que ainda não têm a etiqueta; `sem_etiqueta=centro-custo:matriz` retorna as que não têm esse valor, incluindo as sem a etiqueta. Serve para classificar em rodadas, pegando só o que falta. - `cfop` string: Filtra por CFOP dos itens. Múltiplos separados por vírgula: `cfop=5905,6905` retorna documentos com item em qualquer um deles. O CFOP vem dos itens do XML completo, então documentos sem extração completa são excluídos quando este filtro é usado; NFS-e não tem CFOP e também fica de fora. - `incluir` string: Blocos opcionais a incluir em cada item da listagem, separados por vírgula. Bloco não pedido não aparece na resposta. Valores aceitos: cfop. - `limite` integer: Itens por página. Entre 1 e 100. Padrão 50. - `cursor` string: Cursor de paginação devolvido em `proximo_cursor`. ## Response `200` Página de resultados (até 100 itens). - ListaNotas - `dados` Nota[], required - `id` string, uuid, required: Identificador interno, estável. - `chave` string, required: Chave de acesso do documento, somente dígitos. O tamanho varia por tipo: 44 em NF-e e NFC-e, 50 na NFS-e do padrão nacional, 26 em alguns municípios. - `tipo` 'NFe' | 'NFCe' | 'NFSe', required - `numero` integer, nullable, required: Número do documento. - `serie` string, nullable, required - `emissor` object, required - `documento` string, nullable, required: CNPJ (14 dígitos) ou CPF (11 dígitos), somente dígitos. O NotaGuard suporta empresa pessoa física, por isso o campo aceita os dois. - `nome` string, nullable, required: Razão social ou nome do emissor. - `destinatario` object, nullable, required: A outra parte do documento: destinatário na NF-e e NFC-e, tomador na NFS-e. `null` quando ainda não conhecido. - `documento` string, nullable, required: CNPJ (14 dígitos) ou CPF (11 dígitos), somente dígitos. O NotaGuard suporta empresa pessoa física, por isso o campo aceita os dois. - `nome` string, nullable, required: Razão social ou nome. Em NF-e depende da extração completa do XML, então pode vir `null` mesmo com o documento presente. - `vinculo` 'emissor' | 'receptor' | 'transportador' | 'terceiro' | 'indefinido', required: Vínculo da sua empresa com este documento (mesmo termo do painel). `indefinido` quando ainda não foi determinado, o que é comum em documentos que só têm resumo; dá para filtrar por ele na listagem. - `valor` number, nullable, required: Valor total. `null` quando o XML completo ainda não chegou. Nulo significa desconhecido, não zero. - `status` 'autorizada' | 'resumida' | 'cancelada' | 'denegada' | 'desconhecido', required: Situação do documento. - `autorizada`: Documento autorizado, com XML completo disponível. - `resumida`: Só existe o **resumo** do documento, sem o XML completo: `valor` e `data_emissao` geralmente vêm `null` e `xml_completo_disponivel` é `false` (o XML de resumo continua disponível para download). Em nota recebida é um estado transitório, que dura até o documento completo chegar; em nota emitida pela sua empresa é permanente, porque a SEFAZ não devolve pela distribuição o XML da própria emissão. Veja a seção "Documentos que só têm resumo". - `cancelada`: Documento cancelado na SEFAZ. - `denegada`: Emissão denegada pela SEFAZ. - `desconhecido`: A SEFAZ não informou situação reconhecível para o documento. - `status_motivo` string, nullable, required: Descrição devolvida pela SEFAZ para o status atual. - `manifestacao` 'ciencia' | 'confirmacao' | 'desconhecimento' | 'nao_realizada', nullable, required: Manifestação do destinatário registrada na SEFAZ. Apenas NF-e. - `natureza_operacao` string, nullable, required: Natureza da operação declarada no XML (`natOp`). Apenas NF-e e NFC-e. - `cfop` string[], nullable: Presente apenas com `incluir=cfop`: CFOPs distintos dos itens do documento, em ordem crescente. Um documento pode ter mais de um (medido em produção: 10% têm; ex.: 5102 e 5405 na mesma nota). `null` quando o CFOP não é conhecido: documento sem XML completo processado, ou NFS-e (serviço não tem CFOP). O CFOP por item está em `GET /v1/notas/{id}/itens`. - `data_emissao` string, date-time, nullable, required: Data e hora de emissão (ISO 8601, UTC). `null` em documentos que só têm resumo. - `data_competencia` string, nullable, required: Competência (AAAA-MM-DD). Apenas NFS-e. - `data_recebimento` string, date-time, nullable, required: Quando a SEFAZ disponibilizou o documento para a sua empresa (ISO 8601, UTC). Apenas NF-e e NFC-e. - `origem` 'monitored' | 'imported' | 'fisco_facil_rj' | 'sae_sp', required: `monitored`: capturado automaticamente na SEFAZ. `imported`: XML enviado manualmente. `fisco_facil_rj`: NFC-e obtida via Fisco Fácil RJ. `sae_sp`: NFC-e emitida pela empresa, obtida no serviço de apoio à escrituração da SEFAZ-SP; vem autorizada, com XML e protocolo, mas sem `status_codigo` (a SEFAZ-SP não devolve o código de status), e ainda sem PDF. - `xml_completo_disponivel` boolean, required: Se `true`, o XML completo autorizado está disponível e o PDF pode ser gerado. Se `false`, `GET /v1/notas/{id}/xml` ainda pode devolver o XML de **resumo** da SEFAZ, mas `GET /v1/notas/{id}/pdf` responde `409 xml_indisponivel`. Use este campo como filtro (`?xml_completo_disponivel=true`) em vez de descobrir documento a documento. - `criada_em` string, date-time, required: Quando o documento entrou no NotaGuard (ISO 8601, UTC). Nunca nulo. - `atualizada_em` string, date-time, required: Última alteração no documento (ISO 8601, UTC). Nunca nulo. - `proximo_cursor` string, nullable, required: Passe este valor em `cursor` para obter a próxima página. `null` na última página. Trate como opaco: o formato interno pode mudar sem aviso. - `tem_mais` boolean, required: `true` se existe pelo menos uma página adiante. ## Other responses - `400`: Parâmetro inválido ou cursor corrompido. - `401`: Chave ausente, inválida, revogada ou expirada. - `403`: Escopo insuficiente ou plano sem acesso via API. - `429`: Limite de requisições excedido. - `500`: Erro interno. --- [API](https://skmtc.dev/notaguard/apis/api-notaguard.md) · [All operations](https://skmtc.dev/notaguard/apis/api-notaguard/llms.txt) · [OpenAPI document](https://skmtc.dev/notaguard/apis/api-notaguard/revisions/118f819f30d6?raw)