FACEKYC API — إنشاء الجلسات

نقطة نهاية لفتح جلسة KYC/KYB والحصول على روابط بدء التدفق.

POST https://api.facekyc.com/v1/orderrequest.php Auth: Bearer / ApiKey / X-API-Key Content-Type: application/json

نقطة نهاية لفتح جلسة KYC/KYB والحصول على روابط بدء التدفق.

API para Cajeros y Control de Accesos

Para los cajeros y control de accesos, utiliza la siguiente API:

curl -X POST "https://api.facekyc.com/v1/orderrequest.php" \
  -H "Authorization: Bearer fk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "atmId": "ES_ONLINE",
        "reference": "order_123"
      }'
// JavaScript (fetch)
const res = await fetch("https://api.facekyc.com/v1/orderrequest.php", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    atmId: "ES_ONLINE",
    reference: "order_123"
  })
});
const data = await res.json();
console.log("session:", data.session_id, "pwa:", data.pwa_url);
<?php
// PHP with GuzzleHttp
require __DIR__."/vendor/autoload.php";
use GuzzleHttp\Client;

$client = new Client(["base_uri" => "https://api.facekyc.com"]);

try {
  $r = $client->post("/v1/orderrequest.php", [
    "headers" => ["Authorization" => "Bearer fk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"],
    "json"    => ["atmId" => "ES_ONLINE", "reference" => "order_123"],
    "http_errors" => false
  ]);
  $status = $r->getStatusCode();
  $body   = json_decode((string)$r->getBody(), true);
  var_dump($status, $body);
} catch (\Throwable $e) {
  echo "Error: ".$e->getMessage();
}

Respuesta de ejemplo

{
  "ok": true,
  "session_id": "6a6b0d78e6c84e8490b3f1c2f6a1b2cd",
  "status": "pending",
  "atm_id": "ES_ONLINE",
  "atm_url": "https://api.facekyc.com/atm/start_session.php?session=...&atmId=ES_ONLINE",
  "pwa_url": "https://api.facekyc.com/pwa/?session=...&atmId=ES_ONLINE",
  "service": { "id": 12, "name": "CONTROL DE ACCESOS", "price": 1.0, "cost_units": 1 },
  "contract": { "contrato_id": 345, "empresa_id": 78 },
  "credits": { "debited": 1, "remaining": 149 },
  "reference": "order_123",
  "filled_meta": true
}

محتوى الطلب (JSON)

الحقل النوع مطلوب الوصف
atmIdstringشرطي قناة/ATM (A-Z0-9_-). إذا لم تُرسَل وكان هناك ATM_DEFAULT في الإعدادات فسيُستخدم.
referencestringاختياري مرجع حر (order_id، user_id، …).

المصادقة

  • Authorization: Bearer <API_KEY>
  • Authorization: ApiKey <API_KEY>
  • X-API-Key: <API_KEY>

مفتاح الـ API أبجدي رقمي (مع شرطات) بطول ≥36. احفظ المفاتيح في الخلفية فقط.

الأخطاء

HTTPالخطأتعليق
201(ok)تم إنشاء الجلسة، وتم خصم الأرصدة.
400INVALID_BODYJSON غير صالح.
400ATM_NOT_PROVIDEDقيمة atmId مفقودة ولا يوجد ATM_DEFAULT مُعرَّف.
401UNAUTHORIZEDمفتاح الـ API مفقود أو غير صالح.
402INSUFFICIENT_CREDITSرصيد غير كافٍ (يتضمن required/available).
403FORBIDDENالخدمة/العقد مُعلّق.
403SERVICE_DISABLEDالخدمة غير مفعّلة.
404SERVICE_NOT_FOUNDخدمة العقد غير موجودة.
404COMPANY_NOT_FOUNDالشركة غير موجودة.
405METHOD_NOT_ALLOWEDيجب أن يكون الطلب POST.
500SERVER_ERRORخطأ داخلي (رسالة معلوماتية).
500CONFIG_NOT_FOUNDتعذّر تحميل الإعدادات.

API para KYC

POST https://api.facekyc.com/v1/orderkyc.php Auth: Bearer / ApiKey / X-API-Key Content-Type: application/json

Para KYC, utiliza la siguiente API:

curl -X POST "https://api.facekyc.com/v1/orderkyc.php" \
  -H "Authorization: Bearer fk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "user_id": "user_123",
        "document_type": "DNI",
        "document_number": "12345678Z"
      }'

Probar con Postman

Puedes probar ambos endpoints con Postman. Crea una petición POST y usa Bearer <API_KEY>:

POST https://api.facekyc.com/v1/orderrequest.php (Cajeros / Control) POST https://api.facekyc.com/v1/orderkyc.php (KYC)

1) Cajeros / Control de Accesos

  • Auth: Bearer <API_KEY>
  • Headers: Content-Type: application/json
  • Body (JSON): {"atmId":"ES_ONLINE","reference":"order_123"}
curl -X POST "https://api.facekyc.com/v1/orderrequest.php" \
  -H "Authorization: Bearer fk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "atmId": "ES_ONLINE",
        "reference": "order_123"
      }'

2) KYC

  • Auth: Bearer <API_KEY>
  • Headers: Content-Type: application/json
  • Body (JSON): {"user_id":"user_123","document_type":"DNI","document_number":"12345678Z"}
curl -X POST "https://api.facekyc.com/v1/orderkyc.php" \
  -H "Authorization: Bearer fk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "user_id": "user_123",
        "document_type": "DNI",
        "document_number": "12345678Z"
      }'

Abrir Postman

Probar con Insomnia

En Insomnia, crea una petición POST y usa Auth → Bearer Token con tu clave:

