التوثيق / مرجع الواجهة

الملاحظات بالجملة

يرسل حتى 1,000 نتيجة دفع وتصنيف في استدعاء واحد، للمزامنة الليلية ولإرسال تاريخك السابق.

نظرة عامة#

feedback/bulk طريقة POST بمحتوى JSON بالشكل {"items": [...]}. كل عنصر إمّا نتيجة دفع (kind: "payment" بحقول الإبلاغ عن نتيجة الدفع) وإمّا تصنيف (kind: "event" بحقول تصنيف هوية أو حدث).

متى تستدعيها#

مرة كل ليلة، مع كل نتائج اليوم أو اليومين الأخيرين. الاستدعاء لا يكرّر شيئاً: العناصر الموجودة لدى Gurdx تعود unchanged، فلا بأس بتداخل الفترات.
مرة واحدة، لإرسال طلبات الأشهر الماضية ونتائجها قبل أن يبدأ Gurdx التعلّم.

كيف تعمل#

تُعالج العناصر بالترتيب وكلٌّ على حدة. يعدّ الرد العناصر created وupdated وunchanged وpending (نتائج بانتظار معاملتها) وfailed، ويسرد نتيجة لكل عنصر مع index الخاص به. يُبلَّغ عن العنصر الخاطئ بـstatus: "error" وcode وdescription، ولا يوقف البقية.

ملاحظات#

مجانية: لا تُحتسب من حصتك ومتاحة في كل الباقات. ويُحتسب الاستدعاء مرة واحدة في حدّ التدفق مهما كان حجمه.
أكثر من 1,000 عنصر يُرجع الخطأ 132 (too_many_feedback_items)، وغياب items أو كونها فارغة يُرجع 131 (invalid_feedback)، مع HTTP 200.
وضع الاختبار يتحقق من كل عنصر ولا يحفظ شيئاً.

الطلب#

POST https://gurdx.cretip.com/api/feedback/bulk

صادِق بمعامل key أو بترويسة Authorization: Bearer.
مجانية — لا تُحتسب من حصتك.
متاحة في: تجربة مجانية القياسية المميّزة الدفع حسب الاستخدام

المعاملات#

الاسم	النوع	الوصف
`items` مطلوب جسم	`array`	Up to 1,000 feedback objects. Each has `kind`: `payment` (fields of Payment Outcome Feedback) or `event` (fields of Fraud Label Feedback). When `kind` is missing it is `payment` if the item has `transaction_id` or `outcome`.

تقبل كل خدمة أيضاً format, lang, mode, userID. راجع الخيارات.

أمثلة برمجية#

curl -X POST "https://gurdx.cretip.com/api/feedback/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
        {
            "kind": "payment",
            "transaction_id": "ORD-10492",
            "outcome": "approved"
        },
        {
            "kind": "payment",
            "transaction_id": "ORD-9921",
            "outcome": "chargeback",
            "reason": "fraudulent"
        },
        {
            "kind": "event",
            "type": "ip",
            "value": "203.0.113.42",
            "label": "fraud"
        }
    ]
}'

<?php

$payload = [
    'items' => [
        [
            'kind' => 'payment',
            'transaction_id' => 'ORD-10492',
            'outcome' => 'approved',
        ],
        [
            'kind' => 'payment',
            'transaction_id' => 'ORD-9921',
            'outcome' => 'chargeback',
            'reason' => 'fraudulent',
        ],
        [
            'kind' => 'event',
            'type' => 'ip',
            'value' => '203.0.113.42',
            'label' => 'fraud',
        ],
    ],
];

$ch = curl_init('https://gurdx.cretip.com/api/feedback/bulk');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$result = json_decode(curl_exec($ch), true);

if ($result['status'] !== 'success') {
    error_log($result['code'].': '.$result['description']);
}

const res = await fetch('https://gurdx.cretip.com/api/feedback/bulk', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "items": [
        {
            "kind": "payment",
            "transaction_id": "ORD-10492",
            "outcome": "approved"
        },
        {
            "kind": "payment",
            "transaction_id": "ORD-9921",
            "outcome": "chargeback",
            "reason": "fraudulent"
        },
        {
            "kind": "event",
            "type": "ip",
            "value": "203.0.113.42",
            "label": "fraud"
        }
    ]
}),
});
const result = await res.json();

if (result.status !== 'success') {
  console.error(result.code, result.description);
}

import requests

res = requests.post(
    "https://gurdx.cretip.com/api/feedback/bulk",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "items": [
            {
                "kind": "payment",
                "transaction_id": "ORD-10492",
                "outcome": "approved",
            },
            {
                "kind": "payment",
                "transaction_id": "ORD-9921",
                "outcome": "chargeback",
                "reason": "fraudulent",
            },
            {
                "kind": "event",
                "type": "ip",
                "value": "203.0.113.42",
                "label": "fraud",
            },
        ],
    },
)
result = res.json()

if result["status"] != "success":
    print(result["code"], result["description"])

الاستجابة#

نجاح#

{
    "data": {
        "received": 3,
        "created": 2,
        "updated": 0,
        "unchanged": 1,
        "pending": 1,
        "failed": 0,
        "results": [
            {
                "index": 0,
                "kind": "payment",
                "transaction_id": "ORD-10492",
                "outcome": "approved",
                "status": "applied",
                "matched": 1,
                "label": "created"
            },
            {
                "index": 1,
                "kind": "payment",
                "transaction_id": "ORD-9921",
                "outcome": "chargeback",
                "status": "pending",
                "matched": 0,
                "label": "created"
            },
            {
                "index": 2,
                "kind": "event",
                "type": "ip",
                "value": "203.0.*.*",
                "label": "fraud",
                "status": "unchanged"
            }
        ]
    },
    "status": "success",
    "executionTime": 21
}

خطأ#

تُسلَّم الأخطاء بحالة HTTP 200 — افحص دائماً حقل status.

{
    "status": "error",
    "code": 101,
    "type": "invalid_key",
    "description": "The API Key is missing or invalid."
}

حقول الاستجابة#

الاسم	النوع	الوصف
`data.received`	`integer`	Items received.
`data.created`	`integer`	New labels.
`data.updated`	`integer`	Labels whose value changed.
`data.unchanged`	`integer`	Items identical to what Gurdx already had (safe to re-send).
`data.pending`	`integer`	Payment outcomes kept until their transaction is scored.
`data.failed`	`integer`	Items rejected; see their result.
`data.results`	`array`	One result per item, in order, with its `index`. A rejected item has `status: "error"`, `code` and `description`; the others are not affected.

وجدت خطأ؟ أخبرنا عبر صفحة التواصل. تواصل معنا