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

# Boas práticas

> Segurança, performance e operação em produção

<Danger>
  **API keys são credenciais secretas**

  Trate `shp_live_...` como senha de banco de dados. Qualquer pessoa com a chave pode consumir sua cota e enfileirar downloads no seu projeto.

  **Nunca:**

  * commite no Git (`.env` no `.gitignore`)
  * coloque em código frontend (React, Vue, Svelte, Next.js client components)
  * envie em apps mobile sem proxy backend
  * armazene em `localStorage`, `sessionStorage` ou cookies do browser
  * exponha em URLs, query strings ou repositórios públicos
</Danger>

## Arquitetura correta

```
Browser / App
      ↓
Backend do cliente (seu servidor)
      ↓  X-API-Key: shp_live_... (variável de ambiente)
Shappire API
```

O usuário final **nunca** vê a chave. Seu backend valida a sessão do usuário e chama a Shappire server-to-server.

## Arquitetura incorreta

```
Browser / App
      ↓  X-API-Key: shp_live_... (hardcoded ou em bundle JS)
Shappire API
```

Qualquer usuário pode abrir DevTools → Network, copiar a chave e usar fora do seu controle.

## Onde armazenar

| Ambiente                | Recomendação                                  |
| ----------------------- | --------------------------------------------- |
| Servidor Node/Python/Go | `process.env.SHAPPIRE_API_KEY` / `os.environ` |
| Docker / K8s            | Secret do orchestrator                        |
| CI/CD                   | Secret do pipeline (GitHub Actions, etc.)     |
| Local                   | `.env` (nunca commitado)                      |

Veja também: [Chaves de API](/pages/guides/authentication) · [Boas práticas](/pages/guides/boas-praticas)

## Segurança

* Use `process.env.SHAPPIRE_API_KEY` (ou equivalente) — nunca hardcode
* Secret manager em produção (AWS Secrets Manager, Vault, Doppler)
* Uma API key por serviço/ambiente
* Rotacione chaves periodicamente
* Mascare chaves em logs: `shp_live_...abc1`

## Performance

* Faça resolve **uma vez** e reutilize `data.id` como `media_id` dentro do TTL (1h)
* Cache `GET /platforms` por 5 min (a API já envia `Cache-Control: max-age=300`)
* Polling com intervalo de 2–5 s — não consulte jobs a cada 500 ms
* Baixe `download_url` assim que o job completar

## Operação

* Registre `X-Request-Id` em todos os erros
* Monitore taxa de `429` e jobs `failed`
* Alerta se fila de jobs crescer sem conclusão
* Armazene arquivos no seu storage — URLs assinadas expiram (TTL 1h)

## Escopos mínimos

| Serviço            | Escopos          |
| ------------------ | ---------------- |
| Preview/metadata   | `media:resolve`  |
| Worker de download | `media:download` |
| Full stack         | ambos            |

## Erros recuperáveis

| Código                       | Retentar?                    |
| ---------------------------- | ---------------------------- |
| `rate_limit_exceeded`        | Sim, após reset              |
| `daily_limit_exceeded`       | Sim, após meia-noite UTC     |
| `internal_error`             | Sim, com backoff             |
| `concurrency_limit_exceeded` | Sim, após job atual terminar |
| `invalid_url`                | Não                          |
| `unsupported_platform`       | Não                          |
| `media_not_found`            | Novo resolve                 |

## Checklist de produção

* [ ] `SHAPPIRE_API_KEY` em variável de ambiente
* [ ] Backend como proxy (sem chave no cliente)
* [ ] Fila para downloads (respeitar limite de 2 jobs simultâneos)
* [ ] Polling com timeout máximo
* [ ] Download imediato após `completed`
* [ ] Logs com `request_id`
* [ ] YouTube tratado como não suportado no seu produto