مستندات

شروع
فاکتور
دیاگرام فاکتور
موجودی
نرخ
تبدیل
انتقال

شروع

در ابتدا از طریق پنل کاربری بخش API کلید های api_key و secret_key را تولید کنید . همچنین در بخش API میتوانید دسترسی به سرویس API را با IP محدود بکنید و فقط از IP های خود به سرویس متصل بشوید . اگر نمیدانید IP سرور شما چیست میتوانید در سرور خود دستور زیر را اجرا کنید .

curl 'https://api.zipay.io/api/'

نحوه استفاده از کلید های API

ابتدا در پنل api_key و secret_key را تولید کنید . و متدهایی که نیاز دارید را فعال کنید .
هرگز کلید های API را با کسی در اشتراک نگذارید
کلید های شما باید مشابه زیر باشند

API Key: 4f3c12fa0a1d1ac8b026298b980f16b2
SECRET KEY: f7d36fd7f60ab0bac12051e0c3240508585dba741e126669bfbc06e002b9df6ac4e457b6

به ازای هر درخواست شما باید دو تا پارامتر را در header درخواست ارسال بکنید یکی از آنها api_key و دیگری api_sign هست .
api_sign را باید با استفاده از الگوریتم hmac_hash sha256 برروی پارامترهای ارسالی با استفاده از secret_key بسازید .
برای مثال شما میخواهید پارامتر par1=value1 و par2=value2 را به سرویس API ارسال کنید
ابتدا شما باید api_sign با استفاده از secret_key تولید کنید.
اینجا نمونه کدهایی از زبانهای مختلف جهت تولید api_sign قرار داده شده است.

PHP:


$post_encode = http_build_query([
             'par1'=>'value1',
             'par2'=>'value2'
        ]);
$s = hash_hmac('sha256', $post_encode, 'f7d36fd7f60ab0bac12051e0c3240508585dba741e126669bfbc06e002b9df6ac4e457b6', true);
echo base64_encode($s); //g1seBV5gkv7n4EjIdzMjl+ntJ256kvIe2kulu2SfTPk=

>Node.js:

var crypto = require('crypto');
var hash = crypto.createHmac('SHA256', "f7d36fd7f60ab0bac12051e0c3240508585dba741e126669bfbc06e002b9df6ac4e457b6").update("par1=value1&par2=value2").digest('base64');

Python:

import hashlib
import hmac
import base64

dataToBeSigned= bytes("par1=value1&par2=value2").encode('utf-8')
portalKey = bytes("f7d36fd7f60ab0bac12051e0c3240508585dba741e126669bfbc06e002b9df6ac4e457b6").encode('utf-8')

signature = base64.b64encode(hmac.new(portalKey, dataToBeSigned, digestmod=hashlib.sha256).digest())

Ruby:

require 'openssl'
require "base64"

hash  = OpenSSL::HMAC.digest('sha256', "f7d36fd7f60ab0bac12051e0c3240508585dba741e126669bfbc06e002b9df6ac4e457b6", "par1=value1&par2=value2")
token = Base64.encode64(hash)
token.delete("\n")

Java:

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Base64;

public class ApiSecurityExample {
  public static void main(String[] args) {
    String portalKey = "f7d36fd7f60ab0bac12051e0c3240508585dba741e126669bfbc06e002b9df6ac4e457b6";
    String dataToBeSigned= "par1=value1&par2=value2";

    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key = new SecretKeySpec(portalKey.getBytes(), "HmacSHA256");
    sha256_HMAC.init(secret_key);

    String hash = Base64.encodeBase64String(sha256_HMAC.doFinal(dataToBeSigned.getBytes()));
  }
}

ارسال درخواست

در این مرحله شما بایدapi_key و api_sign و پارامترهای par1=value1&par2=value2 را داشته باشید .
پارامتر ها را بصورت POST (و نه json ) به سرویس API ارسال کنید ! و همچنین api_key و api_sign در header قرار دهید .

CURL

curl -H "api_key:4f3c12fa0a1d1ac8b026298b980f16b2" -H "api_sign:g1seBV5gkv7n4EjIdzMjl+ntJ256kvIe2kulu2SfTPk=" --data "par1=value1&par2=value2" https://api.zipay.io/api/example

PHP

$_headers = [
	'api_key:4f3c12fa0a1d1ac8b026298b980f16b2',
	'api_sign:g1seBV5gkv7n4EjIdzMjl+ntJ256kvIe2kulu2SfTPk=',
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, $_headers);
curl_setopt($ch, CURLOPT_URL, 'https://api.zipay.io/api/example');
curl_setopt($ch, CURLOPT_POSTFIELDS, 'par1=value1&par2=value2');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
$result = curl_exec($ch);
curl_close($ch);
echo $result;

پاسخ

همه پاسخ ها با فرمت JSON هستند .

نمونه پاسخ موفق:

{
	...
	"success": true,
	"status": 200
}

مقدار "success" زمانیکه true باشد به این معنی هست که همه چیز درست هست و همچنین مقدار status بیانگر HTTP status code است .

مثال ناموفق:

{
	"errors": {
		"auth": "INVALID_API_SIGN"
	},
	"success": false,
	"status": 403
}

متد Random

POST https://api.zipay.io/api/random

نام پارامتر	نوع	اجباری	توضیحات
min	integer	بله	یک عدد وارد کنید
max	integer	بله	یک عدد دیگر بزرگتر از min وارد کنید

خروجی:

{
	"trackid": "08B171-F259CB-3E300C-9ABE83",
	"result": 15,
	"success": true,
	"status": 200
}