مستندات فنی

راهنمای جامع API

این مستندات به شما کمک می‌کند تا با سرویس‌های مدیریت مخاطبین (Contacts) و رویدادها (Events) به سادگی کار کنید. در ادامه، نحوه احراز هویت، ساختار درخواست‌ها و نمونه کدهای کاربردی را بررسی خواهیم کرد.

احراز هویت (Authentication)

برای تمام درخواست‌ها به API، لازم است توکن دسترسی خود را در هدر `Authorization` به صورت `Bearer Token` ارسال کنید. همچنین هدر `Accept` باید روی `application/json` تنظیم شود.

Headers

Authorization: Bearer <YOUR_ACCESS_TOKEN>
Accept: application/json
Content-Type: application/json

Base URL

برای استفاده از تمام متدهای زیر، آدرس پایه (Base URL) را به صورت زیر در نظر بگیرید:

Base URL

https://marketing.technorah.com

برای نمونه، اگر در مستندات ذکر شده است /api/v1/contact/store، باید آدرس نهایی را به‌صورت زیر صدا بزنید:

Example

https://marketing.technorah.com/api/v1/contact/store

بخش مخاطبین (Contacts)

این مجموعه از APIها به شما امکان مدیریت کامل مخاطبین را می‌دهد.

ایجاد مخاطب جدید

POST /api/contact/store

برای ایجاد یک مخاطب جدید، ارسال حداقل یکی از فیلدهای `phone` یا `email` الزامی است.

پارامترهای Body:

پارامتر	نوع	توضیحات
external_id	string \| nullable	شناسه خارجی (اختیاری و یکتا برای هر کاربر)
name	string \| nullable	نام کامل مخاطب
phone	string \| nullable	شماره تماس (در صورت نبود ایمیل، الزامی)
email	string \| nullable	آدرس ایمیل (در صورت نبود شماره تماس، الزامی)
meta	object \| nullable	مجموعه‌ای از داده‌های کلید-مقدار (مانند `{"city": "Tehran"}`)

PHP Example: Create Contact

Http::withToken('YOUR_TOKEN')->post('/api/contact/store', [
                        'name' => 'سعید جلالی',
                        'phone' => '09120000000',
                        'external_id' => 'user-123',
                        'meta' => [
                        'city' => 'Tehran',
                        'plan' => 'premium'
                        ]
                        ]);

JavaScript Example: Create Contact

fetch('/api/contact/store', {
                        method: 'POST',
                        headers: {
                        'Authorization': 'Bearer YOUR_TOKEN',
                        'Content-Type': 'application/json',
                        'Accept': 'application/json'
                        },
                        body: JSON.stringify({
                        name: 'سعید جلالی',
                        phone: '09120000000',
                        meta: { city: 'Tehran' }
                        })
                        });

Python Example: Create Contact

import requests
                        headers = {'Authorization': 'Bearer YOUR_TOKEN'}
                        payload = {
                        'name': 'سعید جلالی',
                        'phone': '09120000000',
                        'meta': {'city': 'Tehran'}
                        }
                        requests.post('/api/contact/store', json=payload, headers=headers)

سایر متدها

برای مشاهده، ویرایش و حذف مخاطب می‌توانید از شناسه‌ی `uuid` یا `external_id` در آدرس URL استفاده کنید.

GET/api/contact/show/{identifier}
PATCH/api/contact/update/{identifier}
DELETE/api/contact/delete/{identifier}

بخش رویدادها (Events)

از این APIها برای ثبت رویدادهای مختلف مرتبط با مخاطبین استفاده کنید.

ایجاد رویداد جدید

POST /api/event/store

برای ثبت یک رویداد، باید شناسه مخاطب (`contact_id`) و نام رویداد (`name`) را ارسال کنید. `contact_id` می‌تواند `uuid` یا `external_id` مخاطب باشد.

پارامترهای Body:

پارامتر	نوع	توضیحات
contact_id	string \| required	شناسه `uuid` یا `external_id` مخاطب
name	string \| required	نام رویداد (فقط حروف انگلیسی و خط تیره)
meta	object \| nullable	داده‌های اضافی مرتبط با رویداد
occurred_at	datetime \| nullable	زمان دقیق وقوع رویداد (پیش‌فرض: اکنون)

JavaScript Example: Create Event

Http::withToken('YOUR_TOKEN')->post('/api/event/store', [
                        'contact_id' => 'uuid-or-external-id-of-contact',
                        'name' => 'product-viewed',
                        'meta' => [
                        'product_id' => 'P-54321',
                        'product_name' => 'کفش ورزشی نایکی'
                        ]
                        ]);

سایر متدها

برای مشاهده، ویرایش و حذف رویداد باید از `uuid` خود رویداد استفاده کنید.

GET/api/event/show/{event_uuid}
PATCH/api/event/update/{event_uuid}
DELETE/api/event/delete/{event_uuid}