Fluxo de cupons

1. 1

   Você envia o pedido

   POST /orders com o status que o fluxo espera, normalmente completed.

2. 2

   O fluxo reconhece o pedido

   O fluxo cujo gatilho é Status do pedido executa para o cliente daquele pedido.

3. 3

   O step Criar cupom gera o cupom

   Giftback, que é um percentual sobre a compra concluída, ou cupom de valor fixo, conforme configurado no step.

4. 4

   A Zoppy chama a sua URL

   POST na URL cadastrada em POST /webhooks com o evento coupon_create.

4. O que fazer ao receber

1. 1

   Responda 2xx primeiro

   Confirme o recebimento e processe em background. Não deixe a nossa chamada esperando pela criação do cupom no seu lado.

2. 2

   Busque os dados do cupom

   GET /coupons/code/{code} devolve amount, type, expiryDate, minPurchaseValue, acumulative, used, isValid e o cliente vinculado. Alternativa: GET /coupons/order/{orderId} com o orderId do payload.

3. 3

   Crie o cupom no seu sistema

   Use amount com type, que é percent ou fixed_cart, expiryDate como validade e minPurchaseValue como valor mínimo de compra. Se acumulative for true, permita combinar o cupom com outras promoções e descontos da loja; se false, crie como não acumulável.

4. 4

   Devolva o seu ID, recomendado

   PUT /coupons/code/{code} com externalId igual ao ID do cupom no seu sistema. Depois disso GET /coupons/external/{externalId} funciona e a reconciliação entre os dois lados fica direta.

5. 5

   Informe o resgate

   Quando o cliente usar o cupom, envie o pedido com couponCode preenchido em POST /orders. É assim que a Zoppy vincula o resgate ao pedido. No POST qualquer código é aceito: sem cupom correspondente na Zoppy, o pedido é gravado com couponUsed null. No PUT /orders/:id o código precisa ser de um cupom individual existente na Zoppy, senão a resposta é 422 Coupon code not found. O cupom individual usado em pedido passa a used true, mesmo com o pedido on-hold, e isValid false.

{
  "id": "1f7c9a2e-5b31-4c88-9d0a-2e64f1b7c3aa",
  "externalId": null,
  "code": "GIFT15-4A9C2B",
  "type": "fixed_cart",
  "amount": 82.35,
  "used": false,
  "isValid": true,
  "minPurchaseValue": 329.4,
  "acumulative": true,
  "startDate": "2026-08-04T13:02:11.000Z",
  "expiryDate": "2026-09-18T13:02:11.000Z",
  "customer": {
    "id": "7d4b1c60-8e35-4f21-9a07-3b62ce9d18af",
    "externalId": "cliente-erp-4471",
    "firstName": "João",
    "lastName": "Silva",
    "phone": "11987654321",
    "email": "joao@email.com"
  }
}

• •O cancelamento atinge apenas o giftback que ainda não foi utilizado. Giftback já utilizado permanece como está.
• •O cupom cancelado também é removido da loja, então ele deixa de ser aceito no checkout a partir daquele momento.
• •Cupons que você registra pela API, com POST /coupons ou POST /coupons/shared, não são afetados por essa regra nem a acionam.

{
  "externalId": "cupom-erp-99213",
  "code": "PROMO50-JULHO",
  "type": "fixed_cart",
  "amount": 50,
  "minPurchaseValue": 200,
  "expiryDate": "2026-09-30T23:59:59.000Z",
  "phone": "11987654321",
  "awaitingOrder": false
}

• •externalId ou createOnProvider: um dos dois é obrigatório. Envie externalId quando o cupom já existe no seu sistema. Use createOnProvider apenas se quiser que a Zoppy crie o cupom na plataforma de e-commerce.
• •O externalId é tratado de forma diferente em cada endpoint, e nenhum dos dois avisa quando o valor se perde. Em POST /coupons ele é texto livre, UUID serve, e acima de 255 caracteres o valor é cortado. Em POST /coupons/shared ele é guardado como número inteiro de 1 a 2147483647: texto vira o número do começo ou 0, decimal é arredondado e valor acima do limite vira 2147483647, a chamada responde 200 e depois a busca por esse identificador não encontra o cupom, ou encontra outro. Lá o externalId também não é único: consulte pelo code.
• •awaitingOrder vem true por padrão: o próximo pedido do telefone que chegar sem couponCode recebe o cupom. Se você controla o resgate do seu lado, registre com awaitingOrder false. Para baixar o cupom à mão, use PUT com { "used": true, "awaitingOrder": false }: used true sozinho não desliga awaitingOrder.
• •Para cupom sem cliente específico e com limite de uso global, use POST /coupons/shared.

7. Como testar

1. 1

   Monte e ative o fluxo

   Siga o passo a passo da seção 2 na conta que você está usando para integrar e confirme que a coluna ATIVO ficou ligada.

2. 2

   Cadastre a sua URL

   POST /webhooks com event coupon_create e a sua URL. Cadastre também o bearerToken se você valida autenticação no seu endpoint.

3. 3

   Se for giftback, confira o fluxo, não a configuração

   Quem decide se o cupom sai, e com qual percentual, validade e valor mínimo, é o step Criar cupom do fluxo de automação. GET /coupons-config devolve os parâmetros padrão de giftback da conta como referência de leitura, mas não é essa configuração que libera ou bloqueia a geração do cupom.

4. 4

   Mande um pedido concluído

   Crie o cliente e o produto, então chame POST /orders com status completed e o lineItems do produto. O cliente precisa ter telefone e endereço.

5. 5

   Se nada chegar, isole o lado

   O disparo é assíncrono e passa por fila, então dê alguns segundos. Passado isso, chame GET /coupons/order/{orderId} com o id do pedido que você criou: cupom gerado e webhook não recebido é problema de entrega na sua URL, cupom não gerado é o fluxo de automação.