Saltar para o conteúdo principal
O endpoint Atualizar Encomenda permite-lhe modificar uma encomenda (projeto) existente no AgencyHandy — alterar o nome, estado, orçamento, prazo, gestores atribuídos e muito mais — tudo a partir de um sistema externo ou script de automação. O endpoint também suporta anexos de ficheiros, que são acrescentados à pasta do sistema da encomenda.
Antes de utilizar este endpoint, complete o guia de Primeiros Passos para obter a sua chave de API e ID de Empresa.
Este endpoint utiliza Authorization: Bearer <token> (o token de acesso de um membro com sessão iniciada) em vez do cabeçalho x-api-key apenas. Certifique-se de que o seu cliente está autenticado como membro aprovado da empresa alvo. Clientes não autorizados recebem um erro 403 PermissionError.

​
Pré-requisitos

  • ✅ Um token Bearer válido para um membro aprovado do workspace
  • ✅ ID de Empresa obtido a partir de GET {{URL}}/accounts/companies
  • ✅ O ID da Encomenda (ID do Projeto, pid) da encomenda que pretende atualizar

​
Endpoint

PUT {{URL}}/orders?pid=<ORDER_ID>
Content-Type: multipart/form-data — utilize este mesmo quando não há ficheiros a anexar, para satisfazer o parser multipart do servidor.

​
Cabeçalhos

CabeçalhoObrigatórioDescrição
AuthorizationSimBearer <ACCESS_TOKEN> — o token de acesso do membro com sessão iniciada.
companyidSimMongo ObjectId da empresa à qual a encomenda pertence.
clientidOpcionalID de socket do cliente em tempo real. Quando fornecido, as notificações incluem-no.

​
Parâmetros de consulta

​
pid
string
obrigatório
O ID da Encomenda / Projeto a atualizar. Passe este como parâmetro de cadeia de consulta.

​
Campos do corpo do pedido

​
name
string
Atualiza o título da encomenda. Mínimo de 2 caracteres.
​
status
string
Novo estado para a encomenda. Deve ser um de: Pending, Ongoing, Review, Completed, Cancelled.Transições permitidas:
  • Review só pode seguir Ongoing ou outro Review. Saltar de Pending diretamente para Review devolve um erro 400 ValidationError.
  • Encomendas já Completed ou Cancelled não podem ser atualizadas.
  • Os clientes não podem cancelar uma encomenda que tenha avançado além de Pending.
​
budget
number
Valor total do orçamento. Deve ser ≥ 0. Utiliza a moeda existente da encomenda, a menos que currency também seja fornecida.
​
currency
string
Código de moeda para o orçamento. Exemplos: USD, CAD, EUR.
​
quantity
number
Número de unidades adquiridas para o pacote. Deve ser ≥ 1.
​
deadline
string
Data ISO 8601 para o prazo da encomenda. Exemplo: "2025-12-31T00:00:00.000Z".
​
kickoffDate
string
Data ISO 8601 para a data de início do projeto.
​
notes
string
Notas internas visíveis para a sua equipa.
​
brief
string
Briefing do cliente ou resumo do projeto.
​
assignedProjectManagers
array
Lista completa dos IDs de membros gestores de projeto a atribuir a esta encomenda. Novos IDs são adicionados à equipa; IDs removidos são eliminados. Cada ID deve pertencer a um membro com função projectManager na mesma empresa.
​
markTasksAsDone
boolean
Obrigatório quando status é Completed ou Cancelled. Quando true, todas as tarefas da encomenda são marcadas como concluídas após a mudança de estado. Quando false, as tarefas permanecem no estado atual.
​
rejectRequestedTasks
boolean
Permitido apenas quando status é Completed ou Cancelled. Quando true, todas as tarefas pendentes solicitadas por clientes são rejeitadas após a atualização do estado.
​
repeatCount
number
Necessário apenas para encomendas de subscrição ao alterar a frequência de recorrência. Use em conjunto com repeatDuration.
​
repeatDuration
string
Necessário juntamente com repeatCount para encomendas de subscrição. Um de: day, week, month, year.
​
billingCycleCount
number
Limite opcional de ciclos de faturação recorrentes. Predefinição para 0 (sem limite).
​
billingCycleEvent
string
Como cada ciclo de faturação é tratado. Um de: createOrderWithTask, noChange.
​
files
file
Zero ou mais anexos de ficheiros. Os ficheiros são acrescentados à pasta do sistema da encomenda; os ficheiros existentes nunca são substituídos. Utilize codificação multipart/form-data e anexe cada ficheiro sob o campo files.

​
Exemplo de pedido

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 (converta para entradas de formulário multipart ao enviar ficheiros): 
{
  "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."
}

​
Respostas

Estado HTTPDescrição
200 OKAtualização bem-sucedida.
400 ValidationErrorID de encomenda inválido, transição de estado bloqueada ou payload malformado. A resposta inclui fieldName quando relevante.
403 PermissionErrorO cliente não é um membro aprovado, não tem a função na empresa, a subscrição do workspace expirou, ou um cliente tentou um cancelamento proibido.
500 Internal Server ErrorExceção não tratada — verifique os registos do servidor.

​
Resposta de sucesso

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

​
Regras de negócio e efeitos secundários

  • As transições de estado são restritas. Review só pode seguir Ongoing ou outro Review. Tentar Pending → Review devolve 400 ValidationError.
  • Mover um estado de Pending para Ongoing, Review ou Completed ativa a pasta de ficheiros da encomenda, tornando os ficheiros carregados acessíveis à equipa do projeto.
  • Definir status como Completed ou Cancelled requer que markTasksAsDone seja explicitamente definido como true ou false.
  • Mudanças de estado para Review, Completed ou Cancelled acionam automaticamente notificações ao cliente:
    • Review — notifica o cliente de que a revisão é necessária.
    • Completed — envia a notificação orderCompletion ao cliente.
    • Cancelled — envia a notificação orderCancellation ao cliente.
  • Cada atualização bem-sucedida aciona um evento de webhook ORDER.UPDATED com o documento da encomenda atualizado e metadados de anexos, caso tenha um webhook ativo subscrito a esse evento.