Pular para o conteúdo
platform
PT EN

Referência da API · CashBack

Atualizar Cashback de Pedido Externo

Método
PUT
Rota
/loyaltyProgram/earnRewardExternal
URL base
https://ws.autorei.net
Parâmetros de consulta do exemplo
externalOrderId=PED-EXT-900201
Token
Exige token Bearer
Testar no Postman

Abre esta requisição na documentação pública da API, a fonte oficial da referência.

Descrição

Altera um cashback já concedido por pedido externo: libera o crédito que estava em carência, cancela a concessão, corrige o valor ou a data de entrega. O pedido é identificado pelo mesmo externalOrderId usado na concessão.

Parâmetros de Consulta

Parâmetro Tipo Obrigatório Descrição
externalOrderId string Sim Número do pedido externo, como enviado em POST /loyaltyProgram/earnRewardExternal. Vai na query string, não no corpo.

Corpo da Requisição (JSON)

Campo Tipo Obrigatório Descrição
documentPartner string Sim Documento do parceiro dono da concessão. Mesma regra de marketplace da concessão.
status string Não Novo status do crédito: TO_RELEASE, RELEASED, CANCELLED ou INVALID_EXPIRED.
earning number Não Novo valor total do cashback do pedido. Ver a regra abaixo.
orderDeliveryDate string Não Nova data de entrega, no formato AAAA-MM-DD.
timeToReleasePoints integer Não Nova carência, em dias, antes de o crédito ser liberado.

Não envie partnerId: ele é resolvido pelo backend a partir do documentPartner.

Regras de negócio

Só o cashback em carência pode ser alterado

A atualização alcança apenas os lançamentos que ainda estão em TO_RELEASE. Um pedido cujo cashback já foi liberado, cancelado ou expirado responde 404, mesmo existindo. Na prática: a janela para corrigir a concessão é a carência.

A atualização vale para o pedido inteiro

Um pedido externo com vários itens gerou um lançamento por item, e a atualização é aplicada a todos eles de uma vez. Não há como alterar só um item do pedido por esta rota.

earning é o total do pedido, dividido entre os itens

O valor informado em earning é o cashback do pedido, não de cada item: num pedido de dois itens, "earning": 10 grava 5 em cada lançamento. Omita o campo quando não for corrigir o valor, o cashback calculado na concessão é preservado.

Resposta · 200

Array com um objeto por lançamento atualizado, um por item do pedido externo. Omitir status mantém o status atual e aplica só os demais campos enviados.

Campo Tipo Descrição
id uuid Id do lançamento de cashback.
externalOrderId string Número do pedido externo.
skuId integer Id CWS do produto do lançamento.
value number Valor do lançamento depois da atualização. Número, ao contrário dos endpoints de consulta, que devolvem string.
status string Status depois da atualização.
type string Tipo da estratégia. CASHBACK.
createDate string Data e hora da concessão original, em UTC.
orderDeliveryDate string Data de entrega do pedido, com offset (2026-09-10T00:00:00-03:00).
releaseDate string Data em que o crédito foi liberado. O campo só existe quando o lançamento está RELEASED, nos outros status ele não vem na resposta.
timeToReleasePoints integer Carência em dias vigente no lançamento.
timeToExpire integer Dias de validade do crédito depois de liberado, conforme o programa da loja.
cumulative boolean Se o crédito soma com outras estratégias de fidelidade.
partnerId integer Id do parceiro resolvido a partir do documentPartner.
ownerStoreId integer Id da loja dona do programa.
ownerStoreName string Subdomínio da loja.
ownerStoreEmail string E-mail de contato da loja.
customerRewardId uuid Id da carteira de cashback do cliente.
loyaltyStrategyId uuid Id da estratégia de fidelidade que originou o crédito.
orderId · partnerOrderId integer Ids do pedido na plataforma. Vêm 0 em cashback de pedido externo, que não tem pedido CWS.

Erros

Código Quando
422 externalOrderId ausente na query, documentPartner ausente ou desconhecido, status fora da lista, ou parceria de marketplace não autorizada. O motivo vem na mensagem.
404 Nenhum lançamento a atualizar: o externalOrderId não existe, ou existe e nenhum lançamento está mais em TO_RELEASE. A mensagem distingue os dois casos, leia errors[].message.
401 Token ausente, malformado ou expirado.

A recusa vem como uma lista de mensagens:

{"total":1,"errors":[{"message":"Nenhum registro encontrado com o número do pedido externo informado."}]}

Leia o motivo em errors[].message; total é a quantidade de mensagens.

Exemplo de requisição

curl --request PUT 'https://ws.autorei.net/loyaltyProgram/earnRewardExternal?externalOrderId=PED-EXT-900201' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "documentPartner": "30424972000174",
  "status": "RELEASED",
  "earning": 12.34,
  "orderDeliveryDate": "2026-09-12"
}'

Respostas de exemplo

200Sucesso: cashback liberado

[
  {
    "ownerStoreEmail": "contato@lojaexemplo.com.br",
    "orderDeliveryDate": "2026-09-12T00:00:00-03:00",
    "orderId": 0,
    "partnerOrderId": 0,
    "releaseDate": "2026-09-12T00:00:00-03:00",
    "ownerStoreName": "lojaexemplo",
    "externalOrderId": "PED-EXT-900201",
    "type": "CASHBACK",
    "cumulative": false,
    "timeToReleasePoints": 30,
    "timeToExpire": 90,
    "customerRewardId": "6cf135ce-46a6-411d-82ad-c9a4e2c0ade1",
    "loyaltyStrategyId": "b78d03a7-5186-4d3e-8421-05d45cd3de0e",
    "ownerStoreId": 4470,
    "id": "5eab5e68-c57d-4ef3-8d57-2a809be4f810",
    "partnerId": 4471,
    "value": 6.17,
    "skuId": 500101,
    "createDate": "2026-09-04T14:15:02.534996Z",
    "status": "RELEASED"
  },
  {
    "ownerStoreEmail": "contato@lojaexemplo.com.br",
    "orderDeliveryDate": "2026-09-12T00:00:00-03:00",
    "orderId": 0,
    "partnerOrderId": 0,
    "releaseDate": "2026-09-12T00:00:00-03:00",
    "ownerStoreName": "lojaexemplo",
    "externalOrderId": "PED-EXT-900201",
    "type": "CASHBACK",
    "cumulative": false,
    "timeToReleasePoints": 30,
    "timeToExpire": 90,
    "customerRewardId": "6cf135ce-46a6-411d-82ad-c9a4e2c0ade1",
    "loyaltyStrategyId": "b78d03a7-5186-4d3e-8421-05d45cd3de0e",
    "ownerStoreId": 4470,
    "id": "dfc74296-d75d-4dc0-bd90-3a8af69ada33",
    "partnerId": 4471,
    "value": 6.17,
    "skuId": 500102,
    "createDate": "2026-09-04T14:15:02.534996Z",
    "status": "RELEASED"
  }
]

Usado em

Endpoints relacionados

← Ver o grupo: CashBack

Gerado a partir da coleção pública da API, publicada em 04/09/2026: api-docs.cws.digital.