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

# Personalização

> Estilize QR codes pela API: formatos de pontos e cantos, cores, molduras e logos.

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

Estilize um QR code com os objetos opcionais `styles`, `frameOptions` e `logoOptions` ao criá-lo ou atualizá-lo. Todos os campos são opcionais, e os padrões valem para tudo o que você omitir.

Os mesmos três objetos funcionam em [QR codes](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md), [templates](https://docs.getqr.com/pt-br/api/endpoints/templates.md) e [criações em massa](https://docs.getqr.com/pt-br/api/endpoints/bulk-qr-creations.md). Formatos, molduras ou logos desconhecidos são rejeitados com `422`.

## Exemplo de objeto de design

```json theme={null}
{
  "styles": {
    "dotsOptions": { "type": "rounded", "color": "#000000" },
    "backgroundOptions": { "color": "#ffffff" },
    "cornersSquareOptions": { "type": "dot", "color": "#000000" },
    "cornersDotOptions": { "type": "dot", "color": "#000000" }
  },
  "frameOptions": { "id": "card", "text": "Scan me!", "color": "#000000", "textColor": "#ffffff" },
  "logoOptions": { "type": "suggested", "id": "logo-google", "scalePercent": 25 }
}
```

Envie-o junto com o restante do QR code:

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" } },
    "frameOptions": { "id": "card", "text": "Scan me!" },
    "logoOptions": { "type": "suggested", "id": "logo-website-3" }
  }'
```

## Estilos

O objeto `styles` define os formatos e as cores do padrão.

| Campo | Valores |
| - | - |
| `dotsOptions.type` | Formato dos pontos do corpo: `square`, `dots`, `rounded`, `classy`, `classy-rounded`, `extra-rounded` |
| `cornersSquareOptions.type` | Formato do quadrado de canto (moldura do olho): `square`, `rounded`, `dot`, `classy-rounded` |
| `cornersDotOptions.type` | Formato do ponto de canto (pupila do olho): `square`, `dot`, `dots`, `rounded`, `classy` |
| `dotsOptions.color` | Cor do primeiro plano. Padrão: `#000000`. |
| `backgroundOptions.color` | Cor do fundo. Padrão: `#ffffff`. |
| `cornersSquareOptions.color`, `cornersDotOptions.color` | Aceitos, mas sem efeito: os cantos sempre usam `dotsOptions.color`. |

* **Cores.** Apenas valores hexadecimais: `#RGB` ou `#RRGGBB`.
* **Correção de erros.** Sempre `Q`, e não é um parâmetro de entrada. Enviar `styles.qrOptions` retorna `422`.
* **Designs Branded e com IA.** Não podem ser definidos pela API. Enviar `styles.logoQrArt` retorna `422`.
* **Conteúdo.** `styles.data` é ignorado. A imagem sempre codifica o conteúdo do QR code.

