---
title: Migrar tokens legados
description: Transição das integrações de servidor para chaves com permissões e aplicativos limitados.
---
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.