Langsung ke konten utama
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.
HeaderDiperlukanDeskripsi
AuthorizationYaBearer <ACCESS_TOKEN> — token akses anggota yang masuk.
companyidYaMongo ObjectId dari perusahaan yang pesanannya dimiliki.
clientidOpsionalID socket klien real-time. Jika disediakan, notifikasi menyertakannya.

​
Parameter kueri

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

​
Kolom isi permintaan

​
name
string
Memperbarui judul pesanan. Minimal 2 karakter.
​
status
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.
​
budget
number
Angka total anggaran. Harus ≥ 0. Menggunakan mata uang pesanan yang ada kecuali currency juga disediakan.
​
currency
string
Kode mata uang untuk anggaran. Contoh: USD, CAD, EUR.
​
quantity
number
Jumlah unit yang dibeli untuk paket. Harus ≥ 1.
​
deadline
string
String tanggal ISO 8601 untuk tanggal jatuh tempo pesanan. Contoh: "2025-12-31T00:00:00.000Z".
​
kickoffDate
string
String tanggal ISO 8601 untuk tanggal mulai proyek.
​
notes
string
Catatan internal yang terlihat oleh tim Anda.
​
brief
string
Brief klien atau ringkasan proyek.
​
assignedProjectManagers
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.
​
markTasksAsDone
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.
​
rejectRequestedTasks
boolean
Hanya diizinkan ketika status adalah Completed atau Cancelled. Jika true, semua tugas yang diminta klien yang belum selesai ditolak setelah pembaruan status.
​
repeatCount
number
Hanya diperlukan untuk pesanan langganan saat mengubah frekuensi perulangan. Pasangkan dengan repeatDuration.
​
repeatDuration
string
Diperlukan bersama repeatCount untuk pesanan langganan. Salah satu dari: day, week, month, year.
​
billingCycleCount
number
Batas opsional pada siklus penagihan berulang. Default ke 0 (tanpa batas).
​
billingCycleEvent
string
Cara setiap siklus penagihan ditangani. Salah satu dari: createOrderWithTask, noChange.
​
files
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."
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 HTTPDeskripsi
200 OKPembaruan berhasil.
400 ValidationErrorID pesanan tidak valid, transisi status yang diblokir, atau payload yang salah bentuk. Respons menyertakan fieldName jika relevan.
403 PermissionErrorPemanggil bukan anggota yang disetujui, tidak memiliki peran perusahaan, langganan workspace telah kedaluwarsa, atau klien mencoba pembatalan yang dilarang.
500 Internal Server ErrorPengecualian 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.