Fluxos de trabalho com OAuth v2

Instalação

npm install --global @anakonn/ankk@0.5.1
ankk --version

Entre e escolha uma marca

O ANKK v2 usa sua conta de usuário por meio do OAuth no navegador. Suas permissões existentes se aplicam a todas as solicitações. Conectar um aplicativo não concede permissões adicionais sobre marcas. Escolha a marca ao trabalhar; a autorização OAuth não seleciona uma marca.

Use a CLI 0.5.1 com Node.js 24 ou superior. O ID público identifica a ANKK CLI; não é um segredo.

export ANKK_OAUTH_CLIENT_ID=ankk-cli-production

ankk --json auth login --environment production
ankk auth status --environment production --connection OAUTH_CONNECTION_ID
ankk --json brands list --environment production --connection OAUTH_CONNECTION_ID --all
ankk --json connections list --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --all

Substitua os identificadores em maiúsculas pelos IDs retornados por suas próprias solicitações. O ID da conexão OAuth seleciona seu login. Um ID de conta SNS identifica um destino de publicação; ele é diferente tanto da conexão OAuth quanto do ID de conta do provedor. Use o mesmo ambiente e a mesma marca durante todo o procedimento. Estes exemplos especificam ambos explicitamente, mesmo quando você configurou uma marca padrão local.

Em um terminal que não abra o navegador automaticamente, use ankk auth login --environment production --device --no-open e siga as instruções de verificação exibidas. Os tokens são armazenados no repositório de credenciais do sistema operacional. Se ele estiver indisponível, restaure-o antes de entrar; nunca cole tokens em uma conversa nem os salve em um arquivo JSON de publicação.

Consulte o desempenho e as publicações armazenadas

ankk --json analytics get --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --from 2026-10-01T00:00:00Z --to 2026-10-02T00:00:00Z
ankk --json posts list --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --all

Escolha o período real do relatório. O início é inclusivo e o fim exclusivo; os horários usam UTC. Converta as datas locais do usuário para UTC antes da consulta. Adicione --sns-account SNS_ACCOUNT_ID para limitar o resultado a uma conta.

O resultado descreve observações armazenadas. Confira a cobertura e os horários das observações antes de comparar períodos. Dados ausentes não são zero. O retrato mais recente de uma conta tem seu próprio horário de medição e não corresponde necessariamente ao total de um período. Os insights de um período exato do Instagram são distintos das observações acumuladas. Uma leitura não inicia a coleta do provedor. posts refresh é uma ação separada para dados de publicações e comentários, não um pedido para atualizar a análise.

As listas usam cursores. --all percorre as páginas; os dados podem mudar durante a paginação, portanto o resultado não é um retrato de um único momento. Se um cursor expirar, informe que o resultado está incompleto e inicie uma nova listagem deliberadamente, em vez de combiná-la silenciosamente com as páginas antigas.

Prepare um arquivo antes da publicação

ankk --json media create-upload --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --file ./photo.jpg --idempotency-key UPLOAD_KEY
ankk --json media complete-upload MEDIA_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --idempotency-key INSPECTION_KEY --wait --wait-timeout 180
ankk --json media get MEDIA_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID

O primeiro comando registra e transfere o arquivo. Salve seu ID de mídia mesmo que a transferência falhe ou a resposta seja incerta. O segundo solicita a inspeção; use a mídia somente quando seu estado final for ready. Essas etapas não publicam. A mídia pode ser reutilizada dentro de sua marca. Faça um upload separado para outra marca.

Se apenas a URL de upload expirar, use media refresh-upload MEDIA_ID com o mesmo ambiente, login e marca. A nova URL não estende o prazo original do processo nem substitui o arquivo. Bytes diferentes exigem um novo upload de mídia. Trate URLs de transferência assinadas como credenciais e não as inclua em transcrições compartilhadas. Clientes sem transferência de arquivos podem usar a URL de acompanhamento no navegador retornada, entrar e selecionar o arquivo, depois voltar com o mesmo ID de mídia e verificar se está pronta.

Revise e publique

Confirme a marca, as contas, o texto completo, a ordem dos segmentos da sequência, os anexos, as opções do provedor e o horário de execução antes de publicar conteúdo preparado por IA. Uma aprovação existente para aquela intenção exata é suficiente. Uma solicitação apenas de análise ou elaboração de rascunho não é aprovação de publicação.

Salve esta entrada mínima de publicação imediata como publish.json. Selecione uma conta que suporte a combinação proposta de texto e imagem; o servidor verifica novamente a capacidade atual, a preparação da mídia e a permissão. Substitua o texto em inglês do exemplo pelo texto exato aprovado.

{
  "scheduled_at": null,
  "targets": [
    {
      "sns_account_id": "SNS_ACCOUNT_ID",
      "text": "The exact text you approved",
      "media_ids": ["MEDIA_ID"]
    }
  ]
}

ankk --json contents publish --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --file publish.json --idempotency-key PUBLICATION_KEY

