API AgencyHandy: aktualizacja istniejącego zamówienia metodą PUT

Punkt końcowy aktualizacji zamówienia umożliwia modyfikację istniejącego zamówienia (projektu) w AgencyHandy — zmianę nazwy, statusu, budżetu, harmonogramu, przypisanych kierowników i wiele więcej — wszystko z zewnętrznego systemu lub skryptu automatyzacji. Punkt końcowy obsługuje również załączniki plików, które są dołączane do folderu systemowego zamówienia.

Przed użyciem tego punktu końcowego ukończ przewodnik Pierwsze kroki, aby uzyskać klucz API i identyfikator firmy.

Ten punkt końcowy używa Authorization: Bearer <token> (tokenu dostępu zalogowanego członka) zamiast samego nagłówka x-api-key. Upewnij się, że wywołujący jest uwierzytelniony jako zatwierdzony członek docelowej firmy. Nieautoryzowani wywołujący otrzymują 403 PermissionError.

Wymagania wstępne

✅ Prawidłowy token Bearer dla zatwierdzonego członka przestrzeni roboczej
✅ Identyfikator firmy pobrany z GET {{URL}}/accounts/companies
✅ Identyfikator zamówienia (identyfikator projektu, pid) zamówienia, które chcesz zaktualizować

Punkt końcowy

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

Content-Type: multipart/form-data — użyj tego nawet jeśli nie dołączasz plików, aby spełnić wymagania parsera multipart serwera.

Nagłówki

Nagłówek	Wymagany	Opis
`Authorization`	Tak	`Bearer <ACCESS_TOKEN>` — token dostępu zalogowanego członka.
`companyid`	Tak	Identyfikator ObjectId Mongo firmy, do której należy zamówienie.
`clientid`	Opcjonalny	Identyfikator gniazda klienta w czasie rzeczywistym. Gdy podany, powiadomienia go zawierają.

Parametry zapytania

string

wymagane

Identyfikator zamówienia / projektu do aktualizacji. Przekaż jako parametr ciągu zapytania.

Pola ciała żądania

string

Aktualizuje tytuł zamówienia. Minimum 2 znaki.

string

Nowy status zamówienia. Musi być jednym z: Pending, Ongoing, Review, Completed, Cancelled.Dozwolone przejścia:

Review może następować tylko po Ongoing lub innym Review. Przejście z Pending bezpośrednio do Review zwraca 400 ValidationError.
Zamówień w statusie Completed lub Cancelled nie można aktualizować.
Klienci nie mogą anulować zamówienia, które przeszło poza status Pending.

number

Łączna kwota budżetu. Musi być ≥ 0. Używa istniejącej waluty zamówienia, chyba że podano również currency.

string

Kod waluty dla budżetu. Przykłady: USD, CAD, EUR.

number

Liczba zakupionych jednostek pakietu. Musi być ≥ 1.

string

Ciąg daty ISO 8601 dla terminu realizacji zamówienia. Przykład: "2025-12-31T00:00:00.000Z".

string

Ciąg daty ISO 8601 dla daty rozpoczęcia projektu.

string

Wewnętrzne notatki widoczne dla Twojego zespołu.

string

Brief klienta lub streszczenie projektu.

array

Kompletna lista identyfikatorów członków będących kierownikami projektów do przypisania do tego zamówienia. Nowe identyfikatory są dodawane do zespołu; usunięte identyfikatory są kasowane. Każdy identyfikator musi należeć do członka z rolą projectManager w tej samej firmie.

boolean

Wymagane gdy status to Completed lub Cancelled. Gdy true, wszystkie zadania w zamówieniu są oznaczane jako ukończone po zmianie statusu. Gdy false, zadania pozostają w bieżącym stanie.

boolean

Dozwolone tylko gdy status to Completed lub Cancelled. Gdy true, wszystkie oczekujące zadania zlecone przez klienta są odrzucane po aktualizacji statusu.

number

Wymagane tylko dla zamówień subskrypcyjnych przy zmianie częstotliwości powtarzania. Paruj z repeatDuration.

string

Wymagane razem z repeatCount dla zamówień subskrypcyjnych. Jedno z: day, week, month, year.

number

Opcjonalny limit cykli rozliczeniowych. Domyślnie 0 (bez limitu).

string

Sposób obsługi każdego cyklu rozliczeniowego. Jedno z: createOrderWithTask, noChange.

file

Zero lub więcej załączników plików. Pliki są dołączane do folderu systemowego zamówienia; istniejące pliki nigdy nie są nadpisywane. Użyj kodowania multipart/form-data i dołącz każdy plik w polu files.

Przykładowe żądanie

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"

Równoważny ładunek JSON (zamień na wpisy formularza multipart przy wysyłaniu plików):

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

Odpowiedzi

Status HTTP	Opis
`200 OK`	Aktualizacja zakończona sukcesem.
`400 ValidationError`	Nieprawidłowy identyfikator zamówienia, zablokowane przejście statusu lub niepoprawnie sformułowany ładunek. Odpowiedź zawiera `fieldName`, gdy jest to istotne.
`403 PermissionError`	Wywołujący nie jest zatwierdzonym członkiem, nie posiada roli firmowej, subskrypcja przestrzeni roboczej wygasła lub klient podjął próbę niedozwolonego anulowania.
`500 Internal Server Error`	Nieobsłużony wyjątek — sprawdź dzienniki serwera.

Odpowiedź sukcesu

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

Reguły biznesowe i skutki uboczne

Przejścia statusu są ograniczone. Review może następować tylko po Ongoing lub innym Review. Próba przejścia Pending → Review zwraca 400 ValidationError.
Zmiana statusu z Pending na Ongoing, Review lub Completed aktywuje folder plików zamówienia, dzięki czemu przesłane pliki stają się dostępne dla zespołu projektowego.
Ustawienie status na Completed lub Cancelled wymaga jawnego ustawienia markTasksAsDone na true lub false.
Zmiany statusu na Review, Completed lub Cancelled automatycznie wyzwalają powiadomienia dla klientów:
- Review — powiadamia klienta, że wymagana jest recenzja.
- Completed — wysyła powiadomienie orderCompletion do klienta.
- Cancelled — wysyła powiadomienie orderCancellation do klienta.
Każda udana aktualizacja wyzwala zdarzenie webhooka ORDER.UPDATED z zaktualizowanym dokumentem zamówienia i metadanymi załączników, jeśli masz aktywny webhook subskrybujący to zdarzenie.

Wprowadzenie

Endpointy

API AgencyHandy: aktualizacja istniejącego zamówienia metodą PUT

Wymagania wstępne

Punkt końcowy

Nagłówki

Parametry zapytania

Pola ciała żądania

Przykładowe żądanie

Odpowiedzi

Odpowiedź sukcesu

Reguły biznesowe i skutki uboczne

​Wymagania wstępne

​Punkt końcowy

​Nagłówki

​Parametry zapytania

​Pola ciała żądania

​Przykładowe żądanie

​Odpowiedzi

​Odpowiedź sukcesu

​Reguły biznesowe i skutki uboczne

Wymagania wstępne

Punkt końcowy

Nagłówki

Parametry zapytania

Pola ciała żądania

Przykładowe żądanie

Odpowiedzi

Odpowiedź sukcesu

Reguły biznesowe i skutki uboczne