API Ship Toolkit

Les endpoints hébergés pour les étiquettes et les PDF acceptent du JSON via HTTPS et renvoient directement les fichiers PDF générés. Gardez les clés d'API hors du code source et envoyez-les comme jetons bearer.

Démarrage rapide

URL de basehttps://shiptoolkit.com

MéthodePOST pour les API de génération hébergées

AuthentificationAuthorization: Bearer <api-key>

CorpsContent-Type: application/json

IdempotenceIdempotency-Key: <unique value>

Succèsapplication/pdf

Les API hébergées d'étiquettes et de PDF nécessitent une clé d'API. Pour demander l'accès, contactez shiptoolkit@element-express.com.

Les réponses PDF réussies incluent Content-Disposition, X-Page-Count, X-Content-SHA256, ainsi que X-Label-Type ou X-PDF-Operation. Les réponses d'erreur sont du JSON avec un champ 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", "4x4", "4x3", "4x2"]
}

Assistant 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")

Assistant 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 d'étiquettes

Ces endpoints renvoient des fichiers PDF d'étiquettes et nécessitent une clé d'API bearer.

POST /v1/labels/amazon-fnsku

Créez une étiquette produit Amazon à partir d'un FNSKU de 10 caractères.

Champ	Type	Obligatoire	Par défaut	Contraintes
`sku`	`string`	`true`	`-`	`pattern: ^[A-Z0-9]{10}$`
`model`	`string`	`true`	`-`	`maxLength: 240`
`title`	`string`	`true`	`-`	`maxLength: 500`
`madeIn`	`string`	`true`	`-`	`maxLength: 80`
`labelSize`	`enum`	`true`	`-`	`standardLabelSize`
`oldSku`	`string`	`false`	`""`	`maxLength: 128`
`productCondition`	`enum`	`false`	`"other"`	`["new", "other"]`

Python

payload = {
    "sku": "X001ABC123",
    "model": "ABC-123",
    "title": "Sample product",
    "madeIn": "China",
    "productCondition": "new",
    "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": "new",
  "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

Add text overlays to Amazon FBA and UPS labels, then return 4 x 6 inch output pages with optional scaling and duplicate copies.

Champ	Type	Obligatoire	Par défaut	Contraintes
`pdfBase64`	`string`	`true`	`-`	`maxBytes: 7MB`
`filename`	`string`	`false`	`"amazon-fba-ups-labels.pdf"`	`maxLength: 160`
`fbaText`	`string`	`false`	`""`	`maxLength: 500`
`upsText`	`string`	`false`	`""`	`maxLength: 500`
`scalePercent`	`number`	`false`	`95`	`min: 1, max: 100`
`twoFbaCopies`	`boolean`	`false`	`false`	`-`
`twoUpsCopies`	`boolean`	`false`	`false`	`requires twoFbaCopies`

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")
);

Source pages may be native 4 x 6, 4.25 x 6, or US Letter pages with two labels. US Letter pages use the built-in two-label crop layout.

POST /v1/labels/walmart-sku

Créez une étiquette produit Walmart fulfillment à partir d'un SKU Walmart de 14 chiffres.

Champ	Type	Obligatoire	Par défaut	Contraintes
`sku`	`string`	`true`	`-`	`pattern: ^\d{14}$`
`model`	`string`	`true`	`-`	`maxLength: 240`
`title`	`string`	`true`	`-`	`maxLength: 500`
`madeIn`	`string`	`true`	`-`	`maxLength: 80`
`labelSize`	`enum`	`true`	`-`	`standardLabelSize`
`productCondition`	`enum`	`false`	`"other"`	`["new", "other"]`

Python

payload = {
    "sku": "12345678901234",
    "model": "ShipToolkit-001",
    "title": "Walmart fulfillment label",
    "madeIn": "China",
    "productCondition": "new",
    "labelSize": "2.25x1.25",
}
post_pdf("/v1/labels/walmart-sku", payload, "walmart-sku.pdf")

Java

String json = """
{
  "sku": "12345678901234",
  "model": "ShipToolkit-001",
  "title": "Walmart fulfillment label",
  "madeIn": "China",
  "productCondition": "new",
  "labelSize": "2.25x1.25"
}
""";
ShipToolkitApi.postPdf(
    "/v1/labels/walmart-sku",
    json,
    Path.of("walmart-sku.pdf")
);

