JSON

Query String

O que o JSON para Query String faz?

Você montou uma config JSON no código — parâmetros de filtro, payload de analytics, state de OAuth — e agora precisa anexá-la a uma URL. Esta página cuida desse último trecho chato. Cole o JSON à esquerda e receba ?customer=Ava+Chen&status=active&total%5Bgte%5D=49.99&page=2&tag=premium&tag=verified à direita, pronto para colar em um link, uma chamada fetch ou uma URL de webhook. Arrays viram chaves repetidas (a convenção que qualquer servidor moderno entende), valores são corretamente codificados em porcentagem, e o ? inicial vem incluso para você colar direto numa URL.

A conversão usa o URLSearchParams nativo do navegador — a mesma primitiva que o framework do servidor usa para parsear a requisição quando ela volta. URLSearchParams produz saída application/x-www-form-urlencoded conforme o WHATWG URL Standard, e o seu JSON é parseado por JSON.parse seguindo a RFC 8259. Números e booleanos viram strings (query strings não têm sistema de tipos), valores null e undefined são pulados, e objetos aninhados disparam um erro claro para você poder achatá-los.

Tudo roda localmente no seu navegador — sem upload, sem ida ao servidor, sem log. Se você tem o problema oposto (uma query string e quer JSON), use o Query String para JSON. Se quiser quebrar a URL inteira em protocolo, host, caminho e parte de search, a página URL para JSON ou o Parser de URL servem melhor. As regras de codificação em porcentagem usadas aqui estão definidas na RFC 3986 §2.1, e o modelo mais amplo de parsing de URL está na referência da API URL no MDN.

Como converter JSON em query string

Três passos. Cada um corresponde a um botão na página.

Cole o objeto JSON

Coloque o JSON no painel da esquerda. O valor de nível superior precisa ser um objeto — arrays e primitivos não mapeiam direito para parâmetros de query. Clique em Exemplo para um payload realista de filtro de e-commerce com string, número, chave entre colchetes e array. Exemplo:

{
  "customer": "Ava Chen",
  "status": "active",
  "total[gte]": "49.99",
  "page": 2,
  "tag": ["premium", "verified"]
}

Números e booleanos viram strings (query strings não carregam tipos). Valores <code>null</code> e <code>undefined</code> são pulados — caso contrário só sujariam a URL.

Leia a query string

O painel da direita atualiza enquanto você digita. O exemplo acima produz ?customer=Ava+Chen&status=active&total%5Bgte%5D=49.99&page=2&tag=premium&tag=verified. Espaços viram + (estilo form-encoded — veja o FAQ), colchetes viram %5B/%5D, e o array tag se expande em dois parâmetros tag= separados.

Copie ou baixe

Clique em Copiar para mandar a query string para a área de transferência, ou em Baixar para salvá-la como querystring.txt. Limpar reseta o painel de entrada.

Quando você usaria isso de verdade

Criar URLs de filtro compartilháveis

Seu dashboard deixa o usuário filtrar pedidos por cliente, status e intervalo de datas. O estado vive como um objeto JSON no componente ({customer: "Marco Rivera", status: "active", date_from: "2026-04-01"}). Para deixar a view compartilhável, você anexa isso à URL — cole o JSON aqui, copie a query string, pronto. Vale igual para páginas de categoria de e-commerce, resultados de busca, qualquer coisa com filtros que mantêm estado.

Montar URLs de callback de webhooks

Stripe, GitHub e a maioria dos emissores de webhook deixam você colocar metadados na query string da URL de callback. Você tem um objeto JSON descrevendo o usuário ({userId: "USR-1001", source: "checkout", flow: "onboarding"}) e precisa anexá-lo a https://api.example.com/webhook?.... Cola, copia, cola — bem melhor que codificar cada valor na mão e ficar se preocupando com quais caracteres precisam de escape.

Gerar URLs OAuth e OpenID

