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

# Visão geral

> Base URL, chave de API e formato das respostas

A Shappire Media API cobre resolução de metadados de mídia, enfileiramento de downloads assíncronos e consulta de jobs — tudo sob o prefixo `/v1`.

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

## Endpoints disponíveis

| Método | Rota              | Auth    | Escopo           |
| ------ | ----------------- | ------- | ---------------- |
| `GET`  | `/health`         | Pública | —                |
| `GET`  | `/platforms`      | API key | —                |
| `POST` | `/media/resolve`  | API key | `media:resolve`  |
| `POST` | `/media/download` | API key | `media:download` |
| `GET`  | `/jobs/{jobId}`   | API key | —                |

Lista detalhada: [Rotas da API](/api-reference/escopo-api-publica).

## Autenticação (API key)

Crie a chave no dashboard: [Developer → Projetos → API Keys](https://shappire.tools/developer/projects).

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

`Authorization: Bearer shp_live_...` também é aceito. Prefira `X-API-Key` em integrações novas.

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

## Envelope de resposta

Sucesso — sempre `{ "data": ... }`:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "data": {
    "id": "med_abc123",
    "platform": "tiktok",
    "title": "Exemplo de vídeo",
    "formats": [
      {
        "id": "video_best",
        "type": "video",
        "quality": "best",
        "container": "mp4"
      }
    ]
  }
}
```

Erro (rotas `/v1/*`):

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid.",
    "request_id": "req_7f3a2b1c"
  }
}
```

O header `X-Request-Id` repete o `request_id` quando presente.

### Campos omitidos

A API pública não expõe: identificadores internos de projeto, payloads brutos do engine de resolução nem metadados operacionais do worker.

### Resolve → Download

O resolve retorna `data.id` (ex. `med_abc123`). Use esse valor como `media_id` no download. TTL padrão: **1 hora**.

## Rate limiting

| Limite             | Valor padrão      |
| ------------------ | ----------------- |
| Requisições/minuto | 60 por API key    |
| Requisições/dia    | 1.000 por projeto |
| Jobs simultâneos   | 2 por projeto     |

Veja [Rate limiting](/api-reference/rate-limiting).

## Exemplo rápido (multi-linguagem)

<CodeGroup>
  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  // Requer SHAPPIRE_API_KEY em process.env
  import { resolveMedia, enqueueDownload, waitForJob } from './shappire.js';

  const url = 'https://www.tiktok.com/@user/video/7123456789012345678';

  const media = await resolveMedia(url);
  const format = media.formats.find((f) => f.id === 'video_best')?.id ?? 'video_best';
  const jobId = await enqueueDownload(media.id, format);
  const job = await waitForJob(jobId);

  console.log(job.result.download_url);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  import os
  # Requer SHAPPIRE_API_KEY em os.environ
  url = "https://www.tiktok.com/@user/video/7123456789012345678"

  media = resolve_media(url)
  job_id = enqueue_download(media["id"], "video_best")
  job = wait_for_job(job_id)

  print(job["result"]["download_url"])
  ```

  ```go Go theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  media, err := ResolveMedia("https://www.tiktok.com/@user/video/7123456789012345678")
  if err != nil {
  	log.Fatal(err)
  }

  mediaID, _ := media["id"].(string)
  jobID, err := EnqueueDownload(mediaID, "video_best")
  if err != nil {
  	log.Fatal(err)
  }

  job, err := WaitForJob(jobID)
  if err != nil {
  	log.Fatal(err)
  }
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # 1. Resolver
  MEDIA=$(curl -s 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"}')

  MEDIA_ID=$(echo "$MEDIA" | jq -r '.data.id')

  # 2. Enfileirar
  JOB=$(curl -s -X POST https://api.shappire.tools/v1/media/download \
    -H "X-API-Key: $SHAPPIRE_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"media_id\":\"$MEDIA_ID\",\"format\":\"video_best\"}")

  JOB_ID=$(echo "$JOB" | jq -r '.data.job_id')

  # 3. Polling
  curl https://api.shappire.tools/v1/jobs/$JOB_ID \
    -H "X-API-Key: $SHAPPIRE_API_KEY"
  ```
</CodeGroup>

## Mapa rápido

<Columns cols={2}>
  <Card title="Primeira integração" icon="rocket" href="/pages/guides/primeira-integracao">
    Guia passo a passo completo
  </Card>

  <Card title="Chaves de API" icon="key" href="/pages/guides/authentication">
    Segurança e autenticação
  </Card>

  <Card title="Plataformas" icon="globe" href="/pages/guides/plataformas">
    Suportadas e exclusões (YouTube)
  </Card>

  <Card title="Resolver mídia" icon="search" href="/pages/guides/resolver-midia">
    POST /media/resolve
  </Card>

  <Card title="Download assíncrono" icon="download" href="/pages/guides/download-assincrono">
    Jobs e polling
  </Card>

  <Card title="Exemplos por linguagem" icon="code" href="/pages/guides/exemplos-por-linguagem">
    JS, Python, Go, PHP, Ruby, Java
  </Card>

  <Card title="Erros e códigos" icon="triangle-alert" href="/api-reference/guides/errors">
    Todos os error.code
  </Card>

  <Card title="Worker background" icon="server" href="/tutorials/worker-background">
    Fila + polling + storage
  </Card>
</Columns>