> [!TIP]
>
> Mantenha contraste suficiente entre as cores do primeiro plano e do fundo, com um primeiro plano escuro sobre um fundo claro. Códigos com pouco contraste podem não ser lidos. Veja [Cores](https://docs.getqr.com/pt-br/design/colors.md).

## Molduras

O objeto `frameOptions` adiciona ao redor do QR code uma moldura decorativa com uma chamada para ação.

| Campo | Descrição |
| - | - |
| `id` | Obrigatório quando você envia `frameOptions`. O tipo de moldura, das listas abaixo. `none` significa sem moldura. |
| `text` | Texto da chamada para ação, até 12 caracteres. Padrão: `Scan me!`. |
| `color` | Cor da moldura, em hexadecimal. |
| `textColor` | Cor do texto, em hexadecimal. Precisa ser diferente de `color` quando a moldura mostra um texto, a menos que o par seja uma das predefinições de cor da própria moldura. |
| `borderColor` | Cor da borda, em hexadecimal. |
| `fingerPrintColor` | Cor de destaque do ícone da moldura, em hexadecimal. |

> [accordion] Molduras gerais
>
> `none`, `card`, `card-1`, `card-2`, `card-3`, `card-4`, `card-5`, `card-7`, `card-8`, `card-9`, `card-10`, `card-11`, `card-12`, `card-13`, `card-14`, `card-15`, `card-hor`, `wreath`, `envelope`, `waitress`, `coffee-cup`, `scooter`, `clipboard`
>
> `card-hor` não mostra texto.

> [accordion] Molduras por tipo de QR code
>
> | Tipo | Molduras com texto | Molduras sem texto |
> | - | - | - |
> | App Link | `app-3` | `app-1`, `app-2` |
> | vCard | `contact-1`, `contact-5` | `contact-2`, `contact-3`, `contact-4` |
> | E-mail | `email-1` | `email-2`, `email-3`, `email-4`, `email-5` |
> | Feedback | — | `feedback-1`, `feedback-2`, `feedback-3`, `feedback-4`, `feedback-5` |
> | Image | — | `image-1`, `image-2`, `image-3`, `image-4`, `image-5`, `image-6` |
> | Localização | `location-3` | `location-1`, `location-2`, `location-4`, `location-5`, `location-6` |
> | Multi-Link | `multilink-3` | `multilink-1`, `multilink-2` |
> | Pagamento | — | `payment-1`, `payment-2`, `payment-3`, `payment-4`, `payment-5` |
> | PDF | `pdf-1` | `pdf-2`, `pdf-3`, `pdf-4` |
> | SMS | `sms-3`, `sms-5`, `sms-7` | `sms-1`, `sms-2`, `sms-4`, `sms-6` |
> | Social Media | `social-3` | `social-1`, `social-2`, `social-4` |
> | Video | `video-1`, `video-3` | `video-2`, `video-4`, `video-5`, `video-6` |
> | Website | `website-1` | `website-2`, `website-3`, `website-4`, `website-5` |
> | WhatsApp | `whatsapp-2` | `whatsapp-1`, `whatsapp-3`, `whatsapp-4` |
> | WiFi | — | `wifi-1`, `wifi-2`, `wifi-3`, `wifi-4` |
>
> Qualquer moldura funciona com qualquer tipo de QR code. O agrupamento é o mesmo do painel.

Molduras sem texto não têm campo de chamada para ação no painel, e a regra de que `textColor` deve ser diferente de `color` não se aplica a elas.

## Logos

O objeto `logoOptions` coloca um logo no centro do QR code. Defina `type` para escolher o tipo de logo.

### Logo sugerido

Defina `type` como `suggested` e escolha um `id` do catálogo. Use `logo-none` para nenhum logo.

```json theme={null}
{ "logoOptions": { "type": "suggested", "id": "logo-instagram", "scalePercent": 25 } }
```

> [accordion] Todos os IDs de logos sugeridos
>
> `logo-none`, `logo-website-3`, `logo-website-4`, `logo-link`, `logo-pdf-1`, `logo-pdf-2`, `logo-pdf-3`, `logo-picture-1`, `logo-picture-2`, `logo-picture-3`, `logo-picture-5`, `logo-picture-7`, `logo-picture-8`, `logo-video-1`, `logo-video-5`, `logo-whatsapp-1`, `logo-whatsapp-2`, `logo-whatsapp`, `logo-wifi-1`, `logo-wifi-2`, `logo-wifi-3`, `logo-wifi`, `logo-airbnb`, `logo-apple`, `logo-binance`, `logo-bitcoin`, `logo-bolt-food`, `logo-booking`, `logo-facebook`, `logo-glovo`, `logo-google`, `logo-google-maps`, `logo-google-play`, `logo-instagram`, `logo-linkedin`, `logo-location`, `logo-mail`, `logo-paypal`, `logo-stripe`, `logo-venmo`, `logo-cashapp`, `logo-braintree`, `logo-square`, `logo-verifone`, `logo-google-pay`, `logo-apple-pay`, `logo-klarna`, `logo-ayden`, `logo-giropay`, `logo-cartes-bancaires`, `logo-restaurant`, `logo-scan-me`, `logo-tripadvisor`, `logo-trustpilot`, `logo-uber-eats`, `logo-youtube`, `logo-spotify`, `logo-spotify-black`

### Seu próprio logo

**1. Envie a imagem**

Registre-a com [Arquivos](https://docs.getqr.com/pt-br/api/endpoints/files.md) usando `"target": "logo"` e depois envie o arquivo para a `uploadUrl` retornada.

**2. Referencie o arquivo**

Defina `type` como `uploaded` e `fileId` como o `fileId` retornado. `fileId` é obrigatório e precisa ser um ID retornado pelo endpoint Files.

```json theme={null}
{ "logoOptions": { "type": "uploaded", "fileId": "file_7bQ2xR9mKp", "scalePercent": 35 } }
```

Um arquivo desconhecido, um upload não concluído ou um arquivo enviado para outro target é rejeitado.

### Tamanho do logo

`scalePercent` define o tamanho do logo como porcentagem do QR code. Ele aceita um número inteiro de 15 a 45. O padrão é 25. Outros valores, incluindo proporções como `0.25`, retornam `422`.

## Atualizar um design

* **Atualizações parciais.** Em [Atualizar um QR code](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md#atualizar-um-qr-code), `styles`, `frameOptions` e `logoOptions` são mesclados ao design armazenado. Um objeto parcial altera apenas o que ele menciona.
* **Trocar o logo.** Escolher outro logo substitui o armazenado, mas mantém o `scalePercent` dele.
* **Templates.** Com `templateId` na criação, os campos que você envia são mesclados por cima do design do template. Veja [Templates](https://docs.getqr.com/pt-br/api/endpoints/templates.md).
* **Designs Branded e com IA.** Um QR code com `designKind` `branded` ou `ai` foi criado no painel. A API não pode editar a imagem dele, mas a mantém quando você altera outros campos.
* **Ler um design.** As respostas retornam o design armazenado em `design`, com a mesma estrutura dos campos da requisição, para que você possa enviá-lo de volta.

## Problemas comuns

> [accordion] 422 "Error correction is always Q and is not an input"
>
> Remova `styles.qrOptions` da requisição.

> [accordion] 422 "Frame caption is at most 12 characters"
>
> Encurte `frameOptions.text` para 12 caracteres ou menos.

> [accordion] 422 "Frame caption color must differ from the frame color"
>
> `textColor` e `color` são iguais em uma moldura que mostra texto. Escolha um `textColor` contrastante.

> [accordion] 422 "Logo scale is a whole number from 15 to 45"
>
> Envie `scalePercent` como uma porcentagem inteira, por exemplo `25`, e não `0.25`.

> [accordion] A cor dos cantos não muda
>
> Os cantos sempre usam `dotsOptions.color`. `cornersSquareOptions.color` e `cornersDotOptions.color` não têm efeito.

## Próximos passos

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

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

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

> [card] [Visão geral do design](https://docs.getqr.com/pt-br/design/overview.md)


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