Públicos da API e compatibilidade
Quais interfaces do VoiceStudio são públicas, exclusivas do navegador ou nunca destinadas a clientes.
Cada operação do plano de controle pertence a um público. Compartilhar uma fonte OpenAPI não torna uma operação pública.
| Público | Rotas | Quem chama | Publicado aqui? |
|---|---|---|---|
| API pública para desenvolvedores | /v1/* | Credencial de desenvolvedor com escopo | Sim, na projeção Cloud |
| API de borda do site | /v1/marketing/* anônimo revisado | Formulários do próprio site | Não |
| API do painel/BFF | /dashboard/v1/* | Painel com sessão da mesma origem | Não |
| API de operadores | /internal/v1/* revisado | Operadores da plataforma | Não |
| API interna de serviços | Outros /internal/v1/* | Serviços privados | Não |
As rotas de borda do site, de operadores e internas nunca fazem parte da API do cliente. Elas estão ausentes de /cloud-openapi.json, inclusive os esquemas exclusivos delas. Navegadores nunca recebem credencial de desenvolvedor, e clientes públicos nunca usam o cookie de sessão do painel.
Compatibilidade
Nenhum subconjunto de compatibilidade entre produtos foi lançado. Os contratos local 0.5.0 e de prévia Cloud 1.0.0 têm POST /v1/audio/transcriptions, mas campos, autenticação, comportamento de Artifact e Job, tempos limite e erros não são declarados intercambiáveis. Os testes comportamentais de #71 precisam passar para um par definido de versões. Até lá, uma rota com o mesmo nome é sobreposição, não compatibilidade.
Lançamento do Cloud
Publicar um servidor Cloud ativo no documento OpenAPI ou em exemplos executáveis é uma etapa de lançamento. Requer, nesta ordem:
- DNS e TLS de produção verificados.
- Testes básicos de autenticação, roteamento público e falhas seguras para clientes.
- Verificações de compatibilidade e reversão de #71 para as versões exatas.
- Uma projeção regenerada que não diga mais
unavailable.
A reversão remove o servidor ativo. Jobs, Artifacts e registros de idempotência duráveis permanecem como estão.