API upload publik

Endpoint ini digunakan oleh website kantor, scanner, atau sistem administrasi untuk mengirim satu dokumen ke workspace Arsipin tanpa login sebagai pengguna.

POST {BASE_API_URL}/public-api/workspaces/{publicKey}/archives/upload

BASE_API_URL biasanya berakhir dengan /api/v1. Salin alamat lengkap dari bagian Upload otomatis dari aplikasi lain pada halaman workspace agar tidak salah memilih domain atau publicKey.

Prasyarat

Sebelum mengirim dokumen, pemilik workspace harus memastikan:

1. link publik sudah aktif;
2. password publik masih aktif;
3. Google Drive pemilik workspace masih terhubung;
4. saldo credit pemilik minimal Rp500;
5. file memakai format dan ukuran yang diizinkan workspace.

Jika password publik dimatikan, halaman publik dapat tetap dibuka tetapi endpoint ini mengembalikan PUBLIC_API_DISABLED.

Request

Path

Bagian	Keterangan
publicKey	Identitas publik workspace. Gunakan nilai dari alamat yang ditampilkan aplikasi.

Header

Header	Wajib	Nilai
X-Workspace-Password	Ya	Password publik workspace
Content-Type	Ya	multipart/form-data; boundary biasanya dibuat otomatis oleh library HTTP

Jangan menaruh password pada query string atau URL.

Form data

Field	Wajib	Keterangan
file	Ya	Satu file PDF, JPG/JPEG, PNG, atau DOCX sesuai pengaturan workspace

Satu request hanya menerima satu file. Untuk beberapa file, kirim request terpisah dan tetap perhatikan rate limit.

Contoh cURL

curl -X POST "https://api.example.com/api/v1/public-api/workspaces/01PUBLICKEY/archives/upload" \
  -H "X-Workspace-Password: PASSWORD_WORKSPACE" \
  -F "file=@/path/ke/dokumen.pdf"

Ganti alamat endpoint, password, dan lokasi file dengan nilai sebenarnya.

Contoh JavaScript

Contoh berikut memakai API bawaan Node.js 20 atau yang lebih baru.

import { openAsBlob } from "node:fs";

const endpoint =
  "https://api.example.com/api/v1/public-api/workspaces/01PUBLICKEY/archives/upload";
const file = await openAsBlob("./dokumen.pdf");
const form = new FormData();
form.set("file", file, "dokumen.pdf");

const response = await fetch(endpoint, {
  method: "POST",
  headers: {
    "X-Workspace-Password": process.env.ARSIPIN_WORKSPACE_PASSWORD,
  },
  body: form,
});

const payload = await response.json();

if (!response.ok || payload.success !== true) {
  throw new Error(
    `${payload.error?.code ?? "REQUEST_FAILED"}: ${payload.message}`,
  );
}

console.log("Archive:", payload.data.archive.id);
console.log("Job:", payload.data.job.id);

Simpan password pada pengelola secret atau environment server. Jangan menuliskannya langsung di source code yang masuk repository.

Respons berhasil

Server mengembalikan 202 Accepted. Status ini berarti file sudah diterima dan masuk antrean, bukan berarti pemrosesan AI sudah selesai.

{
  "success": true,
  "message": "Dokumen masuk antrean pemrosesan.",
  "data": {
    "archive": {
      "id": "01AR...",
      "workspace_id": "01WS...",
      "original_filename": "dokumen.pdf",
      "stored_filename": "dokumen.pdf",
      "mime_type": "application/pdf",
      "file_size": 245810,
      "drive_sync_status": "pending",
      "status": "processing",
      "metadata_json": {}
    },
    "job": {
      "id": "01JB...",
      "kind": "classify",
      "archive_id": "01AR...",
      "status": "queued",
      "progress": 0,
      "current_step": "pending",
      "retry_count": 0
    },
    "duplicate_of": null
  }
}

Field duplicate_of berisi ID arsip lama jika isi file yang sama sudah pernah diunggah ke workspace. Upload baru tetap diterima dan diproses.

Pantau hasil akhirnya dari halaman workspace atau Arsip di aplikasi. Endpoint publik ini tidak menyediakan polling status untuk sistem eksternal.

Respons gagal

Format umum respons gagal:

{
  "success": false,
  "message": "Password API publik tidak sesuai.",
  "error": {
    "code": "PUBLIC_API_UNAUTHORIZED",
    "fields": null
  }
}

HTTP	Code	Penyebab dan tindakan
400	FILE_REQUIRED	Field file tidak dikirim.
400	FILE_TOO_LARGE	Ukuran melewati batas workspace.
400	FILE_INVALID	File kosong, rusak, tidak dapat dibaca, atau terlalu besar saat disalin.
400	UNSUPPORTED_FILE	Isi file atau formatnya tidak diizinkan workspace.
401	PUBLIC_API_UNAUTHORIZED	Password pada header salah atau kosong.
402	INSUFFICIENT_CREDIT	Saldo pemilik workspace tidak cukup.
403	PUBLIC_API_DISABLED	Password publik tidak aktif sehingga API dinonaktifkan.
404	PUBLIC_NOT_FOUND	publicKey, link publik, workspace, atau akun pemilik tidak tersedia.
409	DRIVE_NOT_CONNECTED	Google Drive pemilik workspace terputus.
429	RATE_LIMITED	Terlalu banyak request, percobaan password, atau upload.
500	DRIVE_STATUS_CHECK_FAILED	Status Google Drive tidak dapat diperiksa sementara.
500	TEMP_STORAGE_FAILED	Penyimpanan sementara server tidak tersedia.
500	UPLOAD_FAILED	Data upload tidak dapat dimasukkan ke antrean.

Untuk error 500, hentikan percobaan berulang yang cepat dan coba kembali dengan jeda. Hubungi pengelola Arsipin jika masalah berlanjut.

Rate limit

Batas berikut diterapkan per workspace dan alamat IP:

Jenis batas	Jumlah	Periode
Semua request API publik	30	15 menit
Percobaan password yang gagal	5	15 menit
Upload yang lolos autentikasi	20	15 menit

Respons yang melewati batas menggunakan status 429 dan code RATE_LIMITED.

CORS dan penggunaan dari browser

Request server-to-server tidak memerlukan pengaturan CORS. Jika endpoint dipanggil langsung dari browser, origin website harus lebih dahulu dimasukkan ke daftar origin yang dipercaya oleh pengelola Arsipin.

Pemanggilan langsung dari browser juga dapat membuka password workspace kepada pengguna website. Untuk penggunaan produksi, kirim file melalui server milik Anda.

Penanganan retry dan duplikat

• Jika server sudah mengembalikan 202, jangan langsung mengirim file yang sama lagi.
• Jika koneksi terputus sebelum respons diterima, request ulang dapat membuat arsip kedua.
• Gunakan duplicate_of untuk menandai file dengan isi yang pernah diterima.
• Beri jeda bertahap ketika menerima 429 atau error server.