Migrar tokens legados

A API nova está disponível em produção e homologação. O portal de desenvolvedores é o primeiro consumidor interno da nova API; cada integração pode migrar gradualmente. Os tokens e contratos existentes permanecem compatíveis; as chaves novas não devem ser enviadas às rotas antigas.

Comparação dos contratos

Integração legada	API nova, sob /v1 na base administrativa
Token com acesso ao app	Chave com appIds, permissões e expiração explícitos
POST /links	POST /links, com idempotência
GET /admin/links/{id}	GET /links/{linkId}, com envelope data e ETag
PUT /links/{id}	PATCH /links/{linkId}, com If-Match forte e idempotência
DELETE /links/{id}, resposta JSON	DELETE /links/{linkId}, resposta 204 sem corpo
POST /links/{id}/invalidate-cache	POST /links/{linkId}/resync, estado consultável em /publication
titulo, descricao, urlImage	title, description, imageUrl
dominio, prefixo, slug	domain, prefix, slug
urlDesktop, urlPlayStore, urlAppStore	desktopUrl, playStoreUrl, appStoreUrl
onlyWeb, parametrosPersonalizados	webOnly, parameters
comportamento=automatico|inteligente	behavior=automatic|intelligent
Revisão no corpo/erro legado	ETag em If-Match; revisão antiga retorna 412

appPath, identidade do link e semântica dos grupos continuam compatíveis. As novas mutações usam os serviços de negócio e a mesma fonte SQL, incluindo validação de domínio, templates, classificação, quotas e outbox. O endpoint público de resolução/SDK mantém seu contrato e sua projeção de campos; ele tem finalidade diferente da consulta administrativa autenticada.

Sequência recomendada

1. Identifique no backend os apps, rotas, campos e permissões usados pelo token atual. Não coloque a credencial em aplicativo móvel, JavaScript público ou URL.
2. Use homologação com recursos sintéticos. Emita uma chave nova por integração, com apenas os apps/permissões necessários, pela sessão humana do proprietário. Guarde o segredo em armazenamento seguro; ele aparece uma única vez.
3. Troque a base, adapte envelopes/status, codifique o ID opaco nas URLs e implemente paginação por cursor. Consulte o recurso antes de alterar para obter seu ETag.
4. Persista a chave de idempotência junto da intenção de negócio. Repita timeout com os mesmos dados; trate 412 consultando a nova revisão antes de decidir uma nova alteração.
5. Compare leituras e execute a jornada de escrita em homologação. Não duplique gravações antigas e novas da mesma intenção em paralelo: os contratos antigos não compartilham os recibos novos.
6. Em produção, ative consumidores gradualmente, acompanhe erros/quotas/publicação e só então revogue o token antigo. Se precisar reverter antes da revogação, restaure o consumidor conhecido; depois da revogação, emita outra credencial de forma autorizada.

Criar um app pela API nova não emite token legado. Excluir um app permitido revoga seus tokens antigos atomicamente. Criar/rotacionar uma chave nova não revoga outras credenciais nem muda o acesso de integrações existentes. Um retry da emissão confirmada retorna 409 secret_not_replayable, com metadados, sem reexibir o segredo.

Autorização delegada por OAuth virá na Tarefa 2. Um agente não deve receber a chave pessoal ampla do usuário como substituição para esse fluxo.