Pular para conteúdo

Coupons reference

CouponClient

Bases: BaseClient

Source code in abacatepay/coupons/client.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
class CouponClient(BaseClient):
  def create(self, data: Optional[CouponIn | dict] = None, **kwargs) -> Coupon:
    """
    Create a new coupon.

    Args:
        data (Coupon): an instance of `abacatepay.coupons.models.Coupon` a dict \
        or the named params following the model schema.

    Keyword args:
        code (str): The unique code for the coupon.
        discount_kind (DISCOUNT_KINDS): The type of discount (e.g., percentage or fixed amount).
        discount (int): The value of the discount.
        notes (Optional[str]): A description or note about the coupon. Defaults to None.
            - Serialization alias: 'notes'
            - Example: "Cupom de desconto pro meu público"
        max_redeems (Optional[int]): The maximum number of times the coupon can be redeemed.
            Defaults to -1 for unlimited redemptions.
        metadata (Optional[dict]): Additional metadata for the coupon. Defaults to None.

    Returns:
        Coupon: The response with the coupon data.
    """
    json_data = prepare_data(data or kwargs, CouponIn)
    logger.debug('creating coupon: %s', json_data)

    response = self._request(
        f"{BASE_URL}/coupon/create",
        method="POST",
        json=json_data,
    )
    logger.debug(f"Response from coupon creation: {response.json()}")
    return Coupon.model_validate(response.json()["data"], by_alias=True)

  def list(self):
    """
    List all coupons.
    Returns:
        list[Coupon]: A list of coupon objects.
    """
    logger.debug(f"Listing coupons with URL: {BASE_URL}/coupon/list")
    response = self._request(f"{BASE_URL}/coupon/list", method="GET")
    data = response.json().get("data", [])

    if not data:
        logger.warning("No coupons found in the response.")
        return []  # Retorna uma lista vazia ou outro valor padrão

    return [Coupon.model_validate(item) for item in data]

create(data=None, **kwargs)

Create a new coupon.

Parameters:

Name Type Description Default
data Coupon

an instance of abacatepay.coupons.models.Coupon a dict or the named params following the model schema.

 None

Other Parameters:

Name Type Description
code str

The unique code for the coupon.
discount_kind DISCOUNT_KINDS

The type of discount (e.g., percentage or fixed amount).
discount int

The value of the discount.
notes Optional[str]

A description or note about the coupon. Defaults to None. - Serialization alias: 'notes' - Example: "Cupom de desconto pro meu público"
max_redeems Optional[int]

The maximum number of times the coupon can be redeemed. Defaults to -1 for unlimited redemptions.
metadata Optional[dict]

Additional metadata for the coupon. Defaults to None.

Returns:

Name Type Description
Coupon Coupon

The response with the coupon data.
Source code in abacatepay/coupons/client.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def create(self, data: Optional[CouponIn | dict] = None, **kwargs) -> Coupon:
  """
  Create a new coupon.

  Args:
      data (Coupon): an instance of `abacatepay.coupons.models.Coupon` a dict \
      or the named params following the model schema.

  Keyword args:
      code (str): The unique code for the coupon.
      discount_kind (DISCOUNT_KINDS): The type of discount (e.g., percentage or fixed amount).
      discount (int): The value of the discount.
      notes (Optional[str]): A description or note about the coupon. Defaults to None.
          - Serialization alias: 'notes'
          - Example: "Cupom de desconto pro meu público"
      max_redeems (Optional[int]): The maximum number of times the coupon can be redeemed.
          Defaults to -1 for unlimited redemptions.
      metadata (Optional[dict]): Additional metadata for the coupon. Defaults to None.

  Returns:
      Coupon: The response with the coupon data.
  """
  json_data = prepare_data(data or kwargs, CouponIn)
  logger.debug('creating coupon: %s', json_data)

  response = self._request(
      f"{BASE_URL}/coupon/create",
      method="POST",
      json=json_data,
  )
  logger.debug(f"Response from coupon creation: {response.json()}")
  return Coupon.model_validate(response.json()["data"], by_alias=True)

list()

List all coupons. Returns: list[Coupon]: A list of coupon objects.

