# Retornar notas fiscais de serviço por filtros

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.

Endpoint: GET /v1/notas-fiscais-servico
Version: v1
Security: BearerAuth

## Query parameters:

  - `pagina` (integer)
    Número da página

  - `tamanho_pagina` (integer)
    Tamanho da página (valores válidos: 10, 20, 50, 100)
    Enum: 10, 20, 50, 100

  - `data_competencia_de` (string, required)
    Data de emissão inicial no formato YYYY-MM-DD (range máximo: 15 dias)
    Example: "2024-01-01"

  - `data_competencia_ate` (string, required)
    Data de emissão final no formato YYYY-MM-DD (range máximo: 15 dias)
    Example: "2024-01-15"

  - `ids` (array)
    Lista de UUIDs das notas fiscais de serviço

  - `id_cliente` (array)
    Lista de IDs de clientes (UUIDs)

  - `numero_venda` (integer)
    Número da venda
    Example: 1001

  - `numero_nfse_inicial` (integer)
    Número inicial da NFS-e
    Example: 100

  - `numero_nfse_final` (integer)
    Número final da NFS-e
    Example: 200

  - `numero_rps_inicial` (integer)
    Número inicial do RPS
    Example: 1000

  - `numero_rps_final` (integer)
    Número final do RPS
    Example: 2000

  - `status` (array)
    Status da nota fiscal
    Enum: "PENDENTE", "PRONTA_ENVIO", "AGUARDANDO_RETORNO", "EM_ESPERA", "EMITINDO", "EMITIDA", "CANCELADA", "FALHA", "FALHA_CANCELAMENTO", "CORRIGIDA_SUCESSO", "AGUARDANDO_CORRECAO", "FALHA_CORRECAO", "DENEGADA", "CANCELAMENTO_MANUAL"

  - `tipo_negociacao` (string)
    Tipo de negociação
    Enum: "VENDA", "CONTRATO"

## Response 200 fields (application/json):

  - `itens` (array)

  - `itens.cidade_emissao` (object)
    Cidade de emissão

  - `itens.cidade_emissao.estado` (string)
    Estado (UF)
    Example: "SC"

  - `itens.cidade_emissao.nome` (string)
    Nome da cidade
    Example: "Joinville"

  - `itens.codigo_cnae` (string)
    Código CNAE
    Example: "6201-5/00"

  - `itens.data_competencia` (string)
    Data de competência
    Example: "2024-01-15"

  - `itens.documento_cliente` (string)
    Documento do cliente
    Example: "12345678000190"

  - `itens.escriturado_manualmente` (boolean)
    Indica se foi escriturado manualmente

  - `itens.id` (string)
    UUID da nota fiscal de serviço
    Example: "550e8400-e29b-41d4-a716-446655440099"

  - `itens.id_contrato` (string)
    UUID do contrato
    Example: "550e8400-e29b-41d4-a716-446655440001"

  - `itens.id_venda` (string)
    UUID da venda
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `itens.informacao_transmissao` (object)
    Informações de transmissão

  - `itens.informacao_transmissao.data_inicio_cancelamento` (string)
    Data de início do cancelamento
    Example: "2024-01-16T14:20:00"

  - `itens.informacao_transmissao.data_inicio_emissao` (string)
    Data de início da emissão
    Example: "2024-01-15T10:30:00"

  - `itens.informacoes_cancelamento` (object)
    Informações de cancelamento

  - `itens.informacoes_cancelamento.motivo` (string)
    Motivo do cancelamento
    Example: "Erro na alíquota de ISS informada"

  - `itens.informacoes_cancelamento.usuario` (string)
    Usuário que cancelou
    Example: "Empresa Teste"

  - `itens.nome_cliente` (string)
    Nome do cliente
    Example: "EMPRESA EXEMPLO LTDA"

  - `itens.numero_nfse` (integer)
    Número da NFS-e
    Example: 123

  - `itens.numero_rps` (integer)
    Número do RPS
    Example: 67890

  - `itens.numero_venda` (string)
    Número da venda
    Example: "1001"

  - `itens.status` (string)
    Status da nota fiscal
    Enum: "PENDENTE", "PRONTA_ENVIO", "AGUARDANDO_RETORNO", "EM_ESPERA", "EMITINDO", "EMITIDA", "CANCELADA", "FALHA", "FALHA_CANCELAMENTO", "CORRIGIDA_SUCESSO", "AGUARDANDO_CORRECAO", "FALHA_CORRECAO", "DENEGADA", "CANCELAMENTO_MANUAL"

  - `itens.valor_total_nfse` (number)
    Valor total da NFS-e
    Example: 1500.5

  - `paginacao` (object)
    Modelo de resposta para paginação dos resultados

  - `paginacao.pagina_atual` (integer)
    Página atual
    Example: 1

  - `paginacao.tamanho_pagina` (integer)
    Tamanho da página
    Example: 10

  - `paginacao.total_itens` (integer)
    Total de itens
    Example: 50

  - `paginacao.total_paginas` (integer)
    Total de páginas
    Example: 5

## Response 400 fields (application/json):

  - `error` (string)
    Mensagem de erro
    Example: "Mensagem de erro detalhada"