{"openapi":"3.1.0","info":{"title":"Trang Vàng Doanh Nghiệp — Agent API","version":"1.0.0","description":"Danh bạ doanh nghiệp Việt Nam cho AI agent. Đọc danh bạ: công khai, không cần key. Dữ liệu riêng của doanh nghiệp: cần key tv_ak_ do người dùng tạo ở Thiết lập → Kết nối AI. Hướng dẫn: https://trangvangdoanhnghiep.vn/api/agent/v1/docs"},"servers":[{"url":"https://trangvangdoanhnghiep.vn/api/agent/v1"}],"paths":{"/me":{"get":{"operationId":"get_me","summary":"Kiểm tra key / chế độ truy cập","description":"Gọi đầu tiên. Không có key: chế độ công khai (chỉ đọc danh bạ). Có key: trả doanh nghiệp (tenant) và scope của key.\n\nScope: `public`","x-scope":"public","x-write":false,"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[],"responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"message":"OK","data":{"authenticated":false,"access":"public","scopes":["public"],"rate_limit":"2 yêu cầu/giây mỗi IP (dồn tối đa 20)"}}}}},"400":{"description":"Tham số sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Thiếu/sai/hết hạn/thu hồi key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key thiếu scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Không thấy đối tượng","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Vượt giới hạn tốc độ (xem header Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/overview":{"get":{"operationId":"get_overview","summary":"Tổng quan danh bạ","description":"Một lượt gọi trả lời câu hỏi chung: số doanh nghiệp, số tỉnh/thành, top tỉnh và top ngành, thời điểm cập nhật dữ liệu.\n\nScope: `public`","x-scope":"public","x-write":false,"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[],"responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"message":"OK","data":{"company_count":43000,"province_count":63,"top_provinces":[{"slug":"thanh-pho-ho-chi-minh","name":"TP. Hồ Chí Minh","company_count":12000}],"data_updated_at":"2026-11-01T09:00:00.000+07:00"}}}}},"400":{"description":"Tham số sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Thiếu/sai/hết hạn/thu hồi key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key thiếu scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Không thấy đối tượng","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Vượt giới hạn tốc độ (xem header Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies":{"get":{"operationId":"search_companies","summary":"Tìm doanh nghiệp","description":"Tìm theo tên hoặc mã số thuế (MST), không phân biệt dấu, sắp AI Score cao trước. Lọc thêm theo slug tỉnh/ngành (lấy từ /provinces, /industries).\n\nScope: `public`","x-scope":"public","x-write":false,"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Tên, từ khoá hoặc MST (≥ 2 ký tự). Bắt buộc nếu không có province/industry","schema":{"type":"string","example":"van tai"}},{"name":"province","in":"query","required":false,"description":"Slug tỉnh/thành, vd thanh-pho-ha-noi","schema":{"type":"string","example":"thanh-pho-ha-noi"}},{"name":"industry","in":"query","required":false,"description":"Slug ngành, vd van-tai-duong-bo","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Số bản ghi, mặc định 20, tối đa 100","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Bỏ qua n bản ghi đầu (tối đa 1000)","schema":{"type":"integer","minimum":0,"maximum":1000}}],"responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"message":"Tìm thấy 24 doanh nghiệp","data":[{"mst":"0100000000","name":"Công ty TNHH Vận Tải Ví Dụ","address":"1 Phố Mẫu, Hà Nội","province":"Hà Nội","industry":"Vận tải đường bộ","phone":"024 0000 0000","website":"https://example.vn","website_status":"alive","ai_score":55,"profile_url":"https://trangvangdoanhnghiep.vn/0100000000-cong-ty-tnhh-van-tai-vi-du"}],"total":24,"limit":1,"offset":0}}}},"400":{"description":"Tham số sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Thiếu/sai/hết hạn/thu hồi key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key thiếu scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Không thấy đối tượng","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Vượt giới hạn tốc độ (xem header Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{mst}":{"get":{"operationId":"get_company","summary":"Hồ sơ một doanh nghiệp","description":"Hồ sơ đầy đủ theo MST (10 chữ số, chi nhánh dạng 0100000000-001): tình trạng, loại hình, năm thành lập, người đại diện, địa chỉ, đơn vị hành chính mới 2025, điện thoại, website, ngành, AI Score, giới thiệu, sản phẩm.\n\nScope: `public`","x-scope":"public","x-write":false,"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"mst","in":"path","required":true,"description":"Mã số thuế","schema":{"type":"string","example":"0100000000"}}],"responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"message":"OK","data":{"mst":"0100000000","name":"Công ty TNHH Vận Tải Ví Dụ","status":"Đang hoạt động","founded_year":"2008","ai_score":55,"updated_at":"2026-10-01T10:00:00.000+07:00"}}}}},"400":{"description":"Tham số sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Thiếu/sai/hết hạn/thu hồi key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key thiếu scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Không thấy đối tượng","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Vượt giới hạn tốc độ (xem header Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/provinces":{"get":{"operationId":"list_provinces","summary":"Danh sách tỉnh/thành và slug","description":"Slug dùng cho tham số province của /companies.\n\nScope: `public`","x-scope":"public","x-write":false,"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Số bản ghi, mặc định 20, tối đa 100","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Bỏ qua n bản ghi đầu (tối đa 1000)","schema":{"type":"integer","minimum":0,"maximum":1000}}],"responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"message":"OK","data":[{"slug":"thanh-pho-ho-chi-minh","name":"TP. Hồ Chí Minh","company_count":12000}],"total":63,"limit":2,"offset":0}}}},"400":{"description":"Tham số sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Thiếu/sai/hết hạn/thu hồi key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key thiếu scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Không thấy đối tượng","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Vượt giới hạn tốc độ (xem header Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/industries":{"get":{"operationId":"list_industries","summary":"Danh sách ngành và slug","description":"Tìm ngành theo tên (q); slug dùng cho tham số industry của /companies.\n\nScope: `public`","x-scope":"public","x-write":false,"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Lọc theo tên ngành","schema":{"type":"string","example":"vận tải"}},{"name":"limit","in":"query","required":false,"description":"Số bản ghi, mặc định 20, tối đa 100","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Bỏ qua n bản ghi đầu (tối đa 1000)","schema":{"type":"integer","minimum":0,"maximum":1000}}],"responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"message":"OK","data":[{"slug":"van-tai-duong-bo","name":"Vận tải đường bộ","company_count":300}],"total":12,"limit":1,"offset":0}}}},"400":{"description":"Tham số sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Thiếu/sai/hết hạn/thu hồi key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key thiếu scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Không thấy đối tượng","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Vượt giới hạn tốc độ (xem header Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/my/company":{"get":{"operationId":"get_my_company","summary":"Hồ sơ doanh nghiệp của chủ key","description":"Hồ sơ đang hiển thị công khai của doanh nghiệp gắn với key (giống get_company), kèm số đề xuất sửa của bạn đang chờ duyệt.\n\nScope: `agent:read`","x-scope":"agent:read","x-write":false,"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[],"responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"message":"OK","data":{"mst":"0100000000","name":"Công ty TNHH Ví Dụ","phone":"024 0000 0000","pending_edit_proposals":1}}}}},"400":{"description":"Tham số sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Thiếu/sai/hết hạn/thu hồi key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key thiếu scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Không thấy đối tượng","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Vượt giới hạn tốc độ (xem header Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/my/edit-proposals":{"get":{"operationId":"list_my_edit_proposals","summary":"Đề xuất sửa thông tin của doanh nghiệp","description":"Các đề xuất sửa hồ sơ doanh nghiệp mà chính tài khoản chủ key đã gửi, mới nhất trước, kèm trạng thái duyệt (PENDING/APPROVED/REJECTED).\n\nScope: `agent:read`","x-scope":"agent:read","x-write":false,"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Mặc định 20, tối đa 100","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Bỏ qua n bản ghi","schema":{"type":"integer","minimum":0,"maximum":1000}}],"responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"message":"OK","data":[{"id":"b3f1…","status":"PENDING","changes":{"tel":"024 1111 2222"},"created_at":"2026-11-02T10:00:00.000+07:00"}],"total":1,"limit":20,"offset":0}}}},"400":{"description":"Tham số sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Thiếu/sai/hết hạn/thu hồi key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key thiếu scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Không thấy đối tượng","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Vượt giới hạn tốc độ (xem header Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_edit_proposal","summary":"Gửi đề xuất sửa hồ sơ doanh nghiệp","description":"Đề xuất sửa thông tin doanh nghiệp gắn với key; quản trị viên Trang Vàng duyệt rồi mới hiển thị. Field được sửa: name, address, phone, fax, website, industry, representative, employees, legal_type, products, description. Luôn gọi dry_run trước để xem thay đổi.\n\nScope: `agent:write` · ghi: hỗ trợ `dry_run` và header `Idempotency-Key`","x-scope":"agent:write","x-write":true,"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Chuỗi duy nhất cho mỗi hành động ghi; gọi lại cùng key trong 24h trả lại kết quả lần đầu.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["changes"],"properties":{"changes":{"type":"object","description":"Đối tượng {field: giá trị mới}, vd {\"phone\":\"024 1111 2222\"}"},"dry_run":{"type":"boolean","description":"true = chỉ kiểm tra và trả bản so sánh, không ghi"}}}}}},"responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"message":"Kiểm tra OK — CHƯA gửi đề xuất","data":{"dry_run":true,"company_mst":"0100000000","diff":[{"field":"phone","current":"024 0000 0000","proposed":"024 1111 2222"}]}}}}},"400":{"description":"Tham số sai","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Thiếu/sai/hết hạn/thu hồi key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key thiếu scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Không thấy đối tượng","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Vượt giới hạn tốc độ (xem header Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer tv_ak_…"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Envelope":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}