Skip to Content
Documentação de integração da plataforma — em evolução contínua.
PedidosAlterar itens do pedido

Alterar itens do pedido

Em supermercado, o pedido separado raramente é idêntico ao pedido feito: o item pesável sai com peso diferente, um produto está em falta, outro é substituído. O fluxo de alteração (change order) existe para refletir isso e ajustar a cobrança.

Enviar a alteração

PUT /v1/Orders/{orderNumber}

{
  "finalOrderPrice": 187.45,
  "skusToUpsert": [
    {
      "skuExternalReference": "114970",
      "quantity": 2,
      "price": 8.99,
      "unitOfMeasure": "Un"
    },
    {
      "skuExternalReference": "220145",
      "quantity": 0.487,
      "price": 39.9,
      "unitOfMeasure": "Kg"
    },
    {
      "skuExternalReference": "331002",
      "quantity": 0
    }
  ]
}
CampoDescrição
finalOrderPricevalor final do pedido após a separação
skusToUpsertlista dos itens com a situação final
quantityquantidade efetivamente separada — 0 remove o item
pricepreço unitário praticado
unitOfMeasureUn, Kg, G ou Mg

A chamada completa

curl -X PUT $GROCERS_API/v1/Orders/104821 \
  -H "Authorization: Basic $BASIC" \
  -H "x-contractAccountId: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "finalOrderPrice": 187.45,
    "skusToUpsert": [
      { "skuExternalReference": "114970", "quantity": 2, "price": 8.99, "unitOfMeasure": "Un" },
      { "skuExternalReference": "220145", "quantity": 0.487, "price": 39.9, "unitOfMeasure": "Kg" },
      { "skuExternalReference": "331002", "quantity": 0 }
    ]
  }'

Esta chamada é síncrona. Diferente do PATCH de status e do cancelamento, ela não enfileira nada: a API repassa o pedido ao core, espera o recálculo e a operação de captura ou estorno, e devolve o resultado no corpo da resposta.

{
  "title": "Pedido atualizado com sucesso",
  "status": 200,
  "detail": "Pedido atualizado com sucesso",
  "errorCode": "",
  "data": {
    "isRebilling": false,
    "isRefund": true,
    "isInitialTransactionCaptured": true
  }
}
CampoSignificado
title / detailresultado em texto
errorCodecódigo da falha quando status não é 200; string vazia no sucesso
data.isRefundhouve estorno da diferença (valor final menor que o original)
data.isRebillinghouve nova cobrança complementar
data.isInitialTransactionCaptureda operação de pagamento no adquirente foi concluída
CódigoSignificadoO que fazer
200alteração aplicada e pagamento ajustadoleia data para saber se houve estorno ou cobrança complementar
400o core recusou a alteração — inclui pedido inexistente e pedido em status que não admite alteração; o motivo vem em detail e errorCodecorrija e reenvie; não é enfileirado, não há retentativa automática
500a API não conseguiu falar com o core, ou recebeu resposta que não sabe interpretarretente com limite; se persistir, chamado com o orderNumber

O sucesso também volta pelo webhook, como Order_Updated com data.status: 1300. Ao concluir a alteração, o core registra o status OrderUpdated (1300) no pedido e publica a notificação. Esse 1300 não é uma etapa da operação e não tem nome em SNAKE_CASE: não o grave como status do pedido no ERP — ele apagaria o ORDER_BEING_PREPARED em que o pedido estava. Trate-o como “os valores deste pedido mudaram” e releia subtotal e items. Veja Receber pedidos (webhook).

A alteração é one-shot por pedido. O core guarda OrderUpdated no histórico e usa isso como chave de idempotência: um segundo PUT no mesmo orderNumber devolve 200 com o resultado da primeira chamada e não altera nada. Envie a situação final de uma vez, ao fim da separação.

Aqui finalOrderPrice e price são decimais em reais (187.45), ao contrário de value no faturamento, que é inteiro em centavos. Veja Faturar um pedido.

finalOrderPrice é o valor total do pedido, não a diferença.

O que acontece depois

A plataforma recalcula

O pedido passa a refletir os itens e o valor enviados.

O pagamento é ajustado

Se o valor final for menor, a diferença é estornada. Se for maior, é feita a captura complementar dentro do limite pré-autorizado.

O cliente é notificado

A alteração aparece no acompanhamento do pedido, com os itens que mudaram.

Item pesável

Para itens vendidos por peso, a alteração é a regra, não a exceção: o cliente pede “500 g” e a balança marca 487 g.

{
  "skuExternalReference": "220145",
  "quantity": 0.487,
  "price": 39.9,
  "unitOfMeasure": "Kg"
}

Quando enviar

O momento certo é ao fim da separação, com o pedido já conferido — uma única chamada com a situação final. Não há segunda chance: o PUT seguinte no mesmo pedido é tratado como repetição e devolve o resultado do primeiro sem alterar nada.

Atualizar statusFaturamento