{"openapi":"3.1.0","info":{"title":"TakaTech Partner API","version":"1.1.0","description":"API cho đối tác, Zalo Mini App, landing page bên ngoài gửi yêu cầu tư vấn / đăng ký demo vào hệ thống TakaTech và lấy danh mục sản phẩm."},"servers":[{"url":"https://takatech.vn/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Access token lấy từ POST /api/auth/login (mode=token)"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"tk_at","description":"Cookie httpOnly do trang quản trị đặt khi đăng nhập"},"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"tk_live_…","description":"API key đối tác (Trang quản trị → API key đối tác)"}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","BAD_REQUEST","UNAUTHORIZED","TOKEN_EXPIRED","FORBIDDEN","NOT_FOUND","CONFLICT","PAYLOAD_TOO_LARGE","UNSUPPORTED_MEDIA_TYPE","TOO_MANY_REQUESTS","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"string"},"description":"Lỗi theo từng trường: { tênTrường: thôngBáo }"}},"required":["code","message"]},"requestId":{"type":"string"}},"required":["success","error"]},"LeadCreate":{"type":"object","properties":{"type":{"type":"string","enum":["CONSULT","DEMO","TRAINING"],"default":"CONSULT","description":"Loại yêu cầu"},"name":{"type":"string","minLength":2,"maxLength":120,"description":"Họ tên người liên hệ","example":"Nguyễn Văn A"},"phone":{"type":"string","description":"SĐT Việt Nam (0xxxxxxxxx hoặc +84xxxxxxxxx)","example":"0914586999"},"email":{"anyOf":[{"type":"string","maxLength":160,"format":"email"},{"type":"string","enum":[""]}],"example":"a@donvi.vn"},"organization":{"type":"string","maxLength":200,"description":"Tên đơn vị (form website bắt buộc khi đăng ký demo/đào tạo)","example":"UBND phường X"},"service":{"type":"string","maxLength":120,"description":"Lĩnh vực / dịch vụ quan tâm","example":"Website & Trang thông tin điện tử"},"product":{"type":"string","maxLength":120,"description":"Sản phẩm – bắt buộc khi type=DEMO","example":"TakaTech ZNS Portal"},"attendees":{"type":"integer","minimum":1,"maximum":2000,"description":"Số học viên (type=TRAINING)"},"message":{"type":"string","maxLength":3000,"description":"Nội dung yêu cầu"},"utmSource":{"type":"string","maxLength":100},"utmMedium":{"type":"string","maxLength":100},"utmCampaign":{"type":"string","maxLength":100},"source":{"type":"string","maxLength":255,"description":"Nguồn gửi, VD: zalo-mini-app, landing-hoi-cho","example":"zalo-mini-app"}},"required":["name","phone"]},"Product":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string"},"audience":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["slug","name","tagline","audience","url"]}},"parameters":{}},"paths":{"/leads":{"post":{"tags":["Partner API"],"summary":"Gửi yêu cầu tư vấn / đăng ký demo","description":"Tạo một yêu cầu mới; đội kinh doanh TakaTech nhận thông báo ngay. Giới hạn 60 yêu cầu/phút cho mỗi API key.","security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadCreate"}}}},"responses":{"201":{"description":"Đã tạo","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Chưa đăng nhập / token hết hạn (error.code = TOKEN_EXPIRED → gọi /api/auth/refresh)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","BAD_REQUEST","UNAUTHORIZED","TOKEN_EXPIRED","FORBIDDEN","NOT_FOUND","CONFLICT","PAYLOAD_TOO_LARGE","UNSUPPORTED_MEDIA_TYPE","TOO_MANY_REQUESTS","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"string"},"description":"Lỗi theo từng trường: { tênTrường: thôngBáo }"}},"required":["code","message"]},"requestId":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Dữ liệu không hợp lệ – xem error.details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","BAD_REQUEST","UNAUTHORIZED","TOKEN_EXPIRED","FORBIDDEN","NOT_FOUND","CONFLICT","PAYLOAD_TOO_LARGE","UNSUPPORTED_MEDIA_TYPE","TOO_MANY_REQUESTS","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"string"},"description":"Lỗi theo từng trường: { tênTrường: thôngBáo }"}},"required":["code","message"]},"requestId":{"type":"string"}},"required":["success","error"]}}}},"429":{"description":"Vượt giới hạn tần suất (header Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","BAD_REQUEST","UNAUTHORIZED","TOKEN_EXPIRED","FORBIDDEN","NOT_FOUND","CONFLICT","PAYLOAD_TOO_LARGE","UNSUPPORTED_MEDIA_TYPE","TOO_MANY_REQUESTS","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"string"},"description":"Lỗi theo từng trường: { tênTrường: thôngBáo }"}},"required":["code","message"]},"requestId":{"type":"string"}},"required":["success","error"]}}}}}}},"/products":{"get":{"tags":["Partner API"],"summary":"Danh mục sản phẩm","description":"Danh sách sản phẩm phần mềm TakaTech (không cần API key).","responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/health":{"get":{"tags":["Partner API"],"summary":"Kiểm tra trạng thái API","responses":{"200":{"description":"OK"}}}}},"webhooks":{}}