AgencyHandy API: Perbarui Pesanan yang Ada dengan PUT

Endpoint Update Order memungkinkan Anda memodifikasi pesanan (proyek) yang ada di AgencyHandy — mengubah nama, status, anggaran, timeline, manajer yang ditetapkan, dan banyak lagi — semuanya dari sistem eksternal atau skrip otomasi. Endpoint ini juga mendukung lampiran file, yang ditambahkan ke folder sistem pesanan.

Sebelum menggunakan endpoint ini, selesaikan panduan Memulai untuk mendapatkan API key dan Company ID Anda.

Endpoint ini menggunakan Authorization: Bearer <token> (token akses anggota yang masuk) dan bukan hanya header x-api-key. Pastikan pemanggil Anda diautentikasi sebagai anggota yang disetujui dari perusahaan target. Pemanggil yang tidak sah menerima 403 PermissionError.

Prasyarat

✅ Bearer token yang valid untuk anggota workspace yang disetujui
✅ Company ID yang diambil dari GET {{URL}}/accounts/companies
✅ Order ID (Project ID, pid) dari pesanan yang ingin Anda perbarui

Endpoint

PUT {{URL}}/orders?pid=<ORDER_ID>

Content-Type: multipart/form-data — gunakan ini bahkan ketika tidak ada file yang dilampirkan untuk memenuhi parser multipart server.

Header	Diperlukan	Deskripsi
`Authorization`	Ya	`Bearer <ACCESS_TOKEN>` — token akses anggota yang masuk.
`companyid`	Ya	Mongo ObjectId dari perusahaan yang pesanannya dimiliki.
`clientid`	Opsional	ID socket klien real-time. Jika disediakan, notifikasi menyertakannya.

Parameter kueri

string

wajib

Order / Project ID yang akan diperbarui. Teruskan ini sebagai parameter string kueri.

Kolom isi permintaan

string

Memperbarui judul pesanan. Minimal 2 karakter.

string

Status baru untuk pesanan. Harus salah satu dari: Pending, Ongoing, Review, Completed, Cancelled.Transisi yang diizinkan:

Review hanya dapat mengikuti Ongoing atau Review lainnya. Melompat dari Pending langsung ke Review mengembalikan 400 ValidationError.
Pesanan yang sudah Completed atau Cancelled tidak dapat diperbarui.
Klien tidak dapat membatalkan pesanan yang telah melewati Pending.

number

Angka total anggaran. Harus ≥ 0. Menggunakan mata uang pesanan yang ada kecuali currency juga disediakan.

string

Kode mata uang untuk anggaran. Contoh: USD, CAD, EUR.

number

Jumlah unit yang dibeli untuk paket. Harus ≥ 1.

string

String tanggal ISO 8601 untuk tanggal jatuh tempo pesanan. Contoh: "2025-12-31T00:00:00.000Z".

string

String tanggal ISO 8601 untuk tanggal mulai proyek.

string

Catatan internal yang terlihat oleh tim Anda.

string

Brief klien atau ringkasan proyek.

array

Daftar lengkap ID anggota manajer proyek yang akan ditetapkan ke pesanan ini. ID baru ditambahkan ke tim; ID yang dihapus dihilangkan. Setiap ID harus milik anggota dengan peran projectManager di perusahaan yang sama.

boolean

Diperlukan ketika status adalah Completed atau Cancelled. Jika true, semua tugas dalam pesanan ditandai selesai setelah perubahan status. Jika false, tugas tetap dalam kondisi saat ini.

boolean

Hanya diizinkan ketika status adalah Completed atau Cancelled. Jika true, semua tugas yang diminta klien yang belum selesai ditolak setelah pembaruan status.

number

Hanya diperlukan untuk pesanan langganan saat mengubah frekuensi perulangan. Pasangkan dengan repeatDuration.

string

Diperlukan bersama repeatCount untuk pesanan langganan. Salah satu dari: day, week, month, year.

number

Batas opsional pada siklus penagihan berulang. Default ke 0 (tanpa batas).

string

Cara setiap siklus penagihan ditangani. Salah satu dari: createOrderWithTask, noChange.

