QR codes - GetQR Docs

A API do GetQR está em beta e disponível para workspaces selecionados. Os detalhes podem mudar antes do lançamento oficial.

No GetQR, um QR code é a imagem mais um link curto pelo qual ela é resolvida. Criar um QR code também cria o link curto dele, então você pode mudar o destino depois sem reimprimir o código.

Método	Caminho	Descrição
`GET`	`/api/v1/qrs`	Listar QR codes
`POST`	`/api/v1/qrs`	Criar um QR code
`GET`	`/api/v1/qrs/{qrId}`	Obter um QR code
`PATCH`	`/api/v1/qrs/{qrId}`	Atualizar um QR code
`PUT`	`/api/v1/qrs/{qrId}`	Definir o estado de pausa
`POST`	`/api/v1/qrs/{qrId}/pause`	Pausar um QR code
`POST`	`/api/v1/qrs/{qrId}/activate`	Reativar um QR code
`POST`	`/api/v1/qrs/{qrId}/duplicate`	Duplicar um QR code
`DELETE`	`/api/v1/qrs/{qrId}`	Excluir um QR code
`GET`	`/api/v1/qrs/{qrId}/download`	Baixar a imagem de um QR code

Dados do QR code por tipo

O formato de data de cada um dos 16 tipos.

Personalização

Estilos de pontos, cores, molduras e logos.

Regras de acesso

Agendamento, limite de leituras e senha.

Para as estatísticas de leituras de um QR code, veja Análises.

O objeto QR code

Todos os endpoints de QR codes respondem com este objeto, exceto Excluir e Baixar. A listagem retorna um array deles.

string

ID único do QR code, por exemplo qr_1EPcVfeHZAY2iNoVLsgW2Aqf.

string

Tipo do QR code, por exemplo website. Veja Dados do QR code por tipo para os 16 valores.

string | null

Nome do QR code, exibido no painel.

string | null

Anotação livre sobre o QR code.

string

O payload armazenado. Para wifi, vcard, social, multilink, event e sms, é o payload que você enviou. Para os outros tipos, é o link curto, então leia o destino em url.

boolean

true quando o QR code está pausado.

boolean

true para um QR code estático criado no painel, que não tem link curto. A API sempre cria QR codes dinâmicos.

string | null

Link curto completo, por exemplo https://getqr.sh/x7Kd2p1.

string | null

Domínio do link curto.

string | null

Slug do link curto.

boolean

true quando o slug foi escolhido, e não gerado.

string | null

Destino para o qual o link curto redireciona.

string | null

Destino para visitantes no iOS, em QR codes app.

string | null

Destino para visitantes no Android, em QR codes app.

integer

Número total de leituras.

object

Regras de acesso. A senha em si nunca é retornada. Veja Regras de acesso.

Mostrar properties

boolean

Se os visitantes precisam digitar uma senha.

string | null

Início agendado, ISO 8601.

string | null

Fim agendado, ISO 8601.

integer | null

Número máximo de leituras.

string

Somente leitura. custom é um design que a API pode editar por completo. branded e ai são um design Branded ou um design com IA criado no painel. A API não pode editar a imagem dele, mas a mantém quando você altera outros campos.

object

O design armazenado: styles, frameOptions e logoOptions, cada um como objeto ou null. Eles têm a mesma estrutura dos campos da requisição, para que você possa enviá-los de volta. Veja Personalização.

object | null

O arquivo de um QR code pdf, image ou video: id, name e size em bytes.

string | null

Somente leitura. Nome de exibição de um QR code app criado no painel.

object | null

Somente leitura. Um QR code pdf com vários arquivos, criado no painel: title, layout e files.

object | null

Somente leitura. Um QR code image com várias imagens, criado no painel: title, layout e files.

string

Data de criação, ISO 8601.

string

Data da última atualização, ISO 8601.

