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

# Primeira integração

> Do zero ao primeiro download — projeto, API key, resolve, job e URL assinada

Este guia leva você da conta Shappire ao primeiro arquivo baixado via API. Tempo estimado: 15–20 minutos.

<Info>
  **Base URL**

  ```
  https://api.shappire.tools/v1
  ```

  Desenvolvimento local: `http://localhost:8080/v1`

  Todas as rotas da API pública usam esse prefixo. Chaves de produção usam o prefixo `shp_live_`; em ambiente local (não-produção), o prefixo é `shp_test_`.
</Info>

## Pré-requisitos

* Conta em [shappire.tools](https://shappire.tools) com login Google
* `curl` ou Postman no **seu backend** (não no browser do usuário)
* URL pública de mídia suportada (TikTok, Instagram, SoundCloud, etc.)

<Warning>
  **YouTube não é suportado.** URLs `youtube.com`, `youtu.be` e `music.youtube.com` falham na resolução. Veja [Plataformas](/pages/guides/plataformas).
</Warning>

<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)

***

## 1. Criar um projeto

1. Acesse [Developer → Projetos](https://shappire.tools/developer/projects)
2. Clique em **Novo projeto**
3. Dê um nome (ex. `Integração Produção`)

Cada projeto agrupa chaves de API, uso e jobs. Use um projeto por ambiente (dev/staging/prod).

Tutorial visual: [Criar chave de API](/tutorials/api-key).

***

## 2. Criar uma API key

1. Abra o projeto criado
2. Vá em **API Keys** → **Nova API Key**
3. Nome descritivo (ex. `Worker Downloads`)
4. Marque os escopos:
   * `media:resolve` — resolver metadados
   * `media:download` — enfileirar downloads
5. Clique em **Criar**

O secret `shp_live_...` aparece **uma única vez**. Copie agora.

***

## 3. Guardar a API key com segurança

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# Linux / macOS
export SHAPPIRE_API_KEY=shp_live_SUA_CHAVE_AQUI

# Windows PowerShell
$env:SHAPPIRE_API_KEY = "shp_live_SUA_CHAVE_AQUI"
```

Em produção, use secret manager (AWS Secrets Manager, Vault, Doppler) — nunca arquivo versionado.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# .env (adicione ao .gitignore)
SHAPPIRE_API_KEY=shp_live_SUA_CHAVE_AQUI
```

***

## 4. Testar autenticação

Confirme que a chave funciona com o endpoint público de health (não exige auth):

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://api.shappire.tools/v1/health
```

Resposta esperada:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "data": {
    "status": "ok",
    "version": "v1"
  }
}
```

Agora teste com sua chave em `GET /platforms`:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://api.shappire.tools/v1/platforms \
  -H "X-API-Key: $SHAPPIRE_API_KEY"
```

| Status                    | Causa provável                                   |
| ------------------------- | ------------------------------------------------ |
| `401` + `invalid_api_key` | Header ausente, chave errada ou formato inválido |
| `401` + `revoked_api_key` | Chave revogada no dashboard                      |
| `403` + `forbidden`       | Projeto inativo                                  |

***

## 5. Consultar plataformas suportadas

A lista é dinâmica — sempre consulte antes de integrar:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://api.shappire.tools/v1/platforms \
  -H "X-API-Key: $SHAPPIRE_API_KEY"
```

Exemplo de item na resposta:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "id": "tiktok",
  "name": "TikTok",
  "capabilities": ["video", "audio", "metadata"],
  "source": "native"
}
```

| Campo          | Descrição                                               |
| -------------- | ------------------------------------------------------- |
| `id`           | Identificador da plataforma                             |
| `capabilities` | Tipos suportados: `video`, `audio`, `image`, `metadata` |
| `source`       | `native` (resolver próprio) ou `yt-dlp` (fallback)      |

A resposta inclui `Cache-Control: public, max-age=300` — pode cachear por 5 minutos.

Detalhes e exclusões: [Plataformas](/pages/guides/plataformas).

***

## 6. Resolver uma mídia

`POST /media/resolve` analisa a URL e retorna metadados + formatos disponíveis. Requer escopo `media:resolve`.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://api.shappire.tools/v1/media/resolve \
  -H "X-API-Key: $SHAPPIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@user/video/7123456789012345678"}'
```

