Códigos QR - GetQR Docs

A API do GetQR está em versão beta e só está disponível para alguns espaços de trabalho. Os detalhes podem mudar antes do lançamento geral.

No GetQR, um código QR é a imagem mais uma ligação curta através da qual é resolvido. Criar um código QR cria também a respetiva ligação curta, pelo que pode alterar o destino mais tarde sem voltar a imprimir o código.

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

Dados do código QR por tipo

O formato de data de cada um dos 16 tipos.

Personalização

Estilos de pontos, cores, molduras e logótipos.

Regras de acesso

Agendamento, limite de leituras e palavra-passe.

Para as estatísticas de leituras de um código QR, consulte Estatísticas.

O objeto de código QR

Todos os endpoints de códigos QR respondem com este objeto, exceto Eliminar e Transferir. A listagem devolve um array destes objetos.

string

ID único do código QR, por exemplo qr_1EPcVfeHZAY2iNoVLsgW2Aqf.

string

Tipo de código QR, por exemplo website. Consulte Dados do código QR por tipo para ver os 16 valores.

string | null

Nome do código QR, apresentado no painel.

string | null

Nota livre sobre o código QR.

string

O payload guardado. Em wifi, vcard, social, multilink, event e sms, é o payload que enviou. Nos restantes tipos, é a ligação curta, pelo que deve ler o destino em url.

boolean

true quando o código QR está em pausa.

boolean

true num código QR estático criado no painel, que não tem ligação curta. A API cria sempre códigos QR dinâmicos.

string | null

Ligação curta completa, por exemplo https://getqr.sh/x7Kd2p1.

string | null

Domínio da ligação curta.

string | null

Slug da ligação curta.

boolean

true quando o slug foi escolhido em vez de gerado.

string | null

Destino para o qual a ligação curta redireciona.

string | null

Destino para os visitantes em iOS, nos códigos QR app.

string | null

Destino para os visitantes em Android, nos códigos QR app.

integer

Número total de leituras.

object

Regras de acesso. A palavra-passe nunca é devolvida. Consulte Regras de acesso.

Mostrar properties

boolean

Se os visitantes têm de introduzir uma palavra-passe.

string | null

Início agendado, ISO 8601.

string | null

Fim agendado, ISO 8601.

integer | null

Número máximo de leituras.

string

Só de leitura. custom é um design que a API pode editar na totalidade. branded e ai são um Branded design ou um AI design criado no painel. A API não pode editar a respetiva imagem, mas mantém-na quando altera outros campos.

object

O design guardado: styles, frameOptions e logoOptions, cada um um objeto ou null. Têm a mesma estrutura dos campos do pedido, pelo que os pode reenviar. Consulte Personalização.

object | null

O ficheiro de um código QR pdf, image ou video: id, name e size em bytes.

string | null

Só de leitura. Nome apresentado de um código QR app criado no painel.

object | null

Só de leitura. Um código QR pdf com vários ficheiros, criado no painel: title, layout e files.

object | null

Só de leitura. Um código QR 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.

Os segredos e os IDs internos (password, userId, workspaceId, projectId) nunca são devolvidos.