Segredos e IDs internos (password, userId, workspaceId, projectId) nunca são retornados.

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "description": null,
  "data": "https://getqr.sh/x7Kd2p1",
  "archived": false,
  "isStatic": false,
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "domain": "getqr.sh",
  "key": "x7Kd2p1",
  "keyIsCustom": false,
  "url": "https://example.com",
  "ios": null,
  "android": null,
  "scans": 128,
  "access": {
    "passwordProtected": false,
    "activeAt": null,
    "pauseAt": null,
    "scanLimit": null
  },
  "designKind": "custom",
  "design": {
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" }, … },
    "frameOptions": { "id": "card", "text": "Scan me!", … },
    "logoOptions": { "type": "suggested", "id": "logo-website-3", "scalePercent": 25 }
  },
  "file": null,
  "appName": null,
  "pdfBundle": null,
  "imageGallery": null,
  "createdAt": "2026-08-01T10:00:00.000Z",
  "updatedAt": "2026-08-01T10:00:00.000Z"
}

Listar QR codes

GET /api/v1/qrs Retorna os QR codes do seu workspace, uma página por vez.

integer

padrão:"1"

Página a retornar, 1 ou mais.

integer

padrão:"100"

QR codes por página, de 1 a 100. Um valor maior é rejeitado.

string

Busca no título do QR code. Buscas com mais de 2 caracteres também consideram o data armazenado. Nos tipos de link, o data armazenado é o link curto, então as URLs de destino não podem ser buscadas.

string

padrão:"createdAt"

Campo de ordenação: createdAt, updatedAt, clicks (total de leituras), lastClicked (leitura mais recente) ou type. type sempre ordena de forma decrescente e ignora sortOrder.

string

padrão:"desc"

Sentido da ordenação: asc ou desc.

boolean

padrão:"false"

Inclui os QR codes pausados.

boolean

padrão:"false"

Retorna apenas os QR codes pausados. Tem prioridade sobre showArchived.

Parâmetros booleanos recebem as strings true ou false. Peça a próxima página enquanto pagination.hasMore for true. Veja Paginação.

curl "https://getqr.com/api/v1/qrs?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "data": [
    {
      "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
      "qrType": "website",
      "title": "Landing page",
      "shortLink": "https://getqr.sh/x7Kd2p1",
      "url": "https://example.com",
      "scans": 128,
      "…": "…"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}

Criar um QR code

POST /api/v1/qrs Cria um QR code junto com o link curto dele. Responde 201 Created com o novo QR code.

string

Seu próprio token para novas tentativas. Repetir a requisição com a mesma chave em até 24 horas retorna a resposta original em vez de criar um segundo QR code. Veja Novas tentativas e duplicados.

string

obrigatório

O que o QR code codifica. Também define o formato que data deve ter. Um entre website, pdf, image, video, whatsapp, social, wifi, app, feedback, vcard, sms, payment, location, multilink, email, event.

string

obrigatório

O payload do tipo, validado de acordo com qrType. Uma string vazia pula a validação. O formato de cada tipo está em Dados do QR code por tipo.

object

O link curto pelo qual o QR code é resolvido. Opcional: se omitido, link.url segue data.

Mostrar properties

string

Destino para o qual o link curto redireciona. Se omitido ou vazio, o padrão é data. Quando os dois são enviados e são diferentes, vale o link.url. QR codes vcard, social, multilink e event sempre apontam para a página hospedada deles, e QR codes pdf, image e video com um fileId, para o arquivo. Esquemas aceitos: http:, https:, wifi:, mailto:, sms:, begin:.

string

Domínio do link curto. Precisa ser um domínio ativo do seu workspace: outro domínio retorna 403, e um domínio que ainda não está ativo retorna 422. Padrão: o domínio padrão do workspace.

string

Slug do link curto, de 3 a 15 caracteres, armazenado em minúsculas. Um slug não permitido retorna 422, e um já em uso retorna 409. Se omitido, é gerado um slug aleatório de 7 caracteres.

string | null

URL de destino para visitantes no iOS, em QR codes app.

string | null

URL de destino para visitantes no Android, em QR codes app.

string | null

