API HTTP

Autentique, descubra ferramentas e confirme alterações pela API HTTP existente.

Envie solicitações à API do produto para sua origem confiável do Influence, como https://influence.so. O domínio da documentação não aceita solicitações à API do produto. Use os caminhos exatos abaixo, sem parâmetros de consulta.

Crie uma chave de API com escopos definidos

Nas Configurações do Influence, abra Aplicativos e automações → Chaves de API. Escolha as permissões necessárias e uma validade. Armazene a chave, exibida uma única vez, no seu gerenciador de segredos como PUBLISH_API_TOKEN. Envie-a em Authorization: Bearer …; nunca a coloque em uma URL, no corpo de uma solicitação nem em uma conversa. Revogue-a quando não for mais necessária.

Descubra ferramentas e leia contas

Defina PUBLISH_API_URL como a origem confiável. Estes exemplos pressupõem que o processo já tenha PUBLISH_API_TOKEN. accountList exige integrations:read; siga seus campos de paginação para obter mais páginas.

export PUBLISH_API_URL="https://influence.so"
curl "$PUBLISH_API_URL/api/v1/tools" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN"

curl "$PUBLISH_API_URL/api/v1/tools/accountList/call" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"input":{}}'

Caminhos de solicitação

Solicitações JSON de ferramentas usam Content-Type: application/json e um corpo que contém apenas input: {"input":{…}}. Obtenha o esquema de entrada de cada ferramenta no catálogo atual de ferramentas.

Prepare e confirme ações

Use o campo confirmation do catálogo: leituras normalmente não exigem confirmação, mas uma atualização dos dados de Análises exige, apesar de ser uma leitura. A consulta de partes de envio, a conclusão e o cancelamento continuam um envio já autorizado por /call.

1. Envie a entrada de negócio exata para /prepare. Uma resposta bem-sucedida tem status: "confirmation_required", confirmationCapability, expiresAt, inputDigest e, opcionalmente, summary.
2. Antes da validade expirar, envie a mesma entrada para /confirm. Coloque a capacidade de confirmação retornada em X-Publish-Confirmation e uma nova chave gerada pelo cliente que faz a chamada em Idempotency-Key.
3. Mantenha a entrada, a capacidade de confirmação e a chave juntas. Após uma confirmação interrompida ou incerta, reutilize as três para a mesma solicitação. Não prepare uma substituição para recuperar um resultado incerto.

Uma chave de idempotência contém de 16 a 200 caracteres de A–Z, a–z, 0–9, ., _, : e -. Capacidades de confirmação são segredos opacos. Uma chave enviada para /call ou /prepare não reserva uma gravação confirmada.

A confirmação de transporte é separada da aprovação para publicação. Para publicar ou alterar agendamentos, apresente a revisão atual completa: contas, texto, configurações, prévias ou links das mídias, horário agendado e fuso horário. O cliente pode informar uma nova aprovação humana explícita com approval: "approved" para revisões elegíveis de publicações sociais de texto, imagem e vídeo; ele não deve inventar consentimento nem tratar preparação como aprovação. O Influence registra isso como aprovação informada pelo cliente. Um cartão incorporado compatível ou uma revisão com login registra sua própria ação humana.

O TikTok Direct aceita escolhas explícitas e consentimento na conversa pelo fluxo de revisão. Salve as escolhas completas com campaignReview e obtenha uma nova aprovação da revisão atualizada antes da execução. O cartão de revisão é opcional. Agendamentos comuns por API/CLI não consomem a franquia de agendamento por IA; a franquia de MCP e Influence IQ, que é separada, segue esses fluxos mesmo quando uma revisão de IA salva é aprovada depois no Influence. Os outros requisitos do plano e do provedor continuam valendo. Leia o recibo salvo antes de outra ação; needs_review exige reconciliação do resultado, não outro envio.

Trate erros e resultados incertos

Confira tanto o status HTTP quanto o corpo da resposta. Ferramentas bem-sucedidas retornam {"ok":true,"toolName":"…","output":{…}}. Falhas de ferramentas retornam {"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}} e podem chegar com HTTP 200. Falhas de transporte usam {"error":{"code":"…","message":"…","retryable":false}}, sem ok ou toolName.

Um 401 significa que é necessária autenticação; confira a validade ou a revogação. Uma permissão ausente exige a autorização adequada, não solicitações repetidas. Um 503 pode significar que o serviço está indisponível ou que outra solicitação de agendamento está atualizando o espaço de trabalho. Use o código de erro e a orientação de nova tentativa retornados; não repita automaticamente uma ação de publicação. Um timeout não comprova que uma gravação falhou: mantenha os dados de confirmação e leia o status atual antes de reenviar. Aceita, agendada e publicada são resultados diferentes.

Envie mídia

Prefira uploadMedia do SDK ou media:upload da CLI para arquivos locais. Eles usam as mesmas ferramentas de envio multipart e preservam um clientKey estável para novas tentativas. Apenas um resultado pronto com assetId pode ser anexado. Para um link HTTPS autorizado, use mediaImport com url e, opcionalmente, name. Referências reais de arquivo do host usam o objeto file separado; uma URL pública não precisa de um ID inventado de arquivo do host. Um caminho de arquivo local não é uma URL de download. Veja os limites de mídia: a importação de vídeos por HTTPS tem limite de 250 MiB, mesmo quando um MP4 pronto maior seria permitido por envio direto.

POST /api/v1/media/import permite o transporte existente de imagens pequenas: prepare mediaImport com o descritor de envio exato e envie os mesmos bytes como application/octet-stream. Inclua X-Publish-Confirmation, Idempotency-Key e X-Publish-Upload contendo o descritor JSON codificado como URI. Os bytes devem corresponder ao tamanho e ao SHA-256 do descritor. Esse transporte tem limite de 3 MiB; use o helper de envio para arquivos maiores compatíveis. Enviar arquivos nunca aprova a publicação.

Explore a referência da API ou baixe a especificação OpenAPI.