POST /v1/labels/outbound-box

Créez une étiquette compacte de colis sortant avec un code-barres de boîte et un résumé des articles.

Champ	Type	Obligatoire	Par défaut	Contraintes
`boxId`	`string`	`true`	`-`	`maxLength: 80`
`organization`	`string`	`true`	`-`	`maxLength: 160`
`items`	`array<object>`	`true`	`-`	`maxItems: 200`
`items[].sku`	`string`	`false`	`items[].model`	`maxLength: 128`
`items[].quantity`	`string\|number`	`false`	`items[].qty`	`maxLength: 20`
`dimension`	`string`	`false`	`""`	`maxLength: 120`
`weight`	`string`	`false`	`""`	`maxLength: 120`
`labelSize`	`enum`	`false`	`"2.25x1.25"`	`standardLabelSize`
`createBarcode`	`boolean`	`false`	`true`	`-`
`barcodeValue`	`string`	`false`	`boxId`	`maxLength: 80`

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

Créez des étiquettes de marquage carton avec une page pour chaque carton.

Champ	Type	Obligatoire	Par défaut	Contraintes
`consignee`	`string`	`true`	`-`	`maxLength: 120`
`shipper`	`string`	`true`	`-`	`maxLength: 120`
`destinationAddress`	`string`	`true`	`-`	`maxLength: 500`
`orderNo`	`string`	`true`	`-`	`maxLength: 80`
`cartonTotal`	`integer`	`true`	`-`	`min: 1`
`quantity`	`string\|number`	`true`	`-`	`maxLength: 80`
`productDescription`	`string`	`true`	`-`	`maxLength: 500`
`labelSize`	`enum`	`false`	`"6x4"`	`cartonMarkLabelSize`
`barcodeValue`	`string`	`false`	`orderNo`	`maxLength: 120`
`cartonStart`	`integer`	`false`	`1`	`min: 1`

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

Personnalisez les PDF d'étiquettes Amazon Transparency avec FNSKU, modèle, date et taille d'étiquette cible.

Champ	Type	Obligatoire	Par défaut	Contraintes
`pdfBase64`	`string`	`true`	`-`	`maxBytes: 7MB`
`fnsku`	`string`	`true`	`-`	`maxLength: 80`
`labelSize`	`enum`	`true`	`-`	`standardLabelSize`
`model`	`string`	`false`	`""`	`maxLength: 240`
`date`	`string`	`false`	`now`	`maxLength: 40`

Python

payload = {
    "pdfBase64": pdf_base64("transparency-source.pdf"),
    "fnsku": "X001ABC123",
    "model": "MODEL-1",
    "date": "2026-07-17",
    "labelSize": "2.25x1.25",
}
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

Ces endpoints renvoient des fichiers PDF transformés et nécessitent une clé d'API bearer.

POST /v1/pdf/resize

Redimensionnez chaque page selon un format prédéfini ou personnalisé sans rogner le contenu source.

Champ	Type	Obligatoire	Par défaut	Contraintes
`pdfBase64`	`string`	`true`	`-`	`maxBytes: 7MB`
`filename`	`string`	`false`	`"document.pdf"`	`maxLength: 160`
`size`	`enum`	`false`	`"letter"`	`"letter"\|"legal"\|"a4"\|"4x6"\|"custom"`
`orientation`	`enum`	`false`	`"match"`	`"match"\|"portrait"\|"landscape"`
`customWidth`	`number`	`false`	`-`	`required when size="custom"`
`customHeight`	`number`	`false`	`-`	`required when size="custom"`
`customUnit`	`enum`	`false`	`"in"`	`"in"\|"mm"`

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

Mettez le contenu de la page à l'échelle autour du centre tout en conservant la taille de chaque page.

Champ	Type	Obligatoire	Par défaut	Contraintes
`pdfBase64`	`string`	`true`	`-`	`maxBytes: 7MB`
`filename`	`string`	`false`	`"document.pdf"`	`maxLength: 160`
`scalePercent`	`number`	`false`	`100`	`min: 1, max: 400`

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"));