URLs de autorização OAuth são 8 a 12 parâmetros: client_id, redirect_uri, scope, state, response_type, etc. Montar uma primeiro em JSON (para ver direitinho) e converter aqui é mais rápido que concatenar strings rezando para a codificação estar certa. O parâmetro state costuma trazer um nonce e um caminho de retorno que precisam do próprio escape.

Construir requisições de API em clientes HTTP

Quando você está testando um endpoint no cURL, no Postman ou num fetch() rápido, geralmente tem os parâmetros como um trechinho JSON tirado da documentação. Converte aqui, anexa na URL, dispara a requisição. O filtro de produto do pedido ORD-1001 {"sku": "SKU-101", "include": "variants"} vira ?sku=SKU-101&include=variants em uma colada só.

Perguntas frequentes

Por que os espaços viram + em vez de %20?

Porque a saída é form-encoded (application/x-www-form-urlencoded), que é o que todo navegador manda e todo servidor espera numa query string. Tecnicamente a RFC 3986 prefere %20 em componentes de URI, mas a convenção form-encoded com + para espaços é mais antiga que a RFC 3986 e é o que query strings vêm usando desde os anos 90. Todo framework de servidor moderno decodifica os dois — Express, FastAPI, ASP.NET, Spring, Rails, Django, qualquer um. Se você precisa especificamente de %20, rode um .replace(/\+/g, "%20") rápido na saída.

Como os arrays são codificados?

Eles se expandem em chaves repetidas. {"tag": ["premium", "verified"]} vira tag=premium&tag=verified. É a convenção que o URLSearchParams produz, e ela faz round-trip limpo via URLSearchParams.getAll() no lado receptor. Se o seu servidor espera notação com colchetes (tag[]=premium&tag[]=verified) — comum em PHP e Rails — nomeie a chave JSON como tag[] em vez de tag.

Posso ter objetos aninhados no JSON?

Não — query strings são planas por design. A página retorna um erro claro se vê um objeto aninhado para você achatar. A solução mais comum são chaves com notação de colchetes: em vez de {"filter": {"status": "active"}}, escreva {"filter[status]": "active"}. Frameworks como Rails, PHP e qs.js parseiam isso de volta para objetos aninhados no servidor. Ou simplesmente achate conceitualmente: {"status": "active"} se não houver ambiguidade real.

O que acontece com valores null e undefined?

São pulados. {"customer": "Ava Chen", "status": null} produz ?customer=Ava+Chen, não ?customer=Ava+Chen&status=. O motivo: status= na URL significa "string vazia", que é um valor real e diferente de "sem status". Mandar null como vazio seria perder informação e confundir. Se você realmente quer status=, mande {"status": ""}.

Números e booleanos preservam o tipo?

Não — query strings só carregam strings. {"page": 2} vira page=2 e {"debug": true} vira debug=true. Seu código no servidor precisa conhecer o schema e fazer a conversão de volta. Isso é fundamental para query strings (e dados de formulário) — o formato de transporte não distingue entre o número 2 e a string "2". Se você precisa de parâmetros tipados, mande no corpo da requisição como JSON.

Como ele lida com Unicode e emoji em chaves ou valores?

Bem direto. URLSearchParams codifica os bytes em UTF-8 e faz percent-escape de qualquer coisa fora do conjunto seguro. Então {"name": "中文"} vira name=%E4%B8%AD%E6%96%87, e {"reaction": "🔥"} vira reaction=%F0%9F%94%A5. Do lado receptor, URLSearchParams (ou o parser de query do framework) decodifica direto. Não tem ajuste de encoding para mexer — UTF-8 é o que o URL Standard manda.

Para que serve o ponto de interrogação inicial?

Para você poder colar a saída direto em uma URL — https://shop.example.com/orders + ?customer=Ava+Chen&page=2 = uma URL funcional. Se vai anexar a uma URL que já tem query string, tire o ? e use &. Se a entrada está vazia ou é {}, a saída também fica vazia (sem ? solto).

Outras ferramentas de URL e JSON

Montar uma query string é uma operação só. Aqui vai o que combina bem com isso: