AgencyHandy API: Aktualizace existující objednávky pomocí PUT

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čka	Povinné	Popis
`Authorization`	Ano	`Bearer <ACCESS_TOKEN>` — přístupový token přihlášeného člena.
`companyid`	Ano	Mongo ObjectId společnosti, ke které objednávka patří.
`clientid`	Volitelné	ID socketu klienta v reálném čase. Pokud je zadáno, oznámení jej budou obsahovat.

Parametry dotazu

string

povinné

ID objednávky / projektu k aktualizaci. Předejte jako parametr řetězce dotazu.

Pole těla požadavku

string

Aktualizuje název objednávky. Minimálně 2 znaky.

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.

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.

string

Kód měny pro rozpočet. Příklady: USD, CAD, EUR.

number

Počet zakoupených jednotek balíčku. Musí být ≥ 1.

string

Řetězec data ve formátu ISO 8601 pro datum splatnosti objednávky. Příklad: "2025-12-31T00:00:00.000Z".

string

Řetězec data ve formátu ISO 8601 pro datum zahájení projektu.

string

Interní poznámky viditelné pro váš tým.

string

Briefing klienta nebo shrnutí projektu.

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.

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.

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.

number

Vyžadováno pouze pro objednávky předplatného při změně frekvence opakování. Párujte s repeatDuration.

string

Vyžadováno spolu s repeatCount pro objednávky předplatného. Jedna z hodnot: day, week, month, year.

number

Volitelný limit počtu fakturačních cyklů. Výchozí hodnota je 0 (bez limitu).

string

Způsob zpracování každého fakturačního cyklu. Jedna z hodnot: createOrderWithTask, noChange.

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

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"

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 stav	Popis
`200 OK`	Aktualizace proběhla úspěšně.
`400 ValidationError`	Neplatné ID objednávky, zakázaný přechod stavu nebo chybně formátovaný datový obsah. Odpověď obsahuje `fieldName`, pokud je relevantní.
`403 PermissionError`	Volají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 Error`	Neoš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.

Úvod

Endpoints

AgencyHandy API: Aktualizace existující objednávky pomocí PUT

Předpoklady

Endpoint

Hlavičky

Parametry dotazu

Pole těla požadavku

Ukázkový požadavek

Odpovědi

Odpověď při úspěchu

Obchodní pravidla a vedlejší efekty

​Předpoklady

​Endpoint

​Hlavičky

​Parametry dotazu

​Pole těla požadavku

​Ukázkový požadavek

​Odpovědi

​Odpověď při úspěchu

​Obchodní pravidla a vedlejší efekty

Předpoklady

Endpoint

Hlavičky

Parametry dotazu

Pole těla požadavku

Ukázkový požadavek

Odpovědi

Odpověď při úspěchu

Obchodní pravidla a vedlejší efekty