Roteiro de prontidão para GA
A plataforma para desenvolvedores da EvoMap está em beta e no ar: OAuth, OpenAPI, modo de teste, APIs de receitas, leituras do catálogo, webhooks, gerenciamento de aplicativos e introspecção para clientes confidenciais já são utilizáveis hoje. GA significa que um desconhecido consegue se servir sozinho a partir do site, integrar sem acompanhamento privado, operar com segurança e obter suporte quando algo quebra.
Esta página acompanha a distância entre utilizável em beta e plataforma aberta qualificada.
Legenda de status
| Status | Significado |
|---|---|
| No ar | Disponível para desenvolvedores externos agora. |
| Beta | Utilizável, mas ainda precisa de exemplos, polimento de UX ou reforço operacional. |
| Planejado | Precisa de design; ainda não é uma capacidade de autoatendimento da plataforma. |
Matriz de capacidades para GA
| Capacidade | Status atual | Alvo para GA | Primeira fatia útil |
|---|---|---|---|
| 1. SDKs em várias linguagens | Planejado | SDKs oficiais de JS/TS, Python e Go gerados a partir da OpenAPI, mais utilitários de OAuth/webhook escritos à mão. | Publicar o beta de @evomap/sdk com construtor de URL OAuth, troca de token, leitura do catálogo, publicação de teste, verificador de webhook e erros tipados. |
| 2. Console unificado do desenvolvedor | Beta | Um único portal para aplicativos, secrets, escopos, versões, uso, chamadas, webhooks, entregas, concessões, faturamento e suporte. | Promover o /dev/portal para dentro do fluxo do /dev; adicionar estados vazios/de erro que digam ao desenvolvedor qual é o próximo passo. |
| 3. Revisão de aplicativo, versões, permissões, instalação por locatário | Beta | Revisão de versão de aplicativo no estilo Feishu, solicitação de escopo, instalação por locatário/organização, consentimento de administrador e histórico de rollback. | Expor no portal as APIs já existentes de solicitação de escopo e de versão de aplicativo, com estado de revisão e changelog. |
| 4. Assinaturas de eventos e replay | Beta | Catálogo de eventos de webhook, assinaturas filtradas, ping, log de entregas, reenvio, replay por id de evento e política de retenção. | Adicionar uma página de detalhe de entrega de primeira classe e um botão de replay; documentar nova tentativa/recuo/retenção. |
| 5. Conjunto amplo de exemplos | Beta | Inícios rápidos, receitas, coleção Postman/Bruno, clientes gerados, verificador de webhook, tratamento de erros e demonstrações em modo de teste. | Lançar os Exemplos mínimos mais projetos de exemplo baixáveis. |
| 6. Explorador de API | Beta | Explorador no navegador guiado pela OpenAPI, com utilitário de autenticação, construtor de requisições, trechos de exemplo e ocultação segura de dados sensíveis. | Reforçar o /dev/docs/41-api-explorer para que ele importe um token localmente sem registrá-lo em log e mostre curl/JS/Python copiáveis. |
| 7. Sistema de códigos de erro | Beta | Catálogo estável de erros com causa, correção, possibilidade de nova tentativa e caminho de escalonamento para suporte. | Criar o errors.md e vincular cada falha comum de invalid_*, insufficient_scope, cota, moderação e idempotência. |
| 8. Marketplace | Planejado | Listagem pública de aplicativos, perfil do desenvolvedor, instalação de aplicativo, escopos mostrados antes do consentimento, avaliações/notas e fluxo de remoção. | Começar com cards curados de aplicativos parceiros vinculados no /dev, não com listagem aberta. |
| 9. Suporte e tickets para desenvolvedores | Planejado | Formulário de suporte, discussão na comunidade, modelos de issue, SLA de contato e escalonamento para incidentes de segurança. | Adicionar /dev/support ou uma página de documentação com GitHub Discussions, e-mail/formulário e os campos de depuração obrigatórios. |
| 10. Página de status e SLA | Planejado | Status público, histórico de incidentes, metas de disponibilidade da API, SLO de entrega de webhooks e avisos de manutenção. | Vincular o /status a partir do /dev e adicionar linhas de status de API/webhook específicas para desenvolvedores. |
| 11. Governança de permissões / autorização de administrador | Beta | Consentimento de administrador para instalações abrangendo a organização, avisos de escopos de alto risco, revisão de menor privilégio e logs de auditoria. | Adicionar no portal um estado explícito de consentimento de administrador e avisos de escopo de alto risco. |
| 12. Isolamento e auditoria de locatários corporativos | Beta | Chaves de API delimitadas por organização/locatário, controles de carteira/gasto, logs de auditoria, SCIM/SSO e garantias de isolamento de dados. | Documentar os limites de agentes/tokens da organização e expor logs de auditoria baixáveis para eventos de aplicativos OAuth. |
O que já está no ar
- Código de Autorização OAuth 2.0 + PKCE (somente
S256). - Descoberta OIDC, userinfo e JWKS.
- Metadados do servidor de autorização OAuth e metadados de recurso protegido.
- Registro Dinâmico de Clientes para clientes públicos somente leitura, quando habilitado.
- Revogação de token e introspecção de token para clientes confidenciais.
- OpenAPI 3.1 em
/openapi.jsone espelho em YAML. - APIs de leitura de receitas / genes / reutilização.
- APIs de rascunho e publicação de receitas, com modo de teste para ciclos de publicação no ambiente de testes.
- Registro de aplicativos, solicitações de escopo, versões de aplicativo, logs de uso/chamadas/atividade e histórico de rotação de secrets.
- Registro de webhooks, assinatura, ping, logs de entrega e reenvio.
- Superfícies de organização e de token de agente para casos de uso corporativos.
Verificações de aceite para GA
Um lançamento pode ser chamado de GA quando isto for verdade:
- Um desenvolvedor novo consegue concluir o Início rápido em menos de 30 minutos sem ajuda privada.
- Primeiro token, primeira leitura do catálogo, publicação de teste, ping de webhook e depuração de erro têm todos exemplos copiáveis.
- O portal mostra status do aplicativo, escopos solicitados, estado de revisão, modo produção/teste, chamadas recentes, cota, falhas de entrega de webhook e próximas ações.
- OpenAPI, descoberta, documentação e implementação seguem alinhados na CI.
- Existem SDKs pelo menos para JS/TS e Python, com Go planejado ou gerado.
- Escopos de alto risco exigem revisão/consentimento de administrador explícitos e são auditáveis.
- Canais de suporte, status, changelog e incidentes são públicos e descobríveis.
- Os sinais de segurança são acionáveis: laços repetidos de clientes desatualizados são deduplicados, para que incidentes reais de reuso de token não fiquem soterrados no ruído.
Roteiro de curto prazo
P0 — fazer desconhecidos terem sucesso
- Manter o
/devcomo porta de entrada pública. - Concluir o Início rápido e os exemplos mínimos.
- Adicionar catálogo de erros e diagnóstico.
- Adicionar aplicativos de exemplo baixáveis em Node/Python.
- Reforçar o tratamento de token e os trechos do explorador de API.
P1 — tornar as integrações operáveis
- UI de detalhe de entrega de webhook e replay.
- Página de suporte ao desenvolvedor e modelo de issue.
- Linhas de status de API/webhook e linguagem de SLA.
- Estados de próxima ação no portal para revisão de aplicativo, solicitações de escopo, cota e webhooks com falha.
- Orientação de tratamento de falha de token de atualização (interromper laços de nova tentativa; forçar novo login).
P2 — construir um ecossistema
- Pacotes de SDK.
- Listagem inicial de Marketplace para aplicativos parceiros curados.
- Fluxo de instalação por locatário/organização e consentimento de administrador.
- Exportação de auditoria e controles de governança corporativa.