Ir para o conteúdo

API de Campanhas

Criação e gestão de campanhas no Propz, consulta de elegibilidade e registro de resgates.

Escopo necessário: propz:read (consultas) · propz:write (criação/resgate)

Endpoints

Método Path Descrição
GET /v1/campaigns Listar campanhas
GET /v1/campaigns/{id} Detalhes de uma campanha
POST /v1/campaigns Criar campanha
POST /v1/campaigns/validate Validar elegibilidade (uso no PDV)
POST /v1/campaigns/{id}/redeem Registrar resgate
DELETE /v1/campaigns/{id} Desativar campanha

GET /v1/campaigns

Lista campanhas com filtros.

Parâmetros de query

Parâmetro Tipo Descrição
status string active, scheduled, ended, paused
type string discount, cashback, bonus_points, gift
limit integer Itens por página (padrão: 20)

Exemplo de resposta

{
  "data": [
    {
      "id": "cmp_01ABC123",
      "name": "Dobro de Pontos em Vinhos",
      "type": "bonus_points",
      "status": "active",
      "starts_at": "2026-05-01T00:00:00-03:00",
      "ends_at": "2026-05-31T23:59:59-03:00",
      "segment_id": "seg_wine_lovers",
      "redemptions_count": 1204,
      "redemptions_limit": 5000
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false,
    "total": 1
  }
}

POST /v1/campaigns

Cria uma nova campanha.

Body

{
  "name": "Frete Grátis para Clientes Gold",
  "type": "discount",
  "discount": {
    "mode": "free_shipping"
  },
  "segment_id": "seg_gold_customers",
  "channels": ["ecommerce", "app"],
  "starts_at": "2026-06-01T00:00:00-03:00",
  "ends_at": "2026-06-30T23:59:59-03:00",
  "limits": {
    "per_customer": 3,
    "total": 10000
  }
}

Tipos de desconto

"discount": {
  "mode": "percentage",
  "value": 20,
  "max_discount_value": 50.00,
  "eligible_categories": ["laticinios", "frios"]
}

"discount": {
  "mode": "fixed",
  "value": 15.00,
  "min_cart_value": 80.00
}

"discount": {
  "mode": "bonus_points",
  "multiplier": 3,
  "eligible_categories": ["vinhos"]
}

"discount": {
  "mode": "cashback",
  "value": 5,
  "max_cashback_value": 30.00,
  "credit_after_days": 30
}

POST /v1/campaigns/validate

Ponto de integração principal para o PDV. Verifica quais campanhas um cliente pode usar para um dado carrinho de compras.

Body

{
  "customer_id": "cus_01HXYZ123ABC",
  "store_id": "loja_001",
  "channel": "pdv",
  "cart": {
    "subtotal": 145.90,
    "items": [
      { "sku": "VINHO001", "category": "vinhos", "quantity": 2, "unit_price": 49.90 },
      { "sku": "QUEIJO001", "category": "frios", "quantity": 1, "unit_price": 46.10 }
    ]
  }
}

Resposta

{
  "customer_id": "cus_01HXYZ123ABC",
  "eligible_campaigns": [
    {
      "campaign_id": "cmp_01ABC123",
      "name": "Dobro de Pontos em Vinhos",
      "type": "bonus_points",
      "description": "2x pontos nos vinhos do carrinho",
      "applicable_items": ["VINHO001"],
      "estimated_benefit": {
        "bonus_points": 100
      }
    }
  ],
  "validation_token": "vtk_9f3a2c1e",
  "expires_at": "2026-04-30T15:05:00-03:00"
}

Tempo de expiração

O validation_token é válido por 5 minutos. Passe-o na chamada de resgate para garantir que as mesmas condições sejam aplicadas.

POST /v1/campaigns/{id}/redeem

Registra o resgate de uma campanha após a compra ser confirmada.

Body

{
  "customer_id": "cus_01HXYZ123ABC",
  "order_id": "ped_20260430001",
  "validation_token": "vtk_9f3a2c1e",
  "amount_paid": 145.90
}

Resposta 201 Created

{
  "redemption_id": "rdm_01XYZ789",
  "campaign_id": "cmp_01ABC123",
  "customer_id": "cus_01HXYZ123ABC",
  "benefit_applied": {
    "bonus_points": 100
  },
  "redeemed_at": "2026-04-30T14:58:12-03:00"
}