{
  "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 códigos QR

GET /api/v1/qrs Devolve os códigos QR do seu espaço de trabalho, uma página de cada vez.

integer

padrão:"1"

Página a devolver, 1 ou mais.

integer

padrão:"100"

Códigos QR por página, de 1 a 100. Um valor superior é rejeitado.

string

Pesquisa no título do código QR. As pesquisas com mais de 2 caracteres também pesquisam no data guardado. Nos tipos de ligação, o data guardado é a ligação curta, pelo que não é possível pesquisar pelos URL de destino.

string

padrão:"createdAt"

Campo pelo qual ordenar: createdAt, updatedAt, clicks (leituras totais), lastClicked (última leitura) ou type. type ordena sempre por ordem decrescente e ignora sortOrder.

string

padrão:"desc"

Sentido da ordenação: asc ou desc.

boolean

padrão:"false"

Inclui os códigos QR em pausa.

boolean

padrão:"false"

Devolve apenas os códigos QR em pausa. Prevalece sobre showArchived.

Os parâmetros booleanos aceitam as strings true ou false. Peça a página seguinte enquanto pagination.hasMore for true. Consulte 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 código QR

POST /api/v1/qrs Cria um código QR e a respetiva ligação curta em conjunto. Responde 201 Created com o novo código QR.

string

O seu próprio token de repetição. Se repetir o pedido com a mesma chave no prazo de 24 horas, recebe a resposta original em vez de um segundo código QR. Consulte Repetições e duplicados.

string

obrigatório

O que o código QR codifica. Define também o formato que data tem de ter. Um de website, pdf, image, video, whatsapp, social, wifi, app, feedback, vcard, sms, payment, location, multilink, email, event.

string

obrigatório

O payload do tipo, validado face a qrType. Uma string vazia ignora a validação. O formato de cada tipo está em Dados do código QR por tipo.

object

A ligação curta através da qual o código QR é resolvido. Opcional: se for omitida, link.url segue data.

Mostrar properties

string

Destino para o qual a ligação curta redireciona. Se for omitido ou estiver vazio, assume o valor de data. Quando ambos são enviados e são diferentes, prevalece link.url. Os códigos QR vcard, social, multilink e event apontam sempre para a respetiva página alojada, e os códigos QR pdf, image e video com um fileId, para o ficheiro. Esquemas aceites: http:, https:, wifi:, mailto:, sms:, begin:.

string

Domínio da ligação curta. Tem de ser um domínio ativo do seu espaço de trabalho: outro domínio devolve 403, e um domínio que ainda não está ativo devolve 422. Por predefinição, o domínio predefinido do espaço de trabalho.

string

Slug da ligação curta, de 3 a 15 caracteres, guardado em minúsculas. Um slug não permitido devolve 422, e um slug já utilizado devolve 409. Se for omitido, é gerado um slug aleatório de 7 caracteres.

string | null

URL de destino para os visitantes em iOS, nos códigos QR app.

string | null

URL de destino para os visitantes em Android, nos códigos QR app.

string | null

Título da pré-visualização da ligação (og:title), guardado na ligação curta. Não confundir com o title do próprio código QR. De momento, não é apresentado em lado nenhum.

string | null

Descrição da pré-visualização da ligação (og:description), guardada na ligação curta. De momento, não é apresentada em lado nenhum.

—

Não disponíveis nesta API: enviar qualquer um deles devolve 422. Use access.pauseAt para parar o código QR num determinado momento.

string

Nome do código QR, apresentado no painel. Os espaços no início e no fim são removidos; de 1 a 40 caracteres. Se for omitido, o código QR fica sem título.

string

Nota livre sobre o código QR. Até 280 caracteres.

string

O ficheiro de um código QR pdf, image ou video, carregado com o target correspondente. Em vcard, social e multilink, uma imagem de perfil opcional carregada com o target logo. event também o aceita, mas a respetiva página lê a capa a partir de data.fileId. Os outros tipos devolvem 422. Carregue primeiro o ficheiro com Ficheiros. Consulte Ficheiros em códigos QR.

string

Modelo cujo design é aplicado ao novo código QR. Os campos de design que enviar são combinados sobre ele. Um modelo de Branded design ou AI design devolve 422 (art_template_unsupported). Um modelo desconhecido, ou de outro espaço de trabalho, devolve 404.

object

Formas e cores dos pontos e dos cantos. Consulte Personalização.

object

Moldura desenhada à volta do código QR e o respetivo texto de apelo à ação. Consulte Personalização.

object

Logótipo no centro: um logótipo sugerido ou o seu próprio ficheiro carregado com o target logo. Um ficheiro desconhecido, um carregamento não concluído ou um ficheiro de outro target é rejeitado. Consulte Personalização.

object

Agendamento, limite de leituras e proteção por palavra-passe. Consulte 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 número inteiro positivo.

string | null

Palavra-passe que os visitantes têm de introduzir. Enviá-la ativa a proteção.

boolean

Desativa ou volta a ativar a proteção, mantendo a palavra-passe guardada.

boolean

Se o código QR está em pausa. true cria-o já em pausa: as leituras mostram a página de pausa em vez do destino.

Os campos desconhecidos são descartados sem erro. Consulte Não suportado na 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 },
  "…": "…"
}

