AgencyHandy API: Een Bestaande Bestelling Bijwerken met PUT

Met het eindpunt Bestelling bijwerken kunt u een bestaande bestelling (project) in AgencyHandy aanpassen — naam, status, budget, tijdlijn, toegewezen managers en meer wijzigen — allemaal vanuit een extern systeem of automatiseringsscript. Het eindpunt ondersteunt ook bestandsbijlagen, die worden toegevoegd aan de systeemmap van de bestelling.

Voltooi voordat u dit eindpunt gebruikt de gids Aan de Slag om uw API-sleutel en Bedrijfs-ID te verkrijgen.

Dit eindpunt gebruikt Authorization: Bearer <token> (het toegangstoken van een aangemeld lid) in plaats van alleen de x-api-key-header. Zorg ervoor dat uw aanroeper is geauthenticeerd als een goedgekeurd lid van het doelbedrijf. Niet-geautoriseerde aanroepers ontvangen een 403 PermissionError.

Vereisten

✅ Een geldig Bearer-token voor een goedgekeurd werkruimtelid
✅ Bedrijfs-ID opgehaald via GET {{URL}}/accounts/companies
✅ Het Bestelling-ID (Project-ID, pid) van de bestelling die u wilt bijwerken

Eindpunt

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

Content-Type: multipart/form-data — gebruik dit ook wanneer er geen bestanden zijn bijgevoegd om te voldoen aan de multipart-parser van de server.

Headers

Header	Vereist	Beschrijving
`Authorization`	Ja	`Bearer <ACCESS_TOKEN>` — het toegangstoken van het aangemelde lid.
`companyid`	Ja	Mongo ObjectId van het bedrijf waartoe de bestelling behoort.
`clientid`	Optioneel	Real-time client socket-ID. Wanneer opgegeven, worden meldingen hiermee inclusief.

Queryparameters

string

vereist

Het Bestelling-/Project-ID dat bijgewerkt moet worden. Geef dit door als een querystring-parameter.

Verzoekbody-velden

string

Werkt de bestellingstitel bij. Minimaal 2 tekens.

string

Nieuwe status voor de bestelling. Moet een van de volgende zijn: Pending, Ongoing, Review, Completed, Cancelled.Toegestane overgangen:

Review kan alleen volgen op Ongoing of een andere Review. Springen van Pending direct naar Review geeft een 400 ValidationError.
Bestellingen die al Completed of Cancelled zijn, kunnen niet worden bijgewerkt.
Klanten kunnen een bestelling die verder is gegaan dan Pending niet annuleren.

number

Totaal budgetbedrag. Moet ≥ 0 zijn. Gebruikt de bestaande valuta van de bestelling tenzij ook currency is opgegeven.

string

Valutacode voor het budget. Voorbeelden: USD, CAD, EUR.

number

Aantal gekochte eenheden voor het pakket. Moet ≥ 1 zijn.

string

ISO 8601-datumreeks voor de vervaldatum van de bestelling. Voorbeeld: "2025-12-31T00:00:00.000Z".

string

ISO 8601-datumreeks voor de startdatum van het project.

string

Interne notities zichtbaar voor uw team.

string

Klantbriefing of projectsamenvatting.

array

Volledige lijst van projectmanager-lid-ID’s om toe te wijzen aan deze bestelling. Nieuwe ID’s worden aan het team toegevoegd; verwijderde ID’s worden verwijderd. Elk ID moet behoren aan een lid met een projectManager-rol binnen hetzelfde bedrijf.

boolean

Vereist wanneer status Completed of Cancelled is. Wanneer true, worden alle taken in de bestelling als gereed gemarkeerd na de statuswijziging. Wanneer false, blijven taken in hun huidige staat.

boolean

Alleen toegestaan wanneer status Completed of Cancelled is. Wanneer true, worden alle openstaande door de klant verzochte taken afgewezen na de statusupdate.

number

Alleen vereist voor abonnementsbestellingen bij het wijzigen van de herhalingsfrequentie. Combineer met repeatDuration.

string

Vereist naast repeatCount voor abonnementsbestellingen. Een van: day, week, month, year.

number

Optionele limiet op terugkerende factureringscycli. Standaard 0 (geen limiet).

string

Hoe elke factureringscyclus wordt afgehandeld. Een van: createOrderWithTask, noChange.

file

Nul of meer bestandsbijlagen. Bestanden worden toegevoegd aan de systeemmap van de bestelling; bestaande bestanden worden nooit overschreven. Gebruik multipart/form-data-codering en voeg elk bestand toe onder het veld files.

Voorbeeldverzoek

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"

Equivalent JSON-payload (converteer naar multipart-formulieritems bij het verzenden van bestanden):

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

Antwoorden

HTTP-status	Beschrijving
`200 OK`	Update geslaagd.
`400 ValidationError`	Ongeldig bestelling-ID, geblokkeerde statusovergang of onjuist gevormde payload. Het antwoord bevat `fieldName` indien van toepassing.
`403 PermissionError`	De aanroeper is geen goedgekeurd lid, mist de bedrijfsrol, het werkruimteabonnement is verlopen of een klant probeerde een verboden annulering.
`500 Internal Server Error`	Onverwerkte uitzondering — controleer serverlogs.

Succesantwoord

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

Bedrijfsregels en neveneffecten

Statusovergangen zijn beperkt. Review kan alleen volgen op Ongoing of een andere Review. Een poging tot Pending → Review geeft een 400 ValidationError.
Het verplaatsen van een status van Pending naar Ongoing, Review of Completed activeert de bestandsmap van de bestelling zodat geüploade bestanden toegankelijk worden voor het projectteam.
Het instellen van status op Completed of Cancelled vereist dat markTasksAsDone expliciet wordt ingesteld op true of false.
Statuswijzigingen naar Review, Completed of Cancelled activeren automatisch klantmeldingen:
- Review — informeert de klant dat beoordeling nodig is.
- Completed — stuurt de orderCompletion-melding naar de klant.
- Cancelled — stuurt de orderCancellation-melding naar de klant.
Elke succesvolle update activeert een ORDER.UPDATED-webhookgebeurtenis met het bijgewerkte bestellingsdocument en bijlagemetadata, als u een actieve webhook heeft die is geabonneerd op die gebeurtenis.

Introductie

Endpoints

AgencyHandy API: Een Bestaande Bestelling Bijwerken met PUT

Vereisten

Eindpunt

Headers

Queryparameters

Verzoekbody-velden

Voorbeeldverzoek

Antwoorden

Succesantwoord

Bedrijfsregels en neveneffecten

​Vereisten

​Eindpunt

​Headers

​Queryparameters

​Verzoekbody-velden

​Voorbeeldverzoek

​Antwoorden

​Succesantwoord

​Bedrijfsregels en neveneffecten

Vereisten

Eindpunt

Headers

Queryparameters

Verzoekbody-velden

Voorbeeldverzoek

Antwoorden

Succesantwoord

Bedrijfsregels en neveneffecten