Ações nos Pedidos

Cancelamento Parcial de Itens

Este endpoint permite que o parceiro integrador remova itens específicos de um pedido em andamento. Esta operação é comum em cenários de falta de estoque ou problemas na separação dos produtos. Pode ser aplicado apenas para pedidos de loja catálogo.

POST

/orders/{order_id}/cancel-items

Regras de Negócio e Restrições:

• Tipo de Pagamento: Permitido exclusivamente para pedidos com pagamento online; pedidos offline não suportam esta operação via endpoint.
• Quantidade Mínima: Não é permitido cancelar todos os itens; se o pedido tiver apenas um item, o cancelamento individual não é possível.

Payload Cancelamento Parcial de Itens

{
  "order_refund_reason_id": 14,
  "reason": "Item fora de estoque",
  "order_items": [
    {
      "id": 123456,
      "quantity": 1
    }
  ]
}

Detalhes dos Parâmetros do Corpo (Payload)

Parâmetros do Payload

Campo	Obrigatório	Descrição
order_refund_reason_id	❌	ID do motivo do estorno/cancelamento.
reason	❌	Descrição textual do motivo para registro interno e log.
order_items	✅	Lista de objetos contendo os itens que serão cancelados.

Detalhes do Objeto order_items[]

Campo	Descrição
id	ID único do item dentro do pedido a ser cancelado (ID do order_item).
quantity	Quantidade do item que será removida do pedido.

Detalhamento dos Motivos (order_refund_reason_id)

ID	Motivo (Reason)
11	período de cancelamento expirado
12	fominha pagou duas vezes
13	problemas com a qualidade do produto
14	faltou algum item
15	item entregue errado
16	o item está revirado
17	outro

Troca de Itens

Este endpoint permite substituir um item original de um pedido por um novo item. Pode ser aplicado apenas para pedidos de loja catálogo.

POST

/orders/{order_id}/replace-items

Regras de Negócio e Restrições:

• Tipo de Pagamento: Permitido exclusivamente para pedidos com pagamento online. Pedidos com pagamento offline não suportam esta operação.
• Regra de Valor: O valor total do novo item (incluindo opcionais) não pode ser maior que o valor do item que está sendo substituído.
• Acompanhamento de IDs (Catálogo): Para lojas de catálogo, os campos culinary_id e category_id necessários para a troca devem ser consultados via Endpoint de Detalhes do Item no Catálogo.

Payload Troca de Itens Catálogo

{
  "order_refund_reason_id": 17,
  "reason": "Item sem estoque",
  "order_items": [
    {
      "id": 68666658,
      "new_item": {
        "uuid": "e2d3634d-360e-3058-9f2a-d759e9a5d518",
        "size_id": 4079712,
        "category_id": 824353,
        "culinary_id": 492,
        "packaging_tax": 0,
        "quantity": 1
      }
    }
  ]
}

Parâmetros do Corpo (Payload)

Payload principal

Campo	Obrigatório	Descrição
order_refund_reason_id	❌	ID do motivo da troca (Utilizar a mesma tabela do cancelamento parcial).
reason	❌	Texto descritivo justificando a substituição.
order_items	✅	Lista de objetos contendo a instrução de troca.

Objeto order_items[]

Campo	Obrigatório	Descrição
id	✅	ID único do item dentro do pedido a ser substituído (ID do order_item).
new_item	✅	Objeto contendo os dados do novo produto que entrará no pedido.

Objeto new_item

Campo	Obrigatório	Descrição
uuid	✅	Identificador único do novo item que será inserido.
quantity	✅	Quantidade do novo item.
size_id	✅	ID do tamanho.
category_id	✅	ID da categoria do item.
culinary_id	✅	ID da culinária do item.
packaging_tax	✅	Valor da taxa de embalagem do novo item.
mandatory_items	❌	Array de IDs de itens obrigatórios (complementos).
additional_items	❌	Array de IDs de itens adicionais (opcionais).

Detalhamento dos Motivos (order_refund_reason_id)

ID	Motivo (Reason)
11	período de cancelamento expirado
12	fominha pagou duas vezes
13	problemas com a qualidade do produto
14	faltou algum item
15	item entregue errado
16	o item está revirado
17	outro

Confirmar Leitura do Pedido

Este endpoint informa ao aiqfome que o parceiro recebeu e leu o pedido no sistema da loja.

Observação Importante: Prazo de Aceite

O ecossistema aiqfome preza pela agilidade no atendimento ao cliente final. Por isso, existe uma regra de cancelamento automático baseada no tempo de resposta da loja:

• Prazo Limite: Uma vez que o pedido é criado, o parceiro tem um prazo máximo de 10 minutos para realizar a chamada deste endpoint (Order Read).
• Cancelamento Automático: Caso o pedido não seja marcado como lido dentro deste intervalo de 10 minutos, o sistema irá cancelar o pedido automaticamente por falta de confirmação da loja, notificando o cliente sobre a indisponibilidade.
• Recomendação técnica: Certifique-se de que seu serviço de monitoramento de novos pedidos ou o consumo de Webhooks esteja operante e processe a confirmação de leitura imediatamente após a integração do pedido no seu sistema (ERP/PDV).

POST

/orders/mark-as-read

Parâmetros do Corpo (Payload)

Campo	Obrigatório	Descrição
order_id	✅	ID numérico do pedido que foi visualizado pelo seller.

Marcar Pedido como em Separação

Este endpoint informa que o processo de picking (coleta dos itens nas prateleiras) foi iniciado. Ele é utilizado para dar visibilidade ao cliente sobre o progresso interno da loja.

POST

/orders/mark-as-in-separation

Regras e Observações:

• Aplicabilidade: Este endpoint é destinado apenas para lojas do modelo Catálogo (Mercados, Farmácias, Pets, etc.). Não deve ser utilizado por lojas de Cardápio.
• Sequência do Fluxo: Deve ser executado após a confirmação da leitura do pedido.

Parâmetros do Corpo (Payload)

Campo	Obrigatório	Descrição
order_id	✅	ID numérico do pedido que entrou em fase de separação.

Marcar Pedido como Pronto

Este endpoint informa que o pedido já foi finalizado (preparado ou separado) e está aguardando apenas o entregador ou a chegada do cliente para retirada.

POST

/orders/mark-as-ready

Regras e Observações:

• Gatilho Logístico: Para sellers que utilizam serviços de logística de terceiros, este status serve como ponto de referência para iniciar o processo de entrega. Ao marcar o pedido como pronto, o serviço de logística pode alocar um entregador para realizar a coleta na loja.
• Visibilidade: Ao chamar este endpoint, o cliente final recebe uma notificação informando que o pedido já está pronto caso seja retirada.
• Modelos de Negócio: Aplicável tanto para lojas de Cardápio quanto de Catálogo.

Parâmetros do Corpo (Payload)

Campo	Obrigatório	Descrição
order_id	✅	ID numérico do pedido que está pronto para entrega ou retirada.