{
 "openapi": "3.0.3",
 "info": {
  "title": "Monshiva Public API",
  "version": "1.4.0",
  "description": "API عمومی منشیوا: تماس‌ها، مشتریان، نوبت‌ها، پیگیری‌ها، سرنخ و وب‌هوک.\n\nاحراز هویت با کلید `msk_live_…` از پنل ← «ابزارها و اتصال‌ها» ← API. محدودیت: ۶۰ درخواست در دقیقه و ۵٬۰۰۰ در روز برای هر کلید. همهٔ زمان‌ها به وقت تهران (Asia/Tehran). راهنمای کامل: https://monshiva.com/docs/api/",
  "contact": {
   "name": "Monshiva",
   "url": "https://monshiva.com/docs/api/"
  }
 },
 "servers": [
  {
   "url": "https://monshiva.com/api/public/v1"
  }
 ],
 "security": [
  {
   "bearerAuth": []
  }
 ],
 "tags": [
  {
   "name": "حساب"
  },
  {
   "name": "تماس‌ها"
  },
  {
   "name": "مشتریان"
  },
  {
   "name": "نوبت‌ها"
  },
  {
   "name": "پیگیری‌ها"
  },
  {
   "name": "سرنخ‌ها"
  },
  {
   "name": "سایت‌ها"
  },
  {
   "name": "وب‌هوک‌ها"
  }
 ],
 "paths": {
  "/me": {
   "get": {
    "tags": [
     "حساب"
    ],
    "summary": "اطلاعات کلید و فضای کار",
    "operationId": "getMe",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "workspace": {
           "type": "object",
           "properties": {
            "id": {
             "type": "string"
            },
            "name": {
             "type": "string"
            },
            "industry": {
             "type": "string"
            },
            "branch": {
             "type": "object",
             "nullable": true,
             "additionalProperties": true
            }
           }
          },
          "plan": {
           "type": "string",
           "nullable": true
          },
          "key": {
           "type": "object",
           "properties": {
            "id": {
             "type": "string"
            },
            "name": {
             "type": "string"
            },
            "scopes": {
             "type": "array",
             "items": {
              "type": "string"
             }
            }
           }
          },
          "limits": {
           "type": "object",
           "properties": {
            "per_minute": {
             "type": "integer"
            },
            "per_day": {
             "type": "integer"
            }
           }
          },
          "version": {
           "type": "string"
          },
          "time": {
           "type": "string",
           "format": "date-time"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "read",
    "description": "دسترسی لازم: `read`"
   }
  },
  "/calls": {
   "get": {
    "tags": [
     "تماس‌ها"
    ],
    "summary": "فهرست تماس‌های واقعی مشتریان (تازه‌ترین اول، ۲۰ در هر صفحه)",
    "operationId": "listCalls",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "calls": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Call"
           }
          },
          "page": {
           "type": "integer"
          },
          "limit": {
           "type": "integer"
          },
          "has_more": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "ورودی نامعتبر (فیلد در error.field)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "موتور مکالمه یا CRM موقتاً در دسترس نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "read",
    "description": "دسترسی لازم: `read`",
    "parameters": [
     {
      "name": "page",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50,
       "default": 1
      },
      "description": "شمارهٔ صفحه"
     },
     {
      "name": "status",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "all",
        "completed",
        "incomplete"
       ],
       "default": "all"
      },
      "description": "وضعیت"
     }
    ]
   }
  },
  "/calls/{call_id}": {
   "get": {
    "tags": [
     "تماس‌ها"
    ],
    "summary": "جزئیات یک تماس",
    "operationId": "getCall",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "call": {
           "$ref": "#/components/schemas/Call"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "پیدا نشد",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "موتور مکالمه یا CRM موقتاً در دسترس نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "read",
    "description": "دسترسی لازم: `read`",
    "parameters": [
     {
      "name": "call_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 1
      },
      "description": "شناسهٔ تماس"
     }
    ]
   }
  },
  "/contacts": {
   "get": {
    "tags": [
     "مشتریان"
    ],
    "summary": "جستجو و فهرست مشتریان (۲۵ در هر صفحه)",
    "operationId": "listContacts",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "contacts": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Contact"
           }
          },
          "page": {
           "type": "integer"
          },
          "limit": {
           "type": "integer"
          },
          "total": {
           "type": "integer"
          },
          "stages": {
           "type": "object",
           "additionalProperties": {
            "type": "string"
           },
           "description": "کلید مرحله ← عنوان فارسی"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "ورودی نامعتبر (فیلد در error.field)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "موتور مکالمه یا CRM موقتاً در دسترس نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "read",
    "description": "دسترسی لازم: `read`",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "maxLength": 80
      },
      "description": "نام یا شماره"
     },
     {
      "name": "page",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "default": 1
      },
      "description": "صفحه"
     },
     {
      "name": "stage",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "all",
        "new",
        "qualified",
        "consultation",
        "proposal",
        "won",
        "closed"
       ],
       "default": "all"
      },
      "description": "مرحلهٔ فروش"
     }
    ]
   }
  },
  "/contacts/{contact_id}": {
   "get": {
    "tags": [
     "مشتریان"
    ],
    "summary": "پروندهٔ یک مشتری با تماس‌ها، نوبت‌ها و پیگیری‌ها",
    "operationId": "getContact",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "contact": {
           "$ref": "#/components/schemas/Contact"
          },
          "activities": {
           "type": "object",
           "properties": {
            "calls": {
             "type": "array",
             "items": {
              "type": "object",
              "additionalProperties": true
             }
            },
            "bookings": {
             "type": "array",
             "items": {
              "type": "object",
              "additionalProperties": true
             }
            },
            "tasks": {
             "type": "array",
             "items": {
              "type": "object",
              "additionalProperties": true
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "پیدا نشد",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "موتور مکالمه یا CRM موقتاً در دسترس نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "read",
    "description": "دسترسی لازم: `read`",
    "parameters": [
     {
      "name": "contact_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^[a-zA-Z0-9]{10,32}$"
      },
      "description": "شناسهٔ مشتری"
     }
    ]
   }
  },
  "/bookings": {
   "get": {
    "tags": [
     "نوبت‌ها"
    ],
    "summary": "فهرست نوبت‌ها",
    "operationId": "listBookings",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "bookings": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Booking"
           }
          },
          "timezone": {
           "type": "string",
           "example": "Asia/Tehran"
          },
          "duration_minutes": {
           "type": "integer",
           "nullable": true
          },
          "today": {
           "type": "string",
           "nullable": true
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "ورودی نامعتبر (فیلد در error.field)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "موتور مکالمه یا CRM موقتاً در دسترس نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "read",
    "description": "دسترسی لازم: `read`",
    "parameters": [
     {
      "name": "date_from",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
       "example": "2026-12-01"
      },
      "description": "از تاریخ (میلادی)"
     },
     {
      "name": "date_to",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
       "example": "2026-12-01"
      },
      "description": "تا تاریخ"
     },
     {
      "name": "status",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "مثلاً confirmed"
     }
    ]
   },
   "post": {
    "tags": [
     "نوبت‌ها"
    ],
    "summary": "ثبت نوبت برای یک تماس تکمیل‌شده",
    "operationId": "createBooking",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true,
         "properties": {
          "booking": {
           "$ref": "#/components/schemas/Booking"
          },
          "duplicate": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "بدنهٔ نامعتبر",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "ورودی نامعتبر (فیلد در error.field)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "موتور مکالمه یا CRM موقتاً در دسترس نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "bookings:write",
    "description": "در نسخهٔ ۱ ثبت نوبت فقط با `call_id` یک تماس تکمیل‌شده ممکن است. زمان‌ها به وقت تهران.\n\nدسترسی لازم: `bookings:write`",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "call_id": {
          "type": "integer"
         },
         "date": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "example": "2026-12-01"
         },
         "time": {
          "type": "string",
          "pattern": "^[0-2]\\d:[0-5]\\d$",
          "example": "10:30"
         },
         "service": {
          "type": "string",
          "maxLength": 120
         },
         "advisor_id": {
          "type": "string",
          "default": "default"
         },
         "request_key": {
          "type": "string",
          "description": "کلید یکتای خودتان برای جلوگیری از ثبت تکراری"
         }
        },
        "required": [
         "call_id",
         "date",
         "time"
        ],
        "additionalProperties": false
       }
      }
     }
    }
   }
  },
  "/bookings/{booking_id}": {
   "patch": {
    "tags": [
     "نوبت‌ها"
    ],
    "summary": "جابه‌جایی یا لغو نوبت",
    "operationId": "changeBooking",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true,
         "properties": {
          "booking": {
           "$ref": "#/components/schemas/Booking"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "بدنهٔ نامعتبر",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "پیدا نشد",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "ورودی نامعتبر (فیلد در error.field)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "موتور مکالمه یا CRM موقتاً در دسترس نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "bookings:write",
    "description": "دسترسی لازم: `bookings:write`",
    "parameters": [
     {
      "name": "booking_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^VV-[A-F0-9]{10}$"
      },
      "description": "شناسهٔ نوبت"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "operation": {
          "type": "string",
          "enum": [
           "reschedule",
           "cancel"
          ]
         },
         "revision": {
          "type": "integer",
          "description": "revision فعلی نوبت (قفل خوش‌بینانه)"
         },
         "date": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "example": "2026-12-01"
         },
         "time": {
          "type": "string",
          "pattern": "^[0-2]\\d:[0-5]\\d$",
          "example": "10:30"
         },
         "reason": {
          "type": "string",
          "maxLength": 200
         },
         "request_key": {
          "type": "string"
         }
        },
        "required": [
         "operation",
         "revision"
        ],
        "additionalProperties": false
       }
      }
     }
    }
   }
  },
  "/availability": {
   "get": {
    "tags": [
     "نوبت‌ها"
    ],
    "summary": "زمان‌های آزاد یک روز",
    "operationId": "getAvailability",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "date": {
           "type": "string",
           "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
           "example": "2026-12-01"
          },
          "advisor_id": {
           "type": "string"
          },
          "slots": {
           "type": "array",
           "items": {}
          },
          "calendar": {
           "nullable": true
          },
          "timezone": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "ورودی نامعتبر (فیلد در error.field)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "موتور مکالمه یا CRM موقتاً در دسترس نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "read",
    "description": "دسترسی لازم: `read`",
    "parameters": [
     {
      "name": "date",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
       "example": "2026-12-01"
      },
      "description": "روز موردنظر"
     },
     {
      "name": "advisor_id",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "default": "default",
       "pattern": "^[A-Za-z0-9_-]{1,40}$"
      },
      "description": "شناسهٔ مشاور"
     }
    ]
   }
  },
  "/tasks": {
   "get": {
    "tags": [
     "پیگیری‌ها"
    ],
    "summary": "فهرست پیگیری‌ها (۲۵ در هر صفحه)",
    "operationId": "listTasks",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "tasks": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Task"
           }
          },
          "page": {
           "type": "integer"
          },
          "limit": {
           "type": "integer"
          },
          "total": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "ورودی نامعتبر (فیلد در error.field)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "موتور مکالمه یا CRM موقتاً در دسترس نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "read",
    "description": "دسترسی لازم: `read`",
    "parameters": [
     {
      "name": "status",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "open",
        "completed",
        "all"
       ],
       "default": "open"
      },
      "description": "وضعیت"
     },
     {
      "name": "page",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "default": 1
      },
      "description": "صفحه"
     }
    ]
   },
   "post": {
    "tags": [
     "پیگیری‌ها"
    ],
    "summary": "ساخت پیگیری برای یک مشتری",
    "operationId": "createTask",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "task": {
           "type": "object",
           "properties": {
            "id": {
             "type": "string"
            },
            "title": {
             "type": "string"
            },
            "due": {
             "type": "string",
             "format": "date-time"
            },
            "contact_id": {
             "type": "string"
            },
            "status": {
             "type": "string",
             "example": "open"
            }
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "بدنهٔ نامعتبر",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "پیدا نشد",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "ورودی نامعتبر (فیلد در error.field)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "موتور مکالمه یا CRM موقتاً در دسترس نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "tasks:write",
    "description": "دسترسی لازم: `tasks:write`",
    "parameters": [
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "contact_id": {
          "type": "string"
         },
         "title": {
          "type": "string",
          "minLength": 3,
          "maxLength": 150
         },
         "note": {
          "type": "string",
          "maxLength": 2000
         },
         "due": {
          "type": "string",
          "description": "تاریخ آینده، ISO 8601؛ بدون منطقهٔ زمانی = وقت تهران",
          "example": "2026-12-01T10:00:00"
         },
         "assignee": {
          "type": "string",
          "description": "نام یا نقش همکار (اختیاری)"
         }
        },
        "required": [
         "contact_id",
         "title",
         "due"
        ],
        "additionalProperties": false
       }
      }
     }
    }
   }
  },
  "/leads": {
   "post": {
    "tags": [
     "سرنخ‌ها"
    ],
    "summary": "ثبت سرنخ و (اختیاری) تماس فوری",
    "operationId": "createLead",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/LeadResult"
        }
       }
      }
     },
     "400": {
      "description": "بدنهٔ نامعتبر",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "ورودی نامعتبر (فیلد در error.field)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "موتور مکالمه یا CRM موقتاً در دسترس نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "leads:write",
    "description": "دسترسی لازم: `leads:write`",
    "parameters": [
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string",
          "maxLength": 100
         },
         "mobile": {
          "type": "string",
          "description": "موبایل ایرانی: 09…، ‎+98…‎ یا 0098…",
          "example": "09121234567"
         },
         "email": {
          "type": "string",
          "format": "email"
         },
         "source": {
          "type": "string",
          "maxLength": 60,
          "default": "api"
         },
         "note": {
          "type": "string",
          "maxLength": 2000
         },
         "call_now": {
          "type": "boolean",
          "description": "تماس فوری دستیار با سرنخ (برای فضاهایی که خط خروجی دارند؛ ۰۸:۰۰ تا ۲۱:۳۰ تهران)"
         }
        },
        "required": [
         "mobile"
        ],
        "additionalProperties": false
       }
      }
     }
    }
   }
  },
  "/forms/inbound": {
   "post": {
    "tags": [
     "سرنخ‌ها"
    ],
    "summary": "وب‌هوک فرم‌سازها ← سرنخ",
    "operationId": "formInbound",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/LeadResult"
        }
       }
      }
     },
     "400": {
      "description": "بدنهٔ نامعتبر",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "413": {
      "description": "بدنه بیش از ۲۰۰ کیلوبایت",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "ورودی نامعتبر (فیلد در error.field)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "موتور مکالمه یا CRM موقتاً در دسترس نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "leads:write",
    "description": "هر بدنهٔ JSON یا form-encoded را می‌پذیرد (پرس‌لاین، فرمالو، اول‌فرم، Google Forms، Typeform…). موبایل ایرانی، نام و ایمیل خودکار پیدا می‌شوند و همهٔ پاسخ‌ها در یادداشت سرنخ می‌آید. ارسال دوبارهٔ همان بدنه سرنخ تکراری نمی‌سازد.\n\nدسترسی لازم: `leads:write`",
    "parameters": [
     {
      "name": "source",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "maxLength": 40,
       "default": "form"
      },
      "description": "نام منبع، مثل porsline"
     },
     {
      "name": "call_now",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "1",
        "true",
        "yes"
       ]
      },
      "description": "تماس فوری با هر پاسخ"
     },
     {
      "name": "key",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "کلید API، فقط برای فرم‌سازهایی که سرآیند نمی‌فرستند"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "additionalProperties": true
       },
       "example": {
        "نام و نام خانوادگی": "سارا محمدی",
        "شماره موبایل": "۰۹۱۲۱۲۳۴۵۶۷",
        "خدمت": "مشاوره"
       }
      },
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "additionalProperties": true
       }
      }
     }
    },
    "security": [
     {
      "bearerAuth": []
     },
     {
      "keyQuery": []
     }
    ]
   }
  },
  "/sites": {
   "post": {
    "tags": [
     "سایت‌ها"
    ],
    "summary": "اتصال یک سایت و دریافت کد دستیار",
    "operationId": "connectSite",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "site": {
           "type": "object",
           "properties": {
            "domain": {
             "type": "string"
            },
            "platform": {
             "type": "string"
            }
           }
          },
          "widget": {
           "type": "object",
           "properties": {
            "token": {
             "type": "string"
            },
            "script": {
             "type": "string",
             "format": "uri"
            },
            "type": {
             "type": "string",
             "nullable": true
            }
           }
          },
          "outbound_calls": {
           "type": "boolean"
          },
          "business": {
           "type": "object",
           "properties": {
            "name": {
             "type": "string"
            }
           }
          },
          "learning": {
           "type": "boolean",
           "description": "true = اولین اتصال؛ منشیوا در پس‌زمینه از سایت یاد می‌گیرد"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "بدنهٔ نامعتبر",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "ورودی نامعتبر (فیلد در error.field)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "موتور مکالمه یا CRM موقتاً در دسترس نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "leads:write",
    "description": "دسترسی لازم: `leads:write`",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "domain": {
          "type": "string",
          "example": "example.com"
         },
         "platform": {
          "type": "string",
          "maxLength": 30,
          "example": "wordpress"
         },
         "version": {
          "type": "string",
          "maxLength": 20
         }
        },
        "required": [
         "domain"
        ],
        "additionalProperties": false
       }
      }
     }
    }
   }
  },
  "/deposits": {
   "get": {
    "tags": [
     "نوبت‌ها"
    ],
    "summary": "فهرست بیعانه‌ها (۲۰ در هر صفحه)",
    "operationId": "listDeposits",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "deposits": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Deposit"
           }
          },
          "page": {
           "type": "integer"
          },
          "limit": {
           "type": "integer"
          },
          "has_more": {
           "type": "boolean"
          },
          "enabled": {
           "type": "boolean",
           "description": "بیعانه برای این فضای کار فعال است"
          },
          "amount": {
           "type": "integer",
           "nullable": true
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "ورودی نامعتبر (فیلد در error.field)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "read",
    "description": "دسترسی لازم: `read`",
    "parameters": [
     {
      "name": "booking_id",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "pattern": "^VV-[A-F0-9]{10}$"
      },
      "description": "فقط بیعانهٔ یک نوبت"
     },
     {
      "name": "status",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "pending",
        "creating",
        "ready",
        "verifying",
        "paid",
        "review",
        "expired",
        "cancelled",
        "waived"
       ]
      },
      "description": "وضعیت"
     },
     {
      "name": "page",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50,
       "default": 1
      },
      "description": "صفحه"
     }
    ]
   }
  },
  "/webhooks": {
   "get": {
    "tags": [
     "وب‌هوک‌ها"
    ],
    "summary": "فهرست وب‌هوک‌ها",
    "operationId": "listWebhooks",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "webhooks": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Webhook"
           }
          },
          "events": {
           "type": "array",
           "items": {
            "type": "string"
           }
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "webhooks:manage",
    "description": "دسترسی لازم: `webhooks:manage`"
   },
   "post": {
    "tags": [
     "وب‌هوک‌ها"
    ],
    "summary": "ساخت وب‌هوک (حداکثر ۱۰)",
    "operationId": "createWebhook",
    "responses": {
     "200": {
      "description": "ساخته شد؛ secret فقط همین یک بار برمی‌گردد",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Webhook"
        }
       }
      }
     },
     "400": {
      "description": "بدنهٔ نامعتبر",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "409": {
      "description": "سقف مجاز پر شده",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "ورودی نامعتبر (فیلد در error.field)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "webhooks:manage",
    "description": "دسترسی لازم: `webhooks:manage`",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "url": {
          "type": "string",
          "description": "نشانی https عمومی",
          "format": "uri",
          "maxLength": 500
         },
         "events": {
          "type": "array",
          "items": {
           "type": "string",
           "enum": [
            "call.completed",
            "booking.created",
            "callback.created",
            "lead.created",
            "task.created",
            "deposit.created",
            "deposit.paid",
            "deposit.expired"
           ]
          },
          "default": [
           "call.completed"
          ]
         }
        },
        "required": [
         "url"
        ],
        "additionalProperties": false
       }
      }
     }
    }
   }
  },
  "/webhooks/{webhook_id}": {
   "delete": {
    "tags": [
     "وب‌هوک‌ها"
    ],
    "summary": "حذف وب‌هوک",
    "operationId": "deleteWebhook",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "deleted": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "پیدا نشد",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "webhooks:manage",
    "description": "دسترسی لازم: `webhooks:manage`",
    "parameters": [
     {
      "name": "webhook_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "شناسهٔ وب‌هوک"
     }
    ]
   }
  },
  "/webhooks/{webhook_id}/test": {
   "post": {
    "tags": [
     "وب‌هوک‌ها"
    ],
    "summary": "ارسال رویداد آزمایشی",
    "operationId": "testWebhook",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "queued": {
           "type": "boolean"
          },
          "event": {
           "type": "string"
          },
          "note": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "پیدا نشد",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "webhooks:manage",
    "description": "دسترسی لازم: `webhooks:manage`",
    "parameters": [
     {
      "name": "webhook_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "شناسهٔ وب‌هوک"
     }
    ]
   }
  },
  "/webhooks/{webhook_id}/deliveries": {
   "get": {
    "tags": [
     "وب‌هوک‌ها"
    ],
    "summary": "۵۰ تحویل آخر",
    "operationId": "listWebhookDeliveries",
    "responses": {
     "200": {
      "description": "موفق",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "deliveries": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "integer"
             },
             "event": {
              "type": "string"
             },
             "type": {
              "type": "string"
             },
             "attempt": {
              "type": "integer",
              "nullable": true
             },
             "status": {
              "type": "string",
              "nullable": true
             },
             "code": {
              "type": "integer",
              "nullable": true
             },
             "next_at": {
              "type": "string",
              "nullable": true
             },
             "excerpt": {
              "type": "string",
              "nullable": true
             },
             "updated": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "کلید API نیست یا نامعتبر است",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "دسترسی (scope) کافی نیست یا CRM فعال نیست",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "پیدا نشد",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "محدودیت نرخ؛ سرآیند Retry-After",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    },
    "x-required-scope": "webhooks:manage",
    "description": "دسترسی لازم: `webhooks:manage`",
    "parameters": [
     {
      "name": "webhook_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "شناسهٔ وب‌هوک"
     }
    ]
   }
  }
 },
 "components": {
  "securitySchemes": {
   "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "description": "Authorization: Bearer msk_live_…"
   },
   "keyQuery": {
    "type": "apiKey",
    "in": "query",
    "name": "key",
    "description": "فقط برای /forms/inbound"
   }
  },
  "parameters": {
   "IdempotencyKey": {
    "name": "Idempotency-Key",
    "in": "header",
    "required": false,
    "schema": {
     "type": "string",
     "pattern": "^[A-Za-z0-9_-]{8,80}$"
    },
    "description": "تکرار همان درخواست با همین کلید تا ۲۴ ساعت همان پاسخ را برمی‌گرداند."
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "object",
      "properties": {
       "code": {
        "type": "string",
        "example": "validation_error"
       },
       "message": {
        "type": "string",
        "description": "پیام فارسی قابل نمایش"
       },
       "field": {
        "type": "string",
        "description": "نام فیلد نامعتبر (در صورت وجود)"
       }
      },
      "required": [
       "code",
       "message"
      ]
     }
    },
    "required": [
     "error"
    ]
   },
   "Call": {
    "type": "object",
    "properties": {
     "id": {
      "type": "integer"
     },
     "created": {
      "type": "string",
      "format": "date-time"
     },
     "completed": {
      "type": "boolean"
     },
     "state": {
      "type": "string",
      "nullable": true
     },
     "channel": {
      "type": "string",
      "description": "phone | web | chat"
     },
     "direction": {
      "type": "string",
      "example": "inbound"
     },
     "customer": {
      "type": "object",
      "properties": {
       "name": {
        "type": "string"
       },
       "phone": {
        "type": "string",
        "description": "بدون دسترسی contacts:phone به‌شکل 0912***4567"
       }
      }
     },
     "summary": {
      "type": "string"
     },
     "requested_service": {
      "type": "string"
     },
     "booking": {
      "type": "object",
      "properties": {
       "id": {
        "type": "string"
       },
       "status": {
        "type": "string"
       }
      },
      "nullable": true
     },
     "callback_requested": {
      "type": "boolean"
     },
     "recording_available": {
      "type": "boolean"
     },
     "transcript_available": {
      "type": "boolean"
     },
     "gathered": {
      "type": "object",
      "additionalProperties": true,
      "description": "فقط در GET /calls/{id}: اطلاعات جمع‌آوری‌شده در گفتگو"
     }
    }
   },
   "Contact": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "phone": {
      "type": "string"
     },
     "verified": {
      "type": "boolean"
     },
     "stage": {
      "type": "string",
      "enum": [
       "new",
       "qualified",
       "consultation",
       "proposal",
       "won",
       "closed"
      ],
      "nullable": true
     },
     "created": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "Booking": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string",
      "example": "VV-0A1B2C3D4E"
     },
     "call_id": {
      "type": "integer",
      "nullable": true
     },
     "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "example": "2026-12-01"
     },
     "time": {
      "type": "string",
      "pattern": "^[0-2]\\d:[0-5]\\d$",
      "example": "10:30"
     },
     "customer": {
      "type": "string",
      "nullable": true
     },
     "service": {
      "type": "string",
      "nullable": true
     },
     "status": {
      "type": "string",
      "example": "confirmed"
     },
     "revision": {
      "type": "integer"
     },
     "advisor_id": {
      "type": "string",
      "nullable": true
     },
     "created": {
      "type": "string",
      "nullable": true
     },
     "deposit": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "وضعیت بیعانه، اگر فعال باشد"
     }
    }
   },
   "Task": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "title": {
      "type": "string",
      "nullable": true
     },
     "status": {
      "type": "string",
      "nullable": true
     },
     "due": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "contact": {
      "type": "object",
      "properties": {
       "id": {
        "type": "string",
        "nullable": true
       },
       "name": {
        "type": "string",
        "nullable": true
       }
      }
     },
     "assignee": {
      "type": "string",
      "nullable": true
     },
     "note": {
      "type": "string",
      "nullable": true
     },
     "result": {
      "type": "string",
      "nullable": true
     },
     "created": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "LeadResult": {
    "type": "object",
    "properties": {
     "lead": {
      "type": "object",
      "properties": {
       "id": {
        "type": "string"
       },
       "name": {
        "type": "string"
       },
       "mobile": {
        "type": "string"
       },
       "source": {
        "type": "string"
       },
       "duplicate": {
        "type": "boolean"
       },
       "created": {
        "type": "string",
        "format": "date-time"
       }
      }
     },
     "call_now": {
      "type": "object",
      "properties": {
       "queued": {
        "type": "boolean"
       },
       "reason": {
        "type": "string",
        "description": "outbound_not_enabled | duplicate | hourly_limit",
        "nullable": true
       },
       "window": {
        "type": "string",
        "example": "08:00–21:30 Asia/Tehran"
       }
      }
     }
    }
   },
   "Deposit": {
    "type": "object",
    "properties": {
     "token": {
      "type": "string"
     },
     "booking_id": {
      "type": "string"
     },
     "call_id": {
      "type": "integer",
      "nullable": true
     },
     "amount": {
      "type": "integer",
      "description": "تومان"
     },
     "currency": {
      "type": "string",
      "example": "IRT"
     },
     "gateway": {
      "type": "string",
      "nullable": true
     },
     "state": {
      "type": "string",
      "enum": [
       "pending",
       "creating",
       "ready",
       "verifying",
       "paid",
       "review",
       "expired",
       "cancelled",
       "waived"
      ]
     },
     "state_label": {
      "type": "string"
     },
     "pay_url": {
      "type": "string",
      "format": "uri",
      "nullable": true
     },
     "customer": {
      "type": "object",
      "properties": {
       "name": {
        "type": "string",
        "nullable": true
       },
       "phone": {
        "type": "string",
        "nullable": true
       }
      }
     },
     "service": {
      "type": "string",
      "nullable": true
     },
     "date": {
      "type": "string",
      "nullable": true
     },
     "time": {
      "type": "string",
      "nullable": true
     },
     "ref_id": {
      "type": "string",
      "nullable": true
     },
     "sms_status": {
      "type": "string",
      "nullable": true
     },
     "created": {
      "type": "string"
     },
     "expires": {
      "type": "string"
     },
     "paid_at": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "Webhook": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string",
      "example": "wh_0123456789ab"
     },
     "url": {
      "type": "string",
      "format": "uri"
     },
     "events": {
      "type": "array",
      "items": {
       "type": "string",
       "enum": [
        "call.completed",
        "booking.created",
        "callback.created",
        "lead.created",
        "task.created",
        "deposit.created",
        "deposit.paid",
        "deposit.expired",
        "webhook.test"
       ]
      }
     },
     "active": {
      "type": "boolean"
     },
     "failures": {
      "type": "integer"
     },
     "created": {
      "type": "string",
      "format": "date-time"
     },
     "secret": {
      "type": "string",
      "description": "فقط در پاسخ ساخت؛ whsec_…"
     }
    }
   },
   "WebhookEvent": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string",
      "example": "evt_0123456789abcdef0123"
     },
     "type": {
      "type": "string",
      "enum": [
       "call.completed",
       "booking.created",
       "callback.created",
       "lead.created",
       "task.created",
       "deposit.created",
       "deposit.paid",
       "deposit.expired",
       "webhook.test"
      ]
     },
     "created": {
      "type": "string",
      "format": "date-time"
     },
     "workspace": {
      "type": "string"
     },
     "branch": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true
     },
     "data": {
      "type": "object",
      "additionalProperties": true
     }
    },
    "description": "بدنهٔ POST به نشانی وب‌هوک شما. امضا: HMAC-SHA256 با کلید whsec_ روی رشتهٔ `<timestamp>.<body>`؛ جزئیات سرآیندها در مستندات."
   }
  }
 }
}