{"openapi":"3.0.3","info":{"title":"CNV Work — CRM Partner API","version":"1.0.0","description":"API CRM cho đối tác thứ 3 (ADR-031). Auth bằng API key (header `X-Api-Key`) do tenant cấp với scope cụ thể. Pagination keyset (cursor). Write yêu cầu `Idempotency-Key`. Đăng ký webhook để nhận sự kiện CRM (lead.created, crm.deal.won, ...)."},"servers":[{"url":"https://api.cnvwork.com/api/v1/partner/crm","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Lead"},{"name":"Deal"},{"name":"Contact"},{"name":"Company"},{"name":"Activity"},{"name":"Invoice"},{"name":"Quotation"},{"name":"Payment"},{"name":"Product"},{"name":"Subscription"}],"paths":{"/leads":{"get":{"tags":["Lead"],"summary":"List leads","operationId":"list_leads","security":[{"ApiKeyAuth":["crm_leads:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Keyset cursor từ next_cursor trang trước"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Lọc theo status (không áp dụng activities)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"tags":["Lead"],"summary":"Create lead","operationId":"create_leads","security":[{"ApiKeyAuth":["crm_leads:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Lead"},{"type":"object","properties":{"auto_assign":{"type":"boolean","nullable":true,"description":"Nhờ bộ chia vòng giao lead (chỉ khi tạo)"}}}]}}}},"description":"Số điện thoại đã nằm trên một lead còn sống của người khác: lead VẪN được tạo (201) và giao về người đang phụ trách khách đó — không trả 409. `auto_assign: true` = nhờ bộ chia vòng giao lead (khách cũ vẫn về người đang phụ trách trước). Không gửi `assigned_to` lẫn `auto_assign` ⇒ khách mới vào danh sách chung.","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"400":{"$ref":"#/components/responses/BadInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/fields/leads":{"get":{"tags":["Lead"],"summary":"List custom fields of leads","operationId":"list_leads_custom_fields","security":[{"ApiKeyAuth":["crm_leads:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"field_type":{"type":"string","enum":["text","textarea","number","currency","percent","date","datetime","boolean","select","multiselect","email","phone","url","user"]},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}}}},"currency":{"type":"string","nullable":true},"is_required":{"type":"boolean"},"is_unique":{"type":"boolean"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/leads/{id}":{"get":{"tags":["Lead"],"summary":"Get lead by id","operationId":"get_leads","security":[{"ApiKeyAuth":["crm_leads:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Lead"],"summary":"Update lead","operationId":"update_leads","security":[{"ApiKeyAuth":["crm_leads:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/deals":{"get":{"tags":["Deal"],"summary":"List deals","operationId":"list_deals","security":[{"ApiKeyAuth":["crm_deals:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Keyset cursor từ next_cursor trang trước"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Lọc theo status (không áp dụng activities)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Deal"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"tags":["Deal"],"summary":"Create deal","operationId":"create_deals","security":[{"ApiKeyAuth":["crm_deals:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"400":{"$ref":"#/components/responses/BadInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/fields/deals":{"get":{"tags":["Deal"],"summary":"List custom fields of deals","operationId":"list_deals_custom_fields","security":[{"ApiKeyAuth":["crm_deals:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"field_type":{"type":"string","enum":["text","textarea","number","currency","percent","date","datetime","boolean","select","multiselect","email","phone","url","user"]},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}}}},"currency":{"type":"string","nullable":true},"is_required":{"type":"boolean"},"is_unique":{"type":"boolean"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/deals/{id}":{"get":{"tags":["Deal"],"summary":"Get deal by id","operationId":"get_deals","security":[{"ApiKeyAuth":["crm_deals:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Deal"],"summary":"Update deal","operationId":"update_deals","security":[{"ApiKeyAuth":["crm_deals:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/contacts":{"get":{"tags":["Contact"],"summary":"List contacts","operationId":"list_contacts","security":[{"ApiKeyAuth":["crm_contacts:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Keyset cursor từ next_cursor trang trước"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Lọc theo status (không áp dụng activities)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"tags":["Contact"],"summary":"Create contact","operationId":"create_contacts","security":[{"ApiKeyAuth":["crm_contacts:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"$ref":"#/components/responses/BadInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/fields/contacts":{"get":{"tags":["Contact"],"summary":"List custom fields of contacts","operationId":"list_contacts_custom_fields","security":[{"ApiKeyAuth":["crm_contacts:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"field_type":{"type":"string","enum":["text","textarea","number","currency","percent","date","datetime","boolean","select","multiselect","email","phone","url","user"]},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}}}},"currency":{"type":"string","nullable":true},"is_required":{"type":"boolean"},"is_unique":{"type":"boolean"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/contacts/{id}":{"get":{"tags":["Contact"],"summary":"Get contact by id","operationId":"get_contacts","security":[{"ApiKeyAuth":["crm_contacts:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Contact"],"summary":"Update contact","operationId":"update_contacts","security":[{"ApiKeyAuth":["crm_contacts:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/companies":{"get":{"tags":["Company"],"summary":"List companies","operationId":"list_companies","security":[{"ApiKeyAuth":["crm_companies:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Keyset cursor từ next_cursor trang trước"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Lọc theo status (không áp dụng activities)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"tags":["Company"],"summary":"Create company","operationId":"create_companies","security":[{"ApiKeyAuth":["crm_companies:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"400":{"$ref":"#/components/responses/BadInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/fields/companies":{"get":{"tags":["Company"],"summary":"List custom fields of companies","operationId":"list_companies_custom_fields","security":[{"ApiKeyAuth":["crm_companies:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"field_type":{"type":"string","enum":["text","textarea","number","currency","percent","date","datetime","boolean","select","multiselect","email","phone","url","user"]},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}}}},"currency":{"type":"string","nullable":true},"is_required":{"type":"boolean"},"is_unique":{"type":"boolean"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/companies/{id}":{"get":{"tags":["Company"],"summary":"Get company by id","operationId":"get_companies","security":[{"ApiKeyAuth":["crm_companies:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Company"],"summary":"Update company","operationId":"update_companies","security":[{"ApiKeyAuth":["crm_companies:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/activities":{"get":{"tags":["Activity"],"summary":"List activities","operationId":"list_activities","security":[{"ApiKeyAuth":["crm_activities:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Keyset cursor từ next_cursor trang trước"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Lọc theo status (không áp dụng activities)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Activity"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"tags":["Activity"],"summary":"Create activity","operationId":"create_activities","security":[{"ApiKeyAuth":["crm_activities:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Activity"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Activity"}}}},"400":{"$ref":"#/components/responses/BadInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/activities/{id}":{"get":{"tags":["Activity"],"summary":"Get activity by id","operationId":"get_activities","security":[{"ApiKeyAuth":["crm_activities:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Activity"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/invoices":{"get":{"tags":["Invoice"],"summary":"List invoices","operationId":"list_invoices","security":[{"ApiKeyAuth":["crm_invoices:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Keyset cursor từ next_cursor trang trước"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Lọc theo status (không áp dụng activities)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/invoices/{id}":{"get":{"tags":["Invoice"],"summary":"Get invoice by id","operationId":"get_invoices","security":[{"ApiKeyAuth":["crm_invoices:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/quotations":{"get":{"tags":["Quotation"],"summary":"List quotations","operationId":"list_quotations","security":[{"ApiKeyAuth":["crm_quotations:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Keyset cursor từ next_cursor trang trước"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Lọc theo status (không áp dụng activities)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Quotation"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/quotations/{id}":{"get":{"tags":["Quotation"],"summary":"Get quotation by id","operationId":"get_quotations","security":[{"ApiKeyAuth":["crm_quotations:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quotation"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/payments":{"get":{"tags":["Payment"],"summary":"List payments","operationId":"list_payments","security":[{"ApiKeyAuth":["crm_payments:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Keyset cursor từ next_cursor trang trước"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Lọc theo status (không áp dụng activities)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/payments/{id}":{"get":{"tags":["Payment"],"summary":"Get payment by id","operationId":"get_payments","security":[{"ApiKeyAuth":["crm_payments:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/products":{"get":{"tags":["Product"],"summary":"List products","operationId":"list_products","security":[{"ApiKeyAuth":["crm_products:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Keyset cursor từ next_cursor trang trước"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Lọc theo status (không áp dụng activities)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/products/{id}":{"get":{"tags":["Product"],"summary":"Get product by id","operationId":"get_products","security":[{"ApiKeyAuth":["crm_products:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/subscriptions":{"get":{"tags":["Subscription"],"summary":"List subscriptions","operationId":"list_subscriptions","security":[{"ApiKeyAuth":["crm_subscriptions:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Keyset cursor từ next_cursor trang trước"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Lọc theo status (không áp dụng activities)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/subscriptions/{id}":{"get":{"tags":["Subscription"],"summary":"Get subscription by id","operationId":"get_subscriptions","security":[{"ApiKeyAuth":["crm_subscriptions:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key tenant cấp. Scope khả dụng: crm_leads:read, crm_leads:write, crm_deals:read, crm_deals:write, crm_contacts:read, crm_contacts:write, crm_companies:read, crm_companies:write, crm_activities:read, crm_activities:write, crm_invoices:read, crm_quotations:read, crm_payments:read, crm_products:read, crm_subscriptions:read"}},"schemas":{"Lead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","example":"crm.lead"},"schema_version":{"type":"integer","example":1},"lead_type":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"salutation":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"job_title":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"company_phone":{"type":"string","nullable":true},"company_email":{"type":"string","nullable":true},"tax_code":{"type":"string","nullable":true},"province":{"type":"string","nullable":true},"ward":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"pipeline_id":{"type":"string","nullable":true},"stage_id":{"type":"string","nullable":true},"stage_name":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"score":{"type":"string","nullable":true},"source":{"type":"string","nullable":true},"source_detail":{"type":"string","nullable":true},"marketing_channel":{"type":"string","nullable":true},"utm_source":{"type":"string","nullable":true},"utm_medium":{"type":"string","nullable":true},"utm_campaign":{"type":"string","nullable":true},"utm_content":{"type":"string","nullable":true},"utm_term":{"type":"string","nullable":true},"landing_page_url":{"type":"string","nullable":true},"referrer_url":{"type":"string","nullable":true},"interested_service":{"type":"string","nullable":true},"form_submitted_at":{"type":"string","format":"date-time","nullable":true,"description":"Giờ khách bấm gửi biểu mẫu"},"form_answers":{"type":"array","nullable":true,"description":"Câu trả lời biểu mẫu chưa có cột riêng","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"value":{"type":"string"}}}},"qualification_stage":{"type":"string","nullable":true},"assigned_to":{"type":"string","nullable":true},"converted_contact_id":{"type":"string","nullable":true},"converted_company_id":{"type":"string","nullable":true},"converted_deal_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"custom_fields":{"type":"object","additionalProperties":true,"description":"Trường tùy chỉnh của workspace { <mã trường>: giá trị } — danh sách mã + kiểu ở GET /fields/leads. Ghi: mã lạ / sai kiểu ⇒ 400; gửi null = xoá giá trị."}}},"Deal":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","example":"crm.deal"},"schema_version":{"type":"integer","example":1},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"probability":{"type":"string","nullable":true},"pipeline_id":{"type":"string","nullable":true},"stage_id":{"type":"string","nullable":true},"stage_name":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"expected_close_date":{"type":"string","nullable":true},"actual_close_date":{"type":"string","nullable":true},"closed_at":{"type":"string","nullable":true},"primary_contact_id":{"type":"string","nullable":true},"primary_company_id":{"type":"string","nullable":true},"source_lead_id":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"source":{"type":"string","nullable":true},"source_group":{"type":"string","nullable":true},"deal_type":{"type":"string","nullable":true},"lost_reason":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"custom_fields":{"type":"object","additionalProperties":true,"description":"Trường tùy chỉnh của workspace { <mã trường>: giá trị } — danh sách mã + kiểu ở GET /fields/deals. Ghi: mã lạ / sai kiểu ⇒ 400; gửi null = xoá giá trị."}}},"Contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","example":"crm.contact"},"schema_version":{"type":"integer","example":1},"full_name":{"type":"string","nullable":true},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"salutation":{"type":"string","nullable":true},"job_title":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobile":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"relationship_type":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"province":{"type":"string","nullable":true},"ward":{"type":"string","nullable":true},"district":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"tax_code":{"type":"string","nullable":true},"source":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"score":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"custom_fields":{"type":"object","additionalProperties":true,"description":"Trường tùy chỉnh của workspace { <mã trường>: giá trị } — danh sách mã + kiểu ở GET /fields/contacts. Ghi: mã lạ / sai kiểu ⇒ 400; gửi null = xoá giá trị."}}},"Company":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","example":"crm.company"},"schema_version":{"type":"integer","example":1},"name":{"type":"string","nullable":true},"short_name":{"type":"string","nullable":true},"alias_name":{"type":"string","nullable":true},"tax_code":{"type":"string","nullable":true},"industry":{"type":"string","nullable":true},"size_category":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"province":{"type":"string","nullable":true},"ward":{"type":"string","nullable":true},"district":{"type":"string","nullable":true},"relationship_type":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"source":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"representative_name":{"type":"string","nullable":true},"representative_title":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"custom_fields":{"type":"object","additionalProperties":true,"description":"Trường tùy chỉnh của workspace { <mã trường>: giá trị } — danh sách mã + kiểu ở GET /fields/companies. Ghi: mã lạ / sai kiểu ⇒ 400; gửi null = xoá giá trị."}}},"Activity":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","example":"crm.activity"},"schema_version":{"type":"integer","example":1},"entity_type":{"type":"string","nullable":true},"entity_id":{"type":"string","nullable":true},"activity_type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"scheduled_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"duration_min":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Invoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","example":"crm.invoice"},"schema_version":{"type":"integer","example":1},"invoice_number":{"type":"string","nullable":true},"contract_code":{"type":"string","nullable":true},"invoice_type":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"billing_name":{"type":"string","nullable":true},"deal_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"contact_id":{"type":"string","nullable":true},"subscription_id":{"type":"string","nullable":true},"quotation_id":{"type":"string","nullable":true},"issue_date":{"type":"string","nullable":true},"due_date":{"type":"string","nullable":true},"sent_at":{"type":"string","nullable":true},"paid_at":{"type":"string","nullable":true},"subtotal":{"type":"string","nullable":true},"tax_percent":{"type":"string","nullable":true},"tax_amount":{"type":"string","nullable":true},"discount_amount":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"amount_paid":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"payment_terms":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Quotation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","example":"crm.quotation"},"schema_version":{"type":"integer","example":1},"quotation_code":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"contract_code":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"invoice_type":{"type":"string","nullable":true},"deal_id":{"type":"string","nullable":true},"contact_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"lead_id":{"type":"string","nullable":true},"invoice_id":{"type":"string","nullable":true},"issue_date":{"type":"string","nullable":true},"valid_until":{"type":"string","nullable":true},"sent_at":{"type":"string","nullable":true},"accepted_at":{"type":"string","nullable":true},"subtotal":{"type":"string","nullable":true},"tax_percent":{"type":"string","nullable":true},"tax_amount":{"type":"string","nullable":true},"discount_amount":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","example":"crm.payment"},"schema_version":{"type":"integer","example":1},"payment_code":{"type":"string","nullable":true},"invoice_id":{"type":"string","nullable":true},"deal_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_type":{"type":"string","nullable":true},"payment_method":{"type":"string","nullable":true},"payment_date":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"reference_code":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"source":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","example":"crm.product"},"schema_version":{"type":"integer","example":1},"name":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"unit_price":{"type":"string","nullable":true},"renewal_price":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"category_id":{"type":"string","nullable":true},"product_type":{"type":"string","nullable":true},"billing_cycle":{"type":"string","nullable":true},"unit":{"type":"string","nullable":true},"is_active":{"type":"string","nullable":true},"min_quantity":{"type":"string","nullable":true},"trial_days":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Subscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","example":"crm.subscription"},"schema_version":{"type":"integer","example":1},"name":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"contact_id":{"type":"string","nullable":true},"deal_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"billing_cycle":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"start_date":{"type":"string","nullable":true},"end_date":{"type":"string","nullable":true},"next_billing_date":{"type":"string","nullable":true},"trial_end_date":{"type":"string","nullable":true},"cancelled_at":{"type":"string","nullable":true},"auto_renew":{"type":"string","nullable":true},"renewal_status":{"type":"string","nullable":true},"renewal_count":{"type":"string","nullable":true},"grace_end_date":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"API key thiếu/không hợp lệ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Thiếu scope hoặc org chưa bật external API (code: scope_required | external_api_disabled)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BadInput":{"description":"Input không hợp lệ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Không tìm thấy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}