Primeira integração

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

Base URL

https://api.shappire.tools/v1

Desenvolvimento local: http://localhost:8080/v1Todas 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_.

Pré-requisitos

Conta em 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.)

YouTube não é suportado. URLs youtube.com, youtu.be e music.youtube.com falham na resolução. Veja Plataformas.

API keys são credenciais secretasTrate 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

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 · Boas práticas

1. Criar um projeto

Acesse Developer → Projetos
Clique em Novo projeto
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.

2. Criar uma API key

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

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

3. Guardar a API key com segurança

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

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

curl https://api.shappire.tools/v1/health

Resposta esperada:

{
  "data": {
    "status": "ok",
    "version": "v1"
  }
}

Agora teste com sua chave em GET /platforms:

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:

curl https://api.shappire.tools/v1/platforms \
  -H "X-API-Key: $SHAPPIRE_API_KEY"

Exemplo de item na resposta:

{
  "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.

6. Resolver uma mídia

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

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:

{
  "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"
      }
    ]
  }
}

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.

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.

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:

{
  "data": {
    "job_id": "job_x9y8z7",
    "status": "queued"
  }
}

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

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.

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:

{
  "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:

curl -L -OJ "URL_ASSINADA_DA_RESPOSTA"

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

11. Tratar erros

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

{
  "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.

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.

Começar

Integração

Exemplos de código

Tutoriais

Referência

Pré-requisitos

Arquitetura correta

Arquitetura incorreta

Onde armazenar

1. Criar um projeto

2. Criar uma API key

3. Guardar a API key com segurança

4. Testar autenticação

5. Consultar plataformas suportadas

6. Resolver uma mídia

7. Escolher um formato

8. Enfileirar o download (criar job)

9. Consultar status do job (polling)

10. Obter o resultado e baixar

11. Tratar erros

12. Mesmo fluxo em outras linguagens

Próximos passos

​Pré-requisitos

​Arquitetura correta

​Arquitetura incorreta

​Onde armazenar

​1. Criar um projeto

​2. Criar uma API key

​3. Guardar a API key com segurança

​4. Testar autenticação

​5. Consultar plataformas suportadas

​6. Resolver uma mídia

​7. Escolher um formato

​8. Enfileirar o download (criar job)

​9. Consultar status do job (polling)

​10. Obter o resultado e baixar

​11. Tratar erros

​12. Mesmo fluxo em outras linguagens

​Próximos passos

Pré-requisitos

Arquitetura correta

Arquitetura incorreta

Onde armazenar

1. Criar um projeto

2. Criar uma API key

3. Guardar a API key com segurança

4. Testar autenticação

5. Consultar plataformas suportadas

6. Resolver uma mídia

7. Escolher um formato

8. Enfileirar o download (criar job)

9. Consultar status do job (polling)

10. Obter o resultado e baixar

11. Tratar erros

12. Mesmo fluxo em outras linguagens

Próximos passos