Integrar organização, QR e ciclo de vida

As 29 operações deste marco estão na API isolada https://api.staging.agilink.io/v1. A referência interativa contém os schemas completos. Leia primeiro a semântica do produto.

Criar e associar

Crie /tags, /folders ou /campaigns com appId e name. Campanha aceita utm com as cinco chaves documentadas. Tags/pastas não aceitam UTMs não vazias. Metadados incluem descrição e arquivamento. Listagem tem appId, q, archived=all|true|false, limit e cursor assinado. Atualizações/exclusões exigem ETag forte e UUID v4 de idempotência. Nomes duplicados e remoção com associações retornam 409.

PATCH /links/{linkId} aceita folderId, campaignId, utm e lifecycle, junto dos campos existentes. As associações usam UUID, ou null para retirar. utm substitui o objeto anterior; {} limpa. Não há cópia implícita de UTMs por associação: consulte a campanha e envie a cópia no patch. lifecycle substitui o objeto completo:

{"lifecycle":{"archived":false,"paused":false,"startsAt":"2026-12-01T12:00:00Z","expiresAt":"2027-01-01T00:00:00Z","fallbackUrl":null}}

PUT /links/{linkId}/tags substitui tagIds, até vinte UUIDs únicos, usando a revisão do link. PUT /links/{linkId}/routing-rules substitui rules, até dez regras com IDs únicos e estáveis dentro do link. Ordem é prioridade; campos e exemplos em cada operação. A revisão devolvida é a nova revisão do link, compartilhada com patch/tags/regras/template. Duplicação de link pela operação existente copia campos básicos; organização, disponibilidade, regras e UTMs começam independentes e precisam ser atribuídas explicitamente.

Regras e lifecycle são validados por schema, URLs HTTPS sem credenciais e intervalo início < fim. Persistência e associações são transacionais; outbox no mesmo commit. O histórico tem paginação assinada e campos sanitizados. Excluir um app exige remover suas coleções/configurações dependentes; o histórico administrativo é eliminado com o app.

Buscar e medir

GET /links acrescenta folderId, campaignId, tagId, state=active|paused|scheduled|expired e archived=true|false. Sem filtros, inclui todos. GET /campaigns/{campaignId}/links pagina os links da associação atual. Analytics de eventos aceita campaignId, folderId, tagId e mantém o contrato de período/timezone do A3c. /analytics/campaigns/{campaignId} retorna o mesmo resumo de eventos para aquela campanha. Recovery de tokens não aceita esses filtros e não é somado ao relatório de campanha.

A chave com analytics:read pode consultar a campanha do app concedido, sem obter seus metadados. Chaves de tags/QR precisam das permissões específicas, sem ganho implícito de links:update. Filtros não ampliam o app autorizado. Redução/revogação da credencial é revalidada.

QR binário

GET /links/{linkId}/qr?format=png|svg gera um QR sem persistir. Pode receber size, margin, errorCorrectionLevel, dark, light, respeitando o schema QrStyle. Default: 512px, quatro módulos, M, azul escuro sobre branco. POST /qr-codes salva appId, linkId, name e opcionalmente o estilo completo. Vínculo é imutável. GET /qr-codes/{qrId}/download?format=svg usa o estilo salvo. PNG e SVG são corpos binários com Content-Type e Content-Disposition; não existe envelope JSON nesses downloads. Erros seguem o envelope administrativo, inclusive 422 para densidade/tamanho incompatível.

curl 'https://api.staging.agilink.io/v1/qr-codes/90000000-0000-4000-8000-000000000002/download?format=png' \
  --header 'Authorization: Bearer <credencial>' --output agilink-qr.png

Nenhum download gera clique, nem busca/baixa destino ou imagem externa. O gerador usa node-qrcode, versão fixada, sem logo externo. QR salvo impede excluir seu link. Excluir configuração de QR usa revisão/idempotência e retorna 204; imagens já distribuídas continuam válidas.

Painel isolado

A página /platform é carregada separadamente e usa sessão Auth própria do staging. Defina a tríade pública VITE_PLATFORM_API_URL, VITE_PLATFORM_AUTH_URL, VITE_PLATFORM_PUBLIC_KEY com os destinos exatos do staging descritos no runbook; nunca service role. O menu aparece somente nessa configuração. Para trabalhar isolado do dashboard produtivo, use npm run dev:platform-staging --prefix dashboard: entrada própria, sem providers ou chamadas de dados produtivos. O servidor local usa um proxy fixo para a API de staging; não é necessário ampliar o CORS remoto. Builds continuam apontando diretamente ao host HTTPS permitido do staging. Não reutiliza o JWT produtivo do dashboard. Em produção, use https://developers.agilink.io/platform com a conta existente autorizada. A sessão fica em memória e é independente do painel principal. O painel mantém UUID da intenção em memória quando o resultado fica incerto; repetir os mesmos valores na mesma sessão reutiliza o recibo. Após recarregar a página, consulte o estado antes de tentar novamente.

Campos desconhecidos, queries repetidas e permissões insuficientes são rejeitados. Para 412, consulte o item e reaplique a intenção na revisão atual. Para timeout/503, preserve corpo/If-Match/chave; consulte publicação. Veja erros e repetição.