Přejít na hlavní obsah
Endpoint pro aktualizaci objednávky umožňuje upravit existující objednávku (projekt) v AgencyHandy — změnit její název, stav, rozpočet, časový plán, přiřazené manažery a další — vše z externího systému nebo automatizačního skriptu. Endpoint také podporuje přílohy souborů, které jsou připojeny do systémové složky objednávky.
Před použitím tohoto endpointu dokončete průvodce Začínáme a získejte svůj API klíč a ID společnosti.
Tento endpoint používá Authorization: Bearer <token> (přístupový token přihlášeného člena) namísto pouhé hlavičky x-api-key. Ujistěte se, že volající je ověřen jako schválený člen cílové společnosti. Neoprávnění volající obdrží odpověď 403 PermissionError.

​
Předpoklady

  • ✅ Platný Bearer token pro schváleného člena workspace
  • ✅ ID společnosti získané z GET {{URL}}/accounts/companies
  • ✅ ID objednávky (ID projektu, pid) objednávky, kterou chcete aktualizovat

​
Endpoint

PUT {{URL}}/orders?pid=<ORDER_ID>
Content-Type: multipart/form-data — použijte i tehdy, když nejsou připojeny žádné soubory, aby byl uspokojen multipart parser serveru.

​
Hlavičky

HlavičkaPovinnéPopis
AuthorizationAnoBearer <ACCESS_TOKEN> — přístupový token přihlášeného člena.
companyidAnoMongo ObjectId společnosti, ke které objednávka patří.
clientidVolitelnéID socketu klienta v reálném čase. Pokud je zadáno, oznámení jej budou obsahovat.

​
Parametry dotazu

​
pid
string
povinné
ID objednávky / projektu k aktualizaci. Předejte jako parametr řetězce dotazu.

​
Pole těla požadavku

​
name
string
Aktualizuje název objednávky. Minimálně 2 znaky.
​
status
string
Nový stav objednávky. Musí být jedním z: Pending, Ongoing, Review, Completed, Cancelled.Povolené přechody:
  • Review může následovat pouze po Ongoing nebo dalším Review. Přechod přímo z Pending na Review vrátí chybu 400 ValidationError.
  • Objednávky ve stavu Completed nebo Cancelled nelze aktualizovat.
  • Klienti nemohou zrušit objednávku, která postoupila za stav Pending.
​
budget
number
Celková výše rozpočtu. Musí být ≥ 0. Používá stávající měnu objednávky, pokud není zároveň zadána i currency.
​
currency
string
Kód měny pro rozpočet. Příklady: USD, CAD, EUR.
​
quantity
number
Počet zakoupených jednotek balíčku. Musí být ≥ 1.
​
deadline
string
Řetězec data ve formátu ISO 8601 pro datum splatnosti objednávky. Příklad: "2025-12-31T00:00:00.000Z".
​
kickoffDate
string
Řetězec data ve formátu ISO 8601 pro datum zahájení projektu.
​
notes
string
Interní poznámky viditelné pro váš tým.
​
brief
string
Briefing klienta nebo shrnutí projektu.
​
assignedProjectManagers
array
Úplný seznam ID členů projektových manažerů přiřazených k této objednávce. Nová ID jsou přidána do týmu; odebraná ID jsou smazána. Každé ID musí patřit členovi s rolí projectManager ve stejné společnosti.
​
markTasksAsDone
boolean
Povinné když je status Completed nebo Cancelled. Pokud je true, všechny úkoly v objednávce jsou po změně stavu označeny jako dokončené. Pokud je false, úkoly zůstanou ve svém aktuálním stavu.
​
rejectRequestedTasks
boolean
Povoleno pouze když je status Completed nebo Cancelled. Pokud je true, všechny nevyřešené úkoly vyžádané klientem jsou po aktualizaci stavu zamítnuty.
​
repeatCount
number
Vyžadováno pouze pro objednávky předplatného při změně frekvence opakování. Párujte s repeatDuration.
​
repeatDuration
string
Vyžadováno spolu s repeatCount pro objednávky předplatného. Jedna z hodnot: day, week, month, year.
​
billingCycleCount
number
Volitelný limit počtu fakturačních cyklů. Výchozí hodnota je 0 (bez limitu).
​
billingCycleEvent
string
Způsob zpracování každého fakturačního cyklu. Jedna z hodnot: createOrderWithTask, noChange.
​
files
file
Nula nebo více příloh souborů. Soubory jsou připojeny do systémové složky objednávky; stávající soubory nejsou nikdy přepsány. Použijte kódování multipart/form-data a každý soubor připojte pod pole files.

​
Ukázkový požadavek

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."
Ekvivalentní JSON datový obsah (převeďte na záznamy multipart formuláře při odesílání souborů): 
{
  "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."
}

​
Odpovědi

HTTP stavPopis
200 OKAktualizace proběhla úspěšně.
400 ValidationErrorNeplatné ID objednávky, zakázaný přechod stavu nebo chybně formátovaný datový obsah. Odpověď obsahuje fieldName, pokud je relevantní.
403 PermissionErrorVolající není schváleným členem, nemá roli ve společnosti, předplatné workspace vypršelo nebo se klient pokusil o zakázané zrušení.
500 Internal Server ErrorNeošetřená výjimka — zkontrolujte protokoly serveru.

​
Odpověď při úspěchu

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

​
Obchodní pravidla a vedlejší efekty

  • Přechody stavů jsou omezeny. Review může následovat pouze po Ongoing nebo dalším Review. Pokus o přechod Pending → Review vrátí chybu 400 ValidationError.
  • Přechod stavu z Pending na Ongoing, Review nebo Completed aktivuje složku souborů objednávky, takže nahrané soubory budou přístupné projektovému týmu.
  • Nastavení status na Completed nebo Cancelled vyžaduje explicitní nastavení markTasksAsDone na true nebo false.
  • Změny stavu na Review, Completed nebo Cancelled automaticky spustí oznámení klientovi:
    • Review — upozorní klienta, že je potřeba kontrola.
    • Completed — odešle klientovi oznámení orderCompletion.
    • Cancelled — odešle klientovi oznámení orderCancellation.
  • Každá úspěšná aktualizace spustí webhook událost ORDER.UPDATED s aktualizovaným dokumentem objednávky a metadaty příloh, pokud máte aktivní webhook přihlášený k odběru této události.