API do Ship Toolkit

Os endpoints hospedados de etiquetas e PDF aceitam JSON via HTTPS e retornam diretamente os arquivos PDF gerados. Mantenha as chaves de API fora do código-fonte e envie-as como tokens bearer.

Início rápido

URL basehttps://shiptoolkit.com

MétodoPOST para APIs de geração hospedadas

AutenticaçãoAuthorization: Bearer <api-key>

CorpoContent-Type: application/json

IdempotênciaIdempotency-Key: <unique value>

Sucessoapplication/pdf

As APIs hospedadas de etiquetas e PDF exigem uma chave de API. Para solicitar acesso, entre em contato com shiptoolkit@element-express.com.

Respostas PDF bem-sucedidas incluem Content-Disposition, X-Page-Count, X-Content-SHA256, e também X-Label-Type ou X-PDF-Operation. Respostas de erro são JSON com um campo 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"]
}

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

Auxiliar 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));
    }
}

APIs de etiquetas

Esses endpoints retornam arquivos PDF de etiquetas e exigem uma chave de API bearer.

POST /v1/labels/amazon-fnsku

Crie uma etiqueta de produto da Amazon a partir de um FNSKU de 10 caracteres.

Campo	Tipo	Obrigatório	Padrão	Restrições
`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.

Campo	Tipo	Obrigatório	Padrão	Restrições
`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

Crie uma etiqueta de produto Walmart fulfillment a partir de um SKU Walmart de 14 dígitos.

Campo	Tipo	Obrigatório	Padrão	Restrições
`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

Crie uma etiqueta compacta para caixa de saída com código de barras da caixa e resumo dos itens.

Campo	Tipo	Obrigatório	Padrão	Restrições
`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

Crie etiquetas de marcação de caixa com uma página para cada caixa.

Campo	Tipo	Obrigatório	Padrão	Restrições
`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

Personalize PDFs de etiquetas Amazon Transparency com FNSKU, modelo, data e tamanho de etiqueta de destino.

Campo	Tipo	Obrigatório	Padrão	Restrições
`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")
);

APIs de PDF

Esses endpoints retornam arquivos PDF transformados e exigem uma chave de API bearer.

POST /v1/pdf/resize

Redimensione cada página para um tamanho predefinido ou personalizado sem recortar o conteúdo de origem.

Campo	Tipo	Obrigatório	Padrão	Restrições
`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

Dimensione o conteúdo da página a partir do centro mantendo o tamanho de cada página inalterado.

Campo	Tipo	Obrigatório	Padrão	Restrições
`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"));