--- sidebar: order: 1 title: API HTTP description: >- 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 [#create-a-scoped-api-key] Nas [Configurações do Influence](https://influence.so/sign-in?next=%2Fapp%2Fsettings%2Faccount%23settings-developer), 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 [#discover-tools-and-make-a-read] 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. ```sh 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 [#request-paths] | Método | Caminho | Finalidade | | --- | --- | --- | | `GET` | `/api/v1/tools` | Listar as ferramentas disponíveis para esta credencial. | | `POST` | `/api/v1/tools/{tool}/call` | Chamar uma ferramenta que não exige confirmação, incluindo a continuação de envios autorizados. | | `POST` | `/api/v1/tools/{tool}/prepare` | Preparar uma gravação exata sem executá-la. | | `POST` | `/api/v1/tools/{tool}/confirm` | Confirmar a gravação preparada. | | `POST` | `/api/v1/media/import` | Confirmar um envio binário preparado de imagem pequena. | 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 [#prepare-and-confirm-actions] 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](/pt-BR/developers/mcp#prepare-finished-content). 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](/pt-BR/help/ai-assistants#scheduling-allowance), 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 [#handle-errors-and-uncertain-results] 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 [#upload-media] 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](/pt-BR/help/media): 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](/pt-BR/api-reference) ou [baixe a especificação OpenAPI](/specs/influence.openapi.json).