AgencyHandy API: Eine bestehende Bestellung mit PUT aktualisieren

Der Endpunkt „Bestellung aktualisieren“ ermöglicht es Ihnen, eine bestehende Bestellung (Projekt) in AgencyHandy zu ändern — Name, Status, Budget, Zeitplan, zugewiesene Manager und mehr — alles aus einem externen System oder Automatisierungsskript heraus. Der Endpunkt unterstützt auch Dateianhänge, die dem Systemordner der Bestellung hinzugefügt werden.

Bevor Sie diesen Endpunkt verwenden, schließen Sie den Leitfaden Erste Schritte ab, um Ihren API-Schlüssel und Ihre Unternehmens-ID zu erhalten.

Dieser Endpunkt verwendet Authorization: Bearer <token> (das Zugriffstoken eines angemeldeten Mitglieds) anstatt nur den x-api-key-Header. Stellen Sie sicher, dass Ihr Aufrufer als genehmigtes Mitglied des Zielunternehmens authentifiziert ist. Nicht autorisierte Aufrufer erhalten einen 403 PermissionError.

Voraussetzungen

✅ Ein gültiges Bearer-Token für ein genehmigtes Workspace-Mitglied
✅ Unternehmens-ID abgerufen aus GET {{URL}}/accounts/companies
✅ Die Bestell-ID (Projekt-ID, pid) der Bestellung, die Sie aktualisieren möchten

Endpunkt

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

Content-Type: multipart/form-data — verwenden Sie dies auch dann, wenn keine Dateien angehängt werden, um den Multipart-Parser des Servers zu erfüllen.

Header	Erforderlich	Beschreibung
`Authorization`	Ja	`Bearer <ACCESS_TOKEN>` — das Zugriffstoken des angemeldeten Mitglieds.
`companyid`	Ja	Mongo ObjectId des Unternehmens, zu dem die Bestellung gehört.
`clientid`	Optional	Echtzeit-Client-Socket-ID. Wenn angegeben, werden Benachrichtigungen damit versehen.

Abfrageparameter

string

erforderlich

Die zu aktualisierende Bestell-/Projekt-ID. Übergeben Sie diese als Abfrage-String-Parameter.

Anfrage-Body-Felder

string

Aktualisiert den Bestelltitel. Mindestens 2 Zeichen.

string

Neuer Status für die Bestellung. Muss eines der folgenden sein: Pending, Ongoing, Review, Completed, Cancelled.Erlaubte Übergänge:

Review kann nur auf Ongoing oder ein weiteres Review folgen. Ein direkter Sprung von Pending zu Review gibt einen 400 ValidationError zurück.
Bestellungen, die bereits Completed oder Cancelled sind, können nicht aktualisiert werden.
Kunden können eine Bestellung, die über Pending hinausgegangen ist, nicht stornieren.

number

Gesamtbudgetbetrag. Muss ≥ 0 sein. Verwendet die bestehende Währung der Bestellung, es sei denn, currency wird ebenfalls angegeben.

string

Währungscode für das Budget. Beispiele: USD, CAD, EUR.

number

Anzahl der für das Paket gekauften Einheiten. Muss ≥ 1 sein.

string

ISO 8601-Datumszeichenfolge für das Fälligkeitsdatum der Bestellung. Beispiel: "2025-12-31T00:00:00.000Z".

string

ISO 8601-Datumszeichenfolge für das Projektstartdatum.

string

Interne Notizen, die für Ihr Team sichtbar sind.

string

Kundenbriefing oder Projektzusammenfassung.

array

Vollständige Liste der Projektmanager-Mitglieds-IDs, die dieser Bestellung zugewiesen werden sollen. Neue IDs werden dem Team hinzugefügt; entfernte IDs werden gelöscht. Jede ID muss einem Mitglied mit einer projectManager-Rolle im selben Unternehmen gehören.

boolean

