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`	`"new"`	`["new", "used", "empty"]`

productCondition accepts new, used, or empty case-insensitively. It prints Neuf ou Utilisé before the model. Use empty to print no condition text.

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

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

Les pages source peuvent être des étiquettes natives 4 x 6, 4,25 x 6 ou des pages US Letter avec deux étiquettes. Les fenêtres de recadrage US Letter sont élargies, ajustées à nouveau dans des pages de sortie 4 x 6, puis le scalePercent demandé est appliqué depuis le centre de la page.

POST /v1/labels/walmart-gtin

Créez une étiquette produit Walmart GTIN à 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`	`"new"`	`["new", "used", "empty"]`

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

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"\|"a5"\|"4x6"\|"custom"`
`orientation`	`enum`	`false`	`"match"`	`"match"\|"portrait"\|"landscape"`
`scaleMode`	`enum`	`false`	`"preserve-original-size"`	`"preserve-original-size"\|"fit-to-page"\|"scale-down-only"`
`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"));