{ "openapi": "3.0.0", "info": { "title": "Salezy Public API v1", "description": "API công khai của Salezy để đồng bộ lead, khách hàng, cơ hội và đơn hàng với hệ thống khác (Make, Zapier, website…).\n\nXác thực: gửi header `x-api-key: sk__` (tạo khóa ở Cài đặt › Tích hợp).\nGiới hạn: 120 yêu cầu/phút và 1.000 yêu cầu/giờ cho mỗi key.\nPhản hồi bọc `{ success, message, data }`; danh sách trả `data: { data: [...], meta: { page, limit, total, totalPages } }`.\n\nHướng dẫn tổng quan: https://salezy.vn/developers", "version": "1.0", "contact": {} }, "tags": [ { "name": "Public API v1", "description": "Lead, liên hệ, cơ hội, đơn hàng." } ], "servers": [ { "url": "https://api.salezy.vn", "description": "Production" } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "sk__" } }, "schemas": { "OpenCreateContactDto": { "type": "object", "properties": { "fullName": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "jobTitle": { "type": "string" }, "note": { "type": "string" }, "customFields": { "type": "object" } }, "required": [ "fullName" ] }, "OpenCreateLeadDto": { "type": "object", "properties": { "fullName": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "companyName": { "type": "string" }, "need": { "type": "string" }, "budget": { "type": "string" }, "region": { "type": "string" }, "note": { "type": "string" }, "customFields": { "type": "object" }, "utm": { "type": "object", "description": "UTM { source, medium, campaign, term, content }" } }, "required": [ "fullName" ] } } }, "paths": { "/api/v1/open/me": { "get": { "operationId": "OpenApiController_me", "responses": { "200": { "description": "" }, "401": { "description": "Thiếu hoặc sai `x-api-key`, hoặc key đã bị thu hồi." }, "403": { "description": "Key không có quyền (scope) cần cho endpoint này." }, "429": { "description": "Vượt giới hạn tần suất của key." } }, "tags": [ "Public API v1" ], "security": [ { "apiKey": [] } ], "summary": "Thông tin key và tổ chức", "description": "Chỉ cần key hợp lệ." } }, "/api/v1/open/leads": { "post": { "operationId": "OpenApiController_createLead", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenCreateLeadDto" } } } }, "responses": { "201": { "description": "" }, "401": { "description": "Thiếu hoặc sai `x-api-key`, hoặc key đã bị thu hồi." }, "403": { "description": "Key không có quyền (scope) cần cho endpoint này." }, "429": { "description": "Vượt giới hạn tần suất của key." } }, "tags": [ "Public API v1" ], "security": [ { "apiKey": [] } ], "summary": "Tạo lead", "description": "Cần scope `leads:write`.", "x-required-scope": "leads:write" }, "get": { "operationId": "OpenApiController_listLeads", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 10000, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "updatedSince", "required": false, "in": "query", "description": "Chỉ lấy bản ghi cập nhật từ thời điểm này (ISO 8601)", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "NEW", "WORKING", "QUALIFIED", "UNQUALIFIED", "CONVERTED" ] } }, { "name": "phone", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "email", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Thiếu hoặc sai `x-api-key`, hoặc key đã bị thu hồi." }, "403": { "description": "Key không có quyền (scope) cần cho endpoint này." }, "429": { "description": "Vượt giới hạn tần suất của key." } }, "tags": [ "Public API v1" ], "security": [ { "apiKey": [] } ], "summary": "Danh sách lead", "description": "Cần scope `leads:read`.", "x-required-scope": "leads:read" } }, "/api/v1/open/leads/{id}": { "get": { "operationId": "OpenApiController_getLead", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Thiếu hoặc sai `x-api-key`, hoặc key đã bị thu hồi." }, "403": { "description": "Key không có quyền (scope) cần cho endpoint này." }, "429": { "description": "Vượt giới hạn tần suất của key." } }, "tags": [ "Public API v1" ], "security": [ { "apiKey": [] } ], "summary": "Chi tiết lead", "description": "Cần scope `leads:read`.", "x-required-scope": "leads:read" } }, "/api/v1/open/contacts": { "post": { "operationId": "OpenApiController_createContact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenCreateContactDto" } } } }, "responses": { "201": { "description": "" }, "401": { "description": "Thiếu hoặc sai `x-api-key`, hoặc key đã bị thu hồi." }, "403": { "description": "Key không có quyền (scope) cần cho endpoint này." }, "429": { "description": "Vượt giới hạn tần suất của key." } }, "tags": [ "Public API v1" ], "security": [ { "apiKey": [] } ], "summary": "Tạo liên hệ", "description": "Cần scope `contacts:write`.", "x-required-scope": "contacts:write" }, "get": { "operationId": "OpenApiController_listContacts", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 10000, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "updatedSince", "required": false, "in": "query", "description": "Chỉ lấy bản ghi cập nhật từ thời điểm này (ISO 8601)", "schema": { "type": "string" } }, { "name": "phone", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "email", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Thiếu hoặc sai `x-api-key`, hoặc key đã bị thu hồi." }, "403": { "description": "Key không có quyền (scope) cần cho endpoint này." }, "429": { "description": "Vượt giới hạn tần suất của key." } }, "tags": [ "Public API v1" ], "security": [ { "apiKey": [] } ], "summary": "Danh sách liên hệ", "description": "Cần scope `contacts:read`.", "x-required-scope": "contacts:read" } }, "/api/v1/open/contacts/{id}": { "get": { "operationId": "OpenApiController_getContact", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Thiếu hoặc sai `x-api-key`, hoặc key đã bị thu hồi." }, "403": { "description": "Key không có quyền (scope) cần cho endpoint này." }, "429": { "description": "Vượt giới hạn tần suất của key." } }, "tags": [ "Public API v1" ], "security": [ { "apiKey": [] } ], "summary": "Chi tiết liên hệ", "description": "Cần scope `contacts:read`.", "x-required-scope": "contacts:read" } }, "/api/v1/open/deals": { "get": { "operationId": "OpenApiController_listDeals", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 10000, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "updatedSince", "required": false, "in": "query", "description": "Chỉ lấy bản ghi cập nhật từ thời điểm này (ISO 8601)", "schema": { "type": "string" } }, { "name": "stageId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "pipelineId", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Thiếu hoặc sai `x-api-key`, hoặc key đã bị thu hồi." }, "403": { "description": "Key không có quyền (scope) cần cho endpoint này." }, "429": { "description": "Vượt giới hạn tần suất của key." } }, "tags": [ "Public API v1" ], "security": [ { "apiKey": [] } ], "summary": "Danh sách cơ hội", "description": "Cần scope `deals:read`.", "x-required-scope": "deals:read" } }, "/api/v1/open/deals/{id}": { "get": { "operationId": "OpenApiController_getDeal", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Thiếu hoặc sai `x-api-key`, hoặc key đã bị thu hồi." }, "403": { "description": "Key không có quyền (scope) cần cho endpoint này." }, "429": { "description": "Vượt giới hạn tần suất của key." } }, "tags": [ "Public API v1" ], "security": [ { "apiKey": [] } ], "summary": "Chi tiết cơ hội", "description": "Cần scope `deals:read`.", "x-required-scope": "deals:read" } }, "/api/v1/open/orders": { "get": { "operationId": "OpenApiController_listOrders", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 10000, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "updatedSince", "required": false, "in": "query", "description": "Chỉ lấy bản ghi cập nhật từ thời điểm này (ISO 8601)", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "PROCESSING", "SHIPPING", "COMPLETED", "CANCELLED", "RETURNED" ] } } ], "responses": { "200": { "description": "" }, "401": { "description": "Thiếu hoặc sai `x-api-key`, hoặc key đã bị thu hồi." }, "403": { "description": "Key không có quyền (scope) cần cho endpoint này." }, "429": { "description": "Vượt giới hạn tần suất của key." } }, "tags": [ "Public API v1" ], "security": [ { "apiKey": [] } ], "summary": "Danh sách đơn hàng", "description": "Cần scope `orders:read`.", "x-required-scope": "orders:read" } }, "/api/v1/open/orders/{id}": { "get": { "operationId": "OpenApiController_getOrder", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Thiếu hoặc sai `x-api-key`, hoặc key đã bị thu hồi." }, "403": { "description": "Key không có quyền (scope) cần cho endpoint này." }, "429": { "description": "Vượt giới hạn tần suất của key." } }, "tags": [ "Public API v1" ], "security": [ { "apiKey": [] } ], "summary": "Chi tiết đơn hàng", "description": "Cần scope `orders:read`.", "x-required-scope": "orders:read" } } }, "security": [ { "apiKey": [] } ] }