--- sidebar: order: 1 title: API HTTP description: >- Autenticati, individua gli strumenti e conferma le modifiche tramite l’API HTTP esistente. --- Invia le richieste API del prodotto alla tua origine attendibile di Influence, per esempio `https://influence.so`. Il dominio della documentazione non accetta richieste API del prodotto. Usa i percorsi esatti qui sotto, senza parametri di query. ## Crea una chiave API con ambiti di autorizzazione limitati [#create-a-scoped-api-key] Nelle [impostazioni di Influence](https://influence.so/sign-in?next=%2Fapp%2Fsettings%2Faccount%23settings-developer), apri App e automazioni → Chiavi API. Scegli le autorizzazioni necessarie e una scadenza. Conserva la chiave, mostrata 1 sola volta, nel tuo archivio segreto come `PUBLISH_API_TOKEN`. Inviala in `Authorization: Bearer …`; non inserirla mai in un URL, nel corpo di una richiesta o in una chat. Revocala quando non serve più. ## Individua gli strumenti e leggi gli account [#discover-tools-and-make-a-read] Imposta `PUBLISH_API_URL` sull’origine attendibile. Questi esempi presuppongono che il processo disponga già di `PUBLISH_API_TOKEN`. `accountList` richiede `integrations:read`; segui i suoi campi di paginazione per recuperare altre pagine. ```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":{}}' ``` ## Percorsi delle richieste [#request-paths] | Metodo | Percorso | Scopo | | --- | --- | --- | | `GET` | `/api/v1/tools` | Elenca gli strumenti disponibili per questa credenziale. | | `POST` | `/api/v1/tools/{tool}/call` | Chiama uno strumento che non richiede conferma, incluse le prosecuzioni di caricamenti autorizzati. | | `POST` | `/api/v1/tools/{tool}/prepare` | Prepara una scrittura esatta senza eseguirla. | | `POST` | `/api/v1/tools/{tool}/confirm` | Conferma la scrittura preparata. | | `POST` | `/api/v1/media/import` | Conferma un piccolo caricamento binario di un’immagine già preparato. | Le richieste JSON agli strumenti usano `Content-Type: application/json` e un corpo che contiene soltanto `input`: `{"input":{…}}`. Ottieni lo schema di input di ogni strumento dal catalogo attuale degli strumenti. ## Prepara e conferma le azioni [#prepare-and-confirm-actions] Usa il campo `confirmation` del catalogo: le letture di solito non richiedono conferma, mentre un aggiornamento delle statistiche la richiede pur essendo una lettura. La ricerca delle parti di caricamento, il completamento e l’annullamento proseguono un caricamento già autorizzato tramite `/call`. 1. Invia l’input operativo esatto a `/prepare`. Una risposta riuscita contiene `status: "confirmation_required"`, `confirmationCapability`, `expiresAt`, `inputDigest` e un eventuale `summary`. 2. Prima della scadenza, invia lo stesso input a `/confirm`. Inserisci la capability restituita in `X-Publish-Confirmation` e una nuova chiave generata dal chiamante in `Idempotency-Key`. 3. Conserva insieme input, capability e chiave. Dopo una conferma interrotta o dall’esito incerto, riutilizzali tutti e 3 per la stessa richiesta. Non preparare una sostituzione per recuperare un risultato incerto. Una chiave di idempotenza contiene 16–200 caratteri tra `A–Z`, `a–z`, `0–9`, `.`, `_`, `:` e `-`. Le capability di conferma sono segreti opachi. Una chiave inviata a `/call` o `/prepare` non riserva una scrittura confermata. La conferma di trasporto è separata dall’approvazione della pubblicazione. Per la pubblicazione o le modifiche alla programmazione, presenta la revisione attuale completa: account, testo, impostazioni, anteprime o link dei contenuti multimediali effettivi, orario programmato e fuso orario. Il client può segnalare una nuova approvazione umana esplicita con `approval: "approved"` per le revisioni idonee di post social di testo, immagini e video; non deve inventare il consenso né considerare la preparazione un’approvazione. Influence registra questa approvazione come dichiarata dal client. Una scheda incorporata supportata o una revisione dopo l’accesso registra invece l’azione umana eseguita nella propria interfaccia. TikTok Direct accetta scelte e consenso espliciti in chat tramite il [flusso di revisione](/it/developers/mcp#prepare-finished-content). Salva le scelte complete con `campaignReview`, poi ottieni una nuova approvazione della revisione aggiornata prima dell’esecuzione. La scheda di revisione è facoltativa. La programmazione ordinaria tramite API/CLI non consuma la quota di programmazione con IA; la [quota separata di MCP e Influence IQ](/it/help/ai-assistants#scheduling-allowance) segue quei flussi anche quando una revisione IA salvata viene approvata in seguito in Influence. Si applicano comunque gli altri requisiti del piano e dei fornitori. Leggi la ricevuta salvata prima di altre azioni; `needs_review` richiede la riconciliazione, non un altro invio. ## Gestisci gli errori e i risultati incerti [#handle-errors-and-uncertain-results] Controlla sia lo stato HTTP sia il corpo della risposta. Le chiamate agli strumenti riuscite restituiscono `{"ok":true,"toolName":"…","output":{…}}`. Gli errori degli strumenti restituiscono `{"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}}` e possono arrivare con HTTP 200. Gli errori di trasporto usano `{"error":{"code":"…","message":"…","retryable":false}}` senza `ok` o `toolName`. Un 401 significa che serve l’autenticazione; controlla la scadenza o la revoca. Un’autorizzazione mancante richiede la concessione appropriata, non richieste ripetute. Un 503 può significare che il servizio non è disponibile o che un’altra richiesta di programmazione sta aggiornando lo spazio di lavoro. Usa il codice di errore e le indicazioni sui nuovi tentativi restituiti; non ripetere automaticamente un’azione di pubblicazione. Un timeout non dimostra che una scrittura sia fallita: conserva i dati di conferma e leggi lo stato attuale prima di inviare di nuovo. Accettato, programmato e pubblicato sono esiti diversi. ## Carica contenuti multimediali [#upload-media] Per i file locali, preferisci `uploadMedia` dell’SDK o `media:upload` della CLI. Usano gli stessi strumenti di caricamento multipart e mantengono un `clientKey` stabile per i nuovi tentativi. Si può allegare soltanto un risultato pronto con un `assetId`. Per un link HTTPS autorizzato, usa `mediaImport` con `url` e l’eventuale `name`. I veri riferimenti a file dell’host usano l’oggetto separato `file`; un URL pubblico non richiede un ID file dell’host inventato. Il percorso di un file locale non è un URL di download. Consulta i [limiti dei contenuti multimediali](/it/help/media): l’importazione di video tramite HTTPS ha un limite di 250 MiB, anche quando un MP4 pronto più grande sarebbe consentito tramite caricamento diretto. `POST /api/v1/media/import` supporta il trasporto esistente per immagini piccole: prepara `mediaImport` con il descrittore di caricamento esatto, poi invia gli stessi byte come `application/octet-stream`. Includi `X-Publish-Confirmation`, `Idempotency-Key` e `X-Publish-Upload` con il descrittore JSON codificato come URI. I byte devono corrispondere alla dimensione e a SHA-256 indicati. Questo trasporto ha un limite di 3 MiB; usa la funzione di caricamento per file supportati più grandi. Il caricamento non approva mai la pubblicazione. [Consulta il riferimento API](/it/api-reference) o [scarica la specifica OpenAPI](/specs/influence.openapi.json).