نقطة نهاية لفتح جلسة 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)
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
atmId | string | شرطي | قناة/ATM (A-Z0-9_-). إذا لم تُرسَل وكان هناك ATM_DEFAULT في الإعدادات فسيُستخدم. |
reference | string | اختياري | مرجع حر (order_id، user_id، …). |
المصادقة
Authorization: Bearer <API_KEY>Authorization: ApiKey <API_KEY>X-API-Key: <API_KEY>
مفتاح الـ API أبجدي رقمي (مع شرطات) بطول ≥36. احفظ المفاتيح في الخلفية فقط.
الأخطاء
| HTTP | الخطأ | تعليق |
|---|---|---|
| 201 | (ok) | تم إنشاء الجلسة، وتم خصم الأرصدة. |
| 400 | INVALID_BODY | JSON غير صالح. |
| 400 | ATM_NOT_PROVIDED | قيمة atmId مفقودة ولا يوجد ATM_DEFAULT مُعرَّف. |
| 401 | UNAUTHORIZED | مفتاح الـ API مفقود أو غير صالح. |
| 402 | INSUFFICIENT_CREDITS | رصيد غير كافٍ (يتضمن required/available). |
| 403 | FORBIDDEN | الخدمة/العقد مُعلّق. |
| 403 | SERVICE_DISABLED | الخدمة غير مفعّلة. |
| 404 | SERVICE_NOT_FOUND | خدمة العقد غير موجودة. |
| 404 | COMPANY_NOT_FOUND | الشركة غير موجودة. |
| 405 | METHOD_NOT_ALLOWED | يجب أن يكون الطلب POST. |
| 500 | SERVER_ERROR | خطأ داخلي (رسالة معلوماتية). |
| 500 | CONFIG_NOT_FOUND | تعذّر تحميل الإعدادات. |
API para KYC
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>:
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"
}'
Probar con Insomnia
En Insomnia, crea una petición POST y usa Auth → Bearer Token con tu clave:
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"
}'
📱 التكامل في التطبيقات الأصلية (iOS/Android)
إذا كنت تقوم بتحميل نموذج KYC داخل تطبيق أصلي عبر WebView، يجب عليك تكوين تشغيل الفيديو المضمّن. بدون هذا التكوين، سيفتح فيديو الكاميرا في وضع ملء الشاشة وستختفي العناصر المتراكبة (الإطار، الأزرار، العد التنازلي).
Express:
allowsInlineMediaPlayback={true}
mediaPlaybackRequiresUserAction={false}
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" />
ممارسات مُوصى بها
- Idempotency: أعد استخدام قيمة reference لتجنّب التكرار عند إعادة المحاولة.
- الأمان: احفظ مفتاح الـ API على الخادم فقط (أبدًا في تطبيقات العميل).
- Backoff: عند 402/403/5xx أعد المحاولة بتدرّجٍ زمني (exponential backoff).