# SHAPPIRE DOCS

> Documentação oficial da Shappire Media API: resolução de mídia, downloads assíncronos e jobs para integradores.

- [Primeira integração](https://docs.shappire.tools/pages/guides/primeira-integracao.md): Do zero ao primeiro download — projeto, API key, resolve, job e URL assinada
- [Conceitos fundamentais](https://docs.shappire.tools/pages/guides/conceitos.md): Projeto, API key, resolve, job, plataformas e envelope da API
- [Plataformas suportadas](https://docs.shappire.tools/pages/guides/plataformas.md): Hosts suportados, exclusões e lista baseada no yt-dlp
- [Chaves de API](https://docs.shappire.tools/pages/guides/authentication.md): Criar, rotacionar e proteger shp_live_ — header X-API-Key e escopos
- [Permissões da API key](https://docs.shappire.tools/pages/guides/api-permissions.md): Escopos por rota e presets para integrações Shappire
- [Rotas da API pública](https://docs.shappire.tools/api-reference/escopo-api-publica.md): Todas as rotas /v1 disponíveis com chave shp_live_
- [Erros e códigos HTTP](https://docs.shappire.tools/api-reference/guides/errors.md): Envelope de erro da API v1, status comuns e boas práticas
- [Tratamento de erros na prática](https://docs.shappire.tools/pages/guides/tratamento-erros-pratica.md): Padrões de retry, logging e resposta ao usuário
- [Boas práticas](https://docs.shappire.tools/pages/guides/boas-praticas.md): Segurança, performance e operação em produção
- [Exemplos por linguagem](https://docs.shappire.tools/pages/guides/exemplos-por-linguagem.md): Integração completa em JavaScript, Python, Go, PHP, Ruby, Java e cURL
- [Exemplos em JavaScript](https://docs.shappire.tools/pages/guides/exemplos-javascript.md): Integração com fetch, axios e Node.js
- [Exemplos em Python](https://docs.shappire.tools/pages/guides/exemplos-python.md): Integração com requests, httpx e asyncio
- [Exemplos em Go](https://docs.shappire.tools/pages/guides/exemplos-go.md): Cliente HTTP com net/http e tratamento de erros
- [Exemplos em PHP](https://docs.shappire.tools/pages/guides/exemplos-php.md): Integração com cURL, Guzzle e Laravel
- [Exemplos em Ruby](https://docs.shappire.tools/pages/guides/exemplos-ruby.md): Integração com Net::HTTP e Sidekiq
- [Exemplos em Java](https://docs.shappire.tools/pages/guides/exemplos-java.md): HttpClient, Spring Boot e tratamento de erros
- [Criar chave de API](https://docs.shappire.tools/tutorials/api-key.md): Passo a passo no dashboard — acessar Developer, criar, configurar e copiar o secret shp_live_
- [Resolver mídia](https://docs.shappire.tools/pages/guides/resolver-midia.md): Tutorial — extrair metadados, formatos e id de uma URL pública
- [Download assíncrono](https://docs.shappire.tools/pages/guides/download-assincrono.md): Tutorial — enfileirar jobs, polling e URL assinada de download
- [Polling e retentativas](https://docs.shappire.tools/pages/guides/polling-e-retentativas.md): Como aguardar jobs, backoff e idempotência
- [Download do TikTok](https://docs.shappire.tools/tutorials/tiktok-download.md): Baixar vídeos do TikTok sem marca d'água via API
- [Download do Instagram](https://docs.shappire.tools/tutorials/instagram-download.md): Reels, posts e stories públicos via API
- [Extrair áudio](https://docs.shappire.tools/tutorials/extrair-audio.md): MP3/M4A de TikTok, SoundCloud, Vimeo e mais
- [Worker em background](https://docs.shappire.tools/tutorials/worker-background.md): Arquitetura com fila, worker e storage próprio
- [Casos de uso](https://docs.shappire.tools/pages/guides/casos-de-uso.md): Padrões reais de integração com a Shappire Media API
- [Perguntas frequentes](https://docs.shappire.tools/pages/faq/index.md): Respostas sobre API key, plataformas, jobs e exemplos de código
- [Troubleshooting](https://docs.shappire.tools/pages/guides/troubleshooting.md): Problemas comuns na integração com a Shappire Media API
- [Glossário](https://docs.shappire.tools/pages/glossario.md): Termos da API e da plataforma Shappire
- [Visão geral](https://docs.shappire.tools/api-reference/overview.md): Base URL, chave de API e formato das respostas
- [Rate limiting](https://docs.shappire.tools/api-reference/rate-limiting.md): Limites de requisição na API pública Shappire
- [Guia de integração de mídia](https://docs.shappire.tools/api-reference/guides/media.md): Resolver metadados, enfileirar downloads e consultar jobs pela API pública
- [Status da API](https://docs.shappire.tools/api-reference/health/status-da-api.md): Endpoint público — não requer autenticação.
- [Listar plataformas](https://docs.shappire.tools/api-reference/platforms/listar-plataformas.md): Retorna hosts suportados e capacidades. Requer API key válida (sem escopo específico). Resposta cacheável por 5 minutos (Cache-Control). YouTube não é suportado na prática, mesmo que apareça na lista de extratores yt-dlp.
- [Resolver metadados](https://docs.shappire.tools/api-reference/media/resolver-metadados.md): Analisa uma URL pública e retorna id (med_...), título, thumbnail e formatos. Requer escopo media:resolve. O campo data.id é usado como media_id no download. TTL padrão: 1 hora.
- [Enfileirar download](https://docs.shappire.tools/api-reference/media/enfileirar-download.md): Cria job assíncrono de download. Retorna 202 com job_id. Requer escopo media:download. Máximo 2 jobs simultâneos (queued + processing) por projeto.
- [Consultar job](https://docs.shappire.tools/api-reference/jobs/consultar-job.md): Retorna status, progresso e result.download_url quando completed. Requer API key válida do mesmo projeto.

## OpenAPI Specs

- [openapi](/openapi.yaml)