Query string

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.