API Documentation

zferral API


Introduction

Authentication of affiliates

API Objects

Coupon

Methods:

Examples:


All of the coupon attribute fields are returned from GET (read) operations. Only those attributes not marked as read only may be set via POST (create) operations. Only those attributes marked as edit may be set via PUT (update) operations.

Parameters:

  • id INT (Read Only) The unique identifier of coupon
  • affiliate_id INT (Required) Affiliate id
  • campaign_id INT (Required) Campaign id
  • code STRING (limited to 15 characters) (Required) Coupon code
  • misc STRING (limited to 255 characters)(Optional) Description of coupon
  • created_at TIMESTAMP (Read Only) The creation date of coupon


Methods

create – creates coupon

URL: "https://<subdomain>.zferral.com/api/<api_key>/coupon.<format>"
Method: POST
Format: xml or json
Required Parameters: XML or JSON data, as specified by the required attributes
Response: The created Coupon id
XML and JSON example


get – retrieves coupon data

URL: "https://<subdomain>.zferral.com/api/<api_key>/coupon/<id>.<format>"
Method: GET
Format: xml or json
Required Parameters: id
Response: An single coupon
XML and JSON example


getByCode – retrieves coupon data by code

URL: "https://<subdomain>.zferral.com/api/<api_key>/coupon/getByCode/<code>.<format>"
Method: GET
Format: xml or json
Required Parameters: code
Response: An single coupon
XML and JSON example


list – retrieves list of coupons

URL: "https://<subdomain>.zferral.com/api/<api_key>/coupon.<format>"
Method: GET
Format: xml or json
Optional Parameters: affiliate_id, page, limit
Response: An array of coupons, up to 50 per page
XML and JSON example


delete – removes coupon

URL: "https://<subdomain>.zferral.com/api/<api_key>/coupon/<id>.<format>"
Method: DELETE
Format: xml or json
Required Parameters: id
XML and JSON example

create - Usage Example

Scenarios [examples]:

Requirements:

  • Correct <api_key>
  • Returned data format <format>


  1. Scenario: Creating coupon

    Request

    a) XML 

          <?xml version="1.0" encoding="UTF-8" ?>
      <coupon>
        <affiliate_id>1</affiliate_id>
        <code>code123</code>
      </coupon>

    b) JSON 

            {
          "coupon" : {
            "affiliate_id"  : "2",
            "code"          : "code123"
        }}


    Response (return status code "201 Created"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <coupon>
          <id>13</id>
        </coupon>

    b) JSON 

            {
         "coupon" : {
            "id" : "13",
        }}

  2. Scenario: Creating Coupon (sending not all required parameters)

    Request

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <coupon>
          <affiliate_id>1</affiliate_id>
        </coupon>

    b) JSON 

            {
         "coupon" : {
            "affiliate_id"  : 1,
        }}


    Response (return status code "422 Unprocessable Entity"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <errors>
            <code>Required.</code>
        </errors>

    b) JSON 

            {
         "errors": {
            "code":"Required.",
        }}


get – Usage Example

Scenarios [examples]:

Requirements:

  • Give correct <api_key>
  • Returned data format <format>
  • Give <id>


  1. Scenario: Retrieve coupon data


    Request

    URL: "https://subdomain.zferral.com/api/<api_key>/coupon/1.<format>"


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <coupon>
            <id>1</id>
            <affiliate_id>1</affiliate_id>
            <campaign_id>1</campaign_id>
            <code>codenr1</code>
            <created_at>2010-03-25 09:22:14</created_at>
            <misc>Some description</misc>
        </coupon>

    b) JSON 

            {
          "coupon": {
            "id"              : 1,
            "affiliate_id"    : 1,
            "campaign_id"     : 1,
            "code"            : "codenr1",
            "created_at"      : "2010-03-25 09:22:14",
            "misc"            : "Some description"
        }}


getByCode – Usage Example

Scenarios [examples]:

Requirements:

  • Give correct <api_key>
  • Returned data format <format>
  • Give <code>


  1. Scenario: Retrieve coupon data by code


    Request

    URL: "https://subdomain.zferral.com/api/<api_key>/coupon/getByCode/abcd.<format>"


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <coupon>
            <id>1</id>
            <affiliate_id>1</affiliate_id>
            <campaign_id>1</campaign_id>
            <code>abcd</code>
            <created_at>2010-03-25 09:22:14</created_at>
            <misc>Some description</misc>
        </coupon>

    b) JSON 

            {
          "coupon": {
            "id"              : 1,
            "affiliate_id"    : 1,
            "campaign_id"     : 1,
            "code"            : "abcd",
            "created_at"      : "2010-03-25 09:22:14",
            "misc"            : "Some description"
        }}


list – Usage Example

Scenarios [examples]:

Requirements:

  • Give correct <api_key>
  • Returned data format <format>


  1. Scenario: Retrieve list of coupons


    Request

    URL: "https://subdomain.zferral.com/api/<api_key>/coupons.<format>"


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <coupons type="array">
            <coupon>
                <id>1</id>
                <affiliate_id>1</affiliate_id>
                <campaign_id>1</campaign_id>
                <code>abcd</code>
                <created_at>2010-03-25 09:22:14</created_at>
                <misc>Some description</misc>
            </coupon>
            <coupon>
                <id>2</id>
                <affiliate_id>2</affiliate_id>
                <campaign_id>2</campaign_id>
                <code>efgh</code>
                <created_at>2010-03-25 09:22:14</created_at>
                <misc>Some description</misc>
            </coupon>
            <coupon>
                <id>3</id>
                <affiliate_id>2</affiliate_id>
                <campaign_id>1</campaign_id>
                <code>ijkl</code>
                <created_at>2010-03-25 09:22:14</created_at>
                <misc>Some description</misc>
            </coupon>
            <coupon>
                <id>4</id>
                <affiliate_id>1</affiliate_id>
                <campaign_id>2</campaign_id>
                <code>mnop</code>
                <created_at>2010-03-25 09:22:14</created_at>
                <is_approved></is_approved>
            </coupon>
            <coupon>
                <id>5</id>
                <affiliate_id>3</affiliate_id>
                <campaign_id>1</campaign_id>
                <code>rstuv</code>
                <created_at>2010-03-25 09:22:14</created_at>
                <misc>Some description</misc>
            </coupon>
        </coupons>

    b) JSON 

            {
         "coupons" : {
            "coupon" : {
              (...)
            },
            "coupon" : {
              (...)
            },
            "coupon" : {
              (...)
            }
        }}


delete – Usage Example

Scenarios [examples]:

Requirements:

  • Correct <api_key>
  • Returned data format <format>
  • Correct <id>


  1. Scenario: Delete coupon


    Request

    URL: "https://subdomain.zferral.com/api/<api_key>/coupon/10.<format>"


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <coupon>
          <id>10</id>
        </coupon>

    b) JSON 

            {
         "coupon" : {
            "id" : "10",
        }}