file

Nol atau lebih lampiran file. File ditambahkan ke folder sistem pesanan; file yang ada tidak pernah ditimpa. Gunakan encoding multipart/form-data dan lampirkan setiap file di bawah kolom files.

Contoh permintaan

curl --request PUT "https://api.agencyhandy.com/orders?pid=ORDER_ID_HERE" \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  --header "companyid: <COMPANY_ID>" \
  --form "name=Website Redesign" \
  --form "status=Review" \
  --form "budget=12000" \
  --form "currency=USD" \
  --form "quantity=1" \
  --form "assignedProjectManagers[]=PROJECT_MANAGER_ID" \
  --form "notes=Scope finalized with client." \
  --form "brief=Launch-ready design refresh."

curl --request PUT "https://api.agencyhandy.com/orders?pid=ORDER_ID_HERE" \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  --header "companyid: <COMPANY_ID>" \
  --form "name=Website Redesign" \
  --form "status=Review" \
  --form "budget=12000" \
  --form "repeatCount=3" \
  --form "repeatDuration=month" \
  --form "billingCycleEvent=createOrderWithTask" \
  --form "files=@/path/to/creative-brief.pdf"

Payload JSON yang setara (konversi ke entri formulir multipart saat mengirim file):

{
  "name": "Website Redesign",
  "status": "Review",
  "budget": 12000,
  "currency": "USD",
  "quantity": 1,
  "assignedProjectManagers": ["{{PROJECT_MANAGER_ID}}"],
  "repeatCount": 3,
  "repeatDuration": "month",
  "billingCycleEvent": "createOrderWithTask",
  "notes": "Scope finalized with client.",
  "brief": "Launch-ready design refresh."
}

Respons

Status HTTP	Deskripsi
`200 OK`	Pembaruan berhasil.
`400 ValidationError`	ID pesanan tidak valid, transisi status yang diblokir, atau payload yang salah bentuk. Respons menyertakan `fieldName` jika relevan.
`403 PermissionError`	Pemanggil bukan anggota yang disetujui, tidak memiliki peran perusahaan, langganan workspace telah kedaluwarsa, atau klien mencoba pembatalan yang dilarang.
`500 Internal Server Error`	Pengecualian yang tidak ditangani — periksa log server.

Respons sukses

{
  "message": "Project has been updated"
}

Aturan bisnis dan efek samping

Transisi status dibatasi. Review hanya dapat mengikuti Ongoing atau Review lainnya. Mencoba Pending → Review mengembalikan 400 ValidationError.
Memindahkan status dari Pending ke Ongoing, Review, atau Completed mengaktifkan folder file pesanan sehingga file yang diunggah dapat diakses oleh tim proyek.
Menetapkan status ke Completed atau Cancelled mengharuskan markTasksAsDone diatur secara eksplisit ke true atau false.
Perubahan status ke Review, Completed, atau Cancelled secara otomatis memicu notifikasi klien:
- Review — memberi tahu klien bahwa tinjauan diperlukan.
- Completed — mengirimkan notifikasi orderCompletion ke klien.
- Cancelled — mengirimkan notifikasi orderCancellation ke klien.
Setiap pembaruan yang berhasil memicu peristiwa webhook ORDER.UPDATED dengan dokumen pesanan yang diperbarui dan metadata lampiran, jika Anda memiliki webhook aktif yang berlangganan peristiwa tersebut.

Pengantar

Endpoints

AgencyHandy API: Perbarui Pesanan yang Ada dengan PUT

Prasyarat

Endpoint

Header

Parameter kueri

Kolom isi permintaan

Contoh permintaan

Respons

Respons sukses

Aturan bisnis dan efek samping

​Prasyarat

​Endpoint

​Header

​Parameter kueri

​Kolom isi permintaan

​Contoh permintaan

​Respons

​Respons sukses

​Aturan bisnis dan efek samping

Prasyarat

Endpoint

Header

Parameter kueri

Kolom isi permintaan

Contoh permintaan

Respons

Respons sukses

Aturan bisnis dan efek samping