Escolha e guarde uma chave única para esta intenção antes de enviar. Reutilize exatamente essa chave e os mesmos dados após uma resposta incerta, inclusive ao alternar entre API, CLI e MCP. Não crie outra publicação apenas porque uma conexão excedeu o tempo limite. A mesma chave com entrada alterada gera conflito. Uma chave expirada não cria novo trabalho: examine o resultado anterior antes de iniciar deliberadamente uma nova intenção.

Para agendar, substitua scheduled_at: null pelo horário futuro em UTC aprovado, por exemplo 2026-12-01T09:00:00Z. Substitua essa data ilustrativa antes de usar e verifique se ainda está no futuro. Um registro concluído retorna um publish_operation_id separado; isso não significa que as publicações SNS agendadas já foram publicadas.

Acompanhe o resultado

ankk --json operations get OPERATION_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --wait --wait-timeout 180

Para publicação imediata, acompanhe o ID de operação retornado. Para agendamento, acompanhe publish_operation_id no horário de execução. A espera é opcional e local. O código de saída 10 da CLI significa que o limite de espera expirou; o código 130 significa que a espera foi interrompida. Nenhum deles cancela a tarefa no servidor. Continue consultando a mesma operação. O código 11 durante a espera indica um resultado final com falha, cancelado ou parcialmente bem-sucedido; examine os resultados por conta. Uma consulta normal de estado pode terminar com código 0 enquanto informa uma operação com falha, portanto os scripts também precisam examinar o estado da resposta.

Informe cada conta separadamente. Preserve as publicações bem-sucedidas e suas URLs. O array ordenado posts contém as publicações confirmadas de uma sequência; o post_url representativo sozinho pode não descrever toda a sequência. A ausência de URL ou um estado não resolvido não prova que o provedor não criou nada. Mantenha resultados em reconciliação e desconhecidos como não resolvidos até que a tarefa existente forneça evidências.

Altere um agendamento ou recupere uma falha

Consulte contents get CONTENT_ID com o mesmo ambiente, login e marca antes de mudar o conteúdo ou o horário. Passe a versão atual como --expected-version. contents update edita destinos elegíveis ainda não iniciados; contents reschedule altera seu agendamento em UTC. Um conflito de versão exige uma nova leitura e revisão, não uma sobrescrita silenciosa. contents cancel solicita o cancelamento; examine a operação de publicação retornada até confirmar o cancelamento. A execução pode acontecer primeiro.

Tente novamente apenas as contas com falha selecionadas que estejam atualmente marcadas com can_retry:

ankk --json contents retry ORIGINAL_OPERATION_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --accounts FAILED_SNS_ACCOUNT_ID --idempotency-key RETRY_KEY

Esta é uma nova intenção de execução e precisa de uma nova chave adequada e aprovação do usuário, a menos que já esteja coberta. Guarde essa chave de nova tentativa após uma resposta incerta. A nova tentativa usa conteúdo armazenado e executa assim que possível; nunca republica destinos bem-sucedidos ou incertos. Para um novo agendamento futuro, contents duplicate retorna apenas uma entrada editável. Revise-a e envie uma nova publicação aprovada.

Descartar entradas elegíveis com falha da fila as oculta da fila de trabalho; não exclui publicações, apaga o histórico de execução nem tenta nada novamente. O cancelamento em massa pode retornar grupos aceitos e rejeitados juntos; acompanhe cada operação de publicação aceita. O descarte em massa termina de forma síncrona: examine os grupos descartados e rejeitados no comprovante, sem esperar por uma nova operação. Em ambos os casos, leia o comprovante completo em vez de tratar um código de saída como um resultado de tudo ou nada.

Trate erros de solicitação e desconecte

Leia o código de erro estruturado, o ID da solicitação, o ID da operação quando disponível, next_action e retry_at. Após recuperar a autenticação, volte à operação original. Erros de permissão exigem acesso legítimo, não uma interface diferente. Respeite limites de solicitações e restrições de capacidades. Uma solicitação que permite nova tentativa não autoriza uma nova publicação nem uma chave substituta.

ankk auth logout --environment production --connection OAUTH_CONNECTION_ID

A saída informa separadamente a revogação no servidor e a remoção das credenciais locais. Se a revogação no servidor não estiver confirmada, revogue a conexão antiga nas configurações do ANKK ou por outra conexão válida. Remover uma conexão OAuth não cancela publicações já aceitas nem exclui mídias pertencentes à marca.

Use MCP e Skills

O MCP usa OAuth de usuário em https://api.ankk.app/mcp/v2. O host precisa de um cliente registrado; a URL sozinha não conclui a conexão. Não há listagens oficiais nos diretórios do ChatGPT e Claude. Sem cartões, use texto e resultados estruturados. Confira os valores e horários de observação, não apenas o resumo da conversa.

Skills fornece procedimentos, não permissões nem credenciais. Instale a tag candidata fixa e confira marca, aprovação e resultado final.

npx skills add https://github.com/Anakonn/ankk-skills/tree/v0.1.0-rc.1 --skill ankk-analyze --skill ankk-publish