Título da prévia do link (og:title), armazenado no link curto. É diferente do title do próprio QR code. Nada o exibe ainda.

string | null

Descrição da prévia do link (og:description), armazenada no link curto. Nada a exibe ainda.

—

Não disponíveis nesta API: enviar qualquer um deles retorna 422. Use access.pauseAt para parar o QR code em um horário definido.

string

Nome do QR code, exibido no painel. Sem espaços nas pontas, de 1 a 40 caracteres. Se omitido, o QR code fica sem título.

string

Anotação livre sobre o QR code. Até 280 caracteres.

string

O arquivo de um QR code pdf, image ou video, enviado com o target correspondente. Para vcard, social e multilink, uma imagem de perfil opcional enviada com o target logo. event também o aceita, mas a página dele lê a capa de data.fileId. Outros tipos retornam 422. Envie o arquivo antes com Arquivos. Veja Arquivos em QR codes.

string

Template cujo design é aplicado ao novo QR code. Os campos de design que você envia são mesclados por cima dele. Um template de design Branded ou de design com IA retorna 422 (art_template_unsupported). Um template desconhecido, ou de outro workspace, retorna 404.

object

Formatos e cores dos pontos e dos cantos. Veja Personalização.

object

Moldura desenhada ao redor do QR code e o texto da chamada para ação dela. Veja Personalização.

object

Logo no centro: um logo sugerido ou seu próprio arquivo enviado com o target logo. Um arquivo desconhecido, um upload não concluído ou um arquivo de outro target é rejeitado. Veja Personalização.

object

Agendamento, limite de leituras e proteção por senha. Veja Regras de acesso.

Mostrar properties

string | null

Início agendado, ISO 8601.

string | null

Fim agendado, ISO 8601.

integer | null

Número máximo de leituras, um inteiro positivo.

string | null

Senha que os visitantes precisam digitar. Enviá-la ativa a proteção.

boolean

Desativa ou reativa a proteção, mantendo a senha armazenada.

boolean

Se o QR code está pausado. true o cria pausado: as leituras mostram a página de pausa em vez do destino.

Campos desconhecidos são descartados sem erro. Veja Não suportado pela API.

curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: landing-page-2026-08" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page",
    "access": { "scanLimit": 500 }
  }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "data": "https://getqr.sh/x7Kd2p1",
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "url": "https://example.com",
  "scans": 0,
  "access": { "passwordProtected": false, "activeAt": null, "pauseAt": null, "scanLimit": 500 },
  "…": "…"
}

Novas tentativas e duplicados

Com chave. Com um cabeçalho Idempotency-Key, a resposta é repetida por 24 horas.
Sem chave. Um corpo idêntico enviado em até 30 segundos é tratado como duplicado.
Repetições. Uma repetição retorna a resposta armazenada com x-idempotent-replay: true. Um novo QR code retorna false.
Em andamento. Uma segunda requisição enquanto a primeira ainda está em andamento recebe 409 conflict.
Falhas. Uma criação com falha libera a chave na hora, então você pode tentar de novo com a mesma chave.
Melhor esforço. Se a proteção estiver indisponível, as criações passam sem proteção.

Veja também Idempotência.

Obter um QR code

GET /api/v1/qrs/{qrId} Retorna um QR code com o link curto, as regras de acesso, o design e, nos tipos baseados em arquivo, o arquivo dele.

string

obrigatório

ID do QR code, da resposta da listagem ou da criação.

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"

A resposta é o objeto QR code completo.

Atualizar um QR code

PATCH /api/v1/qrs/{qrId} Altera o conteúdo, o destino, o design ou as regras de acesso de um QR code. Envie apenas os campos que você quer alterar. Responde com o QR code atualizado.

string

obrigatório

ID do QR code.

O corpo aceita os mesmos campos de Criar um QR code, todos opcionais, com estas diferenças:

