> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Salve designs de QR code reutilizáveis e aplique-os a novos QR codes.

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

Um template guarda um design reutilizável: `styles`, `frameOptions` e `logoOptions`. Ele nunca inclui conteúdo nem link. Os templates são compartilhados por todos no workspace.

| Método | Caminho | Descrição |
| - | - | - |
| `GET` | `/api/v1/templates` | [Listar templates](#listar-templates) |
| `POST` | `/api/v1/templates` | [Criar um template](#criar-um-template) |
| `GET` | `/api/v1/templates/{templateId}` | [Obter um template](#obter-um-template) |
| `PATCH` | `/api/v1/templates/{templateId}` | [Atualizar um template](#atualizar-um-template) |
| `DELETE` | `/api/v1/templates/{templateId}` | [Excluir um template](#excluir-um-template) |
| `POST` | `/api/v1/templates/{templateId}/duplicate` | [Duplicar um template](#duplicar-um-template) |

## Aplicar um template

Passe `templateId` ao [criar um QR code](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md). O design do template é aplicado ao novo QR code. Qualquer um dos três objetos de design enviados na mesma requisição é mesclado por cima dele.

* **Copiado, não vinculado.** O QR code guarda uma cópia própria do design. Editar ou excluir o template depois não o altera.
* **Somente designs personalizados.** Um template com `designKind` `branded` ou `ai` não pode ser aplicado pela API e retorna `422` (`art_template_unsupported`).
* **Somente o seu workspace.** Um template desconhecido, ou de outro workspace, retorna `404`.

## Cabeçalhos

**Authorization** `string` *required*

`Bearer` seguido da sua chave de API. Veja [Autenticação](https://docs.getqr.com/pt-br/api/authentication.md).

**Content-Type** `string`

`application/json`. Obrigatório em requisições com corpo.

## O objeto template

**id** `string`

ID do template, por exemplo `qrt_8Hs2mQvKpLd4RtYw`.

**name** `string`

Nome exibido na hora de escolher um template.

**designKind** `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 imagem dele não pode ser editada pela API, e ela é mantida quando você altera os outros campos de design.

**design** `object`

O design armazenado. Cada campo tem a mesma estrutura do campo de mesmo nome na requisição, para que você possa enviá-lo de volta.

**properties**

**styles** `object | null`

Formatos e cores dos pontos e dos cantos.

**frameOptions** `object | null`

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

**logoOptions** `object | null`

Logo no centro.

**createdAt** `string`

Data de criação, ISO 8601.

**updatedAt** `string`

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

## Listar templates

`GET /api/v1/templates`

Retorna os templates do seu workspace, dos mais novos para os mais antigos. A lista é paginada: veja [Paginação](https://docs.getqr.com/pt-br/api/introduction.md#paginação).

**page** `integer` (default: 1)

Página a retornar, 1 ou mais.

**pageSize** `integer` (default: 100)

Resultados por página, de 1 a 100.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/templates?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "qrt_8Hs2mQvKpLd4RtYw",
      "name": "Brand blue",
      "designKind": "custom",
      "design": {
        "styles": {
          "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
          "backgroundOptions": { "color": "#FFFFFF" }
        },
        "frameOptions": null,
        "logoOptions": null
      },
      "createdAt": "2026-07-20T09:12:00.000Z",
      "updatedAt": "2026-07-20T09:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}
```

## Criar um template

`POST /api/v1/templates`

Salva um novo design. Responde `201 Created`. Os campos de design são validados com os catálogos de [Personalização](https://docs.getqr.com/pt-br/api/guides/customization.md), então um formato, uma moldura ou um logo desconhecido é rejeitado com `422`.

**name** `string` *required*

Nome exibido na hora de escolher um template, de 1 a 40 caracteres.

**styles** `object`

Formatos e cores dos pontos e dos cantos. Veja [Personalização](https://docs.getqr.com/pt-br/api/guides/customization.md).

**frameOptions** `object`

Moldura desenhada ao redor do QR code e o texto da chamada para ação dela. Veja [Personalização](https://docs.getqr.com/pt-br/api/guides/customization.md).

**logoOptions** `object`

Logo colocado no centro: um logo sugerido ou seu próprio arquivo enviado com o target `logo` de [Arquivos](https://docs.getqr.com/pt-br/api/endpoints/files.md). Veja [Personalização](https://docs.getqr.com/pt-br/api/guides/customization.md).

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/templates" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand blue",
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    }
  }'
```

```json 201 theme={null}
{
  "id": "qrt_8Hs2mQvKpLd4RtYw",
  "name": "Brand blue",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-07-20T09:12:00.000Z",
  "updatedAt": "2026-07-20T09:12:00.000Z"
}
```

## Obter um template

`GET /api/v1/templates/{templateId}`

**templateId** `string` *required*

ID do template. Pegue-o na resposta da listagem ou da criação.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "qrt_8Hs2mQvKpLd4RtYw",
  "name": "Brand blue",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-07-20T09:12:00.000Z",
  "updatedAt": "2026-07-20T09:12:00.000Z"
}
```

## Atualizar um template

`PATCH /api/v1/templates/{templateId}`

Envie apenas os campos que você quer alterar. Os objetos de design são mesclados ao design armazenado, então um `styles` parcial mantém o restante. Os QR codes já criados a partir do template mantêm o design com que foram criados.

**templateId** `string` *required*

ID do template.

**name** `string`

Novo nome, de 1 a 40 caracteres.

**styles** `object`

Alterações de estilo, mescladas ao `styles` armazenado.

**frameOptions** `object`

Alterações da moldura, mescladas à moldura armazenada.

**logoOptions** `object`

Alterações do logo, mescladas ao logo armazenado.

```bash cURL theme={null}
curl -X PATCH "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Brand blue (2026)" }'
```

```json 200 theme={null}
{
  "id": "qrt_8Hs2mQvKpLd4RtYw",
  "name": "Brand blue (2026)",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-07-20T09:12:00.000Z",
  "updatedAt": "2026-08-14T09:00:00.000Z"
}
```

## Excluir um template

`DELETE /api/v1/templates/{templateId}`

Exclui o template. Os QR codes criados a partir dele mantêm o design.

**templateId** `string` *required*

ID do template.

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{ "id": "qrt_8Hs2mQvKpLd4RtYw", "deleted": true }
```

## Duplicar um template

`POST /api/v1/templates/{templateId}/duplicate`

Cria uma cópia chamada `<name> copy`, com ID próprio e um design independente que você pode editar livremente. Não recebe corpo de requisição. Responde `201 Created`.

**templateId** `string` *required*

ID do template a copiar.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw/duplicate" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 201 theme={null}
{
  "id": "qrt_2Kd9pLm4Xs7BnVcQ",
  "name": "Brand blue copy",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-08-14T09:30:00.000Z",
  "updatedAt": "2026-08-14T09:30:00.000Z"
}
```

## Problemas comuns

> [accordion] 404 "QR template not found."
>
> O `templateId` não corresponde a um template do seu workspace. Pegue-o em [Listar templates](#listar-templates).

> [accordion] 422 ao criar ou atualizar um template
>
> Um campo de design não corresponde aos catálogos, por exemplo um tipo de ponto, uma moldura ou um logo sugerido desconhecido. A mensagem informa o campo. Veja [Personalização](https://docs.getqr.com/pt-br/api/guides/customization.md).

> [accordion] 422 art\_template\_unsupported ao criar um QR code
>
> O template usa um design Branded ou um design com IA. Aplique um template com `designKind` `custom`.

## Próximos passos

> [card] [Personalização](https://docs.getqr.com/pt-br/api/guides/customization.md)

> [card] [QR codes](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md)

> [card] [Templates no app](https://docs.getqr.com/pt-br/templates/save-template.md)

> [card] [Arquivos](https://docs.getqr.com/pt-br/api/endpoints/files.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.