التحقق من مفتاح API

curl --request GET \
  --url https://billapi.oneclickdz.com/v3/validate \
  --header 'X-Access-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://billapi.oneclickdz.com/v3/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billapi.oneclickdz.com/v3/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Access-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billapi.oneclickdz.com/v3/validate"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Access-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billapi.oneclickdz.com/v3/validate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

GET

validate

التحقق من مفتاح API

curl --request GET \
  --url https://billapi.oneclickdz.com/v3/validate \
  --header 'X-Access-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://billapi.oneclickdz.com/v3/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billapi.oneclickdz.com/v3/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Access-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billapi.oneclickdz.com/v3/validate"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Access-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billapi.oneclickdz.com/v3/validate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

نظرة عامة

يتحقق من مفتاح API الخاص بدفع الفواتير ويعيد إليك من أنت والبيئة التي يرتبط بها المفتاح. وهو أول استدعاء يجب إجراؤه في أي تكامل جديد، وأأمن وسيلة لإثبات أنك موجَّه إلى sandbox لا إلى الإنتاج، قبل أن تحرّك أي أموال.

كل مفتاح مرتبط ببيئة واحدة فقط لا غير — SANDBOX أو PRODUCTION. البيئة خاصية للمفتاح الذي نُصدره لك. لا تستنتجها أبدًا من نص المفتاح أو من بادئته؛ اقرأ key.type من هذا endpoint.

يوجد دفع الفواتير على https://billapi.oneclickdz.com، لا على عنوان URL الأساسي الذي تستخدمه بقية المنصة. أما الترويسة فهي نفسها التي تستخدمها بالفعل: X-Access-Token.

الاستجابة

boolean

مطلوب

true عند التحقق من المفتاح بنجاح.

object

مطلوب

إظهار properties

object

مطلوب

إظهار properties

string

مطلوب

معرّف حساب الشريك الخاص بك.

string

مطلوب

ACTIVE لمفتاح اجتاز التحقق.

string

مطلوب

دائمًا DZD.

object

مطلوب

إظهار properties

string

مطلوب

SANDBOX أو PRODUCTION. البيان الموثوق الوحيد للبيئة التي يعمل فيها هذا المفتاح.

object

مطلوب

إظهار properties

string

مطلوب

وقت الاستجابة، بتنسيق ISO 8601 UTC.

string

مطلوب

معرّف الربط، يُرسَل أيضًا في ترويسة الاستجابة X-Request-Id.

الأمثلة

curl https://billapi.oneclickdz.com/v3/validate \
  -H "X-Access-Token: YOUR_API_KEY"

const response = await fetch("https://billapi.oneclickdz.com/v3/validate", {
  headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
});

const body = await response.json();

if (!body.success) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

console.log(`Account ${body.data.account.id} — ${body.data.key.type}`);

import os
import requests

response = requests.get(
    'https://billapi.oneclickdz.com/v3/validate',
    headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')}
)

body = response.json()

if not body['success']:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")

print(f"Account {body['data']['account']['id']} — {body['data']['key']['type']}")

<?php
$ch = curl_init('https://billapi.oneclickdz.com/v3/validate');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!$body['success']) {
    throw new Exception($body['error']['code'] . ': ' . $body['error']['message']);
}

echo "Account {$body['data']['account']['id']} — {$body['data']['key']['type']}";
?>

استجابة النجاح

