AgencyHandy API: PUT ile Mevcut Siparişi Güncelleyin

Siparişi Güncelle uç noktası, AgencyHandy’deki mevcut bir siparişi (projeyi) harici bir sistem veya otomasyon komut dosyasından değiştirmenizi sağlar — adını, durumunu, bütçesini, zaman çizelgesini, atanan yöneticileri ve daha fazlasını güncelleyebilirsiniz. Uç nokta ayrıca dosya eklerini de destekler; eklenen dosyalar siparişin sistem klasörüne eklenir.

Bu uç noktayı kullanmadan önce API anahtarınızı ve Şirket Kimliğinizi edinmek için Başlarken rehberini tamamlayın.

Bu uç nokta yalnızca x-api-key başlığı yerine Authorization: Bearer <token> (giriş yapmış bir üyenin erişim token’ı) kullanır. Çağrı yapanın hedef şirketin onaylı bir üyesi olarak kimliği doğrulanmış olduğundan emin olun. Yetkisiz çağrı yapanlar 403 PermissionError alır.

Ön koşullar

✅ Onaylı bir çalışma alanı üyesi için geçerli Bearer token
✅ GET {{URL}}/accounts/companies ile alınan Şirket Kimliği
✅ Güncellemek istediğiniz siparişin Sipariş Kimliği (Proje Kimliği, pid)

Uç nokta

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

Content-Type: multipart/form-data — dosya eklenmese bile sunucunun çok parçalı ayrıştırıcısını karşılamak için bunu kullanın.

Başlıklar

Başlık	Zorunlu	Açıklama
`Authorization`	Evet	`Bearer <ACCESS_TOKEN>` — giriş yapmış üyenin erişim token’ı.
`companyid`	Evet	Siparişin ait olduğu şirketin Mongo ObjectId’si.
`clientid`	İsteğe bağlı	Gerçek zamanlı istemci soket kimliği. Sağlandığında bildirimler bunu içerir.

Sorgu parametreleri

string

gerekli

Güncellenecek Sipariş / Proje Kimliği. Bunu sorgu dizesi parametresi olarak iletin.

İstek gövdesi alanları

string

Sipariş başlığını günceller. En az 2 karakter olmalıdır.

string

Sipariş için yeni durum. Şunlardan biri olmalıdır: Pending, Ongoing, Review, Completed, Cancelled.İzin verilen geçişler:

Review yalnızca Ongoing veya başka bir Review durumunun ardından gelebilir. Pending durumundan doğrudan Review durumuna geçiş yapmak 400 ValidationError döndürür.
Completed veya Cancelled durumundaki siparişler güncellenemez.
Müşteriler, Pending aşamasını geçmiş bir siparişi iptal edemez.

number

Toplam bütçe rakamı. ≥ 0 olmalıdır. currency de sağlanmadığı sürece siparişin mevcut para birimini kullanır.

string

Bütçe için para birimi kodu. Örnekler: USD, CAD, EUR.

number

Paket için satın alınan birim sayısı. ≥ 1 olmalıdır.

string

Siparişin son tarihi için ISO 8601 tarih dizesi. Örnek: "2025-12-31T00:00:00.000Z".

string

Projenin başlangıç tarihi için ISO 8601 tarih dizesi.

string

Ekibinize görünen dahili notlar.

string

Müşteri brifing’i veya proje özeti.

array

Bu siparişe atanacak proje yöneticisi üye kimliklerinin tam listesi. Yeni kimlikler ekibe eklenir; kaldırılan kimlikler silinir. Her kimlik, aynı şirket içinde projectManager rolüne sahip bir üyeye ait olmalıdır.

boolean

status Completed veya Cancelled olduğunda zorunludur. true olduğunda, durum değişikliğinin ardından siparişteki tüm görevler tamamlandı olarak işaretlenir. false olduğunda görevler mevcut durumlarında kalır.

boolean

Yalnızca status Completed veya Cancelled olduğunda kullanılabilir. true olduğunda, durum güncellemesinin ardından bekleyen tüm müşteri talep edilen görevler reddedilir.

number

Yalnızca tekrarlama sıklığı değiştirilirken abonelik siparişleri için zorunludur. repeatDuration ile birlikte kullanın.

string

Abonelik siparişleri için repeatCount ile birlikte zorunludur. Şunlardan biri: day, week, month, year.

number

Tekrarlayan faturalama döngüsü sayısı için isteğe bağlı sınır. Varsayılan olarak 0 (sınır yok) kullanılır.

string

Her faturalama döngüsünün nasıl işleneceği. Şunlardan biri: createOrderWithTask, noChange.

file

Sıfır veya daha fazla dosya eki. Dosyalar siparişin sistem klasörüne eklenir; mevcut dosyaların üzerine hiçbir zaman yazılmaz. multipart/form-data kodlamasını kullanın ve her dosyayı files alanı altında ekleyin.

Örnek istek

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"

Eşdeğer JSON içeriği (dosya gönderirken çok parçalı form girişlerine dönüştürün):

{
  "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."
}

Yanıtlar

HTTP Durumu	Açıklama
`200 OK`	Güncelleme başarılı.
`400 ValidationError`	Geçersiz sipariş kimliği, engellenmiş durum geçişi veya hatalı biçimlendirilmiş içerik. Yanıt, ilgili olduğunda `fieldName` içerir.
`403 PermissionError`	Çağrı yapan onaylı bir üye değil, şirket rolü eksik, çalışma alanı aboneliği süresi dolmuş veya bir müşteri yasak iptal işlemi denedi.
`500 Internal Server Error`	İşlenmeyen istisna — sunucu günlüklerini kontrol edin.

Başarı yanıtı

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

İş kuralları ve yan etkiler

Durum geçişleri kısıtlıdır. Review yalnızca Ongoing veya başka bir Review durumunun ardından gelebilir. Pending → Review geçişi denenirse 400 ValidationError döndürür.
Durumu Pending’den Ongoing, Review veya Completed’a taşımak, yüklenen dosyaların proje ekibine erişilebilir hale gelmesi için siparişin dosya klasörünü etkinleştirir.
status değerini Completed veya Cancelled olarak ayarlamak, markTasksAsDone değerinin açıkça true veya false olarak ayarlanmasını gerektirir.
Review, Completed veya Cancelled durumuna geçişler otomatik olarak müşteri bildirimlerini tetikler:
- Review — müşteriye inceleme gerektiği bildirilir.
- Completed — müşteriye orderCompletion bildirimi gönderilir.
- Cancelled — müşteriye orderCancellation bildirimi gönderilir.
Her başarılı güncelleme, bu olaya abone aktif bir webhook’unuz varsa güncellenmiş sipariş belgesi ve ek meta verileriyle birlikte ORDER.UPDATED webhook olayını tetikler.

Giriş

Uç Noktalar

AgencyHandy API: PUT ile Mevcut Siparişi Güncelleyin

Ön koşullar

Uç nokta

Başlıklar

Sorgu parametreleri

İstek gövdesi alanları

Örnek istek

Yanıtlar

Başarı yanıtı

İş kuralları ve yan etkiler

​Ön koşullar

​Uç nokta

​Başlıklar

​Sorgu parametreleri

​İstek gövdesi alanları

​Örnek istek

​Yanıtlar

​Başarı yanıtı

​İş kuralları ve yan etkiler

Ön koşullar

Uç nokta

Başlıklar

Sorgu parametreleri

İstek gövdesi alanları

Örnek istek

Yanıtlar

Başarı yanıtı

İş kuralları ve yan etkiler