API Documentation

zferral API


Introduction

Authentication of affiliates

API Objects

Commission

Methods:

Examples:


All of the commission 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 for this commission
  • affiliate_id INT (Required) Affiliate id
  • campaign_id INT (Required) Campaign id
  • amount DECIMAL(10,2) (Required) Amount of commission (if 'count_method' is set to 'commission') or Revenue (if 'count_method' is set to 'revenue', then commission will be counted according to campaign setup)
  • count_method STRING (Required) Allowed values: [commission, revenue] See description of 'amount' parameter
  • customer_id VARCHAR(255) (Required) It is a unique id of the customer in your system
  • created_at TIMESTAMP (Read Only) The creation date for this commission
  • is_approved BOOL (Optional)(Edit) Whether the commission has been approved


**Please note that if you wish to have the Commissions calculated via zferral (or have tiered commissions) set the count_method to "revenue". If you have questions please email support@zferral.com

Methods

create - creates new commission

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


update - edits or updates data of commission object

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


get – retrieve commisison data

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


list – retrieve list of commissions

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

create - Usage Example

Scenarios [examples]:

Requirements:

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


  1. Scenario: Create a commission

    Request

    a) XML 

          <?xml version="1.0" encoding="UTF-8" ?>
      <commission>
        <affiliate_id>1</affiliate_id>
        <campaign_id>1</campaign_id>
        <amount>35</amount>
        <count_method>revenue</count_method>
        <customer_id>33</customer_id>
      </commission>

    b) JSON 

            {
          "commission" : {
            "affiliate_id"  : "2",
            "campaign_id"   : "2",
            "amount"        : "128",
            "count_method"  : "revenue",
            "customer_id"   : "33"
        }}


    Response (return status code "201 Created"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <commission>
          <id>23</id>
        </commission>

    b) JSON 

            {
         "commission" : {
            "id" : "39",
        }}

  2. Scenario: Create a commission (sending not all required parameters)

    Request

    a) XML 

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

    b) JSON 

            {
         "commission" : {
            "affiliate_id"  : 1,
        }}


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

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <errors>
            <campaign_id>Required.</campaign_id>
            <amount>Required.</amount>
            <count_method>Required.</count_method>
            <customer_id>Required.</customer_id>
        </errors>

    b) JSON 

            {
         "errors": {
            "campaign_id" : "Required.",
            "amount"      : "Required.",
            "count_method": "Required.",
            "customer_id" : "Required."
        }}


update - Usage Example

Scenarios [examples]:

Requirements:

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


  1. Scenario: Edit commission data (sending correct parameter: is_approved)

    Request

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <commission>
          <is_approved>true</is_approved>
        </commission>

    b) JSON 

            {
         "commission" : {
            "is_approved" : true
        }}


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <commission>
          <id>7</id>
        </commission>

    b) JSON 

            {
         "commission" : {
            "id" : "7",
        }}


get – Usage Example

Scenarios [examples]:

Requirements:

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


  1. Scenario: Retrieve commission data


    Request

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


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <commission>
            <id>1</id>
            <affiliate_id>1</affiliate_id>
            <campaign_id>1</campaign_id>
            <amount>79.00</amount>
            <created_at>2010-03-25 09:22:14</created_at>
            <is_approved>1</is_approved>
        </commission>

    b) JSON 

            {
          "commission": {
            "id"              : 1,
            "affiliate_id"    : 1,
            "campaign_id"     : 1,
            "amount"          : "79.00",
            "created_at"      : "2010-03-25 09:22:14",
            "is_approved"     : true
        }}


list – Usage Example

Scenarios [examples]:

Requirements:

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


  1. Scenario: Retrieve list of commissions


    Request

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


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <commissions type="array">
            <commission>
                <id>1</id>
                <affiliate_id>1</affiliate_id>
                <campaign_id>1</campaign_id>
                <amount>79.00</amount>
                <created_at>2010-03-25 09:22:14</created_at>
                <is_approved>1</is_approved>
            </commission>
            <commission>
                <id>2</id>
                <affiliate_id>2</affiliate_id>
                <campaign_id>2</campaign_id>
                <amount>5.00</amount>
                <created_at>2010-03-25 09:22:14</created_at>
                <is_approved></is_approved>
            </commission>
            <commission>
                <id>3</id>
                <affiliate_id>2</affiliate_id>
                <campaign_id>1</campaign_id>
                <amount>202.00</amount>
                <created_at>2010-03-25 09:22:14</created_at>
                <is_approved>1</is_approved>
            </commission>
            <commission>
                <id>4</id>
                <affiliate_id>1</affiliate_id>
                <campaign_id>2</campaign_id>
                <amount>31.00</amount>
                <created_at>2010-03-25 09:22:14</created_at>
                <is_approved></is_approved>
            </commission>
            <commission>
                <id>5</id>
                <affiliate_id>3</affiliate_id>
                <campaign_id>1</campaign_id>
                <amount>490.00</amount>
                <created_at>2010-03-25 09:22:14</created_at>
                <is_approved>1</is_approved>
            </commission>
        </commissions>

    b) JSON 

            {
         "commissions" : {
            "commission" : {
              (...)
            },
            "commission" : {
              (...)
            },
            "commission" : {
              (...)
            }
        }}