# Query string > Query string é a parte de um endereço web (URL) que vem depois do ponto de interrogação e carrega informações extras para o servidor, em pares de nome e valor separados por &. Em APIs fiscais, ela é usada principalmente para filtrar, ordenar e paginar consultas de documentos, como listar notas autorizadas em um período. **Também conhecido como:** Querystring, String de consulta, Parâmetros de URL, Parâmetros de consulta, Query string **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Q ## O que é uma query string, na prática? Toda vez que um sistema faz uma requisição a uma API, ele chama um endereço, a URL. A query string é o trecho final desse endereço, que começa logo depois do sinal de interrogação (?). Ela serve para passar detalhes adicionais sobre o que se quer pedir, sem mudar o endereço principal. O formato é simples: cada informação é escrita como nome=valor, e várias informações são unidas pelo símbolo &. Em um endereço como /notas?status=autorizada&pagina=2, a query string é status=autorizada&pagina=2. Ela contém dois parâmetros: status, com valor autorizada, e pagina, com valor 2. ## Para que serve a query string em uma API fiscal? Em integrações fiscais, a query string aparece principalmente nas consultas. Quando um ERP ou uma plataforma de vendas quer listar documentos, ela permite dizer quais documentos interessam: apenas NF-e autorizadas, apenas notas de um CNPJ específico, apenas as emitidas em determinado mês ou apenas as que foram rejeitadas. Ela também é usada para controlar a paginação, ou seja, dividir resultados grandes em partes menores, e para definir ordenação, como trazer primeiro as notas mais recentes. Assim, o sistema recebe só o que precisa, o que deixa a resposta mais rápida e o processamento mais leve. ## Qual a diferença entre query string e query parameter? Os dois termos andam juntos, mas não são a mesma coisa. A query string é o trecho inteiro depois do ponto de interrogação. O query parameter é cada item individual dentro dela, cada par nome=valor. Usando o exemplo status=autorizada&pagina=2, a query string é o conjunto completo, enquanto status=autorizada e pagina=2 são dois query parameters. No dia a dia, muita gente usa as expressões como se fossem sinônimos, e o contexto costuma deixar claro o que se quer dizer. ## Qual a diferença entre query string e corpo da requisição? A query string viaja dentro da própria URL e é indicada para informações curtas, que ajudam a localizar ou filtrar dados. Por isso, é muito comum em requisições do tipo GET, que apenas leem informações. Já o corpo da requisição (body) é onde vão dados maiores e estruturados, normalmente em JSON. Na emissão de uma nota fiscal, por exemplo, os dados do emitente, do destinatário, dos itens e dos impostos seguem no corpo, e não na query string. Em resumo: a query string pergunta e filtra; o corpo envia o conteúdo principal. ## Quais cuidados tomar ao usar query string? O primeiro cuidado é com segurança. Como a URL costuma ficar registrada em logs de servidores, navegadores e ferramentas de monitoramento, nunca se deve colocar chaves de API, tokens ou senhas na query string. Credenciais devem ir em um header de autenticação. O segundo é a codificação. Caracteres como espaço, acentos, & e = têm significado especial em URLs e precisam ser convertidos para um formato seguro, chamado URL encoding. Um espaço, por exemplo, vira %20. A maioria das bibliotecas de programação faz isso automaticamente. Também vale seguir exatamente os nomes e formatos documentados pela API, como o padrão de datas aceito, e lembrar que URLs muito longas podem ser recusadas por alguns servidores. ## Exemplos de Query string - Um ERP consulta GET /nfe?status=autorizada&data_inicio=2024-01-01&data_fim=2024-01-31 para listar as NF-e autorizadas em janeiro e conciliar com o financeiro. - Um marketplace com vários vendedores usa GET /nfse?cnpj=00000000000000&pagina=3&por_pagina=50 para buscar a terceira página de NFS-e de um CNPJ específico, com 50 notas por página. - Uma equipe de suporte filtra documentos rejeitados com GET /documentos?tipo=nfce&status=rejeitada para identificar notas de varejo que precisam ser corrigidas e reenviadas. - Um sistema de transporte consulta GET /mdfe?situacao=aberto&ordenar=data_emissao para encontrar manifestos ainda não encerrados, do mais antigo para o mais recente. ## Perguntas frequentes ### Posso enviar os dados de uma nota fiscal pela query string? Não é recomendado. Os dados de emissão são extensos e estruturados, por isso devem ir no corpo da requisição, em JSON. A query string serve para informações curtas, como filtros, paginação e ordenação em consultas. ### É seguro colocar a API Key na query string? Não. URLs costumam ser gravadas em logs e históricos, o que pode expor a credencial. A forma adequada é enviar a chave ou o token em um header de autenticação, sempre sobre HTTPS. ### A ordem dos parâmetros na query string faz diferença? Em geral, não. A maioria das APIs lê os parâmetros pelo nome, independentemente da ordem. O importante é usar os nomes e formatos exatamente como descritos na documentação da API. ### O que acontece se eu enviar um parâmetro que a API não reconhece? Depende da API. Algumas simplesmente ignoram o parâmetro desconhecido; outras retornam um erro de validação. Por isso, vale conferir a documentação e testar no ambiente de homologação antes de ir para produção. ## Termos relacionados - [Query parameter](https://conota.dev/glossario/query-parameter.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) - [Header de autenticação](https://conota.dev/glossario/header-de-autenticacao.md) - [HTTP](https://conota.dev/glossario/http.md) --- Fonte: [Query string](https://conota.dev/glossario/query-string/) · Atualizado em 2026-10-22