---
sidebar:
  order: 1
title: "API HTTP"
description: "Sahkan identiti, temukan alat dan sahkan perubahan melalui API HTTP sedia ada."
---

Hantar permintaan API produk ke origin Influence yang dipercayai, seperti `https://influence.so`. Domain dokumentasi tidak menerima permintaan API produk. Gunakan laluan tepat berikut tanpa parameter pertanyaan.

## Cipta kunci API dengan kebenaran yang sesuai

Dalam [tetapan Influence](https://influence.so/sign-in?next=%2Fapp%2Fsettings%2Faccount%23settings-developer), buka Aplikasi dan automasi → Kunci API. Pilih kebenaran yang diperlukan dan tarikh luput. Simpan kunci yang dipaparkan sekali sahaja dalam stor rahsia sebagai `PUBLISH_API_TOKEN`. Hantar melalui `Authorization: Bearer …`, bukan dalam URL, badan permintaan atau sembang. Batalkannya apabila tidak diperlukan lagi.

## Temukan alat dan baca data

Tetapkan `PUBLISH_API_URL` kepada origin yang dipercayai. Contoh ini mengandaikan proses sudah mempunyai `PUBLISH_API_TOKEN`. `accountList` memerlukan `integrations:read`; ikut medan penomboran halaman untuk mendapatkan halaman berikutnya.

```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":{}}'
```

## Laluan permintaan

| Kaedah | Laluan | Tujuan |
| --- | --- | --- |
| `GET` | `/api/v1/tools` | Menyenaraikan alat yang tersedia untuk kelayakan ini. |
| `POST` | `/api/v1/tools/{tool}/call` | Memanggil alat baca sahaja. |
| `POST` | `/api/v1/tools/{tool}/prepare` | Menyediakan perubahan tepat tanpa melaksanakannya. |
| `POST` | `/api/v1/tools/{tool}/confirm` | Mengesahkan perubahan yang disediakan. |
| `POST` | `/api/v1/media/import` | Mengesahkan muat naik binari imej kecil yang disediakan. |

Permintaan alat JSON menggunakan `Content-Type: application/json` dan badan yang mengandungi `input` sahaja: `{"input":{…}}`. Dapatkan skema input setiap alat daripada katalog alat semasa.

## Sediakan dan sahkan perubahan

1. Hantar input operasi yang tepat ke `/prepare`. Respons berjaya mengandungi `status: "confirmation_required"`, `confirmationCapability`, `expiresAt`, `inputDigest` dan `summary` jika ada.
2. Sebelum luput, hantar input yang sama ke `/confirm`. Masukkan nilai pengesahan yang diterima dalam `X-Publish-Confirmation` dan kunci baharu yang dijana klien dalam `Idempotency-Key`.
3. Simpan input, nilai pengesahan dan kunci bersama-sama. Selepas pengesahan terganggu atau hasil yang tidak pasti, gunakan semula ketiga-tiganya untuk permintaan yang sama. Jangan sediakan operasi pengganti untuk memulihkan hasil yang tidak pasti.

Kunci idempotensi mengandungi 16–200 aksara daripada `A–Z`, `a–z`, `0–9`, `.`, `_`, `:` dan `-`. Nilai pengesahan ialah rahsia legap. Kunci yang dihantar ke `/call` atau `/prepare` tidak menempah perubahan yang disahkan.

Pengesahan permintaan berasingan daripada kelulusan penerbitan. Untuk menerbitkan atau mengubah jadual, cipta dan paparkan semakan penuh yang terkini. Teks memerlukan kelulusan baharu selepas semakan itu. Imej dan video memerlukan kelulusan visual daripada orang tersebut melalui antara muka yang disokong atau selepas log masuk ke Influence. Menyediakan semakan tidak menerbitkan apa-apa. Baca hasil tersimpan sebelum tindakan lanjut; `needs_review` memerlukan kepastian tentang apa yang berlaku, bukan penghantaran semula.

## Kendalikan ralat dan hasil yang tidak pasti

Semak status HTTP dan badan respons. Kejayaan mengembalikan `{"ok":true,"toolName":"…","output":{…}}`. Kegagalan alat mengembalikan `{"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}}` dan boleh tiba dengan HTTP 200. Kegagalan pengangkutan menggunakan `{"error":{"code":"…","message":"…","retryable":false}}` tanpa `ok` atau `toolName`.

401 memerlukan pengesahan identiti: semak tamat tempoh atau pembatalan. Kebenaran yang tiada memerlukan pemberian akses yang sesuai, bukan permintaan berulang. 503 bermaksud API tidak tersedia dalam persekitaran itu. Ikut ralat dan panduan cubaan semula. Tamat masa tidak membuktikan perubahan gagal: simpan data pengesahannya dan baca status sebelum menghantar semula. Diterima, dijadualkan dan diterbitkan ialah hasil yang berbeza.

## Muat naik media

Untuk fail setempat, utamakan `uploadMedia` dalam SDK atau `media:upload` dalam CLI. Kedua-duanya menggunakan alat muat naik berbilang bahagian yang sama dan mengekalkan `clientKey` yang tetap untuk cubaan semula. Hanya hasil sedia dengan `assetId` boleh dilampirkan. Gunakan `mediaImport` untuk rujukan fail HTTPS yang dibenarkan; laluan setempat bukan URL muat turun.

`POST /api/v1/media/import` menyokong pengangkutan imej kecil sedia ada: sediakan `mediaImport` dengan deskriptor muat naik yang tepat, kemudian hantar bait yang sama sebagai `application/octet-stream`. Sertakan `X-Publish-Confirmation`, `Idempotency-Key` dan `X-Publish-Upload` yang mengandungi deskriptor JSON berkod URI. Bait mesti sepadan dengan saiz dan SHA-256. Hadnya 3 MiB; gunakan pembantu muat naik untuk fail lebih besar yang disokong. Muat naik tidak pernah meluluskan penerbitan.

[Lihat rujukan API](/ms/api-reference) atau [muat turun spesifikasi OpenAPI](/specs/influence.openapi.json).