Erforderlich, wenn status Completed oder Cancelled ist. Wenn true, werden alle Aufgaben in der Bestellung nach der Statusänderung als erledigt markiert. Wenn false, verbleiben Aufgaben in ihrem aktuellen Zustand.

boolean

Nur erlaubt, wenn status Completed oder Cancelled ist. Wenn true, werden alle ausstehenden vom Kunden angeforderten Aufgaben nach der Statusaktualisierung abgelehnt.

number

Nur bei Abonnement-Bestellungen erforderlich, wenn die Wiederholungsfrequenz geändert wird. Mit repeatDuration kombinieren.

string

Zusammen mit repeatCount für Abonnement-Bestellungen erforderlich. Eines von: day, week, month, year.

number

Optionale Begrenzung der wiederkehrenden Abrechnungszyklen. Standardmäßig 0 (keine Begrenzung).

string

Wie jeder Abrechnungszyklus behandelt wird. Eines von: createOrderWithTask, noChange.

file

Null oder mehr Dateianhänge. Dateien werden dem Systemordner der Bestellung hinzugefügt; bestehende Dateien werden nie überschrieben. Verwenden Sie multipart/form-data-Kodierung und hängen Sie jede Datei unter dem files-Feld an.

Beispielanfrage

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"

Entsprechende JSON-Nutzlast (in Multipart-Formulareinträge umwandeln beim Senden von Dateien):

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

Antworten

HTTP-Status	Beschreibung
`200 OK`	Aktualisierung erfolgreich.
`400 ValidationError`	Ungültige Bestell-ID, blockierter Statusübergang oder fehlerhafte Nutzlast. Antwort enthält `fieldName`, wenn relevant.
`403 PermissionError`	Der Aufrufer ist kein genehmigtes Mitglied, fehlt die Unternehmensrolle, das Workspace-Abonnement ist abgelaufen, oder ein Kunde hat versucht, eine unerlaubte Stornierung durchzuführen.
`500 Internal Server Error`	Nicht behandelte Ausnahme — Serverprotokolle prüfen.

Erfolgsantwort

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

Geschäftsregeln und Nebeneffekte

Statusübergänge sind eingeschränkt. Review kann nur auf Ongoing oder ein weiteres Review folgen. Der Versuch Pending → Review gibt 400 ValidationError zurück.
Das Verschieben eines Status von Pending zu Ongoing, Review oder Completed aktiviert den Dateiordner der Bestellung, sodass hochgeladene Dateien für das Projektteam zugänglich werden.
Das Setzen von status auf Completed oder Cancelled erfordert, dass markTasksAsDone explizit auf true oder false gesetzt wird.
Statusänderungen zu Review, Completed oder Cancelled lösen automatisch Kundenbenachrichtigungen aus:
- Review — benachrichtigt den Kunden, dass eine Überprüfung erforderlich ist.
- Completed — sendet die orderCompletion-Benachrichtigung an den Kunden.
- Cancelled — sendet die orderCancellation-Benachrichtigung an den Kunden.
Jede erfolgreiche Aktualisierung löst ein ORDER.UPDATED-Webhook-Ereignis mit dem aktualisierten Bestelldokument und Anhang-Metadaten aus, wenn Sie einen aktiven Webhook haben, der dieses Ereignis abonniert hat.

Einführung

Endpunkte

AgencyHandy API: Eine bestehende Bestellung mit PUT aktualisieren

Voraussetzungen

Endpunkt

Header

Abfrageparameter

Anfrage-Body-Felder

Beispielanfrage

Antworten

Erfolgsantwort

Geschäftsregeln und Nebeneffekte

​Voraussetzungen

​Endpunkt

​Header

​Abfrageparameter

​Anfrage-Body-Felder

​Beispielanfrage

​Antworten

​Erfolgsantwort

​Geschäftsregeln und Nebeneffekte

Voraussetzungen

Endpunkt

Header

Abfrageparameter

Anfrage-Body-Felder

Beispielanfrage

Antworten

Erfolgsantwort

Geschäftsregeln und Nebeneffekte