واجهة domain.latino البرمجية — وثائق المطوّرين

المصادقة

أرسل مفتاح API الخاص بك كرمز Bearer. أنشئ المفاتيح وأدِرها من إعدادات حسابك — يُعرض المفتاح الكامل مرة واحدة فقط عند الإنشاء، لذا احفظه في مكان آمن.

Authorization: Bearer dpk_live_<selector>_<secret>

تبدو المفاتيح على هذا النحو dpk_<env>_<selector>_<secret>، حيث env هو live أو test.

يمكن لجلسة متصفّح مسجّلة الدخول استدعاء نقاط النهاية نفسها؛ لكن عمليات الكتابة المُصادَق عليها عبر الجلسة تتطلّب إضافةً ترويسة X-CSRF-Token. أمّا طلبات رمز Bearer فلا تتطلّبها.

النطاقات وحدود المعدّل

يحمل كل مفتاح مجموعة من النطاقات. يجب إجراء الاستدعاء بمفتاح يملك نطاق نقطة النهاية. تُطبَّق حدود المعدّل لكل نطاق ولكل مفتاح.

النطاق	الصلاحيات	حدّ المعدّل	المستوى
`domain.check`	Check a single .pay domain — availability + pricing	50/sec	عام
`catalog.search`	AI keyword search against the curated catalog	30/min	عام
`orders.read`	List + read the account's own orders	60/min	عام
`orders.write`	Create a pre-order against a saved payment method	10/min	عام
`payment_methods.read`	List saved cards (Stripe payment methods)	20/min	عام
`payment_methods.write`	Add (SetupIntent) + remove saved cards	20/min	عام
`account.read`	Read account profile: email, role, vip_tier, granted scopes	60/min	عام
`webhooks.read`	List configured webhook endpoints	20/min	عام
`webhooks.write`	Create + delete webhook endpoints	10/min	عام
`zone_file.download`	Download the full daily .pay DNS zone-file snapshot	24/day	مقيَّد
`premium.list`	Paginated registry premium catalogue (incl. reserved/blocked)	60/min	مقيَّد
`registered.list`	Paginated registered .pay names (from the DNS zone file) + AI brand context	60/min	مقيَّد

النطاقات المقيَّدة محميّة بطبقتين: قد يُدرِج المفتاح النطاق، لكن الاستدعاءات لا تنجح إلّا بعد أن يمنحه أحد المشرفين لحسابك. قدّم الطلب من إعدادات حسابك.

نطاقات المجال المدعومة

حساب واحد ومفتاح API واحد يعملان في جميع النطاقات أدناه — عنوان URL الأساسي الذي تستدعيه يحدد النطاق.

`.pay`	`https://domain.pay/api/v1`
`.latino`	`https://domain.latino/api/v1`
`.dot`	`https://domain.dot/api/v1`

البدء السريع

استدعاءان سريعان للبدء:

# تحقّق من اسم
curl -s https://domain.latino/api/v1/check-domain \
  -H "Authorization: Bearer dpk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"domain":"acme.latino"}'

# من أنا + ما الذي يمكنني فعله
curl -s https://domain.latino/api/v1/account \
  -H "Authorization: Bearer dpk_live_…"

نقاط النهاية

جميع نقاط النهاية فعّالة. مخطّطات الطلب والاستجابة والمعاملات ورموز الحالة موصوفة بالكامل في مستند OpenAPI.

Account

GET /account account.read Your profile + the scopes effective for this key.

Domains

POST /check-domain domain.check Availability + pricing for one name in a supported zone. Fast DB-only lookup (no live registry call) — POST /orders re-verifies live.

Catalog

POST /catalog/search catalog.search Keyword search over the curated catalogue.

Orders

GET	`/orders`	`orders.read`	List your orders, newest first.
GET	`/orders/{id}`	`orders.read`	One order + its customer message thread.
POST	`/orders`	`orders.write`	Create a pre-order + charge a saved card (send an Idempotency-Key).

Payment methods

GET	`/account/payment-methods`	`payment_methods.read`	List saved cards.
POST	`/account/payment-methods`	`payment_methods.write`	Start a Stripe SetupIntent to add a card.
DELETE	`/account/payment-methods/{id}`	`payment_methods.write`	Remove a saved card.

