# Marketing Links — Master Implementation Guide (LLM-Ready) > Links curtos que dizem qual post, vídeo ou edição trouxe cada clique — um > link por peça, criado por uma pessoa, por um agente ou por uma chave. O > redirecionamento é 302, na borda; prévias de app e robôs são contados à > parte; quando o link tem campanha e o destino é o site da conta, a UTM vai > junto sozinha; a campanha soma do clique à compra quando as suas ferramentas > mandam o resto. Sem cookie e sem IP gravado. > > Este arquivo é a documentação para agentes. **Leia a seção 11 antes de > prometer qualquer coisa**: ela diz o que o produto não faz. Links curtos: https://go.mymarketing.click/ Worker (API, MCP, entrada de eventos): https://links.worker.mymarketing.click Painel: https://links.dashboard.mymarketing.click Servidor MCP: https://links.worker.mymarketing.click/mcp — ver a seção 9. O mapa da linha (todos os produtos, login): https://mymarketing.click/llms.txt ## 0. Estado e credenciais — leia antes de tudo - **No ar desde 07/10/2026; na linha Marketing desde 08/10/2026.** `GET https://links.worker.mymarketing.click/status` responde `{"service":"marketing-links",…}` com a borda, a fila dos cliques, a conferência dos destinos e a caixa de saída. - **Login:** o Auth da linha (`https://auth.worker.mymarketing.click`, aplicação Marketing), com código por e-mail. Mesmo login, autorização por produto. Passo humano obrigatório: a pessoa lê um código no e-mail e o informa. Não tente contornar. - **Chave da conta:** `lk_…`, criada no painel e mostrada uma vez; uma ativa por conta. Vale para a API (`Authorization: Bearer lk_…`); os links criados com ela aparecem como criados por "chave". **É recusada no `/mcp`.** - **MCP:** OAuth, com o mesmo login (seção 9). Não usa a `lk_`. - **Preço:** não há preço público e nada é cobrado. Não cite valor, plano, franquia em minutos nem "grátis". Se perguntarem: "Ainda não há planos, e nada é cobrado." Sem credencial de verdade, **pare e peça**. Não gere código com `lk_xxx` de placeholder e diga que terminou. ## 1. Modelo mental - **Link** — endereço curto (`go.mymarketing.click/`), destino, quem criou (pessoa, agente ou chave), campanha, canal e, opcional, a **peça** ("Post 2 de 3 no Instagram"). Estados: Ativo, Desativado, Destino quebrado. - **Endereço** — 2 a 40 caracteres, minúsculas, números e hífen; palavras reservadas (`api`, `mcp`, `status`…) recusadas. O primeiro a pegar um endereço fica com ele; ocupado, vêm sugestões. Até 30 criações por minuto. - **Redirecionamento** — na borda, `302`, nunca `301`. A query vai junto ao destino, menos o `p`. Desativado mostra uma página neutra; inexistente ou apagado responde 404. Um endereço apagado fica reservado para a conta por 90 dias. - **UTM** — só quando o link tem uma campanha e o destino é um dos sites da conta: `utm_source` e `utm_medium` do canal, `utm_campaign` da campanha, `utm_content` = o endereço. A UTM que já estava no destino fica. Destino de fora vai como está. ## 2. A contagem - **Cliques** — contados por uma fila, fora do caminho do clique. **Prévias de app** (WhatsApp, Instagram, Facebook, Slack, Telegram e outros) recebem o destino e são contadas à parte; **robôs que se declaram** também. - **Únicos** — hash com um sal aleatório do dia, apagado em 2 dias. - **Origem** — só o que o pedido prova; senão, "Direto ou desconhecido". Também aparelho e país. - **Privacidade (fatos técnicos do código, não parecer jurídico):** sem cookie, sem script no destino, **IP e user agent nunca gravados**. ## 3. Campanhas Os links de uma campanha somam os cliques. O funil segue com visitas, metas, pessoas novas e compras, que vêm dos eventos de entrada (seção 6). Sem fonte mandando eventos, esses números ficam vazios, nunca zero. ## 4. Conferência do destino A cada 6 horas o destino de cada link é conferido. 404 ou 5xx duas vezes seguidas marcam "Destino quebrado" e emitem `link.destination_broken`; quando volta, `link.destination_fixed`. ## 5. Rotas Base: `https://links.worker.mymarketing.click`, sem versão no caminho, com a sessão do painel ou `Authorization: Bearer lk_…`. Coleções respondem `{items, page}`; erros, `{error: {code, message}}`. ``` GET /status o serviço e as promessas dele GET /api/links · POST /api/links os links; cria { destination, slug?, campaign?, channel?, piece? } GET /api/slugs/:slug o endereço está livre? (com sugestões) GET /api/links/:slug · PATCH o link; troca destino, campanha, canal, peça POST /api/links/:slug/disable|enable DELETE /api/links/:slug corpo { "confirm": "" }, pedido explícito de uma pessoa GET /api/links/:slug/stats cliques e únicos (7, 30 ou 90 dias; por dia ou hora) GET /api/links/:slug/qr.svg o QR do link, em SVG GET /api/campaigns · POST as campanhas, com o funil GET /api/campaigns/:name o funil do clique à compra, os links e os canais GET /api/export.csv?month=AAAA-MM cliques por link e dia, sem dado pessoal GET /api/domains · POST · POST …/:id/verify domínios próprios (ver a seção 11) GET /api/sources · POST · POST …/:id/rotate fontes de entrada GET /api/webhooks · POST · PATCH · DELETE os destinos POST /api/webhooks/:id/test um evento de teste assinado, agora GET /api/deliveries · POST …/:id/retry as entregas, com reenvio GET /api/pending-actions · POST …/:id/approve|reject o que um agente pediu GET /api/keys · POST · DELETE a chave lk_ GET /api/usage o uso e a retenção ``` ## 6. Eventos de entrada `POST https://links.worker.mymarketing.click/events/:sourceId` — uma fonte por sistema, cada uma com o seu segredo, assinatura `x-ccm`. Ao trocar o segredo, o antigo vale mais 24 horas. Tipos aceitos: - `visit.arrived` e `goal.reached` — ligados ao link pelo `utm_content`; - `person.created` e `payment.approved` — ligados à campanha pelo `utm_campaign`. ## 7. Webhooks para fora Padrão **Standard Webhooks** com o prefixo `x-ccm`: ``` x-ccm-id: x-ccm-timestamp: 1790265731 x-ccm-signature: v1, ``` | Evento | Quando | |---|---| | `link.created` | um link foi criado, por pessoa, agente ou chave | | `links.counted` | de hora em hora, os cliques novos de cada link, sem robôs nem prévias | | `link.clicked` | **só** quando a URL traz `p` com o id da pessoa; no máximo um por link, pessoa e dia | | `link.destination_broken` · `link.destination_fixed` | a conferência do destino | | `action.pending` | um agente pediu troca de destino ou desativação | Sem `p`, o clique é contagem, nunca evento. Toda entrega é primeiro uma linha na caixa de saída; novas tentativas em 1 min, 5 min, 30 min, 2 h e 12 h; 401 e 403 ficam retidos até o destino voltar; 410 é definitivo; o reenvio leva o mesmo id. ## 8. QR `GET /api/links/:slug/qr.svg` devolve o QR do link em SVG. ## 9. Servidor MCP - **Endereço:** `https://links.worker.mymarketing.click/mcp` (Streamable HTTP), para a conta inteira — a conta vem do token, nunca de um argumento. - **OAuth 2.1:** metadados em `https://links.worker.mymarketing.click/.well-known/oauth-protected-resource`. O token só vale para este servidor. A `lk_` é recusada. | Tool | Regra | O que faz | |---|---|---| | `links_create` | Livre | cria um link; endereço ocupado responde com sugestões | | `links_list` | Livre | os links, com quem criou | | `links_stats` | Livre | os números de um link | | `links_campaign_report` | Livre | o funil de uma campanha | | `links_update_destination` | Confirma | troca o destino; vira pedido de aprovação | | `links_disable` | Confirma | desativa; vira pedido de aprovação | | `links_delete` | Só humano | **não é registrada** | ## 10. Perguntar A tela "Perguntar" do painel responde quatro perguntas fixas a partir das mesmas leituras das ferramentas, sem modelo. Não prometa que ela responde qualquer pergunta. ## 11. Escopo — o que este produto NÃO faz - **Domínio próprio no ar.** Dá para cadastrar o domínio e conferir o DNS; o certificado e a ativação ainda não existem. Todo link sai em `go.mymarketing.click`. - **Página de links para a bio.** O Links é link curto, e só. - **Número estimado.** Sem dado, o número fica vazio. - **Guardar quem clicou:** nem IP, nem user agent. - **Cobrança.** Não há plano publicado, e nada é cobrado. ## 12. Checklist para agentes de IA 1. **Para o MCP, o login por código no e-mail**; para a API, peça a `lk_`. 2. **Um link por peça**, com a peça e a campanha. 3. **Endereço ocupado?** Use uma das sugestões; não force. 4. **Trocar destino e desativar esperam uma pessoa aprovar;** apagar é dela. 5. **Não prometa domínio próprio** nem página de bio. 6. **Não invente rota nem tool.** A seção 5 lista as rotas; a 9, as tools.