Pular para o conteúdo
platform
PT EN

Referência da API · CashBack

Conceder Cashback por Pedido Externo

Método
POST
Rota
/loyaltyProgram/earnRewardExternal
URL base
https://ws.autorei.net
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

Concede cashback a um cliente a partir de um pedido que aconteceu fora da plataforma CWS, uma venda no seu balcão, no seu e-commerce próprio ou em outro canal. Você informa quem comprou, o número do pedido no seu sistema e os itens; o programa de fidelidade calcula quanto cada item rende e registra o crédito.

Corpo da Requisição (JSON)

Campo Tipo Obrigatório Descrição
Identificação do cliente - Sim Não é um campo, é um grupo. Envie cpfCnpj ou email; ver a regra abaixo.
cpfCnpj string Condicional CPF ou CNPJ do cliente. Obrigatório se email não for enviado.
email string Condicional E-mail de acesso do cliente na sua loja. Obrigatório se cpfCnpj não for enviado.
externalOrderId string Sim Número do pedido no seu sistema. Único por loja, ver a regra abaixo.
status string Não Status inicial do crédito. TO_RELEASE, RELEASED, CANCELLED ou INVALID_EXPIRED. Omitido, o crédito nasce como TO_RELEASE.
timeToReleasePoints integer Não Dias de carência antes de o crédito ser liberado. Não pode ser negativo. Omitido, vale a carência configurada no programa de fidelidade da loja.
orderItems array Sim Itens do pedido. Não pode ser lista vazia.
orderItems[].documentPartner string Sim Documento do parceiro que vendeu o item. Ver a regra de marketplace abaixo.
Identificação do produto - Sim Não é um campo, é um grupo. Em cada item, envie skuId ou partnerPartCode.
orderItems[].skuId integer Condicional Id do produto na CWS. Obrigatório se partnerPartCode não for enviado.
orderItems[].partnerPartCode string Condicional Código do produto no seu catálogo, como cadastrado no estoque. Obrigatório se skuId não for enviado.
orderItems[].deliveryDate string Sim Data de entrega do item, no formato AAAA-MM-DD.
orderItems[].quantity integer Sim Quantidade do item. Tem de ser maior que zero.
orderItems[].unitaryValue number Sim Valor unitário do item. Tem de ser maior que zero.

Regras de negócio

Um cliente, por documento ou por e-mail

Envie um dos dois. O cliente precisa já existir na loja autenticada: cliente de outra loja, ou documento sem cadastro, é recusado. Se você mandar os dois, o cpfCnpj é quem vale.

externalOrderId é a chave contra crédito em dobro

O número do pedido externo é único por parceiro. Uma segunda chamada com o mesmo externalOrderId é recusada, não duplicada, é o que protege a integração de conceder cashback duas vezes quando uma entrega é reprocessada. Use o número real do pedido no seu sistema, não um valor gerado a cada tentativa.

documentPartner e a venda de marketplace

O documento informado em cada item define quem vendeu aquele item. Quando é o documento do próprio parceiro autenticado, nada mais é exigido. Quando é o documento de outro parceiro, precisa existir uma parceria de marketplace autorizada entre a sua loja e ele, caso contrário o item é recusado.

O valor do cashback é calculado pela plataforma, não enviado

Você informa quantidade e valor unitário; quanto isso rende é decidido pelas regras do programa de fidelidade da loja (categoria e fabricante do produto, percentual configurado). Item que não se encaixa em nenhuma regra é registrado com valor zero, não gera erro e não impede o restante do pedido.

Recusa é do pedido inteiro

Qualquer item recusado derruba a requisição inteira e nada é gravado, não existe resultado parcial. Quando a recusa é produto não encontrado, a mensagem lista de uma vez todos os itens que não foram localizados, para você não descobrir um por chamada.

Resposta · 200

Array com um objeto por item aceito, na ordem em que você os enviou.

Campo Tipo Descrição
earning number Cashback gerado pelo item. Número, não string, e sem arredondamento: espere valores como 0.49950000000000006. Vem 0 quando o item não se encaixa em nenhuma regra do programa.
type string Tipo da estratégia aplicada. CASHBACK.
value number Valor consumido de saldo na operação. Sempre 0 nesta concessão.
valueType string Vem "" nesta operação.
Reserve objeto Eco do item como a plataforma o interpretou. A chave começa com maiúscula.
Reserve.skuId integer Id CWS do produto, útil quando você identificou o item por partnerPartCode.
Reserve.qty integer Quantidade enviada.
Reserve.unitaryValue number Valor unitário enviado.
Reserve.deliveryDate string Data de entrega enviada.
Reserve.externalOrderId string Número do pedido externo enviado.
Reserve.partnerId integer Id do parceiro resolvido a partir do documentPartner.
Reserve.storeName string Subdomínio da loja autenticada.
Reserve.brandId integer Id do fabricante do produto.
Reserve.categories array Ids das categorias a que o produto pertence.

Erros

Código Quando
422 Qualquer recusa de validação ou de regra de negócio: cliente não identificado ou inexistente, externalOrderId ausente ou repetido, status fora da lista, timeToReleasePoints negativo, orderItems vazio, item sem identificação de produto, sem documentPartner, sem deliveryDate ou com data em formato inválido, quantity ou unitaryValue zerado, produto não encontrado no catálogo do parceiro, documentPartner desconhecido, ou parceria de marketplace não autorizada. O motivo específico vem na mensagem.
401 Token ausente, malformado ou expirado.

A recusa vem como uma lista de mensagens:

{"total":1,"errors":[{"message":"Número de pedido externo já está associado a outro cashback concedido."}]}

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

Exemplo de requisição

curl --request POST 'https://ws.autorei.net/loyaltyProgram/earnRewardExternal' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "cpfCnpj": "70041364856",
  "externalOrderId": "PED-EXT-900201",
  "status": "TO_RELEASE",
  "orderItems": [
    {
      "documentPartner": "30424972000174",
      "skuId": 500101,
      "deliveryDate": "2026-09-10",
      "quantity": 2,
      "unitaryValue": 150.0
    },
    {
      "documentPartner": "30424972000174",
      "partnerPartCode": "SKU-B-002",
      "deliveryDate": "2026-09-10",
      "quantity": 1,
      "unitaryValue": 80.0
    }
  ]
}'

Respostas de exemplo

200Sucesso: pedido externo com dois itens

[
  {
    "Reserve": {
      "brandId": 12593,
      "qty": 2,
      "storeName": "lojaexemplo",
      "partnerId": 4471,
      "categories": [
        26881,
        26903
      ],
      "externalOrderId": "PED-EXT-900201",
      "deliveryDate": "2026-09-10",
      "skuId": 500101,
      "unitaryValue": 150
    },
    "valueType": "",
    "type": "CASHBACK",
    "value": 0,
    "earning": 1.5
  },
  {
    "Reserve": {
      "brandId": 14713,
      "qty": 1,
      "storeName": "lojaexemplo",
      "partnerId": 4471,
      "categories": [
        26885,
        26878,
        26935
      ],
      "externalOrderId": "PED-EXT-900201",
      "deliveryDate": "2026-09-10",
      "skuId": 500102,
      "unitaryValue": 80
    },
    "valueType": "",
    "type": "CASHBACK",
    "value": 0,
    "earning": 0
  }
]

422Recusa: pedido externo já concedido

{
  "total": 1,
  "errors": [
    {
      "message": "Número de pedido externo já está associado a outro cashback concedido."
    }
  ]
}

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.