OnePrint cung cấp dịch vụ fulfill trong lĩnh vực in theo yêu cầu (Print-on-Demand). Hệ thống hỗ trợ tích hợp thông qua RESTful API để đối tác có thể:
\nTạo đơn hàng
\nLấy danh sách đơn
\nTra cứu đơn cụ thể
\nXoá đơn hàng
\nLấy danh sách SKU đang hoạt động
\nNhận thông báo qua webhook khi đơn hàng thay đổi trạng thái hoặc có thông tin tracking mới
\nLưu ý: Rate Limits
\nĐể đảm bảo hệ thống hoạt động ổn định và công bằng cho tất cả người dùng, OnePrint áp dụng giới hạn tốc độ gọi API như sau:
\nGiới hạn: Tối đa 2 requests/giây cho mỗi địa chỉ IP
\nQuá giới hạn: Khi vượt quá giới hạn này, hệ thống sẽ trả về mã lỗi 429 Too Many Requests
Mọi request gửi đến hệ thống OnePrint API đều phải được xác thực bằng cơ chế Signature Base Authentication nhằm đảm bảo tính toàn vẹn và xác minh danh tính người gọi API.
\nHệ thống OnePrint sẽ cung cấp 2 thông tin xác thực: API key và API secret (Liên hệ admin).
Khi gửi request, bạn cần bổ sung 3 header sau:
\nX-API-Key: Chuỗi API key do hệ thống cấp.
\nX-Timestamp: Thời gian gửi request (UNIX timestamp, tính bằng giây).
\nX-Signature: Chữ ký xác thực, tạo bằng HMAC SHA256.
\nGhép chuỗi: [HTTP_METHOD][BODY][API_KEY][TIMESTAMP]
\nHTTP_METHOD: Phương thức request chuẩn RESTful (GET, POST, PUT, DELETE, ...).
\nBODY: Nội dung request (nếu không có thì để rỗng '').
API_KEY: Giá trị API key.
\nTIMESTAMP: Giá trị timestamp.
\nTạo chữ ký:
\nSử dụng thuật toán HMAC SHA256 với secret tương ứng API key.
\nVí dụ (PHP):
$signature = hash_hmac('sha256', $method . $body . $apiKey . $timestamp, $apiSecret);
Gửi request kèm 3 header trên đến endpoint của hệ thống OnePrint.
\ncurl --location 'https://api.oneprint.io/v1/variants?page=1&per_page=50' \\\n--header 'X-API-Key: acb123' \\\n--header 'X-Timestamp: 1750000000' \\\n--header 'X-Signature: acbdef123456' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{}'\n\nX-Timestamp chỉ hợp lệ trong một khoảng thời gian ngắn (5 phút).
\nNếu chữ ký hoặc thông tin không hợp lệ, hệ thống sẽ trả về lỗi xác thực.
\nĐảm bảo đồng bộ thời gian giữa client và server.
\n// HTTP status code: 200, 201\n{\n \"id\": 1001,\n \"order_name\": \"ORD-20240601-001\"\n}\n\n// 422 - UNPROCESSABLE_CONTENT\n{\n \"message\": \"source id field is required.\",\n \"errors\": {\n \"source_id\": [\n \"source id field is required.\"\n ]\n }\n}\n\n// 400, 404, 409...\n{\n \"message\": \"Order not found.\",\n \"code\": \"FS0101\",\n \"data\": []\n}\n\nCung cấp danh sách các SKU đang hoạt động.
\nAPI này chỉ trả về danh sách các SKU đang ở trạng thái active trên hệ thống OnePrint.
\nMỗi SKU đi kèm thông tin chi tiết bao gồm:
\nsku: mã định danh biến thể sản phẩm (bắt buộc để tạo đơn).
product_name: tên sản phẩm hiển thị.
product_type: loại sản phẩm (ví dụ: Shirt, Mug...).
base_cost: giá gốc của sản phẩm, bao gồm:
phí ship tiêu chuẩn (shipping fee)
phí ship tiêu chuẩn cho sản phẩm đi kèm (additional shipping fee)
phí ship nhanh (express fee)
phí ship nhanh cho sản phẩm đi kèm (additional express fee)
Số thứ tự của trang dữ liệu cần lấy (mặc định là 1)
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"Số lượng bản ghi trả về trên mỗi trang (mặc định là 50, tối đa 200)
\n","type":"text/plain"},"key":"per_page","value":"50"}],"variable":[]}},"response":[{"id":"e7fbc103-19e5-49fe-bc83-df71ee4d6612","name":"Successfully","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.oneprint.io/v1/variants?page=1&per_page=50","protocol":"https","host":["api","oneprint","io"],"path":["v1","variants"],"query":[{"key":"page","value":"1"},{"key":"per_page","value":"50"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"page\": 1,\n \"per_page\": 50,\n \"total\": 6,\n \"data\": [\n {\n \"sku\": \"MetalSign-Gold\",\n \"product_name\": \"Metal Sign\",\n \"product_type\": \"Metal Sign\",\n \"base_cost\": \"0.50\",\n \"shipping_fee\": {\n \"zone1_fee\": \"0.10\",\n \"zone1_additional_fee\": \"0.10\",\n \"zone2_fee\": \"0.10\",\n \"zone2_additional_fee\": \"0.10\",\n \"zone3_fee\": \"0.10\",\n \"zone3_additional_fee\": \"0.10\",\n \"zone4_fee\": \"0.10\",\n \"zone4_additional_fee\": \"0.10\",\n \"zone1_express_fee\": \"1.00\",\n \"zone1_additional_express_fee\": \"1.00\",\n \"zone2_express_fee\": \"1.00\",\n \"zone2_additional_express_fee\": \"1.00\",\n \"zone3_express_fee\": \"1.00\",\n \"zone3_additional_express_fee\": \"1.00\",\n \"zone4_express_fee\": \"1.00\",\n \"zone4_additional_express_fee\": \"1.00\"\n }\n },\n {\n \"sku\": \"Heartacrylicplaque-Acrylic\",\n \"product_name\": \"Heart acrylic plaque\",\n \"product_type\": \"Heart Acrylic Plaque\",\n \"base_cost\": \"6.00\",\n \"shipping_fee\": {\n \"zone1_fee\": \"0.10\",\n \"zone1_additional_fee\": \"0.10\",\n \"zone2_fee\": \"0.10\",\n \"zone2_additional_fee\": \"0.10\",\n \"zone3_fee\": \"0.10\",\n \"zone3_additional_fee\": \"0.10\",\n \"zone4_fee\": \"0.10\",\n \"zone4_additional_fee\": \"0.10\",\n \"zone1_express_fee\": \"1.00\",\n \"zone1_additional_express_fee\": \"1.00\",\n \"zone2_express_fee\": \"1.00\",\n \"zone2_additional_express_fee\": \"1.00\",\n \"zone3_express_fee\": \"1.00\",\n \"zone3_additional_express_fee\": \"1.00\",\n \"zone4_express_fee\": \"1.00\",\n \"zone4_additional_express_fee\": \"1.00\"\n }\n },\n {\n \"sku\": \"LSG2400-S\",\n \"product_name\": \"Unisex Long Sleeves Gildan 2400000\",\n \"product_type\": \"Apparel\",\n \"base_cost\": \"5.00\",\n \"shipping_fee\": {\n \"zone1_fee\": \"0.10\",\n \"zone1_additional_fee\": \"0.10\",\n \"zone2_fee\": \"0.10\",\n \"zone2_additional_fee\": \"0.10\",\n \"zone3_fee\": \"0.10\",\n \"zone3_additional_fee\": \"0.10\",\n \"zone4_fee\": \"0.10\",\n \"zone4_additional_fee\": \"0.10\",\n \"zone1_express_fee\": \"2.00\",\n \"zone1_additional_express_fee\": \"2.00\",\n \"zone2_express_fee\": \"2.00\",\n \"zone2_additional_express_fee\": \"2.00\",\n \"zone3_express_fee\": \"2.00\",\n \"zone3_additional_express_fee\": \"2.00\",\n \"zone4_express_fee\": \"2.00\",\n \"zone4_additional_express_fee\": \"2.00\"\n }\n },\n {\n \"sku\": \"LSG2400-M\",\n \"product_name\": \"Unisex Long Sleeves Gildan 2400000\",\n \"product_type\": \"Apparel\",\n \"base_cost\": \"6.00\",\n \"shipping_fee\": {\n \"zone1_fee\": \"0.10\",\n \"zone1_additional_fee\": \"0.10\",\n \"zone2_fee\": \"0.10\",\n \"zone2_additional_fee\": \"0.10\",\n \"zone3_fee\": \"0.10\",\n \"zone3_additional_fee\": \"0.10\",\n \"zone4_fee\": \"0.10\",\n \"zone4_additional_fee\": \"0.10\",\n \"zone1_express_fee\": \"2.00\",\n \"zone1_additional_express_fee\": \"2.00\",\n \"zone2_express_fee\": \"2.00\",\n \"zone2_additional_express_fee\": \"2.00\",\n \"zone3_express_fee\": \"2.00\",\n \"zone3_additional_express_fee\": \"2.00\",\n \"zone4_express_fee\": \"2.00\",\n \"zone4_additional_express_fee\": \"2.00\"\n }\n },\n {\n \"sku\": \"LSG2400-L\",\n \"product_name\": \"Unisex Long Sleeves Gildan 2400000\",\n \"product_type\": \"Apparel\",\n \"base_cost\": \"7.00\",\n \"shipping_fee\": {\n \"zone1_fee\": \"0.10\",\n \"zone1_additional_fee\": \"0.10\",\n \"zone2_fee\": \"0.10\",\n \"zone2_additional_fee\": \"0.10\",\n \"zone3_fee\": \"0.10\",\n \"zone3_additional_fee\": \"0.10\",\n \"zone4_fee\": \"0.10\",\n \"zone4_additional_fee\": \"0.10\",\n \"zone1_express_fee\": \"2.00\",\n \"zone1_additional_express_fee\": \"2.00\",\n \"zone2_express_fee\": \"2.00\",\n \"zone2_additional_express_fee\": \"2.00\",\n \"zone3_express_fee\": \"2.00\",\n \"zone3_additional_express_fee\": \"2.00\",\n \"zone4_express_fee\": \"2.00\",\n \"zone4_additional_express_fee\": \"2.00\"\n }\n },\n {\n \"sku\": \"PhoneCase-Silicone\",\n \"product_name\": \"Phone Case\",\n \"product_type\": \"Phone Case\",\n \"base_cost\": \"1.00\",\n \"shipping_fee\": {\n \"zone1_fee\": \"0.10\",\n \"zone1_additional_fee\": \"0.10\",\n \"zone2_fee\": \"0.10\",\n \"zone2_additional_fee\": \"0.10\",\n \"zone3_fee\": \"0.10\",\n \"zone3_additional_fee\": \"0.10\",\n \"zone4_fee\": \"0.10\",\n \"zone4_additional_fee\": \"0.10\",\n \"zone1_express_fee\": \"2.00\",\n \"zone1_additional_express_fee\": \"2.00\",\n \"zone2_express_fee\": \"2.00\",\n \"zone2_additional_express_fee\": \"2.00\",\n \"zone3_express_fee\": \"2.00\",\n \"zone3_additional_express_fee\": \"2.00\",\n \"zone4_express_fee\": \"2.00\",\n \"zone4_additional_express_fee\": \"2.00\"\n }\n }\n ]\n}"},{"id":"82f1fd0d-f3a5-42b0-96fb-827d7ebbf283","name":"Failed with per_page > 200","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.oneprint.io/v1/variants?page=1&per_page=201","host":["https://api.oneprint.io/v1"],"path":["variants"],"query":[{"key":"page","value":"1"},{"key":"per_page","value":"201"}]}},"status":"Unprocessable Content","code":422,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"per page field must not be greater than 200.\",\n \"errors\": {\n \"per_page\": [\n \"per page field must not be greater than 200.\"\n ]\n }\n}"}],"_postman_id":"21c1e26a-ce19-423a-bd5c-97cac18a39cf"}],"id":"4244b854-6342-4fc1-811a-4042e998fdc5","_postman_id":"4244b854-6342-4fc1-811a-4042e998fdc5","description":""},{"name":"Order","item":[{"name":"Create order","event":[{"listen":"test","script":{"id":"96e1195f-884f-40e1-9e5d-32012e3793d3","exec":[""],"type":"text/javascript","packages":{},"requests":{}}},{"listen":"prerequest","script":{"id":"15315385-adc0-40dd-a373-d328e66a6a20","exec":[""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"a4428e21-f8fd-4411-a349-f7b7c320add2","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{}},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"origin_id\": \"ORD-00009\",\n \"source_id\": \"#OP-12937\",\n \"shipping_info\": {\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"phone\": \"0123456789\",\n \"city\": \"Hanoi\",\n \"state\": \"HN\",\n \"address\": \"123 Main St\",\n \"address2\": \"Apt 4B\",\n \"postal_code\": \"100000\",\n \"country\": \"VN\",\n \"company\": \"Example Co\",\n \"service\": \"EXPRESS\"\n },\n \"items\": [\n {\n \"quantity\": 2,\n \"sku\": \"LSG64400-S-White\",\n \"print_positions\": [\n {\n \"position\": \"back\",\n \"design_url\": \"https://image.shutterstock.com/image-photo/happy-young-pug-dog-panting-260nw-2553323723.jpg\",\n \"mockup_url\": null\n }\n ]\n },\n {\n \"quantity\": 1,\n \"sku\": \"LSG64400-S-Black\",\n \"print_positions\": [\n {\n \"position\": \"front\",\n \"design_url\": \"https://image.shutterstock.com/image-photo/happy-young-pug-dog-panting-260nw-2553323723.jpg\",\n \"mockup_url\": null\n }\n ]\n },\n {\n \"quantity\": 2,\n \"sku\": \"LSG64400-S-Gray\",\n \"print_positions\": [\n {\n \"position\": \"front\",\n \"design_url\": \"https://image.shutterstock.com/image-photo/happy-young-pug-dog-panting-260nw-2553323723.jpg\",\n \"mockup_url\": null\n },\n {\n \"position\": \"back\",\n \"design_url\": \"https://image.shutterstock.com/image-photo/happy-young-pug-dog-panting-260nw-2553323723.jpg\",\n \"mockup_url\": null\n }\n ]\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.oneprint.io/v1/orders","description":"API này cho phép Seller tạo đơn trên OnePrint.
\nCác SKU phải là SKU active (lấy từ API /variants).
Sản phẩm có thể in ở mặt trước (front), mặt sau (back) hoặc in cả 2 mặt.
Địa chỉ giao hàng yêu cầu phải đầy đủ và hợp lệ.
\nHệ thống hỗ trợ 2 hình thức vận chuyển thông qua trường service: STANDARD, EXPRESS.
Lưu ý về trường position:
\nMột số sản phẩm như Shirt,... sẽ hỗ trợ in ở mặt trước khi chọn front hoặc mặt sau khi chọn back hoặc in ở cả 2 mặt khi nhập đủ thông tin design_url ở cả 2 mặt.
Các sản phẩm như Mugs, Doormat, Meta signs, Canvas,... luôn được in mặc định ở mặt trước và không hỗ trợ in 2 mặt (Nhập đúng postion là front).
👉 Để biết thêm Chi tiết các sản phẩm hỗ trợ in 2 mặt có thể liên hệ chúng tôi.
\nLưu ý về trường shipping_label_url:
Khi Seller muốn tự chủ động ship đơn hàng (ship by seller) thì cần cung cấp link shipping label của đơn vị vận chuyển mà Seller sử dụng, thay cho việc nhập thông tin shipping_info (ship by OnePrint).
Nếu không có shipping_label_url → yêu cầu cung cấp shipping_info đầy đủ.
Bắt buộc có 1 trong 2 trường shipping_label_url và shipping_info.
Nếu có đồng thời shipping_label_url và shipping_info → báo lỗi.
Lưu ý về trường service:
Trường service được sử dụng để xác định hình thức vận chuyển của đơn hàng khi ship by OnePrint.
Hệ thống hỗ trợ 2 giá trị: STANDARD, EXPRESS.
Nếu không truyền service, hệ thống mặc định là STANDARD.
Đảm bảo request tuân thủ đúng cấu trúc và dữ liệu theo mô tả trong phần Request body bên dưới. Đặc biệt:
\nTrường source_id, shipping_info hoặc shipping_label_url, và order_items là bắt buộc.
Trong shipping_info, cần cung cấp đầy đủ thông tin địa chỉ. Riêng email hoặc phone, cần có ít nhất một.
Trường service là tùy chọn. Nếu có truyền, chỉ chấp nhận các giá trị STANDARD hoặc EXPRESS.
Mỗi sản phẩm trong items yêu cầu có sku và quantity.
Trường design_url là bắt buộc, file/ ảnh upload phải hợp lệ (ảnh PNG/ JPG/ JPEG).
Các trường mockup_url là tùy chọn, nhưng nếu có cung cấp thì cần đúng định dạng URL hợp lệ.
origin_id (string, nullable)
source_id(string, required)
shipping_label_url (string, required/optional): Required nếu là đơn ship by seller. URL hợp lệ, file định dạng: PNG/JPG/JPEG/WEBP/PDF
shipping_info(required/optional): required nếu là đơn ship by OnePrint.
name (string, required, 255)
email(string, required/optional, 255): required nếu trường phone bỏ trống.
phone(string, required/optional, 20): required nếu trường email bỏ trống.
city (string, required, 100)
state(string, optional, 100)
address (string, required, 255)
address2(string, optional, 255)
postal_code (string, required, 20)
country (string, required)
company (string, optional, 255)
service (string, optional): Hình thức vận chuyển của đơn hàng. Hỗ trợ STANDARD, EXPRESS. Mặc định là STANDARD.
items:
quantity(int, required)
sku(string, required)
print_positions:
position(string, required) mặc định là front
design_url(url, required)
mockup_url(url, optional)
Cho phép Seller xóa đơn hàng chưa được xử lý (chưa hoàn thiện thông tin đơn hoặc chưa thanh toán) khỏi hệ thống OnePrint.
\norder_id trước khi đơn được chuyển sang trạng thái In Production (trạng thái xử lý). Chỉ những đơn còn ở trạng thái Incomplete hoặc Unpaid mới có thể xoá.Cho phép Seller kiểm tra đầy đủ thông tin của một đơn hàng đã tạo trên OnePrint.
\nAPI này trả về toàn bộ dữ liệu của đơn hàng bao gồm:
\nThông tin người nhận.
\nTrạng thái đơn.
\nChi phí (phí sản phẩm, vận chuyển, tổng).
\nDanh sách sản phẩm và file in.
\nThông tin giao hàng và mã vận đơn.
\nTrả về danh sách các đơn hàng đã được tạo bởi Seller.
\nAPI này hỗ trợ phân trang và dùng để lấy toàn bộ đơn hàng đã tạo trong hệ thống OnePrint. Mỗi đơn hàng trả về bao gồm:
\nThông tin đơn hàng (id, order_name)
Mã đơn tham chiếu từ hệ thống đối tác (source_id)
Trạng thái đơn hàng
\nTổng chi phí, chi phí sản phẩm, phí vận chuyển
\nThông tin người nhận và danh sách sản phẩm
\nCác trường trong mỗi đơn phản ánh đúng cấu trúc chi tiết như trong API GET api.oneprint.io/v1/orders/{order_id}.
Có thể truyền thêm query param để phân trang
\nSố thứ tự của trang dữ liệu cần lấy (mặc định là 1)
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"Số lượng bản ghi trả về trên mỗi trang (mặc định là 50, tối đa 200)
\n","type":"text/plain"},"key":"per_page","value":"50"},{"description":{"content":"Trường dữ liệu muốn sắp xếp (id, created_at)
\n","type":"text/plain"},"key":"sort_by","value":"created_at"},{"description":{"content":"Chiều sắp xếp (asc, desc)
\n","type":"text/plain"},"key":"sort_direction","value":"asc"}],"variable":[]}},"response":[{"id":"559e49a4-142e-4e04-ba58-fd6f9a7ead4e","name":"Successfully","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.oneprint.io/v1/orders?per_page=50&page=1&sort_by=created_at&sort_direction=asc","host":["https://api.oneprint.io/v1"],"path":["orders"],"query":[{"key":"per_page","value":"50"},{"key":"page","value":"1"},{"key":"sort_by","value":"created_at"},{"key":"sort_direction","value":"asc"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"page\": 1,\n \"per_page\": 50,\n \"total\": 2,\n \"data\": [\n {\n \"id\": 13,\n \"order_name\": \"5899-SN-10\",\n \"source_id\": \"#CDP-12936\",\n \"origin_id\": null,\n \"status\": \"PROCESSING\",\n \"total_price\": 25,\n \"production_cost\": 20,\n \"shipping_fee\": 5,\n \"shipping_info\": {\n \"name\": \"Ha Nguyen\",\n \"email\": \"vansitterle@hotmail.fr\",\n \"phone\": \"33640230945\",\n \"city\": \"Marckolsheim\",\n \"state\": \"Normandy\",\n \"address\": \"5 route du Rhin\",\n \"address2\": null,\n \"postal_code\": \"67390\",\n \"country\": \"FR\",\n \"company\": null,\n \"service\": \"EXPRESS\"\n },\n \"shipments\": [],\n \"items\": [\n {\n \"sku\": \"LSG2400-S\",\n \"quantity\": 1,\n \"print_positions\": [\n {\n \"position\": \"front\",\n \"design_url\": \"https://image.shutterstock.com/image-photo/happy-young-pug-dog-panting-260nw-2553323723.jpg\",\n \"mockup_url\": null\n }\n ]\n },\n {\n \"sku\": \"LSG2400-M\",\n \"quantity\": 2,\n \"print_positions\": [\n {\n \"position\": \"front\",\n \"design_url\": \"https://image.shutterstock.com/image-photo/happy-young-pug-dog-panting-260nw-2553323723.jpg\",\n \"mockup_url\": null\n }\n ]\n },\n {\n \"sku\": \"LSG2400-L\",\n \"quantity\": 1,\n \"print_positions\": [\n {\n \"position\": \"front\",\n \"design_url\": \"https://image.shutterstock.com/image-photo/happy-young-pug-dog-panting-260nw-2553323723.jpg\",\n \"mockup_url\": null\n }\n ]\n }\n ]\n },\n {\n \"id\": 24,\n \"order_name\": \"1960-SN-15\",\n \"source_id\": \"#CDP-12937\",\n \"origin_id\": null,\n \"status\": \"PROCESSING\",\n \"total_price\": 25,\n \"production_cost\": 20,\n \"shipping_fee\": 5,\n \"shipping_info\": {\n \"name\": \"Ha Nguyen\",\n \"email\": \"vansitterle@hotmail.fr\",\n \"phone\": \"33640230945\",\n \"city\": \"Marckolsheim\",\n \"state\": \"Normandy\",\n \"address\": \"5 route du Rhin\",\n \"address2\": null,\n \"postal_code\": \"67390\",\n \"country\": \"FR\",\n \"company\": null,\n \"service\": \"STANDARD\"\n },\n \"shipments\": [],\n \"items\": [\n {\n \"sku\": \"LSG2400-S\",\n \"quantity\": 1,\n \"print_positions\": [\n {\n \"position\": \"front\",\n \"design_url\": \"https://image.shutterstock.com/image-photo/happy-young-pug-dog-panting-260nw-2553323723.jpg\",\n \"mockup_url\": null\n }\n ]\n },\n {\n \"sku\": \"LSG2400-M\",\n \"quantity\": 2,\n \"print_positions\": [\n {\n \"position\": \"front\",\n \"design_url\": \"https://image.shutterstock.com/image-photo/happy-young-pug-dog-panting-260nw-2553323723.jpg\",\n \"mockup_url\": null\n }\n ]\n },\n {\n \"sku\": \"LSG2400-L\",\n \"quantity\": 1,\n \"print_positions\": [\n {\n \"position\": \"front\",\n \"design_url\": \"https://image.shutterstock.com/image-photo/happy-young-pug-dog-panting-260nw-2553323723.jpg\",\n \"mockup_url\": null\n }\n ]\n }\n ]\n }\n ]\n}"},{"id":"86ea5a67-4d35-4b5b-b5b6-e313e970fbd0","name":"Failed with per_page > 200","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.oneprint.io/v1/orders?per_page=300&page=1&sort_by=created_at&sort_direction=asc","host":["https://api.oneprint.io/v1"],"path":["orders"],"query":[{"key":"per_page","value":"300"},{"key":"page","value":"1"},{"key":"sort_by","value":"created_at"},{"key":"sort_direction","value":"asc"}]}},"status":"Unprocessable Content","code":422,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"per page field must not be greater than 200.\",\n \"errors\": {\n \"per_page\": [\n \"per page field must not be greater than 200.\"\n ]\n }\n}"}],"_postman_id":"86020d8e-0917-40f7-94ea-eea6e8dd30e3"}],"id":"cedaa311-3ab9-4c0d-aeee-e67835857094","description":"Hệ thống OnePrint hỗ trợ đầy đủ các thao tác tích hợp thông qua API, bao gồm:
\nTạo đơn hàng
\nXóa đơn hàng
\nLấy danh sách đơn hàng
\nXem chi tiết đơn hàng
\nThông tin đơn hàng:
\nid (string): ID của order trên hệ thống OnePrint.
order_name (string): Tên đơn hàng trên hệ thống OnePrint.
origin_id (string): ID của order trên hệ thống của Seller.
source_id (string): Tên đơn hàng trên hệ thống của seller.
status (string): Trạng thái đơn hàng (gồm những giá trị như sau: INCOMPLETE, UNPAID, PROCESSING, SHIPPED, CANCELLED).
total_price(float): Tổng chi phí của đơn (gồm cả phí ship).
production_cost(float): Tổng giá trị sản phẩm.
shipping_fee(float): Phí vận chuyển.
service (string): Hình thức vận chuyển của đơn hàng (gồm những giá trị như sau: STANDARD, EXPRESS).
shipping_info: Thông tin người nhận
items:
sku (string): Mã SKU của sản phẩm muốn đặt in.
quantity (int): Số lượng sản phẩm cần in.
print_positions:
position (string): Vị trí in (ví dụ: front, back...)
design_url (url): Link file thiết kế dùng để in thực tế.
mockup_url (url): Link ảnh mockup minh họa cho sản phẩm sau khi in.
Cho phép Seller đăng ký webhook để nhận thông báo tự động từ hệ thống OnePrint khi đơn hàng thay đổi trạng thái hoặc có cập nhật mới.
\nAPI này cho phép khai báo một URL để nhận thông báo sự kiện từ OnePrint. Khi webhook được tạo thành công, hệ thống sẽ tự động gửi dữ liệu về URL đó mỗi khi có cập nhật liên quan đến đơn hàng như trạng thái hay tracking đơn hàng.
\nURL phải là endpoint hợp lệ và có thể tiếp nhận HTTP POST.
\nCallback sẽ bao gồm thông tin đơn hàng và loại sự kiện (event_type).
\nĐối tác cần xác minh chữ ký để đảm bảo tính toàn vẹn dữ liệu (sử dụng HMAC signature giống như request đầu vào).
\nCho phép Seller kiểm tra URL webhook hiện tại và trạng thái kích hoạt.
\nAPI này trả về thông tin cấu hình webhook hiện tại mà Seller đã đăng ký, bao gồm:
\nURL đã đăng ký
\nTrạng thái hoạt động
\nMỗi khi có thay đổi trạng thái đơn hàng hoặc cập nhật tracking, hệ thống OnePrint sẽ gửi một request POST đến Webhook URL mà bạn đã đăng ký. Tương tự như phần HTTP headers OnePrint yêu cầu khi bạn gửi yêu cầu qua API đến OnePrint, OnePrint sẽ gửi thêm một số HTTP headers cùng với payload của sự kiện, bao gồm:
X-API-Key: Chuỗi API key do hệ thống cấp.
\nX-Timestamp: Thời gian gửi request (UNIX timestamp, tính bằng giây).
\nX-Signature: Chữ ký xác thực, tạo bằng HMAC SHA256.
\nĐể đảm bảo request được gửi từ OnePrint và không bị giả mạo, bạn có thể xác thực chữ ký X-Signature. Cách tạo X-Signature giống như khi bạn gọi API tới OnePrint, được mô tả chi tiết tại phần Authentication.
Cơ chế Retry (thử lại) khi OnePrint gửi webhook thất bại:
\nMỗi sự kiện sẽ được gửi tối đa 3 lần: Lần đầu tiên gửi ngay khi có sự kiện. Nếu thất bại, hệ thống sẽ retry tối đa 2 lần, mỗi lần cách nhau 1 giờ đồng hồ.
\nNếu có hơn 10 sự kiện liên tiếp gửi thất bại, hệ thống sẽ tự động vô hiệu hóa (inactive) Webhook URL tương ứng để đảm bảo ổn định hệ thống.
\nLưu ý: Mỗi store được tạo 1 webhook tương ứng. Để kích hoạt lại webhook bị inactive hoặc thay đổi Webhook URL, vui lòng liên hệ với quản trị viên hệ thống OnePrint.
\nDưới đây là ví dụ về data được gửi trong webhook tương ứng với các event:
\n{\n \"event_name\": \"update_status\",\n \"data\": {\n \"order_id\": 2274,\n \"status\": \"PROCESSING\",\n \"time\": \"2025-06-18T02:55:56.000000Z\"\n }\n}\n\nWebhook này được gửi khi đơn hàng có thêm tracking mới hoặc khi trạng thái (status) của bất kỳ tracking nào thay đổi. Mỗi lần gửi, tracking_data trả về toàn bộ danh sách tracking của đơn hàng.
{\n \"event_name\": \"update_tracking\",\n \"data\": {\n \"order_id\": 2608,\n \"tracking_data\": [\n {\n \"tracking_number\": \"A12345\",\n \"tracking_url\": \"https://track.oneprint.io/ORD-20240601-001\",\n \"vendor_name\": \"Colis\",\n \"status\": \"delivered\"\n },\n {\n \"tracking_number\": \"B67890\",\n \"tracking_url\": \"https://track.oneprint.io/ORD-20240601-002\",\n \"vendor_name\": \"Colis\",\n \"status\": \"on_return\"\n }\n ]\n }\n }\n\nstatus được trả về trong từng phần tử của tracking_data.
Mỗi tracking number trong cùng một đơn hàng có thể có trạng thái vận chuyển riêng.
\n