Referência

Endpoint


GET  https://app.qrcode.kadu.pro/api/v1/qr
POST https://app.qrcode.kadu.pro/api/v1/qr

Autenticação: Authorization: Bearer gq_…

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`type`	string	`url`	Um dos doze tipos estáticos
`data`	string ou objeto	—	O conteúdo (veja abaixo)
`size`	número	`1000`	100 a 5000 px
`format`	`svg` \| `json`	`svg`	Formato da resposta
`design`	objeto	padrão	Só no `POST`

`data`

Aceita duas formas:

String — atalho para o campo principal do tipo.


{ "type": "url", "data": "kadu.pro" }

Objeto — os campos nomeados, para tipos com mais de um.


{
  "type": "wifi",
  "data": { "ssid": "MinhaRede", "security": "WPA", "password": "senha123" }
}

Os nomes dos campos são os mesmos descritos em Tipos de QR Code.

No GET, data é sempre string — a query string não carrega objeto. Para tipos de vários campos, use POST.

`design`

Só no POST. É mesclado sobre o design padrão, então você envia apenas o que quer mudar.


{
  "type": "url",
  "data": "kadu.pro",
  "size": 1200,
  "design": {
    "dots": { "shape": "rounded", "color": "#582D1D", "roundness": 0.4, "scale": 1 },
    "eyes": { "frameShape": "rounded", "ballShape": "circle", "frameColor": "#644a40" },
    "background": { "color": "#ffffff" },
    "frame": { "style": "label-bottom", "label": "Escaneie-me", "color": "#582D1D" },
    "errorCorrection": "Q",
    "quietZone": 4
  }
}

Campos do design

Caminho	Valores
`dots.shape`	`square`, `rounded`, `dots`, `classy`, `extra-rounded`
`dots.color`	hexadecimal
`dots.roundness`	0 a 1
`dots.scale`	0.5 a 1
`dots.gradient`	`{ type, rotation, stops }`
`eyes.frameShape`	`square`, `rounded`, `circle`
`eyes.ballShape`	`square`, `circle`
`eyes.frameColor` / `eyes.ballColor`	hexadecimal; ausente herda
`background.color`	hexadecimal ou `transparent`
`frame.style`	`none`, `label-bottom`, `label-top`
`frame.label` / `frame.color`	texto / hexadecimal
`errorCorrection`	`M`, `Q`, `H`
`quietZone`	módulos (padrão 4)

A API não avalia escaneabilidade. Ela obedece ao design que você mandar, inclusive um que o editor marcaria como Risco. Se você monta designs por código, garanta o contraste do seu lado — as faixas estão em O selo de escaneabilidade.

Respostas

`format=svg` (padrão)

Content-Type: image/svg+xml; charset=utf-8, com o SVG no corpo.

`format=json`


{
  "payload": "https://kadu.pro",
  "svg": "<svg …>",
  "size": 1000
}

payload é o conteúdo final gravado no código — útil para conferir o que a normalização fez com a sua entrada (o https:// acrescentado, o telefone normalizado, o BR Code montado).

Headers

Header	Significado
`X-RateLimit-Limit`	Seu teto por minuto
`Cache-Control`	Sempre `no-store`

no-store é proposital: o conteúdo pode ser específico de um usuário, e respostas de QR não deveriam ficar em cache compartilhado. Se você precisa de cache, faça no seu lado, com a chave que fizer sentido para você.

Erros

HTTP	`error`	Significado	O que fazer
401	`missing-key`	Sem header `Authorization`	Envie `Bearer gq_…`
401	`invalid-key`	Chave inexistente ou revogada	Gere outra em Minha conta
401	`key-expired`	A chave passou da validade	Crie outra no console
429	`quota-exceeded`	Cota do dia ou do mês esgotada	Veja `quota` no corpo; espere ou suba de plano
429	`rate-limited`	Limite por minuto estourado	Espere; veja `limit_per_minute`
400	`unknown-type`	Tipo inválido	Veja `supported` na resposta
400	`invalid-data`	Conteúdo não monta	Veja `detail`
400	`blocked-url`	URL recusada pela segurança	Veja `detail` e Link
400	`invalid-json`	Corpo do `POST` malformado	Confira o JSON

O corpo do erro é sempre JSON:


{ "error": "invalid-data", "detail": "Endereço inválido" }

Boas práticas

Guarde a chave em variável de ambiente, nunca no código versionado.
Chame do servidor. Chave em navegador é chave pública.
Faça cache do resultado quando o conteúdo se repete — o mesmo QR gerado mil vezes gasta mil chamadas à toa.
Trate o 429 com espera e nova tentativa, em vez de insistir em laço.
Prefira format=json quando quiser registrar o payload gerado.
Uma chave por integração. Assim revogar uma não derruba as outras.