API AgencyHandy: Atualizar um Pedido Existente com PUT

O endpoint Atualizar Pedido permite que você modifique um pedido (projeto) existente no AgencyHandy — altere seu nome, status, orçamento, prazo, gerentes atribuídos e muito mais — tudo a partir de um sistema externo ou script de automação. O endpoint também suporta anexos de arquivos, que são adicionados à pasta de sistema do pedido.

Antes de usar este endpoint, conclua o guia de Primeiros Passos para obter sua chave de API e ID de Empresa.

Este endpoint usa Authorization: Bearer <token> (o token de acesso de um membro autenticado) em vez apenas do header x-api-key. Certifique-se de que seu chamador está autenticado como um membro aprovado da empresa alvo. Chamadores não autorizados recebem um 403 PermissionError.

Pré-requisitos

✅ Um Bearer token válido para um membro aprovado do workspace
✅ ID de Empresa recuperado de GET {{URL}}/accounts/companies
✅ O ID do Pedido (ID do Projeto, pid) do pedido que você deseja atualizar

Endpoint

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

Content-Type: multipart/form-data — use isso mesmo quando nenhum arquivo for anexado, para satisfazer o parser multipart do servidor.

Headers

Header	Obrigatório	Descrição
`Authorization`	Sim	`Bearer <ACCESS_TOKEN>` — o token de acesso do membro autenticado.
`companyid`	Sim	ObjectId Mongo da empresa à qual o pedido pertence.
`clientid`	Opcional	ID de socket do cliente em tempo real. Quando fornecido, as notificações o incluem.

Parâmetros de consulta

string

obrigatório

O ID do Pedido / Projeto a atualizar. Passe como parâmetro de string de consulta.

Campos do corpo da requisição

string

Atualiza o título do pedido. Mínimo de 2 caracteres.

string

Novo status para o pedido. Deve ser um dos seguintes: Pending, Ongoing, Review, Completed, Cancelled.Transições permitidas:

Review só pode seguir Ongoing ou outro Review. Pular de Pending diretamente para Review retorna um 400 ValidationError.
Pedidos já Completed ou Cancelled não podem ser atualizados.
Clientes não podem cancelar um pedido que tenha avançado além de Pending.

number

Valor total do orçamento. Deve ser ≥ 0. Usa a moeda existente do pedido, a menos que currency também seja fornecido.

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

String de data ISO 8601 para a data de vencimento do pedido. Exemplo: "2025-12-31T00:00:00.000Z".

string

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

string

Notas internas visíveis para sua equipe.

string

Briefing do cliente ou resumo do projeto.

array

Lista completa de IDs de membros gerentes de projeto a atribuir a este pedido. Novos IDs são adicionados à equipe; IDs removidos são excluídos. Cada ID deve pertencer a um membro com perfil projectManager na mesma empresa.

boolean

Obrigatório quando status é Completed ou Cancelled. Quando true, todas as tarefas do pedido são marcadas como concluídas após a mudança de status. Quando false, as tarefas permanecem no estado atual.

boolean

Permitido apenas quando status é Completed ou Cancelled. Quando true, todas as tarefas solicitadas pelo cliente pendentes são rejeitadas após a atualização de status.

number

Obrigatório apenas para pedidos de assinatura ao alterar a frequência de recorrência. Use em conjunto com repeatDuration.

string

Obrigatório junto com repeatCount para pedidos de assinatura. Um dos seguintes: day, week, month, year.

number

Limite opcional de ciclos de faturamento recorrentes. Padrão: 0 (sem limite).

string

Como cada ciclo de faturamento é tratado. Um dos seguintes: createOrderWithTask, noChange.

file

Zero ou mais anexos de arquivos. Os arquivos são adicionados à pasta de sistema do pedido; arquivos existentes nunca são sobrescritos. Use codificação multipart/form-data e anexe cada arquivo no campo files.

Exemplo de requisição

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 arquivos):

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

Status HTTP	Descrição
`200 OK`	Atualização bem-sucedida.
`400 ValidationError`	ID de pedido inválido, transição de status bloqueada ou payload malformado. A resposta inclui `fieldName` quando relevante.
`403 PermissionError`	O chamador não é um membro aprovado, não possui o perfil da empresa, a assinatura do workspace expirou, ou um cliente tentou um cancelamento proibido.
`500 Internal Server Error`	Exceção não tratada — verifique os logs do servidor.

Resposta de sucesso

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

Regras de negócio e efeitos colaterais

Transições de status são restritas. Review só pode seguir Ongoing ou outro Review. Tentar Pending → Review retorna 400 ValidationError.
Mover um status de Pending para Ongoing, Review ou Completed ativa a pasta de arquivos do pedido, tornando os arquivos enviados acessíveis à equipe do projeto.
Definir status como Completed ou Cancelled exige que markTasksAsDone seja explicitamente definido como true ou false.
Mudanças de status 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 dispara um evento de webhook ORDER.UPDATED com o documento do pedido atualizado e metadados de anexos, se você tiver um webhook ativo inscrito nesse evento.

Introdução

Endpoints

API AgencyHandy: Atualizar um Pedido Existente com PUT

Pré-requisitos

Endpoint

Headers

Parâmetros de consulta

Campos do corpo da requisição

Exemplo de requisição

Respostas

Resposta de sucesso

Regras de negócio e efeitos colaterais

​Pré-requisitos

​Endpoint

​Headers

​Parâmetros de consulta

​Campos do corpo da requisição

​Exemplo de requisição

​Respostas

​Resposta de sucesso

​Regras de negócio e efeitos colaterais

Pré-requisitos

Endpoint

Headers

Parâmetros de consulta

Campos do corpo da requisição

Exemplo de requisição

Respostas

Resposta de sucesso

Regras de negócio e efeitos colaterais