> ## 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.

# Template

> Salva design riutilizzabili per i QR code e applicali ai nuovi QR code.

> [!NOTE]
>
> L'API di GetQR è in beta ed è disponibile per alcuni workspace selezionati. I dettagli possono cambiare prima del rilascio generale.

Un template salva un design riutilizzabile: `styles`, `frameOptions` e `logoOptions`. Non contiene mai contenuti né link. I template sono condivisi da tutti i membri del workspace.

| Metodo | Percorso | Descrizione |
| - | - | - |
| `GET` | `/api/v1/templates` | [Elenca i template](#elenca-i-template) |
| `POST` | `/api/v1/templates` | [Crea un template](#crea-un-template) |
| `GET` | `/api/v1/templates/{templateId}` | [Ottieni un template](#ottieni-un-template) |
| `PATCH` | `/api/v1/templates/{templateId}` | [Aggiorna un template](#aggiorna-un-template) |
| `DELETE` | `/api/v1/templates/{templateId}` | [Elimina un template](#elimina-un-template) |
| `POST` | `/api/v1/templates/{templateId}/duplicate` | [Duplica un template](#duplica-un-template) |

## Applica un template

Passa `templateId` quando [crei un QR code](https://docs.getqr.com/it/api/endpoints/qr-codes.md). Il design del template viene applicato al nuovo QR code. Gli oggetti di design che invii nella stessa richiesta vengono uniti sopra di esso.

* **Copiato, non collegato.** Il QR code conserva una propria copia del design. Modificare o eliminare il template in seguito non lo cambia.
* **Solo design personalizzati.** Un template con `designKind` `branded` o `ai` non può essere applicato tramite l'API e restituisce `422` (`art_template_unsupported`).
* **Solo il tuo workspace.** Un template sconosciuto, o di un altro workspace, restituisce `404`.

## Header

**Authorization** `string` *required*

`Bearer` seguito dalla tua chiave API. Consulta [Autenticazione](https://docs.getqr.com/it/api/authentication.md).

**Content-Type** `string`

`application/json`. Obbligatorio nelle richieste con un corpo.

## L'oggetto template

**id** `string`

ID del template, ad esempio `qrt_8Hs2mQvKpLd4RtYw`.

**name** `string`

Nome mostrato quando scegli un template.

**designKind** `string`

Sola lettura. `custom` è un design che l'API può modificare completamente. `branded` e `ai` sono un design Branded o un design AI creato nella dashboard: la sua immagine non può essere modificata tramite l'API e viene mantenuta quando modifichi gli altri campi di design.

**design** `object`

Il design salvato. Ogni campo ha la stessa struttura del campo della richiesta con lo stesso nome, così puoi reinviarlo.

**properties**

**styles** `object | null`

Forme e colori di punti e angoli.

**frameOptions** `object | null`

Cornice attorno al QR code e testo del suo invito all'azione.

**logoOptions** `object | null`

Logo al centro.

**createdAt** `string`

Data di creazione, ISO 8601.

**updatedAt** `string`

Data dell'ultimo aggiornamento, ISO 8601.

## Elenca i template

`GET /api/v1/templates`

Restituisce i template del tuo workspace, dal più recente. L'elenco è paginato: consulta [Paginazione](https://docs.getqr.com/it/api/introduction.md#paginazione).

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

Pagina da restituire, 1 o superiore.

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

Risultati per pagina, da 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 }
}
```

## Crea un template

`POST /api/v1/templates`

Salva un nuovo design. Risponde `201 Created`. I campi di design vengono verificati sui cataloghi riportati in [Personalizzazione](https://docs.getqr.com/it/api/guides/customization.md), quindi una forma, una cornice o un logo sconosciuto viene rifiutato con `422`.

**name** `string` *required*

Nome mostrato quando scegli un template, da 1 a 40 caratteri.

**styles** `object`

Forme e colori di punti e angoli. Consulta [Personalizzazione](https://docs.getqr.com/it/api/guides/customization.md).

**frameOptions** `object`

Cornice disegnata attorno al QR code e testo del suo invito all'azione. Consulta [Personalizzazione](https://docs.getqr.com/it/api/guides/customization.md).

**logoOptions** `object`

Logo posizionato al centro: un logo suggerito, oppure un tuo file caricato con il target `logo` di [File](https://docs.getqr.com/it/api/endpoints/files.md). Consulta [Personalizzazione](https://docs.getqr.com/it/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"
}
```

## Ottieni un template

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

**templateId** `string` *required*

ID del template. Prendilo dalla risposta dell'elenco o della creazione.

```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"
}
```

## Aggiorna un template

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

Invia solo i campi che vuoi modificare. Gli oggetti di design vengono uniti al design salvato, quindi uno `styles` parziale mantiene il resto. I QR code già creati dal template mantengono il design con cui sono stati creati.

**templateId** `string` *required*

ID del template.

**name** `string`

Nuovo nome, da 1 a 40 caratteri.

**styles** `object`

Modifiche allo stile, unite allo `styles` salvato.

**frameOptions** `object`

Modifiche alla cornice, unite alla cornice salvata.

**logoOptions** `object`

Modifiche al logo, unite al logo salvato.

```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"
}
```

## Elimina un template

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

Elimina il template. I QR code creati a partire da esso mantengono il loro design.

**templateId** `string` *required*

ID del 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 }
```

## Duplica un template

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

Crea una copia chiamata `<name> copy`, con un proprio ID e un design indipendente che puoi modificare liberamente. Non richiede un corpo della richiesta. Risponde `201 Created`.

**templateId** `string` *required*

ID del template da copiare.

```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"
}
```

## Problemi comuni

> [accordion] 404 "QR template not found."
>
> Il `templateId` non corrisponde a un template del tuo workspace. Prendilo da [Elenca i template](#elenca-i-template).

> [accordion] 422 durante la creazione o l'aggiornamento di un template
>
> Un campo di design non corrisponde ai cataloghi, ad esempio un tipo di punto, una cornice o un logo suggerito sconosciuto. Il messaggio indica il campo. Consulta [Personalizzazione](https://docs.getqr.com/it/api/guides/customization.md).

> [accordion] 422 art\_template\_unsupported durante la creazione di un QR code
>
> Il template usa un design Branded o un design AI. Applica invece un template con `designKind` `custom`.

## Passaggi successivi

> [card] [Personalizzazione](https://docs.getqr.com/it/api/guides/customization.md)

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

> [card] [Template nell'app](https://docs.getqr.com/it/templates/save-template.md)

> [card] [File](https://docs.getqr.com/it/api/endpoints/files.md)


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