Vai al contenuto principale
L’endpoint Aggiorna Ordine ti consente di modificare un ordine (progetto) esistente in AgencyHandy — cambiarne il nome, lo stato, il budget, la tempistica, i manager assegnati e altro ancora — tutto da un sistema esterno o uno script di automazione. L’endpoint supporta anche gli allegati file, che vengono aggiunti alla cartella di sistema dell’ordine.
Prima di utilizzare questo endpoint, completa la guida Getting Started per ottenere la tua chiave API e l’ID Azienda.
Questo endpoint usa Authorization: Bearer <token> (il token di accesso di un membro autenticato) anziché solo l’header x-api-key. Assicurati che il tuo chiamante sia autenticato come membro approvato dell’azienda di destinazione. I chiamanti non autorizzati ricevono un 403 PermissionError.

​
Prerequisiti

  • ✅ Un token Bearer valido per un membro approvato del workspace
  • ✅ ID Azienda recuperato da GET {{URL}}/accounts/companies
  • ✅ L’ID Ordine (ID Progetto, pid) dell’ordine che vuoi aggiornare

​
Endpoint

PUT {{URL}}/orders?pid=<ORDER_ID>
Content-Type: multipart/form-data — usa questo anche quando non vengono allegati file per soddisfare il parser multipart del server.
HeaderObbligatorioDescrizione
AuthorizationSìBearer <ACCESS_TOKEN> — il token di accesso del membro autenticato.
companyidSìObjectId Mongo dell’azienda a cui appartiene l’ordine.
clientidOpzionaleID socket client in tempo reale. Se fornito, le notifiche lo includono.

​
Parametri di query

​
pid
string
obbligatorio
L’ID Ordine / Progetto da aggiornare. Passalo come parametro della stringa di query.

​
Campi del corpo della richiesta

​
name
string
Aggiorna il titolo dell’ordine. Minimo 2 caratteri.
​
status
string
Nuovo stato per l’ordine. Deve essere uno tra: Pending, Ongoing, Review, Completed, Cancelled.Transizioni consentite:
  • Review può seguire solo Ongoing o un altro Review. Passare direttamente da Pending a Review restituisce un 400 ValidationError.
  • Gli ordini già Completed o Cancelled non possono essere aggiornati.
  • I clienti non possono annullare un ordine che è passato oltre Pending.
​
budget
number
Importo totale del budget. Deve essere ≥ 0. Usa la valuta esistente dell’ordine a meno che non venga fornita anche currency.
​
currency
string
Codice valuta per il budget. Esempi: USD, CAD, EUR.
​
quantity
number
Numero di unità acquistate per il pacchetto. Deve essere ≥ 1.
​
deadline
string
Stringa di data ISO 8601 per la scadenza dell’ordine. Esempio: "2025-12-31T00:00:00.000Z".
​
kickoffDate
string
Stringa di data ISO 8601 per la data di inizio del progetto.
​
notes
string
Note interne visibili al tuo team.
​
brief
string
Brief del cliente o riepilogo del progetto.
​
assignedProjectManagers
array
Elenco completo degli ID membro dei project manager da assegnare a questo ordine. I nuovi ID vengono aggiunti al team; gli ID rimossi vengono eliminati. Ogni ID deve appartenere a un membro con ruolo projectManager all’interno della stessa azienda.
​
markTasksAsDone
boolean
Obbligatorio quando status è Completed o Cancelled. Quando true, tutte le attività nell’ordine vengono segnate come completate dopo il cambio di stato. Quando false, le attività rimangono nel loro stato attuale.
​
rejectRequestedTasks
boolean
Consentito solo quando status è Completed o Cancelled. Quando true, tutte le attività in sospeso richieste dal cliente vengono rifiutate dopo l’aggiornamento dello stato.
​
repeatCount
number
Richiesto solo per gli ordini di abbonamento quando si cambia la frequenza di ricorrenza. Da abbinare a repeatDuration.
​
repeatDuration
string
Richiesto insieme a repeatCount per gli ordini di abbonamento. Uno tra: day, week, month, year.
​
billingCycleCount
number
Limite opzionale sui cicli di fatturazione ricorrenti. Predefinito a 0 (nessun limite).
​
billingCycleEvent
string
Come viene gestito ogni ciclo di fatturazione. Uno tra: createOrderWithTask, noChange.
​
files
file
Zero o più allegati file. I file vengono aggiunti alla cartella di sistema dell’ordine; i file esistenti non vengono mai sovrascritti. Usa la codifica multipart/form-data e allega ogni file nel campo files.

​
Richiesta di esempio

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."
Payload JSON equivalente (converti in voci del modulo multipart quando invii file): 
{
  "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."
}

​
Risposte

Stato HTTPDescrizione
200 OKAggiornamento riuscito.
400 ValidationErrorID ordine non valido, transizione di stato bloccata o payload malformato. La risposta include fieldName quando pertinente.
403 PermissionErrorIl chiamante non è un membro approvato, non ha il ruolo aziendale, l’abbonamento al workspace è scaduto, o un cliente ha tentato una cancellazione non consentita.
500 Internal Server ErrorEccezione non gestita — controlla i log del server.

​
Risposta di successo

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

​
Regole di business ed effetti collaterali

  • Le transizioni di stato sono limitate. Review può seguire solo Ongoing o un altro Review. Il tentativo Pending → Review restituisce 400 ValidationError.
  • Spostare uno stato da Pending a Ongoing, Review o Completed attiva la cartella file dell’ordine in modo che i file caricati diventino accessibili al team di progetto.
  • Impostare status su Completed o Cancelled richiede che markTasksAsDone sia esplicitamente impostato su true o false.
  • I cambi di stato in Review, Completed o Cancelled attivano automaticamente le notifiche ai clienti:
    • Review — notifica al cliente che è necessaria una revisione.
    • Completed — invia la notifica orderCompletion al cliente.
    • Cancelled — invia la notifica orderCancellation al cliente.
  • Ogni aggiornamento riuscito genera un evento webhook ORDER.UPDATED con il documento dell’ordine aggiornato e i metadati degli allegati, se hai un webhook attivo sottoscritto a quell’evento.