templateId. Não é aceito.
link. Parcial. O destino atual é mantido quando você omite link.url. link.domain e link.key retornam 422: o link curto é o que o código impresso codifica, então crie um novo QR code para usar outro.
data. É validado de acordo com o tipo resultante apenas quando data ou qrType muda. Mudar o qrType sem um data compatível é rejeitado. Veja Mudança de tipo.
Design. styles, frameOptions e logoOptions são mesclados ao design armazenado, então um objeto parcial altera apenas o que ele menciona. Escolher outro logo o substitui, mas mantém o tamanho dele.
access. Cada chave é aplicada quando presente. null limpa uma regra. As regras de acesso ficam em access: enviá-las dentro de link retorna 422.
archived. Pausa ou reativa o QR code e o link curto dele juntos, como Pausar e Reativar.

curl -X PATCH "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Autumn campaign",
    "access": { "password": "s3cr3t", "passwordProtected": true }
  }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "title": "Autumn campaign",
  "access": { "passwordProtected": true, "activeAt": null, "pauseAt": null, "scanLimit": null },
  "…": "…"
}

O que cada tipo permite alterar depois da impressão está em Dados do QR code por tipo.

Definir o estado de pausa

PUT /api/v1/qrs/{qrId} Define o estado de pausa diretamente. Pausar e Reativar fazem o mesmo e são mais fáceis de ler.

string

obrigatório

ID do QR code.

boolean

obrigatório

true para pausar o QR code, false para reativá-lo.

curl -X PUT "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}

Pausar um QR code

POST /api/v1/qrs/{qrId}/pause Impede que o QR code seja resolvido para o destino: as leituras mostram a página de pausa. O código impresso e o link curto dele continuam válidos. Sem corpo de requisição.

string

obrigatório

ID do QR code.

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}

Reativar um QR code

POST /api/v1/qrs/{qrId}/activate Faz um QR code pausado voltar a ser resolvido para o destino. Agendamentos e limites de leituras continuam valendo. Sem corpo de requisição.

string

obrigatório

ID do QR code.

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/activate" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": false,
  "…": "…"
}

Duplicar um QR code

POST /api/v1/qrs/{qrId}/duplicate Cria uma cópia com o mesmo conteúdo e o mesmo design. Sem corpo de requisição. Responde 201 Created com o novo QR code.

string

obrigatório

ID do QR code a copiar.

Link curto. A cópia ganha um link curto próprio, com um slug aleatório no domínio padrão do workspace, e não no domínio do original. As leituras dela são contadas separadamente.
Título. O título recebe o sufixo (Copy). O resultado fica dentro de 40 caracteres: um título longo é encurtado antes. Um QR code sem título continua sem título.
Não copiados. Regras de acesso (senha, agendamento, limite de leituras) e o estado de pausa. A cópia sempre fica ativa.
Arquivos. Arquivos de PDF e de imagem, incluindo os de pacotes e galerias, são copiados, então a cópia passa a ser dona deles. Arquivos de vídeo e arquivos de design, como logos, são compartilhados com o original.

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/duplicate" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_7Hk2PqWmX9cTnV4sLbR8YdZe",
  "title": "Landing page (Copy)",
  "shortLink": "https://getqr.sh/p2Wq9dL",
  "url": "https://example.com",
  "archived": false,
  "scans": 0,
  "…": "…"
}

Excluir um QR code

DELETE /api/v1/qrs/{qrId} Exclui o QR code e o link curto dele. Responde com o ID excluído.

A exclusão é permanente. O código impresso e o link curto dele param de funcionar, e o histórico de leituras deixa de estar acessível. Se você puder precisar do QR code de novo, pause-o em vez de excluí-lo.

string

obrigatório

ID do QR code.

string

ID do QR code excluído.

boolean

Sempre true.

curl -X DELETE "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{ "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf", "deleted": true }

Baixar a imagem de um QR code

GET /api/v1/qrs/{qrId}/download Renderiza o QR code com o design dele e retorna o arquivo.

string

obrigatório

ID do QR code a renderizar, da resposta da listagem ou da criação.

string

padrão:"jpg"

