Spring til hovedindhold
Opdater ordre-endpointet lader dig ændre en eksisterende ordre (projekt) i AgencyHandy — ændre dens navn, status, budget, tidslinje, tildelte ledere og meget mere — alt fra et eksternt system eller automatiseringsscript. Endpointet understøtter også filvedhæftninger, som tilføjes til ordrens systemmappe.
Inden du bruger dette endpoint, skal du fuldføre vejledningen Kom godt i gang for at hente din API-nøgle og dit Company ID.
Dette endpoint bruger Authorization: Bearer <token> (et indlogget medlems adgangstoken) frem for blot x-api-key-headeren. Sørg for, at din kaldende part er godkendt som et godkendt medlem af målvirksomheden. Uautoriserede kaldende parter modtager en 403 PermissionError.

​
Forudsætninger

  • ✅ Et gyldigt Bearer-token for et godkendt workspace-medlem
  • ✅ Company ID hentet fra GET {{URL}}/accounts/companies
  • ✅ Ordre-ID’et (Projekt-ID, pid) for den ordre, du vil opdatere

​
Endpoint

PUT {{URL}}/orders?pid=<ORDER_ID>
Content-Type: multipart/form-data — brug dette, selv når ingen filer er vedhæftet, for at tilfredsstille serverens multipart-parser.

​
Headers

HeaderPåkrævetBeskrivelse
AuthorizationJaBearer <ACCESS_TOKEN> — det indloggede medlems adgangstoken.
companyidJaMongo ObjectId for det bureau, ordren tilhører.
clientidValgfritKlientens realtids-socket-ID. Når det angives, inkluderes det i notifikationer.

​
Forespørgselsparametre

​
pid
string
påkrævet
Ordre/Projekt-ID’et der skal opdateres. Send dette som en forespørgselsstrengparameter.

​
Felter i anmodningskroppen

​
name
string
Opdaterer ordretitlen. Minimum 2 tegn.
​
status
string
Ny status for ordren. Skal være én af: Pending, Ongoing, Review, Completed, Cancelled.Tilladte overgange:
  • Review kan kun følge Ongoing eller en anden Review. Hop fra Pending direkte til Review returnerer en 400 ValidationError.
  • Ordrer der allerede er Completed eller Cancelled kan ikke opdateres.
  • Klienter kan ikke annullere en ordre, der er gået videre end Pending.
​
budget
number
Samlet budgettal. Skal være ≥ 0. Bruger ordrens eksisterende valuta, medmindre currency også angives.
​
currency
string
Valutakode for budgettet. Eksempler: USD, CAD, EUR.
​
quantity
number
Antal enheder købt for pakken. Skal være ≥ 1.
​
deadline
string
ISO 8601-datostreng for ordrens forfaldsdato. Eksempel: "2025-12-31T00:00:00.000Z".
​
kickoffDate
string
ISO 8601-datostreng for projektets startdato.
​
notes
string
Interne noter synlige for dit team.
​
brief
string
Klientens brief eller projektsammenfatning.
​
assignedProjectManagers
array
Komplet liste over projektleder-medlem-ID’er, der skal tildeles til denne ordre. Nye ID’er tilføjes til teamet; fjernede ID’er slettes. Hvert ID skal tilhøre et medlem med en projectManager-rolle i det samme bureau.
​
markTasksAsDone
boolean
Påkrævet når status er Completed eller Cancelled. Når true, markeres alle opgaver i ordren som udført efter statusændringen. Når false forbliver opgaverne i deres nuværende tilstand.
​
rejectRequestedTasks
boolean
Kun tilladt når status er Completed eller Cancelled. Når true, afvises alle udestående klient-anmodede opgaver efter statusopdateringen.
​
repeatCount
number
Kun påkrævet for abonnementsordrer ved ændring af gentagelsesfrekvens. Par med repeatDuration.
​
repeatDuration
string
Påkrævet sammen med repeatCount for abonnementsordrer. Én af: day, week, month, year.
​
billingCycleCount
number
Valgfri grænse for tilbagevendende faktureringscyklusser. Standardværdi er 0 (ingen grænse).
​
billingCycleEvent
string
Hvordan hver faktureringscyklus håndteres. Én af: createOrderWithTask, noChange.
​
files
file
Nul eller flere filvedhæftninger. Filer tilføjes til ordrens systemmappe; eksisterende filer overskrives aldrig. Brug multipart/form-data-kodning og vedhæft hver fil under files-feltet.

​
Eksempelanmodning

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."
Tilsvarende JSON-nyttelast (konverter til multipart form-poster ved afsendelse af filer): 
{
  "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."
}

​
Svar

HTTP-statusBeskrivelse
200 OKOpdatering lykkedes.
400 ValidationErrorUgyldigt ordre-ID, blokeret statusovergang eller forkert formateret nyttelast. Svaret inkluderer fieldName, når det er relevant.
403 PermissionErrorDen kaldende part er ikke et godkendt medlem, mangler bureaurollen, workspace-abonnementet er udløbet, eller en klient forsøgte en forbudt annullering.
500 Internal Server ErrorUhåndteret undtagelse — tjek serverlogge.

​
Succesfuldt svar

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

​
Forretningsregler og sideeffekter

  • Statusovergange er begrænsede. Review kan kun følge Ongoing eller en anden Review. Forsøg på Pending → Review returnerer 400 ValidationError.
  • Flytning af en status fra Pending til Ongoing, Review eller Completed aktiverer ordrens filmappe, så uploadede filer bliver tilgængelige for projektteamet.
  • Indstilling af status til Completed eller Cancelled kræver, at markTasksAsDone eksplicit sættes til true eller false.
  • Statusændringer til Review, Completed eller Cancelled udløser automatisk klientnotifikationer:
    • Review — notificerer klienten om, at gennemgang er nødvendig.
    • Completed — sender orderCompletion-notifikationen til klienten.
    • Cancelled — sender orderCancellation-notifikationen til klienten.
  • Hver vellykket opdatering udløser en ORDER.UPDATED webhook-hændelse med det opdaterede ordredokument og vedhæftningsmetadata, hvis du har en aktiv webhook abonneret på den hændelse.