Repetições e duplicados

Com chave. Com um cabeçalho Idempotency-Key, a resposta é reproduzida durante 24 horas.
Sem chave. Um corpo idêntico enviado no espaço de 30 segundos é tratado como duplicado.
Reproduções. Uma reprodução devolve a resposta guardada com x-idempotent-replay: true. Um novo código QR devolve false.
Em curso. Um segundo pedido enquanto o primeiro ainda está em curso devolve 409 conflict.
Falhas. Uma criação falhada liberta a chave de imediato, pelo que pode repetir com a mesma chave.
Sem garantia. Se a proteção não estiver disponível, as criações são processadas sem proteção.

Consulte também Idempotência.

Obter um código QR

GET /api/v1/qrs/{qrId} Devolve um código QR com a respetiva ligação curta, regras de acesso, design e, nos tipos baseados em ficheiros, o ficheiro.

string

obrigatório

ID do código QR, obtido na 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 de código QR completo.

Atualizar um código QR

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

string

obrigatório

ID do código QR.

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

templateId. Não é aceite.
link. Parcial. O destino atual é mantido se omitir link.url. link.domain e link.key devolvem 422: a ligação curta é o que o código impresso codifica, por isso crie um novo código QR para usar outra.
data. Só é validado face ao tipo resultante quando data ou qrType muda. Mudar qrType sem um data correspondente é rejeitado. Consulte Mudar de tipo.
Design. styles, frameOptions e logoOptions são combinados com o design guardado, pelo que um objeto parcial só altera o que indica. Escolher outro logótipo substitui-o, mas mantém o respetivo tamanho.
access. Cada chave é aplicada quando está presente. null apaga uma regra. As regras de acesso ficam dentro de access: enviá-las dentro de link devolve 422.
archived. Coloca em pausa ou reativa em conjunto o código QR e a ligação curta, tal 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 após a impressão está indicado em Dados do código QR por tipo.

Definir o estado de pausa

PUT /api/v1/qrs/{qrId} Define diretamente o estado de pausa. Pausar e Reativar fazem o mesmo de forma mais legível.

string

obrigatório

ID do código QR.

boolean

obrigatório

true para colocar o código QR em pausa, false para o reativar.

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 código QR

POST /api/v1/qrs/{qrId}/pause O código QR deixa de encaminhar para o destino: as leituras mostram a página de pausa. O código impresso e a ligação curta continuam válidos. Sem corpo de pedido.

string

obrigatório

ID do código QR.

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 código QR

POST /api/v1/qrs/{qrId}/activate Um código QR em pausa volta a encaminhar para o destino. O agendamento e o limite de leituras continuam a aplicar-se. Sem corpo de pedido.

string

obrigatório

ID do código QR.

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 código QR

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

string

obrigatório

ID do código QR a copiar.

Ligação curta. A cópia recebe a sua própria ligação curta, com um slug aleatório no domínio predefinido do espaço de trabalho, e não no domínio do original. As respetivas leituras são contadas em separado.
Título. O título recebe o sufixo (Copy). O resultado não ultrapassa os 40 caracteres: um título longo é encurtado primeiro. Um código QR sem título continua sem título.
Não copiado. As regras de acesso (palavra-passe, agendamento, limite de leituras) e o estado de pausa. A cópia fica sempre ativa.
Ficheiros. Os ficheiros PDF e de imagem, incluindo os de conjuntos e galerias, são copiados, pelo que passam a pertencer à cópia. Os ficheiros de vídeo e os ficheiros de design, como os logótipos, são partilhados 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,
  "…": "…"
}

