API de Ship Toolkit

Los endpoints alojados de etiquetas y PDF aceptan JSON por HTTPS y devuelven directamente archivos PDF generados. Mantenga las claves de API fuera del código fuente y envíelas como tokens bearer.

Inicio rápido

URL basehttps://shiptoolkit.com

MétodoPOST para las API de generación alojadas

AutenticaciónAuthorization: Bearer <api-key>

CuerpoContent-Type: application/json

IdempotenciaIdempotency-Key: <unique value>

Éxitoapplication/pdf para las API de etiquetas y PDF

Las API alojadas de etiquetas y PDF requieren una clave de API. Para solicitar acceso, contacte con shiptoolkit@element-express.com.

Las respuestas PDF correctas incluyen Content-Disposition, X-Page-Count, X-Content-SHA256, y también X-Label-Type o X-PDF-Operation. Las respuestas de error son JSON con un campo error .

Ayudante de 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")

Ayudante de 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 de etiquetas

Estos endpoints devuelven archivos PDF de etiquetas y requieren una clave de API bearer.

POST /v1/labels/amazon-fnsku

Cree una etiqueta de producto de Amazon a partir de un FNSKU de 10 caracteres.

Campos obligatorios: sku, model, title, madeIn, labelSize
Campos opcionales: oldSku, productCondition

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/walmart-sku

Cree una etiqueta de producto de Walmart fulfillment a partir de un SKU de Walmart de 14 dígitos.

Campos obligatorios: sku, model, title, madeIn, labelSize
Validación: sku debe contener exactamente 14 dígitos.

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

Cree una etiqueta compacta para caja de salida con código de barras de caja y resumen de artículos.

Campos obligatorios: boxId, organization, items
Campos opcionales: dimension, weight, labelSize

Python

payload = {
    "boxId": "BOX-1001",
    "organization": "Example Seller",
    "dimension": "20 x 10 x 8 in",
    "weight": "15 lbs",
    "labelSize": "2.25x1.25",
    "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": "2.25x1.25",
  "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

Cree etiquetas de marca de caja con una página para cada caja.

Campos obligatorios: consignee, shipper, destinationAddress, orderNo, cartonTotal, quantity, productDescription
Campos opcionales: labelSize, barcodeValue, cartonStart

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

Personalice PDF de etiquetas Amazon Transparency con FNSKU, modelo, fecha y tamaño de etiqueta de destino.

Campos obligatorios: pdfBase64, fnsku, labelSize
Campos opcionales: model, date

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 de PDF

Estos endpoints devuelven archivos PDF transformados y requieren una clave de API bearer.

POST /v1/pdf/resize

Redimensione cada página a un tamaño predefinido o personalizado sin recortar el contenido de origen.

Campos obligatorios: pdfBase64
Campos opcionales: filename, size, orientation, customWidth, customHeight, customUnit

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

Escale el contenido de la página alrededor del centro manteniendo sin cambios el tamaño de cada página.

Campos obligatorios: pdfBase64
Campos opcionales: filename, scalePercent de 1 a 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"));