{
  "info": {
    "_postman_id": "8eaf6e79-495f-4dbc-8cbb-c6cb9ab91aa1",
    "name": "Cupom REST API",
    "description": "Collection única dos endpoints REST públicos do Cupom. Defina a variável token no environment selecionado no Postman. HML e PRD usam https://api.cupom.center; a API key determina o ambiente.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{token}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    { "key": "base_url", "value": "https://api.cupom.center", "type": "string" },
    { "key": "token", "value": "", "type": "string" },
    { "key": "coupon_id", "value": "00000000-0000-0000-0000-000000000000", "type": "string" },
    { "key": "coupon_code", "value": "CUPOM10", "type": "string" },
    { "key": "coupon_code_2", "value": "FRETEGRATIS", "type": "string" },
    { "key": "issuance_id", "value": "00000000-0000-0000-0000-000000000000", "type": "string" },
    { "key": "operation_id", "value": "00000000-0000-0000-0000-000000000000", "type": "string" },
    { "key": "order_id", "value": "order-001", "type": "string" },
    { "key": "redemption_id", "value": "00000000-0000-0000-0000-000000000000", "type": "string" },
    { "key": "currency", "value": "BRL", "type": "string" },
    { "key": "partial_refund_external_id", "value": "refund-001", "type": "string" },
    { "key": "idempotency_key", "value": "issuance-example-001", "type": "string" }
  ],
  "item": [
    {
      "name": "Integração",
      "description": "Validação não faturável da API key e do escopo usado por conectores.",
      "item": [
        {
          "name": "Validar integração",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": "{{base_url}}/v1/coupon/integration",
            "description": "Valida a API key sem faturamento e retorna organização, ambiente, projeto, moeda, permissões e versão da API."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Elegibilidade",
      "description": "Consultas de cupons elegíveis. Estes endpoints usam o método HTTP QUERY.",
      "item": [
        {
          "name": "Consultar cupons elegíveis",
          "request": {
            "method": "QUERY",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"context\": {\n    \"user\": {\n      \"id\": \"user-001\",\n      \"age\": 30,\n      \"sex\": \"other\"\n    },\n    \"attributes\": {},\n    \"location\": {\n      \"country\": \"BR\",\n      \"state\": \"SP\",\n      \"city\": \"Sao Paulo\"\n    },\n    \"payment_method\": \"pix\",\n    \"cart\": [\n      {\n        \"id\": \"product-001\",\n        \"quantity\": 2,\n        \"unitary_price\": 49.90\n      }\n    ],\n    \"shipping\": {\n      \"amount\": 12.50\n    },\n    \"unit_id\": \"unit-001\",\n    \"brand_id\": \"brand-001\",\n    \"public\": true\n  },\n  \"pagination\": {\n    \"page\": 1,\n    \"per_page\": 20\n  }\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/v1/coupon/eligibility",
            "description": "Consulta os cupons elegíveis para o contexto e carrinho informados."
          },
          "response": []
        },
        {
          "name": "Consultar um cupom elegível por unidade",
          "request": {
            "method": "QUERY",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"context\": {\n    \"user\": {\n      \"id\": \"user-001\"\n    },\n    \"attributes\": {},\n    \"location\": {\n      \"country\": \"BR\",\n      \"state\": \"SP\",\n      \"city\": \"Sao Paulo\"\n    },\n    \"payment_method\": \"pix\"\n  },\n  \"selection\": {\n    \"priority\": \"total_discount\"\n  },\n  \"units\": [\n    {\n      \"unit_id\": \"unit-001\",\n      \"brand_id\": \"brand-001\",\n      \"products\": [\n        {\n          \"product_id\": \"product-001\",\n          \"unitary_price\": 49.90\n        }\n      ],\n      \"shipping\": {\n        \"amount\": 12.50\n      }\n    }\n  ]\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/v1/coupon/eligibility/units/single",
            "description": "Consulta e retorna um cupom público elegível para cada unidade."
          },
          "response": []
        },
        {
          "name": "Consultar vários cupons elegíveis por unidade",
          "request": {
            "method": "QUERY",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"context\": {\n    \"user\": {\n      \"id\": \"user-001\"\n    },\n    \"attributes\": {},\n    \"location\": {\n      \"country\": \"BR\",\n      \"state\": \"SP\",\n      \"city\": \"Sao Paulo\"\n    },\n    \"payment_method\": \"credit_card\"\n  },\n  \"selection\": {\n    \"max_coupons_per_unit\": 2,\n    \"priority\": \"total_discount\"\n  },\n  \"units\": [\n    {\n      \"unit_id\": \"unit-001\",\n      \"brand_id\": \"brand-001\",\n      \"products\": [\n        {\n          \"product_id\": \"product-001\",\n          \"unitary_price\": 49.90\n        }\n      ],\n      \"shipping\": {\n        \"amount\": 12.50\n      }\n    }\n  ]\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/v1/coupon/eligibility/units/multiple",
            "description": "Consulta e retorna múltiplos cupons públicos elegíveis para cada unidade."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Descontos",
      "description": "Cálculo e reserva de descontos para carrinhos.",
      "item": [
        {
          "name": "Calcular desconto com um cupom",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"cart_id\": \"cart-001\",\n  \"coupon_code\": \"{{coupon_code}}\",\n  \"context\": {\n    \"user\": {\n      \"id\": \"user-001\"\n    },\n    \"attributes\": {},\n    \"location\": {\n      \"country\": \"BR\",\n      \"state\": \"SP\",\n      \"city\": \"Sao Paulo\"\n    },\n    \"payment_method\": \"pix\",\n    \"cart\": [\n      {\n        \"id\": \"product-001\",\n        \"quantity\": 2,\n        \"unitary_price\": 49.90\n      }\n    ],\n    \"shipping\": {\n      \"amount\": 12.50\n    },\n    \"unit_id\": \"unit-001\",\n    \"brand_id\": \"brand-001\"\n  }\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/v1/coupon/discount/single",
            "description": "Calcula e reserva um cupom no carrinho."
          },
          "response": []
        },
        {
          "name": "Calcular desconto com vários cupons",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"cart_id\": \"cart-001\",\n  \"coupon_codes\": [\n    \"{{coupon_code}}\",\n    \"{{coupon_code_2}}\"\n  ],\n  \"context\": {\n    \"user\": {\n      \"id\": \"user-001\"\n    },\n    \"attributes\": {},\n    \"location\": {\n      \"country\": \"BR\",\n      \"state\": \"SP\",\n      \"city\": \"Sao Paulo\"\n    },\n    \"payment_method\": \"credit_card\",\n    \"cart\": [\n      {\n        \"id\": \"product-001\",\n        \"quantity\": 2,\n        \"unitary_price\": 49.90\n      }\n    ],\n    \"shipping\": {\n      \"amount\": 12.50\n    },\n    \"unit_id\": \"unit-001\",\n    \"brand_id\": \"brand-001\"\n  },\n  \"selection\": {\n    \"strategy\": \"highest_discount_per_product\"\n  }\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/v1/coupon/discount/multiple",
            "description": "Calcula e reserva múltiplos cupons no carrinho."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Emissões",
      "description": "Emissão, consulta e revogação de códigos individuais.",
      "item": [
        {
          "name": "Criar emissão",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Idempotency-Key", "value": "{{idempotency_key}}" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"coupon_id\": \"{{coupon_id}}\",\n  \"external_reference\": \"order-001\",\n  \"subject\": {\n    \"user_id\": \"user-001\",\n    \"cart_id\": \"cart-001\"\n  },\n  \"cart\": [\n    {\n      \"id\": \"product-001\",\n      \"quantity\": 2,\n      \"unitary_price\": 49.90\n    }\n  ],\n  \"shipping\": {\n    \"amount\": 12.50\n  },\n  \"valid_until\": \"2027-12-31T23:59:59Z\",\n  \"metadata\": {\n    \"source\": \"postman\"\n  }\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/v1/coupon/issuances",
            "description": "Emite um código individual. Reutilize a mesma Idempotency-Key somente ao repetir a mesma tentativa."
          },
          "response": []
        },
        {
          "name": "Consultar emissão",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": "{{base_url}}/v1/coupon/issuances/{{issuance_id}}",
            "description": "Consulta uma emissão pelo identificador."
          },
          "response": []
        },
        {
          "name": "Revogar emissão",
          "request": {
            "method": "POST",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": "{{base_url}}/v1/coupon/issuances/{{issuance_id}}/revocations",
            "description": "Revoga uma emissão de forma idempotente."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Resgates e operações",
      "description": "Resgates, pagamentos, consulta de operação e estorno.",
      "item": [
        {
          "name": "Resgatar um cupom",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"cart_id\": \"cart-001\",\n  \"order_id\": \"{{order_id}}\",\n  \"coupon_code\": \"{{coupon_code}}\",\n  \"context\": {\n    \"user\": {\n      \"id\": \"user-001\"\n    },\n    \"attributes\": {},\n    \"location\": {\n      \"country\": \"BR\",\n      \"state\": \"SP\",\n      \"city\": \"Sao Paulo\"\n    },\n    \"payment_method\": \"pix\",\n    \"cart\": [\n      {\n        \"id\": \"product-001\",\n        \"quantity\": 2,\n        \"unitary_price\": 49.90\n      }\n    ],\n    \"shipping\": {\n      \"amount\": 12.50\n    },\n    \"unit_id\": \"unit-001\",\n    \"brand_id\": \"brand-001\"\n  }\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/v1/coupon/redeem/single",
            "description": "Resgata um cupom e opcionalmente registra o pagamento na mesma operação."
          },
          "response": []
        },
        {
          "name": "Resgatar vários cupons",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"cart_id\": \"cart-001\",\n  \"order_id\": \"{{order_id}}\",\n  \"coupon_codes\": [\n    \"{{coupon_code}}\",\n    \"{{coupon_code_2}}\"\n  ],\n  \"context\": {\n    \"user\": {\n      \"id\": \"user-001\"\n    },\n    \"attributes\": {},\n    \"location\": {\n      \"country\": \"BR\",\n      \"state\": \"SP\",\n      \"city\": \"Sao Paulo\"\n    },\n    \"payment_method\": \"credit_card\",\n    \"cart\": [\n      {\n        \"id\": \"product-001\",\n        \"quantity\": 2,\n        \"unitary_price\": 49.90\n      }\n    ],\n    \"shipping\": {\n      \"amount\": 12.50\n    },\n    \"unit_id\": \"unit-001\",\n    \"brand_id\": \"brand-001\"\n  },\n  \"selection\": {\n    \"strategy\": \"highest_discount_per_product\"\n  }\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/v1/coupon/redeem/multiple",
            "description": "Resgata múltiplos cupons em uma única operação."
          },
          "response": []
        },
        {
          "name": "Consultar operação",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": "{{base_url}}/v1/coupon/operations/{{operation_id}}",
            "description": "Consulta o estado atual de uma operação de resgate."
          },
          "response": []
        },
        {
          "name": "Consultar operação pelo pedido",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": "{{base_url}}/v1/coupon/operations/by-order/{{order_id}}",
            "description": "Recupera uma operação pelo order_id após timeout ou repetição incerta do resgate."
          },
          "response": []
        },
        {
          "name": "Registrar pagamento",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"payment-001\",\n  \"method\": \"pix\",\n  \"amount\": 99.80,\n  \"currency\": \"{{currency}}\",\n  \"paid_at\": \"2026-11-03T12:00:00Z\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/v1/coupon/operations/{{operation_id}}/payments",
            "description": "Registra o pagamento de uma operação de resgate. Use a moeda retornada em project.currency por Validar integração."
          },
          "response": []
        },
        {
          "name": "Registrar estorno parcial",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"{{partial_refund_external_id}}\",\n  \"redemptions\": [\n    {\n      \"redemption_id\": \"{{redemption_id}}\",\n      \"items\": [\n        {\n          \"line_number\": 1,\n          \"quantity\": 1,\n          \"discount_amount\": 5.00\n        }\n      ],\n      \"shipping_discount_amount\": 0.00\n    }\n  ]\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": "{{base_url}}/v1/coupon/operations/{{operation_id}}/partial-refunds",
            "description": "Registra de forma idempotente as quantidades e parcelas de desconto devolvidas. Requer pagamento confirmado."
          },
          "response": []
        },
        {
          "name": "Estornar operação",
          "request": {
            "method": "POST",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": "{{base_url}}/v1/coupon/operations/{{operation_id}}/refunds",
            "description": "Libera usos e budgets. O backend classifica como cancelamento sem pagamento ou estorno com pagamento confirmado."
          },
          "response": []
        }
      ]
    }
  ]
}