POST https://api.facekyc.com/v1/orderrequest.php (Cajeros / Control) POST https://api.facekyc.com/v1/orderkyc.php (KYC)

1) Cajeros / Control de Accesos

  • Auth: Bearer <API_KEY> (tab “Auth” → “Bearer Token”)
  • Headers: Content-Type: application/json
  • Body (JSON): {"atmId":"ES_ONLINE","reference":"order_123"}
curl -X POST "https://api.facekyc.com/v1/orderrequest.php" \
  -H "Authorization: Bearer fk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "atmId": "ES_ONLINE",
        "reference": "order_123"
      }'

2) KYC

  • Auth: Bearer <API_KEY>
  • Headers: Content-Type: application/json
  • Body (JSON): {"user_id":"user_123","document_type":"DNI","document_number":"12345678Z"}
curl -X POST "https://api.facekyc.com/v1/orderkyc.php" \
  -H "Authorization: Bearer fk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "user_id": "user_123",
        "document_type": "DNI",
        "document_number": "12345678Z"
      }'

Abrir Insomnia

📱 التكامل في التطبيقات الأصلية (iOS/Android)

إذا كنت تقوم بتحميل نموذج KYC داخل تطبيق أصلي عبر WebView، يجب عليك تكوين تشغيل الفيديو المضمّن. بدون هذا التكوين، سيفتح فيديو الكاميرا في وضع ملء الشاشة وستختفي العناصر المتراكبة (الإطار، الأزرار، العد التنازلي).

Express:
allowsInlineMediaPlayback={true}
mediaPlaybackRequiresUserAction={false}

⚠️ مهم: يجب تطبيق هذه التكوينات قبل إنشاء WebView. إذا لم يتم تكوينها، ستكون تجربة المستخدم غير صحيحة على iOS.

iOS - Swift (WKWebView)

قم بتكوين WKWebViewConfiguration قبل إنشاء WebView:

import WebKit

// 1. Crear configuración ANTES del WebView
let config = WKWebViewConfiguration()
config.allowsInlineMediaPlayback = true
config.mediaTypesRequiringUserActionForPlayback = []
config.allowsPictureInPictureMediaPlayback = false

// 2. Crear WebView con la configuración
let webView = WKWebView(frame: .zero, configuration: config)

// 3. Cargar la URL del KYC
let url = URL(string: "https://api.facekyc.com/pwa/kyc_form.php?session=xxx&atmId=xxx")!
webView.load(URLRequest(url: url))

iOS - React Native (WebView)

استخدم الخصائص المطلوبة في مكون WebView:

import { WebView } from 'react-native-webview';

<WebView
  source={{ 
    uri: 'https://api.facekyc.com/pwa/kyc_form.php?session=xxx&atmId=xxx' 
  }}
  allowsInlineMediaPlayback={true}
  mediaPlaybackRequiresUserAction={false}
  allowsFullscreenVideo={false}
  javaScriptEnabled={true}
  domStorageEnabled={true}
  onPermissionRequest={(request) => {
    if (request.resources.includes('camera')) {
      request.grant();
    }
  }}
/>

Android - Kotlin/Java (WebView)

قم بتكوين WebSettings و WebChromeClient:

import android.webkit.WebView
import android.webkit.WebSettings
import android.webkit.WebChromeClient
import android.webkit.PermissionRequest

// Configurar WebSettings
val webView = findViewById<WebView>(R.id.webview)
val webSettings = webView.settings

webSettings.javaScriptEnabled = true
webSettings.domStorageEnabled = true
webSettings.mediaPlaybackRequiresUserGesture = false

// Gestionar permisos de cámara
webView.webChromeClient = object : WebChromeClient() {
    override fun onPermissionRequest(request: PermissionRequest) {
        request.grant(request.resources)
    }
}

// Cargar URL
webView.loadUrl("https://api.facekyc.com/pwa/kyc_form.php?session=xxx&atmId=xxx")

التكوينات المطلوبة

المنصة الخاصية الوصف
iOS allowsInlineMediaPlayback يسمح بتشغيل الفيديو مضمّنًا بدلاً من ملء الشاشة
iOS mediaTypesRequiringUserActionForPlayback مصفوفة فارغة تسمح بالتشغيل التلقائي دون لمس الشاشة
iOS allowsPictureInPictureMediaPlayback تعطيل صورة في صورة لتجنب التعارضات
Android mediaPlaybackRequiresUserGesture False يسمح للكاميرا بالبدء تلقائيًا
Android WebChromeClient.onPermissionRequest يدير أذونات الكاميرا والميكروفون

الأذونات المطلوبة

iOS - Info.plist:

<key>NSCameraUsageDescription</key>
<string>Necesitamos acceso a la cámara para verificación de identidad KYC</string>

<key>NSMicrophoneUsageDescription</key>
<string>Necesitamos acceso al micrófono para grabación de vídeo KYC</string>

Android - AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />

<uses-feature android:name="android.hardware.camera" android:required="true" />
<uses-feature android:name="android.hardware.camera.autofocus" />
💡 نصيحة: اختبر التكامل بجهاز فعلي، وليس بالمحاكيات. محاكيات iOS لا تحتوي على كاميرا حقيقية وقد تتصرف بشكل مختلف.

ممارسات مُوصى بها

  • Idempotency: أعد استخدام قيمة reference لتجنّب التكرار عند إعادة المحاولة.
  • الأمان: احفظ مفتاح الـ API على الخادم فقط (أبدًا في تطبيقات العميل).
  • Backoff: عند 402/403/5xx أعد المحاولة بتدرّجٍ زمني (exponential backoff).