Eliminar um código QR

DELETE /api/v1/qrs/{qrId} Elimina o código QR e a respetiva ligação curta. Responde com o ID eliminado.

A eliminação é permanente. O código impresso e a ligação curta deixam de funcionar, e o histórico de leituras deixa de estar acessível. Se puder voltar a precisar dele, coloque o código QR em pausa.

string

obrigatório

ID do código QR.

string

ID do código QR eliminado.

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 }

Transferir a imagem de um código QR

GET /api/v1/qrs/{qrId}/download Gera o código QR com o respetivo design e devolve o ficheiro.

string

obrigatório

ID do código QR a gerar, obtido na 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 Branded design ou AI design só é transferido em jpg, png ou pdf.

integer

padrão:"1024"

Tamanho da imagem em píxeis: 1024, 2048 ou 4096. svg e pdf ignoram este valor. Um Branded design ou AI design só é transferido em 1024.

`format`	`Content-Type`	Nome do ficheiro
`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 ficheiro. O nome de ficheiro sugerido está no cabeçalho Content-Disposition, criado a partir do título, ou qr-code num código QR sem título.
Cache. As respostas incluem um ETag e Cache-Control: private, max-age=3600, must-revalidate. Reenvie o ETag em If-None-Match para receber 304 Not Modified quando o código QR não tiver mudado.
Erros. Um formato ou uma resolução não suportados devolvem 400 bad_request. A mensagem de erro indica 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 palavra-passe. As regras omitidas não são alteradas, e null apaga uma regra. O comportamento completo, com exemplos, está em Regras de acesso.

Objetos de design

styles, frameOptions e logoOptions definem as formas dos pontos e dos cantos, as cores, a moldura e o logótipo. Funcionam da mesma forma em códigos QR, modelos e criações em massa. As formas, molduras ou logótipos desconhecidos são rejeitados. Todos os valores aceites e um exemplo completo estão em Personalização.

Problemas comuns

422 ao definir uma palavra-passe, um agendamento ou um limite de leituras

Envie a regra dentro de access e não dentro de link.

422 ao alterar link.domain ou link.key

A ligação curta não pode mudar depois da criação, porque é o que o código impresso codifica. Crie um novo código QR.

422 "Expected … for qrType"

data não corresponde ao formato de qrType. Verifique o tipo em Dados do código QR por tipo.

409 conflict ao criar um código QR

Uma criação idêntica ainda está em curso, ou link.key já está a ser utilizado. Repita quando o primeiro pedido terminar. Com uma Idempotency-Key, a repetição devolve o código QR original.

A transferência é um JPEG e não um PNG

Os parâmetros são format e resolution, e format é jpg por predefinição. Envie format=png.

404 num código QR que vejo no painel

Cada pedido é executado no espaço de trabalho da sua chave de API. Verifique se o código QR pertence a esse espaço de trabalho. Consulte Autenticação.

Dados do código QR por tipo

Personalização

Regras de acesso

​O objeto de código QR

​Listar códigos QR

​Criar um código QR

​Repetições e duplicados

​Obter um código QR

​Atualizar um código QR

​Definir o estado de pausa

​Pausar um código QR

​Reativar um código QR

​Duplicar um código QR

​Eliminar um código QR

​Transferir a imagem de um código QR

​Regras de acesso

​Objetos de design

​Problemas comuns

​Próximos passos

Dados do código QR por tipo

Personalização

Regras de acesso

Estatísticas

O objeto de código QR

Listar códigos QR

Criar um código QR

Repetições e duplicados

Obter um código QR

Atualizar um código QR

Definir o estado de pausa

Pausar um código QR

Reativar um código QR

Duplicar um código QR

Eliminar um código QR

Transferir a imagem de um código QR

Regras de acesso

Objetos de design

Problemas comuns

Próximos passos