# Query parameter > Query parameter é um par de nome e valor adicionado ao final de uma URL, depois do sinal de interrogação, para refinar uma requisição a uma API. Em APIs fiscais, ele costuma servir para filtrar, ordenar e paginar listas de documentos, como buscar notas de um CNPJ, de um período ou com determinado status. **Também conhecido como:** Parâmetro de consulta, Parâmetro de query, Parâmetro de URL, Query param, Query parameter **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Q ## O que é um query parameter, em termos simples? Pense na URL de uma API como o endereço de uma prateleira de documentos. O query parameter funciona como um pedido extra feito ao atendente: em vez de trazer tudo, você pede apenas o que interessa, como as notas emitidas hoje ou somente as rejeitadas. Na prática, ele aparece depois do ponto de interrogação na URL, no formato nome=valor. Quando há mais de um, eles são separados pelo símbolo &. Por exemplo: /nfe?status=autorizada&pagina=2. O conjunto de todos esses parâmetros é chamado de query string. ## Para que serve o query parameter em uma API fiscal? O uso mais comum é em consultas. Um ERP ou plataforma de vendas que precisa listar documentos fiscais raramente quer receber todos de uma vez. Com query parameters, ele pode filtrar por tipo de documento (NF-e, NFS-e, NFC-e, CT-e, MDF-e), por CNPJ emitente, por intervalo de datas ou por status de processamento. Também são usados para paginação, indicando qual página de resultados retornar e quantos itens trazer por vez, e para ordenação, como listar das notas mais recentes para as mais antigas. Isso deixa as respostas menores, mais rápidas e mais fáceis de processar. ## Como funciona um query parameter na prática? O sistema monta a URL do endpoint e acrescenta os parâmetros desejados. O servidor da API lê esses valores, aplica os filtros correspondentes e devolve apenas os registros que atendem aos critérios, geralmente em formato JSON. Alguns cuidados são importantes. Caracteres especiais, como espaços e acentos, precisam ser codificados na URL. Datas costumam seguir um formato padronizado definido pela documentação da API. E parâmetros desconhecidos ou com valores inválidos podem ser ignorados ou gerar um erro de validação, dependendo de como a API foi construída. ## Qual a diferença entre query parameter, path parameter e corpo da requisição? O path parameter faz parte do próprio caminho da URL e geralmente identifica um recurso específico, como o identificador de uma nota em /nfe/12345. Já o query parameter vem depois do ponto de interrogação e serve para refinar ou filtrar o resultado, sendo normalmente opcional. O corpo da requisição, ou payload, carrega dados maiores e estruturados, como todas as informações necessárias para emitir uma NF-e. Por isso, a emissão em si costuma ser enviada no corpo de uma requisição POST, enquanto consultas e listagens usam requisições GET com query parameters. ## Posso enviar dados sensíveis em query parameters? Não é recomendado. URLs podem ficar registradas em logs de servidores, históricos de navegador e ferramentas de monitoramento. Por isso, API Keys, tokens de autenticação e senhas de certificados devem trafegar em cabeçalhos HTTP, como o header de autenticação, e sempre sobre HTTPS. Dados como CNPJ e datas costumam ser aceitáveis como filtros, mas cada empresa deve avaliar sua política de segurança e de proteção de dados antes de expor informações em URLs. ## Exemplos de Query parameter - Um ERP consulta GET /nfe?cnpj_emitente=12345678000190&status=rejeitada para listar as notas rejeitadas de uma filial e corrigir os erros. - Uma plataforma de serviços busca GET /nfse?data_inicio=2024-01-01&data_fim=2024-01-31 para conferir as NFS-e emitidas no mês antes do fechamento contábil. - Um marketplace percorre resultados com GET /documentos?tipo=nfce&pagina=3&limite=50, recebendo 50 NFC-e por vez para não sobrecarregar a integração. - Um agente de IA conectado via MCP solicita documentos com filtro de status pendente, e a ferramenta traduz o pedido em uma consulta com query parameters para a API fiscal. ## Perguntas frequentes ### Query parameter e query string são a mesma coisa? Não exatamente. A query string é todo o trecho da URL depois do ponto de interrogação. Cada par nome=valor dentro dela é um query parameter. Ou seja, a query string é o conjunto, e os query parameters são seus itens. ### Query parameters são obrigatórios? Normalmente não. Eles costumam ser opcionais e, quando omitidos, a API aplica valores padrão, como a primeira página de resultados. Porém, algumas APIs exigem certos parâmetros em endpoints específicos, então vale consultar a documentação, como a especificação OpenAPI. ### Posso usar query parameters para emitir uma nota fiscal? Em geral, não. A emissão envolve muitos dados estruturados, que são enviados no corpo da requisição em JSON. Query parameters são mais adequados para consultas, filtros, ordenação e paginação de documentos já existentes. ### O que acontece se eu enviar um valor inválido? Depende da API. Ela pode ignorar o parâmetro, aplicar um valor padrão ou retornar um erro informando o problema, geralmente com código HTTP 400. Tratar essas respostas evita que a integração exiba resultados incompletos sem perceber. ## Termos relacionados - [Query string](https://conota.dev/glossario/query-string.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [Filtro de documentos fiscais](https://conota.dev/glossario/filtro-de-documentos-fiscais.md) - [Paginação na API fiscal](https://conota.dev/glossario/paginacao-na-api-fiscal.md) - [API REST para emissão fiscal](https://conota.dev/glossario/api-rest-para-emissao-fiscal.md) - [Header de autenticação](https://conota.dev/glossario/header-de-autenticacao.md) --- Fonte: [Query parameter](https://conota.dev/glossario/query-parameter/) · Atualizado em 2026-10-22