A API

A API é servida pelo mesmo Cloudflare Worker que resolve seus links, na origem da Kilo QR. Hoje isso significa que as requisições vão para qr2r.com sob o prefixo /api:

https://qr2r.com/api

Cada caminho nestes guias é relativo a essa base - /links significa https://qr2r.com/api/links. Uma forma rápida de confirmar que uma chave funciona é a raiz da API, que devolve a sua identidade:

{ "api": "qr2r", "version": 0, "user": { "uid": 42, "email": "", "admin": false } }

Envie sua chave como token bearer no cabeçalho Authorization. A chave é verificada antes do cookie de sessão, então um cliente de API fica em um único modo de autenticação sem um cookie de navegador velho se infiltrar.

Authorization: Bearer qr2r_live_1a2b3c…

As chaves começam com qr2r_live_ (ou qr2r_test_ para uma chave em modo de desenvolvimento). Esse prefixo qr2r_ é um identificador de infraestrutura que deliberadamente não foi renomeado - a mesma razão pela qual o domínio ainda é qr2r.com. Você gera uma chave no painel, em API keys; o token completo é mostrado uma única vez na criação, e a Kilo armazena apenas o hash SHA-256, então coloque-o direto em um gerenciador de segredos. Uma requisição sem chave válida (e sem sessão) é recusada:

{ "error": "unauthorized" }

Uma chave carrega um ou ambos de dois escopos. Uma chave de leitura só pode chamar métodos seguros - GET, HEAD, OPTIONS. Uma chave de escrita tem permitido ainda POST, PUT, PATCH e DELETE. Uma tentativa de escrita com uma chave de somente leitura é recusada:

{ "error": "insufficient_scope", "required": "write" }

Os escopos são toda a história de permissões de uma chave: uma chave pode gerenciar links, regras e ler análise, mas nunca pode gerenciar membros, cobrança ou outras chaves - essas ações ficam ligadas a uma sessão interativa. Dê a uma integração uma chave de leitura quando tudo o que ela faz é puxar números.

Cada resposta de erro é um objeto JSON com uma string error, mais campos extras onde ajudam. As falhas de validação carregam a lista completa de problemas sob issues:

{ "error": "invalid_body", "issues": [ /* zod issues */ ] }

Os códigos que você mais encontrará:

• 400 invalid_body - o corpo da requisição falhou na validação.
• 401 unauthorized - chave ausente ou inválida.
• 402 plan_required - o recurso precisa de um plano superior (carrega feature).
• 403 insufficient_scope / forbidden - a chave não pode executar este método ou ação.
• 404 not_found - não existe tal link, regra ou domínio no seu espaço de trabalho.
• 409 - um conflito, como name_taken ou cap_reached.
• 422 destination_unsafe - o destino falhou na verificação de segurança.
• 429 rate_limited - requisições demais (veja abaixo).

As requisições autenticadas têm limite de taxa. O balde geral permite 60 requisições por minuto por usuário. Além disso, uma chave de API ganha seu próprio teto por chave e por minuto, tirado do limite api_rpm do seu plano. Ultrapasse qualquer um e a resposta é:

{ "error": "rate_limited", "retry_after": 42 }

O valor retry_after (enviado também como cabeçalho Retry-After) é o número de segundos até a janela se reiniciar. Aguarde esse tempo e tente de novo.

Com uma chave em mãos, o próximo guia percorre os endpoints de links uma chamada por vez.