تکنوراه

راهنمای جامع 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}

بخش محصولات (Products)

این مجموعه از APIها به شما امکان مدیریت محصولات، نسخه‌ها و دسته‌بندی‌های آن‌ها را به صورت یکپارچه می‌دهد.

ایجاد دسته‌ای محصولات، نسخه‌ها و دسته‌بندی‌ها

POST /api/v1/product/bulk-store

با استفاده از این متد می‌توانید چندین محصول را به همراه نسخه‌ها و دسته‌بندی‌های مربوطه در قالب یک درخواست ارسال کنید. دسته‌بندی‌ها به صورت خودکار شناسایی یا ایجاد می‌شوند.

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

پارامتر نوع توضیحات
products array | required لیست محصولاتی که می‌خواهید ایجاد کنید

جزئیات محصول (در آرایه products):

پارامتر نوع توضیحات
title string | required عنوان محصول
category_title string | nullable نام دسته‌بندی (اگر وجود نداشته باشد، ساخته می‌شود)
invoice_title string | nullable عنوان محصول در فاکتور
code string | nullable کد محصول (SKU)
unit string | nullable واحد اندازه‌گیری (مثلاً: عدد، کیلوگرم)
price numeric | nullable قیمت واحد محصول
is_active boolean | nullable وضعیت فعال بودن (پیش‌فرض: true)
description string | nullable توضیحات محصول
variants array | nullable لیست نسخه‌های محصول (مانند رنگ، سایز و ...)
PHP Example: Bulk Store Products 
Http::withToken('YOUR_TOKEN')->post('/api/v1/product/bulk-store', [
                            'products' => [
                                [
                                    'title' => 'گوشی آیفون 15',
                                    'category_title' => 'موبایل',
                                    'price' => 50000000,
                                    'variants' => [
                                        ['name' => '128 گیگابایت', 'price' => 51000000, 'code' => 'IPH15-128']
                                    ]
                                ]
                            ]
                        ]);
JavaScript Example: Bulk Store Products 
fetch('/api/v1/product/bulk-store', {
                            method: 'POST',
                            headers: {
                                'Authorization': 'Bearer YOUR_TOKEN',
                                'Content-Type': 'application/json'
                            },
                            body: JSON.stringify({
                                products: [
                                    {
                                        title: 'گوشی آیفون 15',
                                        category_title: 'موبایل',
                                        price: 50000000
                                    }
                                ]
                            })
                        });

سایر متدها

برای مشاهده، ویرایش و حذف محصول می‌توانید از شناسه `id` یا کد محصول `code` در آدرس URL استفاده کنید.

  • GET /api/v1/product/show/{identifier}
  • PATCH /api/v1/product/update/{identifier}
  • DELETE /api/v1/product/delete/{identifier}

نکات ویرایش (Update):

در هنگام ویرایش، تنها فیلدهایی که ارسال می‌شوند بروزرسانی خواهند شد. ارسال آرایه `variants` باعث جایگزینی نسخه‌های قبلی با نسخه‌های جدید می‌شود.

بخش معاملات (Deals)

این مجموعه از APIها به شما امکان ایجاد، مشاهده و ویرایش معاملات را می‌دهد. در صورت عدم تعیین کارشناس مسئول، سیستم به صورت خودکار بر اساس ضریب کارشناسان قیف و سابقه مخاطب، کارشناس مناسب را اختصاص می‌دهد.

ایجاد معامله جدید

POST /api/v1/deal/store

برای ایجاد یک معامله، ارسال فیلدهای name، pipeline_id و amount الزامی است. برای مشخص کردن مخاطب معامله، می‌توانید از contact_id یا یکی از فیلدهای contact_phone، contact_email یا contact_external_id استفاده کنید. در صورت عدم ارسال member_id، کارشناس به صورت خودکار تعیین می‌شود.

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

پارامتر نوع توضیحات
name string نام معامله (الزامی)
contact_id integer | nullable شناسه مخاطب؛ در صورت عدم ارسال، باید یکی از فیلدهای شناسایی دیگر ارسال شود.
contact_phone string | nullable شماره تلفن مخاطب جهت شناسایی و اتصال به معامله
contact_email string | nullable ایمیل مخاطب جهت شناسایی و اتصال به معامله
contact_external_id string | nullable شناسه خارجی مخاطب جهت شناسایی و اتصال به معامله
pipeline_id integer شناسه قیف فروش (الزامی)
amount number مبلغ معامله (الزامی، حداقل ۰)
member_id integer | nullable شناسه کارشناس مسئول؛ در صورت عدم ارسال، تخصیص خودکار انجام می‌شود
status integer | nullable وضعیت: ۱=باز، ۲=موفق، ۳=ناموفق (پیش‌فرض: ۱)
currency integer | nullable واحد پول: ۱=ریال، ۲=دلار، ۳=یورو (پیش‌فرض: ۱)
description string | nullable توضیحات معامله
expected_close_date date | nullable تاریخ پیش‌بینی بسته شدن (مثال: 2025-03-15)
PHP Example: Create Deal 
Http::withToken('YOUR_TOKEN')->post('/api/v1/deal/store', [
    'name' => 'فروش پکیج سازمانی',
    'contact_id' => 1,
    'pipeline_id' => 1,
    'amount' => 50000000,
    'description' => 'معامله تست'
]);
JavaScript Example: Create Deal 
fetch('/api/v1/deal/store', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    },
    body: JSON.stringify({
        name: 'فروش پکیج سازمانی',
        contact_id: 1,
        pipeline_id: 1,
        amount: 50000000
    })
});
Python Example: Create Deal 
import requests
headers = {'Authorization': 'Bearer YOUR_TOKEN'}
payload = {
    'name': 'فروش پکیج سازمانی',
    'contact_id': 1,
    'pipeline_id': 1,
    'amount': 50000000
}
requests.post('/api/v1/deal/store', json=payload, headers=headers)

سایر متدها

برای مشاهده و ویرایش معامله از شناسه عددی معامله در آدرس URL استفاده کنید.

  • GET /api/v1/deal/show/{deal_id} — مشاهده جزئیات معامله
  • PATCH /api/v1/deal/update/{deal_id} — ویرایش معامله