Webhooks

GET	`/webhooks`	`webhooks.read`	List webhook endpoints.
POST	`/webhooks`	`webhooks.write`	Register an endpoint (signing secret shown once).
DELETE	`/webhooks/{id}`	`webhooks.write`	Delete an endpoint.

Restricted

GET	`/zone-file`	`zone_file.download`	Daily DNS zone-file snapshot for the zone of the host you call.
GET	`/premium`	`premium.list`	Registry premium catalogue.
GET	`/registered`	`registered.list`	Registered names in the called zone + AI brand context.

للاطّلاع على عقد الطلب/الاستجابة الكامل، استورد مواصفة OpenAPI: تنزيل OpenAPI (JSON).

خطافات الويب (Webhooks)

سجّل نقطة نهاية HTTPS وسنرسل إليك الأحداث الموقّعة فور وقوعها. يُعرض السرّ الخاص بالتوقيع مرة واحدة عند الإنشاء.

الحدث	الوصف
`order.created`	A new order (pre-order) was created on the account
`order.status_changed`	An order changed payment status
`payment.succeeded`	A payment for an order succeeded
`payment.failed`	A payment for an order failed or was canceled
`payment.refunded`	A charge for an order was refunded
`appraisal.completed`	A domain appraisal for an order finished

نرسل مغلّف الحدث عبر POST بصيغة JSON:

{
  "id": "evt_…",
  "event": "payment.succeeded",
  "created": "2026-05-28T12:00:00+00:00",
  "data": { "order": { … } }
}

تحقّق من كل عملية تسليم بإعادة حساب HMAC-SHA256 على جسم الطلب الخام باستخدام سرّ التوقيع الخاص بك، ثم قارِن في زمن ثابت:

X-Domain-Pay-Signature: sha256=<HMAC_SHA256(raw_body, signing_secret)>

تُعاد محاولة الاستجابات غير 2xx (أو حالات انتهاء المهلة) بتراجع أُسّي (من دقيقة واحدة إلى 24 ساعة) حتى 6 محاولات. بعد 5 عمليات تسليم فاشلة متتالية تُعطَّل نقطة النهاية تلقائيًا ويُنبَّه مالكها.

الأخطاء

تتشارك جميع الأخطاء في بنية واحدة. يُعاد إرسال request_id في كل خطأ — اذكره في طلبات الدعم.

{ "error": "scope_required", "message": "…", "request_id": "req_ab12…", "scope": "orders.read" }

HTTP	`error`	المعنى
400	`invalid_request`	Malformed or missing parameters.
401	`unauthorized / invalid_key`	No or invalid credential.
402	`card_declined / authentication_required`	Payment failed or needs SCA.
403	`scope_required`	The key lacks the endpoint's scope.
403	`access_not_granted`	Restricted scope not yet approved for this account.
403	`csrf_required`	Session write without a valid X-CSRF-Token.
404	`not_found`	No such endpoint or resource.
405	`method_not_allowed`	Wrong HTTP verb.
409	`request_in_progress`	An idempotency key's first request is still in flight.
422	`idempotency_key_reused`	Same idempotency key, different parameters.
422	`contact_incomplete`	GA zones: add a registrant contact under /account/contacts first.
423	`account_locked`	Account is locked — contact support.
429	`rate_limited`	Slow down; see the Retry-After header.
500	`server_error`	Our fault.

الوصول المقيَّد

تتطلّب نقاط نهاية ملف المنطقة (zone-file) والنطاقات المميّزة والمسجّلة صلاحيةً معتمَدة إضافةً إلى النطاق:

أنشئ (أو احصل مسبقًا على) مفتاح API يُدرِج النطاق المقيَّد.
في إعدادات حسابك، افتح "الوصول المقيَّد إلى API"، واختر النطاق، واشرح كيف ستستخدم البيانات.
يراجع فريقنا الطلب ويرسل إليك القرار عبر البريد الإلكتروني.
بعد الموافقة، يمكن لأي مفتاح في حسابك يُدرِج ذلك النطاق استخدامه فورًا. لا يوجد مستوى مدفوع — الموافقة على مستوى الحساب.

الحساب

اللغة

السمة

domain.latino API