{
  "success": true,
  "data": {
    "account": {
      "id": "partner_7f21",
      "status": "ACTIVE",
      "currency": "DZD"
    },
    "key": {
      "type": "SANDBOX"
    }
  },
  "meta": {
    "timestamp": "2026-08-31T10:15:32.194Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

استجابات الخطأ

401 — رمز وصول مفقود

لم تُرسَل ترويسة X-Access-Token.

{
  "success": false,
  "error": {
    "code": "MISSING_ACCESS_TOKEN",
    "message": "X-Access-Token header is required."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: أضف الترويسة. لا يقبل دفع الفواتير المفتاح إلا في تلك الترويسة — لا في سلسلة استعلام ولا في متن الطلب.

401 — رمز وصول غير صالح

رُفض المفتاح.

{
  "success": false,
  "error": {
    "code": "INVALID_ACCESS_TOKEN",
    "message": "The provided access token is invalid."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: تحقّق من وجود خطأ في النسخ واللصق، ثم تواصل مع الدعم. إعادة المحاولة بالمفتاح نفسه لن تغيّر الإجابة.

503 — المصادقة غير متاحة

لم نتمكن من التحقق من مفتاحك في الوقت المناسب. مفتاحك ليس هو المشكلة.

{
  "success": false,
  "error": {
    "code": "AUTH_UNAVAILABLE",
    "message": "Authentication is temporarily unavailable. Please retry shortly."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: انتظر المدة المحددة في ترويسة Retry-After (5 ثوانٍ) ثم أعد المحاولة. لا تُظهر هذا لعميلك أبدًا على أنه خطأ في بيانات الاعتماد، ولا تعطّل المفتاح بسببه.

503 — الخدمة غير متاحة

واجهة دفع الفواتير في صيانة مُخطّط لها.

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The service is temporarily unavailable. Please retry shortly."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

ما العمل: التزم بـ Retry-After وأعد المحاولة.

تأكيد بيئتك قبل الإطلاق

نفّذ هذا الفحص عند بدء التشغيل، ثم مرة أخرى في خط النشر لديك. سطر واحد من المخرجات يخبرك ما إذا كان المفتاح الموجود في إعدادات تلك البيئة هو المفتاح الذي قصدت إطلاقه.

async function assertEnvironment(expected) {
  const response = await fetch("https://billapi.oneclickdz.com/v3/validate", {
    headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
  });

  const body = await response.json();

  if (!body.success) {
    throw new Error(`Key check failed: ${body.error.code}`);
  }

  if (body.data.key.type !== expected) {
    throw new Error(
      `Wrong key: expected ${expected}, got ${body.data.key.type}`,
    );
  }

  return body.data.account.id;
}

// In your sandbox deployment
await assertEnvironment("SANDBOX");

مفتاح sandbox ومفتاح الإنتاج متبادلان في الشكل لا في الأثر. مفتاح الإنتاج يحرّك أموالًا حقيقية عند أول عملية دفع ناجحة. تحقّق من key.type قبل تفعيل مسار الدفع.

ما لا يُرجعه هذا endpoint

مفاتيح دفع الفواتير ليس لها نطاقات صلاحية، ولا حقل انتهاء صلاحية، ولا رصيد لكل مفتاح، لذلك لا يظهر أي منها هنا. account وkey.type وmeta وrequestId هي الاستجابة كاملةً.

أفضل الممارسات

استدعِه عند بدء التشغيل

استدعاء واحد عند الإقلاع يثبت أن المفتاح يعمل ويحدّد اسم البيئة، قبل أن تصل أي حركة عملاء إلى مسار الدفع.

لا تسجّل المفتاح أبدًا

سجّل account.id وkey.type بدلًا منه. مكان المفتاح نفسه هو مخزن أسرار، لا سجلات التطبيق.

افصل بين المفتاحين

احتفظ بمفتاح sandbox ومفتاح الإنتاج في مخازن إعدادات مختلفة كي لا يمكن الوصول إلى أيٍّ منهما من البيئة الأخرى.

تعامل مع 503 على أنه عارض

يعني AUTH_UNAVAILABLE أننا لم نتمكن من الإجابة في الوقت المناسب. أعد المحاولة بعد Retry-After؛ ولا تُدوّر المفتاح.

Endpoints ذات الصلة

قائمة الشركاء

تحقّق من الشركاء المتاحين

استكشاف الفواتير

ابدأ استكشاف فاتورة

نظرة عامة على دفع الفواتير

كيف يتكامل التدفق بأكمله

اختبار Sandbox

اختبر كل نتيجة ممكنة قبل الإطلاق

مرجع API

Core

الحساب

شحن الهاتف

شحن الإنترنت

بطاقات الهدايا

Navio

دفع الفواتير

التحقق من مفتاح API

نظرة عامة

الاستجابة

الأمثلة

استجابة النجاح

استجابات الخطأ

تأكيد بيئتك قبل الإطلاق

ما لا يُرجعه هذا endpoint

أفضل الممارسات

استدعِه عند بدء التشغيل

لا تسجّل المفتاح أبدًا

افصل بين المفتاحين

تعامل مع 503 على أنه عارض

Endpoints ذات الصلة

قائمة الشركاء

استكشاف الفواتير

نظرة عامة على دفع الفواتير

اختبار Sandbox

​نظرة عامة

​الاستجابة

​الأمثلة

​استجابة النجاح

​استجابات الخطأ

​تأكيد بيئتك قبل الإطلاق

​ما لا يُرجعه هذا endpoint

​أفضل الممارسات

استدعِه عند بدء التشغيل

لا تسجّل المفتاح أبدًا

افصل بين المفتاحين

تعامل مع 503 على أنه عارض

​Endpoints ذات الصلة

قائمة الشركاء

استكشاف الفواتير

نظرة عامة على دفع الفواتير

اختبار Sandbox

نظرة عامة

الاستجابة

الأمثلة

استجابة النجاح

استجابات الخطأ

تأكيد بيئتك قبل الإطلاق

ما لا يُرجعه هذا endpoint

أفضل الممارسات

Endpoints ذات الصلة