API Ship Toolkit
Các endpoint nhãn và PDF trên máy chủ nhận JSON qua HTTPS và trả trực tiếp tệp PDF đã tạo. Không đưa khóa API vào mã nguồn; hãy gửi khóa dưới dạng bearer token.
Bắt đầu nhanh
URL cơ sởhttps://shiptoolkit.com
Phương thứcPOST cho các API tạo tệp trên máy chủ
Xác thựcAuthorization: Bearer <api-key>
Nội dung yêu cầuContent-Type: application/json
Chống xử lý lặpIdempotency-Key: <unique value>
Thành côngapplication/pdf
Các API nhãn và PDF trên máy chủ yêu cầu khóa API. Để đăng ký truy cập, liên hệ
shiptoolkit@element-express.com.
Phản hồi PDF thành công bao gồm Content-Disposition, X-Page-Count,
X-Content-SHA256, và một trong hai X-Label-Type hoặc X-PDF-Operation. Phản hồi lỗi là JSON có trường error .
{
"standardLabelSize": [
"2.00x1.00",
"2.25x1.25",
"2.50x1.00",
"3.00x1.00",
"3.00x1.50",
"3.00x2.00",
"4.00x2.00",
"50x30mm",
"60x30mm",
"60x40mm"
],
"cartonMarkLabelSize": ["6x4", "4x6", "4x4", "4x3", "4x2"]
}
Hàm hỗ trợ Python
import base64
import json
import os
import uuid
import urllib.request
from pathlib import Path
BASE_URL = "https://shiptoolkit.com"
API_KEY = os.environ["SHIPTOOLKIT_API_KEY"]
def post_pdf(path, payload, output_file):
request = urllib.request.Request(
BASE_URL + path,
data=json.dumps(payload).encode("utf-8"),
method="POST",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"User-Agent": "ShipToolkit-API-Example/1.0",
},
)
with urllib.request.urlopen(request, timeout=60) as response:
pdf = response.read()
if not pdf.startswith(b"%PDF-"):
raise RuntimeError("Ship Toolkit returned a non-PDF response.")
Path(output_file).write_bytes(pdf)
def pdf_base64(filename):
return base64.b64encode(Path(filename).read_bytes()).decode("ascii")
Hàm hỗ trợ Java
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;
import java.util.UUID;
class ShipToolkitApi {
static final String BASE_URL = "https://shiptoolkit.com";
static final String API_KEY = System.getenv("SHIPTOOLKIT_API_KEY");
static final HttpClient CLIENT = HttpClient.newHttpClient();
static void postPdf(String path, String json, Path outputFile)
throws IOException, InterruptedException {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(BASE_URL + path))
.header("Authorization", "Bearer " + API_KEY)
.header("Content-Type", "application/json")
.header("Idempotency-Key", UUID.randomUUID().toString())
.header("User-Agent", "ShipToolkit-API-Example/1.0")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<byte[]> response = CLIENT.send(
request,
HttpResponse.BodyHandlers.ofByteArray()
);
if (response.statusCode() != 200) {
throw new IOException("Ship Toolkit API failed: " + response.statusCode());
}
Files.write(outputFile, response.body());
}
static String pdfBase64(Path file) throws IOException {
return Base64.getEncoder().encodeToString(Files.readAllBytes(file));
}
}
API nhãn
Các endpoint này trả tệp nhãn PDF và yêu cầu khóa API dưới dạng bearer token.
POST /v1/labels/amazon-fnsku
Tạo nhãn sản phẩm Amazon từ mã FNSKU gồm 10 ký tự.
productCondition chấp nhận new, used, hoặc empty
không phân biệt chữ hoa chữ thường. Nhãn in New hoặc Used trước mẫu sản phẩm. Dùng empty để không in tình trạng sản phẩm.
Python
payload = {
"sku": "X001ABC123",
"model": "ABC-123",
"title": "Sample product",
"madeIn": "China",
"productCondition": "used",
"labelSize": "2.25x1.25",
"oldSku": "OLD-123",
}
post_pdf("/v1/labels/amazon-fnsku", payload, "amazon-fnsku.pdf")
Java
String json = """
{
"sku": "X001ABC123",
"model": "ABC-123",
"title": "Sample product",
"madeIn": "China",
"productCondition": "used",
"labelSize": "2.25x1.25",
"oldSku": "OLD-123"
}
""";
ShipToolkitApi.postPdf(
"/v1/labels/amazon-fnsku",
json,
Path.of("amazon-fnsku.pdf")
);
POST /v1/labels/amazon-fba-ups
Thêm văn bản lên nhãn Amazon FBA và UPS, sau đó trả các trang khổ 4 x 6 inch với tùy chọn co giãn và tạo bản sao.
Python
payload = {
"pdfBase64": pdf_base64("fba-ups-source.pdf"),
"filename": "fba-ups-source.pdf",
"fbaText": "BOX 1",
"upsText": "CARTON A",
"scalePercent": 95,
"twoFbaCopies": False,
"twoUpsCopies": False,
}
post_pdf("/v1/labels/amazon-fba-ups", payload, "fba-ups-labels.pdf")
Java
String source = ShipToolkitApi.pdfBase64(Path.of("fba-ups-source.pdf"));
String json = """
{
"pdfBase64": "%s",
"filename": "fba-ups-source.pdf",
"fbaText": "BOX 1",
"upsText": "CARTON A",
"scalePercent": 95
}
""".formatted(source);
ShipToolkitApi.postPdf(
"/v1/labels/amazon-fba-ups",
json,
Path.of("fba-ups-labels.pdf")
);
Trang nguồn có thể là khổ 4 x 6, 4.25 x 6 hoặc US Letter chứa hai nhãn. Các vùng cắt trên khổ US Letter được thêm khoảng đệm, điều chỉnh vừa trang đầu ra 4 x 6, sau đó áp dụng giá trị scalePercent đã yêu cầu từ tâm trang.
POST /v1/labels/walmart-gtin
Tạo nhãn sản phẩm Walmart GTIN từ mã SKU Walmart gồm 14 chữ số.
Python
payload = {
"sku": "12345678901234",
"model": "ShipToolkit-001",
"title": "Walmart GTIN label",
"madeIn": "China",
"productCondition": "new",
"labelSize": "2.25x1.25",
}
post_pdf("/v1/labels/walmart-gtin", payload, "walmart-gtin.pdf")
Java
String json = """
{
"sku": "12345678901234",
"model": "ShipToolkit-001",
"title": "Walmart GTIN label",
"madeIn": "China",
"productCondition": "new",
"labelSize": "2.25x1.25"
}
""";
ShipToolkitApi.postPdf(
"/v1/labels/walmart-gtin",
json,
Path.of("walmart-gtin.pdf")
);
POST /v1/labels/outbound-box
Tạo nhãn thùng xuất hàng nhỏ gọn có mã vạch thùng và tóm tắt sản phẩm.
Python
payload = {
"boxId": "BOX-1001",
"organization": "Example Seller",
"dimension": "20 x 10 x 8 in",
"weight": "15 lbs",
"labelSize": "3.00x1.50",
"createBarcode": true,
"items": [
{"sku": "X001ABC123", "quantity": 4},
{"sku": "X001ABC456", "quantity": 2},
],
}
post_pdf("/v1/labels/outbound-box", payload, "outbound-box.pdf")
Java
String json = """
{
"boxId": "BOX-1001",
"organization": "Example Seller",
"dimension": "20 x 10 x 8 in",
"weight": "15 lbs",
"labelSize": "3.00x1.50",
"createBarcode": true,
"items": [
{"sku": "X001ABC123", "quantity": 4},
{"sku": "X001ABC456", "quantity": 2}
]
}
""";
ShipToolkitApi.postPdf(
"/v1/labels/outbound-box",
json,
Path.of("outbound-box.pdf")
);
POST /v1/labels/carton-mark
Tạo nhãn ký mã hiệu thùng hàng, mỗi thùng tương ứng một trang.
Python
payload = {
"consignee": "Receiving Team",
"shipper": "Example Seller",
"destinationAddress": "123 Warehouse Way, Newark, DE 19713",
"orderNo": "PO-20260717-001",
"cartonTotal": 3,
"quantity": "50 PCS",
"productDescription": "Portable night light",
"labelSize": "6x4",
}
post_pdf("/v1/labels/carton-mark", payload, "carton-mark.pdf")
Java
String json = """
{
"consignee": "Receiving Team",
"shipper": "Example Seller",
"destinationAddress": "123 Warehouse Way, Newark, DE 19713",
"orderNo": "PO-20260717-001",
"cartonTotal": 3,
"quantity": "50 PCS",
"productDescription": "Portable night light",
"labelSize": "6x4"
}
""";
ShipToolkitApi.postPdf(
"/v1/labels/carton-mark",
json,
Path.of("carton-mark.pdf")
);
POST /v1/labels/transparency
Tùy chỉnh PDF nhãn Amazon Transparency với FNSKU, mẫu sản phẩm, ngày và kích thước nhãn đích.
Python
payload = {
"pdfBase64": pdf_base64("transparency-source.pdf"),
"fnsku": "X001ABC123",
"model": "MODEL-1",
"date": "2026-07-17",
"labelSize": "2.25x1.25",
"textOptions": {
"model": {"enabled": True, "x": 0.04, "y": 0.78},
"fnsku": {"enabled": False, "x": 0.36, "y": 0.66},
"date": {"enabled": True, "x": 0.76, "y": 0.78},
},
}
post_pdf("/v1/labels/transparency", payload, "transparency.pdf")
Java
String source = ShipToolkitApi.pdfBase64(Path.of("transparency-source.pdf"));
String json = """
{
"pdfBase64": "%s",
"fnsku": "X001ABC123",
"model": "MODEL-1",
"date": "2026-07-17",
"labelSize": "2.25x1.25"
}
""".formatted(source);
ShipToolkitApi.postPdf(
"/v1/labels/transparency",
json,
Path.of("transparency.pdf")
);
API PDF
Các endpoint này trả tệp PDF đã biến đổi và yêu cầu khóa API dưới dạng bearer token.
POST /v1/pdf/resize
Đổi kích thước mọi trang sang khổ có sẵn hoặc tùy chỉnh mà không cắt nội dung nguồn.
Python
payload = {
"pdfBase64": pdf_base64("source.pdf"),
"filename": "source.pdf",
"size": "custom",
"customWidth": 2.25,
"customHeight": 1.25,
"customUnit": "in",
}
post_pdf("/v1/pdf/resize", payload, "resized.pdf")
Java
String source = ShipToolkitApi.pdfBase64(Path.of("source.pdf"));
String json = """
{
"pdfBase64": "%s",
"filename": "source.pdf",
"size": "custom",
"customWidth": 2.25,
"customHeight": 1.25,
"customUnit": "in"
}
""".formatted(source);
ShipToolkitApi.postPdf("/v1/pdf/resize", json, Path.of("resized.pdf"));
POST /v1/pdf/scale
Co giãn nội dung quanh tâm trang, giữ nguyên kích thước từng trang.
Python
payload = {
"pdfBase64": pdf_base64("source.pdf"),
"filename": "source.pdf",
"scalePercent": 82,
}
post_pdf("/v1/pdf/scale", payload, "scaled.pdf")
Java
String source = ShipToolkitApi.pdfBase64(Path.of("source.pdf"));
String json = """
{
"pdfBase64": "%s",
"filename": "source.pdf",
"scalePercent": 82
}
""".formatted(source);
ShipToolkitApi.postPdf("/v1/pdf/scale", json, Path.of("scaled.pdf"));