Resposta típica:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "data": {
    "id": "med_a1b2c3d4",
    "platform": "tiktok",
    "type": "video",
    "title": "Título do vídeo",
    "thumbnail": "https://...",
    "duration": 42,
    "author": {
      "name": "Autor",
      "username": "@user"
    },
    "formats": [
      {
        "id": "video_best",
        "type": "video",
        "quality": "best",
        "container": "mp4"
      },
      {
        "id": "audio_best",
        "type": "audio",
        "quality": "best",
        "container": "mp3"
      }
    ]
  }
}
```

<Info>
  O campo `data.id` (ex. `med_a1b2c3d4`) é o identificador usado como `media_id` no download. TTL padrão: **1 hora** — após isso, `media_not_found`.
</Info>

***

## 7. Escolher um formato

Use um `formats[].id` da resposta do resolve. Os mais comuns:

| `format`     | Uso                       |
| ------------ | ------------------------- |
| `video_best` | Melhor qualidade de vídeo |
| `audio_best` | Apenas áudio (MP3/M4A)    |

Guarde o `data.id` e o `format` escolhido para o próximo passo.

***

## 8. Enfileirar o download (criar job)

`POST /media/download` cria um job assíncrono. Requer escopo `media:download`. Retorna `202 Accepted`.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -X POST https://api.shappire.tools/v1/media/download \
  -H "X-API-Key: $SHAPPIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_id":"med_a1b2c3d4","format":"video_best"}'
```

Resposta:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "data": {
    "job_id": "job_x9y8z7",
    "status": "queued"
  }
}
```

<Note>
  Você também pode enviar `url` + `format` direto, sem resolve prévio. Resolver antes é recomendado para exibir metadados no seu UI e validar formatos.
</Note>

**Limite de concorrência:** máximo **2 jobs** em `queued` ou `processing` por projeto. Exceder retorna `429 concurrency_limit_exceeded`.

***

## 9. Consultar status do job (polling)

`GET /jobs/{jobId}` não exige escopo específico — só chave válida do mesmo projeto.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://api.shappire.tools/v1/jobs/job_x9y8z7 \
  -H "X-API-Key: $SHAPPIRE_API_KEY"
```

Estados possíveis:

| `status`     | Significado                      |
| ------------ | -------------------------------- |
| `queued`     | Aguardando worker                |
| `processing` | Download em andamento            |
| `completed`  | `result.download_url` disponível |
| `failed`     | Ver `error.code`                 |

Faça polling a cada **2–5 segundos** até `completed` ou `failed`. Não consulte mais rápido que isso.

***

## 10. Obter o resultado e baixar

Quando `status` for `completed`:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "data": {
    "id": "job_x9y8z7",
    "status": "completed",
    "progress": 100,
    "platform": "tiktok",
    "requested_format": "video_best",
    "created_at": "2026-09-14T18:00:00.000Z",
    "started_at": "2026-09-14T18:00:02.000Z",
    "completed_at": "2026-09-14T18:00:15.000Z",
    "result": {
      "download_url": "https://...",
      "filename": "video.mp4",
      "mime_type": "video/mp4",
      "size_bytes": null,
      "expires_at": "2026-09-14T19:00:15.000Z"
    }
  }
}
```

Baixe o arquivo antes de `result.expires_at`:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -L -OJ "URL_ASSINADA_DA_RESPOSTA"
```

<Warning>
  URLs assinadas expiram (TTL padrão: 1 hora). Copie o arquivo para seu storage (S3, GCS, etc.) — não trate como link permanente.
</Warning>

***

## 11. Tratar erros

Todas as rotas `/v1/*` retornam erros no formato:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "error": {
    "code": "unsupported_platform",
    "message": "The platform is not supported.",
    "request_id": "req_abc123"
  }
}
```

| Código                       | HTTP | Ação                                     |
| ---------------------------- | ---- | ---------------------------------------- |
| `invalid_api_key`            | 401  | Verifique header e chave                 |
| `forbidden`                  | 403  | Verifique escopos da chave               |
| `media_not_found`            | 404  | `data.id` expirou — faça resolve de novo |
| `unsupported_platform`       | 422  | URL de plataforma não suportada          |
| `unsupported_format`         | 422  | `format` não existe no resolve           |
| `rate_limit_exceeded`        | 429  | Aguarde reset (veja headers)             |
| `concurrency_limit_exceeded` | 429  | Aguarde job atual terminar               |
| `internal_error`             | 500  | Retente com backoff; logue `request_id`  |

Sempre registre `request_id` nos logs do seu servidor. Referência completa: [Erros e códigos](/api-reference/guides/errors).

***

## 12. Mesmo fluxo em outras linguagens

Os passos 4–10 usam `curl` de ponta a ponta. Para clientes prontos em Node.js, Python, Go, PHP, Ruby e Java — com `process.env.SHAPPIRE_API_KEY` — veja [Exemplos por linguagem](/pages/guides/exemplos-por-linguagem).

***

## Próximos passos

* [Chaves de API e segurança](/pages/guides/authentication)
* [Permissões e escopos](/pages/guides/api-permissions)
* [Rate limiting](/api-reference/rate-limiting)
* [Polling e retentativas](/pages/guides/polling-e-retentativas)
* [Boas práticas de produção](/pages/guides/boas-praticas)
* [Exemplos por linguagem](/pages/guides/exemplos-por-linguagem)
* [API Reference → Visão geral](/api-reference/overview)