# 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

## Security:

  - `BearerAuth` (unknown)
    apiKey in header Authorization

## Query parameters:

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

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

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

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

  - `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

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

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

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

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

  - `status` (array)
    Status da nota fiscal

  - `tipo_negociacao` (string)
    Tipo de negociação

## Response 200:

  - `200` (unknown)
    OK

## 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
    Example: false

  - `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:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

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

## Response 500:

  - `500` (unknown)
    Internal Server Error

## Response 500 fields (application/json):

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