Formato de saída: jpg, png, svg, pdf (uma página A4) ou eps. Um design Branded ou com IA só pode ser baixado como jpg, png ou pdf.

integer

padrão:"1024"

Tamanho da imagem em pixels: 1024, 2048 ou 4096. svg e pdf o ignoram. Um design Branded ou com IA só pode ser baixado em 1024.

`format`	`Content-Type`	Nome do arquivo
`jpg`	`image/jpeg`	`<title>-<resolution>px.jpg`
`png`	`image/png`	`<title>-<resolution>px.png`
`svg`	`image/svg+xml`	`<title>.svg`
`pdf`	`application/pdf`	`<title>.pdf`
`eps`	`application/postscript`	`<title>-<resolution>px.eps`

Corpo. O corpo da resposta é o arquivo. O nome de arquivo sugerido está no cabeçalho Content-Disposition, montado a partir do título, ou qr-code para um QR code sem título.
Cache. As respostas trazem um ETag e Cache-Control: private, max-age=3600, must-revalidate. Envie o ETag de volta em If-None-Match para receber 304 Not Modified quando o QR code não mudou.
Erros. Um formato ou uma resolução não suportados retornam 400 bad_request. A mensagem de erro informa o motivo: qr_download_invalid_format, qr_download_invalid_resolution, qr_download_art_format_unsupported ou qr_download_art_resolution_unsupported.

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="landing-page-1024px.png"
ETag: "9f2c0e1b5a7d43c8b016e2f4a9d5c3718be40f92"
Cache-Control: private, max-age=3600, must-revalidate

<binary image data>

Regras de acesso

Envie um objeto access na criação ou na atualização para agendar um início e um fim, limitar o número de leituras ou exigir uma senha. Regras omitidas permanecem inalteradas, e null limpa uma regra. O comportamento completo, com exemplos, está em Regras de acesso.

Objetos de design

styles, frameOptions e logoOptions definem os formatos dos pontos e dos cantos, as cores, a moldura e o logo. Eles funcionam da mesma forma em QR codes, templates e criações em massa. Formatos, molduras ou logos desconhecidos são rejeitados. Todos os valores aceitos e um exemplo completo estão em Personalização.

Problemas comuns

422 ao definir uma senha, um agendamento ou um limite de leituras

Envie a regra em access, não dentro de link.

422 ao alterar link.domain ou link.key

O link curto não pode mudar depois da criação, porque o código impresso o codifica. Crie um novo QR code.

422 "Expected … for qrType"

data não corresponde ao formato de qrType. Confira o tipo em Dados do QR code por tipo.

409 conflict ao criar um QR code

Uma criação idêntica ainda está em andamento, ou link.key já está em uso. Tente de novo quando a primeira requisição terminar. Com uma Idempotency-Key, a nova tentativa retorna o QR code original.

O download é um JPEG, não um PNG

Os parâmetros são format e resolution, e format tem jpg como padrão. Envie format=png.

404 para um QR code que vejo no painel

Toda requisição é executada no workspace da sua chave de API. Verifique se o QR code pertence a ele. Veja Autenticação.

Dados do QR code por tipo

Personalização

Regras de acesso

​O objeto QR code

​Listar QR codes

​Criar um QR code

​Novas tentativas e duplicados

​Obter um QR code

​Atualizar um QR code

​Definir o estado de pausa

​Pausar um QR code

​Reativar um QR code

​Duplicar um QR code

​Excluir um QR code

​Baixar a imagem de um QR code

​Regras de acesso

​Objetos de design

​Problemas comuns

​Próximos passos

Dados do QR code por tipo

Personalização

Regras de acesso

Análises

O objeto QR code

Listar QR codes

Criar um QR code

Novas tentativas e duplicados

Obter um QR code

Atualizar um QR code

Definir o estado de pausa

Pausar um QR code

Reativar um QR code

Duplicar um QR code

Excluir um QR code

Baixar a imagem de um QR code

Regras de acesso

Objetos de design

Problemas comuns

Próximos passos