Definição
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: Query parameter, Parâmetro de consulta, Parâmetro de query, Parâmetro de URL, Query param
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.
Atualizado em · Como produzimos este glossário