API AgencyHandy: Atualizar uma Encomenda Existente com PUT

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çalho	Obrigatório	Descrição
`Authorization`	Sim	`Bearer <ACCESS_TOKEN>` — o token de acesso do membro com sessão iniciada.
`companyid`	Sim	Mongo ObjectId da empresa à qual a encomenda pertence.
`clientid`	Opcional	ID de socket do cliente em tempo real. Quando fornecido, as notificações incluem-no.

Parâmetros de consulta

string

obrigatório

O ID da Encomenda / Projeto a atualizar. Passe este como parâmetro de cadeia de consulta.

Campos do corpo do pedido

string

Atualiza o título da encomenda. Mínimo de 2 caracteres.

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.

number

Valor total do orçamento. Deve ser ≥ 0. Utiliza a moeda existente da encomenda, a menos que currency também seja fornecida.

string

Código de moeda para o orçamento. Exemplos: USD, CAD, EUR.

number

Número de unidades adquiridas para o pacote. Deve ser ≥ 1.

string

Data ISO 8601 para o prazo da encomenda. Exemplo: "2025-12-31T00:00:00.000Z".

string

Data ISO 8601 para a data de início do projeto.

string

Notas internas visíveis para a sua equipa.

string

Briefing do cliente ou resumo do projeto.

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.

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.

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.

number

Necessário apenas para encomendas de subscrição ao alterar a frequência de recorrência. Use em conjunto com repeatDuration.

string

Necessário juntamente com repeatCount para encomendas de subscrição. Um de: day, week, month, year.

number

Limite opcional de ciclos de faturação recorrentes. Predefinição para 0 (sem limite).

string

Como cada ciclo de faturação é tratado. Um de: createOrderWithTask, noChange.

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

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"

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 HTTP	Descrição
`200 OK`	Atualização bem-sucedida.
`400 ValidationError`	ID de encomenda inválido, transição de estado bloqueada ou payload malformado. A resposta inclui `fieldName` quando relevante.
`403 PermissionError`	O 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 Error`	Exceçã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.

Introdução

Endpoints

API AgencyHandy: Atualizar uma Encomenda Existente com PUT

Pré-requisitos

Endpoint

Cabeçalhos

Parâmetros de consulta

Campos do corpo do pedido

Exemplo de pedido

Respostas

Resposta de sucesso

Regras de negócio e efeitos secundários

​Pré-requisitos

​Endpoint

​Cabeçalhos

​Parâmetros de consulta

​Campos do corpo do pedido

​Exemplo de pedido

​Respostas

​Resposta de sucesso

​Regras de negócio e efeitos secundários

Pré-requisitos

Endpoint

Cabeçalhos

Parâmetros de consulta

Campos do corpo do pedido

Exemplo de pedido

Respostas

Resposta de sucesso

Regras de negócio e efeitos secundários