Source code in abacatepay/coupons/client.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def list(self):
  """
  List all coupons.
  Returns:
      list[Coupon]: A list of coupon objects.
  """
  logger.debug(f"Listing coupons with URL: {BASE_URL}/coupon/list")
  response = self._request(f"{BASE_URL}/coupon/list", method="GET")
  data = response.json().get("data", [])

  if not data:
      logger.warning("No coupons found in the response.")
      return []  # Retorna uma lista vazia ou outro valor padrão

  return [Coupon.model_validate(item) for item in data]

Coupon

Bases: BaseModel

Represents a coupon model for retrieval.

Attributes:

Name Type Description
id str

The unique identifier for the coupon.
discount_kind str

The type of discount (e.g., percentage or fixed amount).
discount int

The value of the discount.
status str

The current status of the coupon (e.g., ACTIVE, INACTIVE).
notes Optional[str]

A description or note about the coupon.
max_redeems int

The maximum number of times the coupon can be redeemed.
redeems_count int

The number of times the coupon has been redeemed.
created_at str

The timestamp when the coupon was created.
updated_at str

The timestamp when the coupon was last updated.
Source code in abacatepay/coupons/models.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
class Coupon(BaseModel):
    """
    Represents a coupon model for retrieval.

    Attributes:
        id (str): The unique identifier for the coupon.
        discount_kind (str): The type of discount (e.g., percentage or fixed amount).
        discount (int): The value of the discount.
        status (str): The current status of the coupon (e.g., ACTIVE, INACTIVE).
        notes (Optional[str]): A description or note about the coupon.
        max_redeems (int): The maximum number of times the coupon can be redeemed.
        redeems_count (int): The number of times the coupon has been redeemed.
        created_at (str): The timestamp when the coupon was created.
        updated_at (str): The timestamp when the coupon was last updated.
    """
    id: str
    discount_kind: str = Field(..., alias='discountKind', description="Type of discount (e.g., percentage or fixed amount)")
    discount: int
    status: str
    notes: Optional[str] = Field(None, validation='notes', description="Coupon's description")
    max_redeems: int = Field(-1, validation_alias='maxRedeems', description="Maximum number of times the coupon can be redeemed.")
    redeems_count: int = Field(0, validation_alias='redeemsCount', description="Number of times the coupon has been redeemed.")
    created_at: str = Field(..., validation_alias='createdAt', description="Timestamp when the coupon was created.")
    updated_at: str = Field(..., validation_alias='updatedAt', description="Timestamp when the coupon was last updated.")
    dev_mode: bool = Field(..., validation_alias='devMode', description="Indicates if the coupon is in development mode.")

CouponIn

Bases: BaseModel

Represents a coupon model for creation.

Attributes:

Name Type Description
code str

The unique code for the coupon.
discount_kind DISCOUNT_KINDS

The type of discount (e.g., percentage or fixed amount).
discount int

The value of the discount.
notes Optional[str]

A description or note about the coupon. Defaults to None. - Serialization alias: 'notes' - Example: "Cupom de desconto pro meu público"
max_redeems Optional[int]

The maximum number of times the coupon can be redeemed. Defaults to -1 for unlimited redemptions.
metadata Optional[dict]

Additional metadata for the coupon. Defaults to None.
Source code in abacatepay/coupons/models.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
class CouponIn(BaseModel):
    """
    Represents a coupon model for creation.

    Attributes:
        code (str): The unique code for the coupon.
        discount_kind (DISCOUNT_KINDS): The type of discount (e.g., percentage or fixed amount).
        discount (int): The value of the discount.
        notes (Optional[str]): A description or note about the coupon. Defaults to None.
            - Serialization alias: 'notes'
            - Example: "Cupom de desconto pro meu público"
        max_redeems (Optional[int]): The maximum number of times the coupon can be redeemed.
            Defaults to -1 for unlimited redemptions.
        metadata (Optional[dict]): Additional metadata for the coupon. Defaults to None.
    """
    code: str
    discount_kind: DISCOUNT_KINDS =  Field(DISCOUNT_KINDS, serialization_alias='discountKind', description="Type of discount (e.g., percentage or fixed amount)", examples=["PERCENTAGE", "FIXED_AMOUNT"])
    discount:int
    notes: Optional[str] = Field(None, serialization_alias='notes', description="Coupon's description", examples=["Cupom de desconto pro meu público"])
    max_redeems: Optional[int] = Field(-1, description="Maximum number of times the coupon can be redeemed. Defaults to -1 for unlimited.", serialization_alias='maxRedeems')
    metadata: Optional[dict] = Field({}, description="Additional metadata for the coupon.")