משלוחים

יצירה, הצגת רשימה, שליפה, מעקב וביטול של משלוחים, ושליפת התוויות להדפסה שלהם. המשלוחים אינם תלויים בחברת שילוח: מבני הבקשה והתשובה זהים ללא קשר לחברת השילוח שמאחורי הקלעים. כל משלוח נוצר ומשויך תחת חשבון חברת שילוח יחיד (רישיון); הוא מזוהה ב-API באמצעות ה-uuid שלו.

כל ה-endpoints בעמוד זה דורשים אימות client-credentials ופועלים תחת רישיון אחד שנקבע. תשובות משתמשות במעטפת הסטנדרטית { "data": ... }; שגיאות משתמשות ב-{ "error": { ... } }.

`GET` /shipments

הצגת רשימת המשלוחים של הקורא, עם עימוד. מכסה את כל הרישיונות שבבעלות החשבון אלא אם license_key מצמצם אותה. אימות: client credentials. רישיון: אופציונלי.

פרמטרים

Query:

שדה	סוג	חובה	תיאור
`license_key`	string	לא	‏`licenses.key` לצמצום התוצאות לחשבון שילוח אחד. אם יישמט, הרשימה מכסה את כל הרישיונות שלכם.
`filter[active]`	boolean	לא	סינון לפי מצב פעילות. `true` מחזיר רק משלוחים פעילים, `false` רק לא-פעילים. השמיטו כדי לקבל את כולם.
`filter[type]`	integer	לא	סוג שירות. `1` מסירה, `2` איסוף. ‏`filter[type]=2` היא הדרך להציג החזרות.
`sort`	string	לא	מפתח מיון שמוחל על-ידי הרפוזיטורי (למשל שם עמודה, אפשר עם קידומת `-` למיון יורד).
`per_page`	integer	לא	פריטים לעמוד. ברירת מחדל `25`, מוגבל ל-`100`.

דוגמת בקשה

bash

curl --location 'https://app.shipos.co.il/api/v2/shipments?filter[active]=true&per_page=25' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json'

// Node.js 18+ / דפדפנים — בלי תלויות
const url = new URL('https://app.shipos.co.il/api/v2/shipments')
url.searchParams.set('filter[active]', 'true')
url.searchParams.set('per_page', '25')

const response = await fetch(url, {
  headers: {
    'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
    'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
    Accept: 'application/json',
  },
})

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data: shipments, meta } = await response.json()
console.log(`${shipments.length} of ${meta.total} shipments`)

php

<?php
// composer require guzzlehttp/guzzle

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.shipos.co.il/api/v2/',
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
    ],
]);

$payload = json_decode($client->get('shipments', [
    'query' => ['filter[active]' => 'true', 'per_page' => 25],
])->getBody()->getContents(), true);

echo count($payload['data']), ' of ', $payload['meta']['total'], PHP_EOL;

php

<?php

use Illuminate\Support\Facades\Http;

$payload = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
])
    ->acceptJson()
    ->get('https://app.shipos.co.il/api/v2/shipments', [
        'filter[active]' => 'true',
        'per_page' => 25,
    ])
    ->throw()
    ->json();

logger()->info(count($payload['data']).' of '.$payload['meta']['total']);

python

# pip install httpx
import os

import httpx

response = httpx.get(
    "https://app.shipos.co.il/api/v2/shipments",
    params={"filter[active]": "true", "per_page": 25},
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
    },
)
response.raise_for_status()
payload = response.json()

print(len(payload["data"]), "of", payload["meta"]["total"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET",
		"https://app.shipos.co.il/api/v2/shipments?filter[active]=true&per_page=25", nil)
	req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
	req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
	req.Header.Set("Accept", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(body)) // {"data":[...],"meta":{...}}
}

java

// Java 17+ — java.net.http, בלי תלויות (פרסור עם Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ShipOsListShipments {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.shipos.co.il/api/v2/shipments"
                + "?filter%5Bactive%5D=true&per_page=25"))
            .header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
            .header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
            .header("Accept", "application/json")
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new RuntimeException("ShipOS error: " + response.body());
        }

        System.out.println(response.body()); // {"data":[...],"meta":{...}}
    }
}

csharp

// .NET 8+ — System.Net.Http.Json
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient
{
    BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));

var payload = await http.GetFromJsonAsync<JsonDocument>(
        "shipments?filter[active]=true&per_page=25")
    ?? throw new InvalidOperationException("Empty response");

var meta = payload.RootElement.GetProperty("meta");
Console.WriteLine($"total: {meta.GetProperty("total").GetInt32()}");

ruby

require "net/http"
require "json"

uri = URI("https://app.shipos.co.il/api/v2/shipments")
uri.query = URI.encode_www_form("filter[active]" => "true", "per_page" => 25)

request = Net::HTTP::Get.new(uri)
request["X-Client-Id"] = ENV.fetch("SHIPOS_CLIENT_ID")
request["X-Client-Secret"] = ENV.fetch("SHIPOS_CLIENT_SECRET")
request["Accept"] = "application/json"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise "ShipOS error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

payload = JSON.parse(response.body)
puts "#{payload["data"].size} of #{payload.dig("meta", "total")}"

rust

// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let payload: Value = reqwest::Client::new()
        .get("https://app.shipos.co.il/api/v2/shipments")
        .query(&[("filter[active]", "true"), ("per_page", "25")])
        .header("X-Client-Id", std::env::var("SHIPOS_CLIENT_ID")?)
        .header("X-Client-Secret", std::env::var("SHIPOS_CLIENT_SECRET")?)
        .header("Accept", "application/json")
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    let count = payload["data"].as_array().map_or(0, Vec::len);
    println!("{} of {}", count, payload["meta"]["total"]);
    Ok(())
}

תשובה `200`

אוסף מעומד. כל איבר הוא אובייקט משלוח; מטא-נתוני עימוד נכללים תחת links ו-meta.

json

{
  "data": [
    {
      "uuid": "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88",
      "tracking_code": "66747921",
      "carrier": { "id": 3, "name": "HFD" },
      "status": { "code": "1", "description": "Created", "is_delivered": false },
      "service_type": "1",
      "is_active": true,
      "recipient": {
        "name": "ישראל ישראלי",
        "phone": "0521234567",
        "company": null,
        "address": {
          "street": "הרצל",
          "number": "10",
          "city": "תל אביב",
          "state": null,
          "zip": "6100000",
          "country": "IL"
        }
      },
      "pickup_point_id": null,
      "packages": 1,
      "cod": null,
      "order": { "id": "1042", "number": "1042" },
      "references": { "external_id": null },
      "short_tracking_code": null,
      "label_generated": false,
      "collection_status": null,
      "collected_at": null,
      "ready_at": null,
      "created_at": "2026-07-29T09:14:00.000000Z",
      "updated_at": "2026-07-29T09:14:00.000000Z"
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": null },
  "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }
}

שגיאות

סטטוס	קוד	מתי
401	`unauthenticated`	client credentials חסרים או לא תקינים.
403	`forbidden`	ה-`license_key` אינו בבעלות הקורא, או שהרישיון שנקבע אינו פעיל / פג תוקף, או שלחשבון אין רישיון פעיל.
422	`validation_failed`	לחשבון יש יותר מרישיון אחד ו-`license_key` הושמט.

`POST` /shipments

יצירת משלוח מול חברת השילוח. אימות: client credentials. רישיון: חובה.

גוף הבקשה הוא מעטפת { ship_data, order } הפונה לחברת השילוח. ship_data הוא ה-payload השטוח עבור חברת השילוח (איש קשר, יעד, אפשרויות שירות); order הוא הקשר ההזמנה שנשמר לצד המשלוח, ובלוק ה-shipping שבו הוא תמונת-מצב הנמען שנכתבת על רשומת המשלוח.

היצירה היא אידמפוטנטית ועמידה בקריסות. אפשר להעביר כותרת בקשה אופציונלית Idempotency-Key כדי לקשור את היצירה למפתח שבחר הלקוח; אחרת נעשה שימוש בטביעת-אצבע יציבה של הגוף. ראו אידמפוטנטיות לחוזה המלא, כולל התנהגות idempotency_key_conflict.

שדות בבעלות השרת

ship_data.license_key,‏ ship_data.license_id ו-ship_data.shipping_id מתעלמים מהם אם נשלחו — הרישיון נקבע מתוך פרטי האימות שלכם (וה-license_key ברמה העליונה), לעולם לא מתוך הגוף.

פרמטרים

גוף ברמה העליונה:

שדה	סוג	חובה	תיאור
`license_key`	string	מותנה	ה-`licenses.key` של חשבון חברת השילוח. אופציונלי עם רישיון פעיל יחיד; חובה עם יותר מאחד. מקסימום 255.
`ship_data`	object	כן	payload המשלוח הפונה לחברת השילוח. ראו בהמשך.
`order`	object	כן	מעטפת ההזמנה. ראו בהמשך.

ship_data:

שדה	סוג	חובה	תיאור
`ship_data.contact_name`	string	כן	שם איש הקשר של הנמען. מקסימום 255.
`ship_data.contact_phone`	string	כן	טלפון איש הקשר של הנמען. מקסימום 32.
`ship_data.contact_mail`	string (email)	לא	דוא"ל הנמען. מקסימום 255.
`ship_data.street`	string	מותנה	רחוב היעד. חובה אלא אם סופק `ship_data.pickup`. מקסימום 255.
`ship_data.number`	string	לא	מספר בית/בניין ביעד. מקסימום 32.
`ship_data.city`	string	מותנה	עיר היעד. חובה אלא אם סופק `ship_data.pickup`. מקסימום 255.
`ship_data.entrance`	string	לא	כניסה לבניין. מקסימום 32.
`ship_data.floor`	string	לא	קומה. מקסימום 32.
`ship_data.apartment`	string	לא	דירה. מקסימום 32.
`ship_data.company`	string	לא	שם חברה ביעד. מקסימום 255.
`ship_data.type`	integer	כן	כיוון: `1` = משלוח רגיל, `2` = איסוף.
`ship_data.return`	integer	כן	מצב החזרה: `1` = חד-כיווני, `2` = הלוך-ושוב.
`ship_data.packages`	integer	כן	מספר חבילות. מינימום 1, מקסימום 100.
`ship_data.pickup`	string	לא	מזהה נקודת איסוף (מפעיל משלוחים לנקודת איסוף). מקסימום 64. כשהוא מוגדר, `street`/`city` אינם נדרשים.
`ship_data.pickup_address`	string	לא	כתובת נקודת האיסוף בפורמט קריא. מקסימום 255.
`ship_data.note`	string	לא	הערת משלוח. מקסימום 1000.
`ship_data.extra_note`	string	לא	הערה נוספת. מקסימום 1000.
`ship_data.urgent`	boolean	לא	בקשה לטיפול דחוף.
`ship_data.motor`	integer	לא	דגל שליח אופנוע: `0` או `1`.
`ship_data.collect`	boolean	לא	דגל גבייה/COD.
`ship_data.exaction_date`	date	לא	תאריך איסוף/גבייה מבוקש.
`ship_data.delivery_time`	string	לא	חלון זמן משלוח מבוקש. מקסימום 64.
`ship_data.IsManual`	boolean	לא	מסמן את המשלוח כהוזן ידנית.

order:

שדה	סוג	חובה	תיאור
`order.id`	string	לא	מזהה ההזמנה שלכם. מקסימום 64. משמש כהפניית ההזמנה הנייטרלית.
`order.number`	string	לא	מספר הזמנה קריא. מקסימום 64. נופל חזרה ל-`order.id` עבור ההפניה.
`order.status`	string	לא	סטטוס ההזמנה. מקסימום 64.
`order.currency`	string	לא	מטבע ISO. מקסימום 8.
`order.total`	number	לא	סך ההזמנה. מינימום 0.
`order.customer_id`	mixed	לא	מזהה הלקוח שלכם.
`order.customer_note`	string	לא	הערת לקוח. מקסימום 1000.
`order.source`	string	לא	תווית מקור/פלטפורמת ההזמנה. מקסימום 32.
`order.shipping`	object	כן	תמונת-מצב הנמען (ראו בהמשך).
`order.billing`	object	לא	בלוק חיוב; משקף את shipping, מאומת באופן רופף.
`order.order_items`	array	לא	שורות פריטים (ראו בהמשך).

order.shipping (תמונת-מצב הנמען; כל השדות יכולים להיות null):

שדה	סוג	חובה	תיאור
`order.shipping.first_name`	string	לא	שם פרטי של הנמען. מקסימום 255.
`order.shipping.last_name`	string	לא	שם משפחה של הנמען. מקסימום 255.
`order.shipping.company`	string	לא	חברת הנמען. מקסימום 255.
`order.shipping.phone`	string	לא	טלפון הנמען. מקסימום 32.
`order.shipping.email`	string (email)	לא	דוא"ל הנמען. מקסימום 255.
`order.shipping.address_1`	string	לא	שורת כתובת 1. מקסימום 255.
`order.shipping.address_2`	string	לא	שורת כתובת 2. מקסימום 255.
`order.shipping.city`	string	לא	עיר. מקסימום 255.
`order.shipping.state`	string	לא	מדינה/מחוז. מקסימום 255.
`order.shipping.postcode`	string	לא	מיקוד. מקסימום 16.
`order.shipping.country`	string	לא	קוד מדינה ISO-2. מקסימום 2.

order.order_items[] (כל השדות יכולים להיות null):

שדה	סוג	חובה	תיאור
`order.order_items.*.sku`	string	לא	מק"ט הפריט. מקסימום 255.
`order.order_items.*.name`	string	לא	שם הפריט. מקסימום 255.
`order.order_items.*.quantity`	integer	לא	כמות. מינימום 1.
`order.order_items.*.price`	number	לא	מחיר ליחידה. מינימום 0.
`order.order_items.*.total`	number	לא	סך השורה. מינימום 0.

דוגמת בקשה

bash

curl --location 'https://app.shipos.co.il/api/v2/shipments' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 9c1a5f4e-2b6d-4a3e-8f10-7d0c2b3a4e5f' \
--data '{
  "license_key": "b3f1c9a7d2e04f8a9c6b1e2d3f4a5b6c",
  "ship_data": {
    "contact_name": "ישראל ישראלי",
    "contact_phone": "0521234567",
    "contact_mail": "dana@example.com",
    "street": "הרצל",
    "number": "10",
    "city": "תל אביב",
    "floor": "3",
    "apartment": "12",
    "type": 1,
    "return": 1,
    "packages": 1,
    "note": "להשאיר אצל השומר"
  },
  "order": {
    "id": "1042",
    "number": "1042",
    "currency": "ILS",
    "total": 199.90,
    "source": "custom",
    "shipping": {
      "first_name": "ישראל",
      "last_name": "ישראלי",
      "phone": "0521234567",
      "email": "dana@example.com",
      "address_1": "הרצל 10",
      "city": "תל אביב",
      "postcode": "6100000",
      "country": "IL"
    },
    "order_items": [
      { "sku": "SKU-1", "name": "ספל כחול", "quantity": 2, "price": 49.95, "total": 99.90 }
    ]
  }
}'

// Node.js 18+ / דפדפנים — בלי תלויות
const response = await fetch('https://app.shipos.co.il/api/v2/shipments', {
  method: 'POST',
  headers: {
    'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
    'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '9c1a5f4e-2b6d-4a3e-8f10-7d0c2b3a4e5f',
  },
  body: JSON.stringify({
    license_key: 'b3f1c9a7d2e04f8a9c6b1e2d3f4a5b6c',
    ship_data: {
      contact_name: 'ישראל ישראלי',
      contact_phone: '0521234567',
      contact_mail: 'dana@example.com',
      street: 'הרצל',
      number: '10',
      city: 'תל אביב',
      floor: '3',
      apartment: '12',
      type: 1,
      return: 1,
      packages: 1,
      note: 'להשאיר אצל השומר',
    },
    order: {
      id: '1042',
      number: '1042',
      currency: 'ILS',
      total: 199.9,
      source: 'custom',
      shipping: {
        first_name: 'ישראל',
        last_name: 'ישראלי',
        phone: '0521234567',
        email: 'dana@example.com',
        address_1: 'הרצל 10',
        city: 'תל אביב',
        postcode: '6100000',
        country: 'IL',
      },
      order_items: [
        { sku: 'SKU-1', name: 'ספל כחול', quantity: 2, price: 49.95, total: 99.9 },
      ],
    },
  }),
})

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data: shipment } = await response.json()
console.log(shipment.uuid, shipment.tracking_code)

php

<?php
// composer require guzzlehttp/guzzle

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.shipos.co.il/api/v2/',
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
        'Idempotency-Key' => '9c1a5f4e-2b6d-4a3e-8f10-7d0c2b3a4e5f',
    ],
]);

$shipment = json_decode($client->post('shipments', [
    'json' => [
        'license_key' => 'b3f1c9a7d2e04f8a9c6b1e2d3f4a5b6c',
        'ship_data' => [
            'contact_name' => 'ישראל ישראלי',
            'contact_phone' => '0521234567',
            'contact_mail' => 'dana@example.com',
            'street' => 'הרצל',
            'number' => '10',
            'city' => 'תל אביב',
            'floor' => '3',
            'apartment' => '12',
            'type' => 1,
            'return' => 1,
            'packages' => 1,
            'note' => 'להשאיר אצל השומר',
        ],
        'order' => [
            'id' => '1042',
            'number' => '1042',
            'currency' => 'ILS',
            'total' => 199.90,
            'source' => 'custom',
            'shipping' => [
                'first_name' => 'ישראל',
                'last_name' => 'ישראלי',
                'phone' => '0521234567',
                'email' => 'dana@example.com',
                'address_1' => 'הרצל 10',
                'city' => 'תל אביב',
                'postcode' => '6100000',
                'country' => 'IL',
            ],
            'order_items' => [
                ['sku' => 'SKU-1', 'name' => 'ספל כחול', 'quantity' => 2, 'price' => 49.95, 'total' => 99.90],
            ],
        ],
    ],
])->getBody()->getContents(), true)['data'];

echo $shipment['uuid'], ' ', $shipment['tracking_code'], PHP_EOL;

php

<?php

use Illuminate\Support\Facades\Http;

$shipment = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
    'Idempotency-Key' => '9c1a5f4e-2b6d-4a3e-8f10-7d0c2b3a4e5f',
])
    ->acceptJson()
    ->post('https://app.shipos.co.il/api/v2/shipments', [
        'license_key' => 'b3f1c9a7d2e04f8a9c6b1e2d3f4a5b6c',
        'ship_data' => [
            'contact_name' => 'ישראל ישראלי',
            'contact_phone' => '0521234567',
            'contact_mail' => 'dana@example.com',
            'street' => 'הרצל',
            'number' => '10',
            'city' => 'תל אביב',
            'floor' => '3',
            'apartment' => '12',
            'type' => 1,
            'return' => 1,
            'packages' => 1,
            'note' => 'להשאיר אצל השומר',
        ],
        'order' => [
            'id' => '1042',
            'number' => '1042',
            'currency' => 'ILS',
            'total' => 199.90,
            'source' => 'custom',
            'shipping' => [
                'first_name' => 'ישראל',
                'last_name' => 'ישראלי',
                'phone' => '0521234567',
                'email' => 'dana@example.com',
                'address_1' => 'הרצל 10',
                'city' => 'תל אביב',
                'postcode' => '6100000',
                'country' => 'IL',
            ],
            'order_items' => [
                ['sku' => 'SKU-1', 'name' => 'ספל כחול', 'quantity' => 2, 'price' => 49.95, 'total' => 99.90],
            ],
        ],
    ])
    ->throw()
    ->json('data');

logger()->info($shipment['uuid'].' '.$shipment['tracking_code']);

python

# pip install httpx
import os

import httpx

response = httpx.post(
    "https://app.shipos.co.il/api/v2/shipments",
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
        "Idempotency-Key": "9c1a5f4e-2b6d-4a3e-8f10-7d0c2b3a4e5f",
    },
    json={
        "license_key": "b3f1c9a7d2e04f8a9c6b1e2d3f4a5b6c",
        "ship_data": {
            "contact_name": "ישראל ישראלי",
            "contact_phone": "0521234567",
            "contact_mail": "dana@example.com",
            "street": "הרצל",
            "number": "10",
            "city": "תל אביב",
            "floor": "3",
            "apartment": "12",
            "type": 1,
            "return": 1,
            "packages": 1,
            "note": "להשאיר אצל השומר",
        },
        "order": {
            "id": "1042",
            "number": "1042",
            "currency": "ILS",
            "total": 199.90,
            "source": "custom",
            "shipping": {
                "first_name": "ישראל",
                "last_name": "ישראלי",
                "phone": "0521234567",
                "email": "dana@example.com",
                "address_1": "הרצל 10",
                "city": "תל אביב",
                "postcode": "6100000",
                "country": "IL",
            },
            "order_items": [
                {"sku": "SKU-1", "name": "ספל כחול", "quantity": 2, "price": 49.95, "total": 99.90},
            ],
        },
    },
)
response.raise_for_status()
shipment = response.json()["data"]

print(shipment["uuid"], shipment["tracking_code"])

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"license_key": "b3f1c9a7d2e04f8a9c6b1e2d3f4a5b6c",
		"ship_data": map[string]any{
			"contact_name":  "ישראל ישראלי",
			"contact_phone": "0521234567",
			"contact_mail":  "dana@example.com",
			"street":        "הרצל",
			"number":        "10",
			"city":          "תל אביב",
			"floor":         "3",
			"apartment":     "12",
			"type":          1,
			"return":        1,
			"packages":      1,
			"note":          "להשאיר אצל השומר",
		},
		"order": map[string]any{
			"id":       "1042",
			"number":   "1042",
			"currency": "ILS",
			"total":    199.90,
			"source":   "custom",
			"shipping": map[string]any{
				"first_name": "ישראל",
				"last_name":  "ישראלי",
				"phone":      "0521234567",
				"email":      "dana@example.com",
				"address_1":  "הרצל 10",
				"city":       "תל אביב",
				"postcode":   "6100000",
				"country":    "IL",
			},
			"order_items": []map[string]any{
				{"sku": "SKU-1", "name": "ספל כחול", "quantity": 2, "price": 49.95, "total": 99.90},
			},
		},
	})

	req, _ := http.NewRequest("POST",
		"https://app.shipos.co.il/api/v2/shipments", bytes.NewReader(body))
	req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
	req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", "9c1a5f4e-2b6d-4a3e-8f10-7d0c2b3a4e5f")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(out)) // 201 {"data":{...}}
}

java

// Java 17+ — java.net.http, בלי תלויות (פרסור עם Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ShipOsCreateShipment {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "license_key": "b3f1c9a7d2e04f8a9c6b1e2d3f4a5b6c",
              "ship_data": {
                "contact_name": "ישראל ישראלי",
                "contact_phone": "0521234567",
                "contact_mail": "dana@example.com",
                "street": "הרצל",
                "number": "10",
                "city": "תל אביב",
                "floor": "3",
                "apartment": "12",
                "type": 1,
                "return": 1,
                "packages": 1,
                "note": "להשאיר אצל השומר"
              },
              "order": {
                "id": "1042",
                "number": "1042",
                "currency": "ILS",
                "total": 199.90,
                "source": "custom",
                "shipping": {
                  "first_name": "ישראל",
                  "last_name": "ישראלי",
                  "phone": "0521234567",
                  "email": "dana@example.com",
                  "address_1": "הרצל 10",
                  "city": "תל אביב",
                  "postcode": "6100000",
                  "country": "IL"
                },
                "order_items": [
                  { "sku": "SKU-1", "name": "ספל כחול", "quantity": 2, "price": 49.95, "total": 99.90 }
                ]
              }
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.shipos.co.il/api/v2/shipments"))
            .header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
            .header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
            .header("Accept", "application/json")
            .header("Content-Type", "application/json")
            .header("Idempotency-Key", "9c1a5f4e-2b6d-4a3e-8f10-7d0c2b3a4e5f")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 201) {
            throw new RuntimeException("ShipOS error: " + response.body());
        }

        System.out.println(response.body()); // {"data":{...}}
    }
}

csharp

// .NET 8+ — System.Net.Http.Json
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient
{
    BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));
http.DefaultRequestHeaders.Add("Idempotency-Key",
    "9c1a5f4e-2b6d-4a3e-8f10-7d0c2b3a4e5f");

var response = await http.PostAsJsonAsync("shipments", new
{
    license_key = "b3f1c9a7d2e04f8a9c6b1e2d3f4a5b6c",
    ship_data = new
    {
        contact_name = "ישראל ישראלי",
        contact_phone = "0521234567",
        contact_mail = "dana@example.com",
        street = "הרצל",
        number = "10",
        city = "תל אביב",
        floor = "3",
        apartment = "12",
        type = 1,
        @return = 1,
        packages = 1,
        note = "להשאיר אצל השומר",
    },
    order = new
    {
        id = "1042",
        number = "1042",
        currency = "ILS",
        total = 199.90,
        source = "custom",
        shipping = new
        {
            first_name = "ישראל",
            last_name = "ישראלי",
            phone = "0521234567",
            email = "dana@example.com",
            address_1 = "הרצל 10",
            city = "תל אביב",
            postcode = "6100000",
            country = "IL",
        },
        order_items = new[]
        {
            new { sku = "SKU-1", name = "ספל כחול", quantity = 2, price = 49.95, total = 99.90 },
        },
    },
});
response.EnsureSuccessStatusCode();

var payload = await response.Content.ReadFromJsonAsync<JsonDocument>()
    ?? throw new InvalidOperationException("Empty response");
var shipment = payload.RootElement.GetProperty("data");

Console.WriteLine(shipment.GetProperty("uuid").GetString());

ruby

require "net/http"
require "json"

uri = URI("https://app.shipos.co.il/api/v2/shipments")

request = Net::HTTP::Post.new(uri)
request["X-Client-Id"] = ENV.fetch("SHIPOS_CLIENT_ID")
request["X-Client-Secret"] = ENV.fetch("SHIPOS_CLIENT_SECRET")
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "9c1a5f4e-2b6d-4a3e-8f10-7d0c2b3a4e5f"
request.body = JSON.dump(
  license_key: "b3f1c9a7d2e04f8a9c6b1e2d3f4a5b6c",
  ship_data: {
    contact_name: "ישראל ישראלי",
    contact_phone: "0521234567",
    contact_mail: "dana@example.com",
    street: "הרצל",
    number: "10",
    city: "תל אביב",
    floor: "3",
    apartment: "12",
    type: 1,
    return: 1,
    packages: 1,
    note: "להשאיר אצל השומר"
  },
  order: {
    id: "1042",
    number: "1042",
    currency: "ILS",
    total: 199.90,
    source: "custom",
    shipping: {
      first_name: "ישראל",
      last_name: "ישראלי",
      phone: "0521234567",
      email: "dana@example.com",
      address_1: "הרצל 10",
      city: "תל אביב",
      postcode: "6100000",
      country: "IL"
    },
    order_items: [
      { sku: "SKU-1", name: "ספל כחול", quantity: 2, price: 49.95, total: 99.90 }
    ]
  }
)

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise "ShipOS error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

shipment = JSON.parse(response.body).fetch("data")
puts "#{shipment["uuid"]} #{shipment["tracking_code"]}"

rust

// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let payload: Value = reqwest::Client::new()
        .post("https://app.shipos.co.il/api/v2/shipments")
        .header("X-Client-Id", std::env::var("SHIPOS_CLIENT_ID")?)
        .header("X-Client-Secret", std::env::var("SHIPOS_CLIENT_SECRET")?)
        .header("Accept", "application/json")
        .header("Idempotency-Key", "9c1a5f4e-2b6d-4a3e-8f10-7d0c2b3a4e5f")
        .json(&serde_json::json!({
            "license_key": "b3f1c9a7d2e04f8a9c6b1e2d3f4a5b6c",
            "ship_data": {
                "contact_name": "ישראל ישראלי",
                "contact_phone": "0521234567",
                "contact_mail": "dana@example.com",
                "street": "הרצל",
                "number": "10",
                "city": "תל אביב",
                "floor": "3",
                "apartment": "12",
                "type": 1,
                "return": 1,
                "packages": 1,
                "note": "להשאיר אצל השומר"
            },
            "order": {
                "id": "1042",
                "number": "1042",
                "currency": "ILS",
                "total": 199.90,
                "source": "custom",
                "shipping": {
                    "first_name": "ישראל",
                    "last_name": "ישראלי",
                    "phone": "0521234567",
                    "email": "dana@example.com",
                    "address_1": "הרצל 10",
                    "city": "תל אביב",
                    "postcode": "6100000",
                    "country": "IL"
                },
                "order_items": [
                    { "sku": "SKU-1", "name": "ספל כחול", "quantity": 2, "price": 49.95, "total": 99.90 }
                ]
            }
        }))
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    println!("{} {}", payload["data"]["uuid"], payload["data"]["tracking_code"]);
    Ok(())
}

תשובה `201`

json

{
  "data": {
    "uuid": "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88",
    "tracking_code": "66747921",
    "carrier": { "id": 3, "name": "HFD" },
    "status": null,
    "service_type": "1",
    "is_active": true,
    "recipient": {
      "name": "ישראל ישראלי",
      "phone": "0521234567",
      "company": null,
      "address": {
        "street": "הרצל 10",
        "number": "10",
        "city": "תל אביב",
        "state": null,
        "zip": "6100000",
        "country": "IL"
      }
    },
    "pickup_point_id": null,
    "packages": 1,
    "cod": null,
    "order": { "id": "1042", "number": "1042" },
    "references": { "external_id": null },
    "short_tracking_code": null,
    "label_generated": false,
    "collection_status": null,
    "collected_at": null,
    "ready_at": null,
    "created_at": "2026-07-29T09:14:00.000000Z",
    "updated_at": "2026-07-29T09:14:00.000000Z"
  }
}

שגיאות

סטטוס	קוד	מתי
401	`unauthenticated`	client credentials חסרים או לא תקינים.
403	`forbidden`	ה-`license_key` אינו בבעלות הקורא, או שהרישיון שנקבע אינו פעיל / פג תוקף, או שלחשבון אין רישיון פעיל.
403	`package_limit_reached`	מכסת המשלוחים של המנוי של הלקוח (`max_no_of_shipping`) מוצתה.
409	`duplicate_request`	יצירה עבור אותה בקשה כבר בתהליך (lock timeout). נסו שוב בעוד רגע.
409	`idempotency_key_conflict`	אותו `Idempotency-Key` שומש שוב עם גוף בקשה שונה. ראו אידמפוטנטיות.
422	`validation_failed`	הגוף נכשל באימות, או שלחשבון יש יותר מרישיון אחד ו-`license_key` הושמט.
424	`carrier_error`	חברת השילוח דחתה את המשלוח.

אובייקט המשלוח

כל endpoint של משלוחים מחזיר את המבנה הזה. השדות נבחרו בקפידה עבור החוזה הציבורי; payloads פנימיים של חברות שילוח ועמודות תפעוליות אינם נחשפים.

שדה	סוג	תיאור
`uuid`	string	מזהה המשלוח הציבורי.
`tracking_code`	string \| null	קוד מעקב של חברת השילוח.
`carrier`	object	חברת השילוח: `{ id, name }`.
`status`	object \| null	`{ code, description, is_delivered }` — מפתחות עם ערך null מושמטים; השדה כולו null עד שסטטוס ידוע.
`service_type`	string \| null	`1` = משלוח, `2` = איסוף/החזרה.
`is_active`	boolean	האם המשלוח פעיל (מוגדר false בביטול).
`recipient`	object	`{ name, phone, company, address: { street, number, city, state, zip, country } }`.
`pickup_point_id`	string \| null	מזהה נקודת איסוף, עבור משלוחים לנקודת איסוף.
`packages`	integer \| null	מספר חבילות.
`cod`	object \| null	`{ amount }` כאשר יש גבייה במסירה (COD), אחרת null.
`order`	object	`{ id, number }` — הפניית ההזמנה הנייטרלית.
`references`	object	`{ external_id }`.
`short_tracking_code`	string \| null	קוד מעקב קצר (תהליכי נקודת איסוף).
`label_generated`	boolean	האם נוצרה תווית.
`collection_status`	mixed \| null	סטטוס מחזור החיים של האיסוף.
`collected_at`	datetime \| null	מתי נאסף.
`ready_at`	datetime \| null	מתי מוכן לאיסוף.
`created_at`	datetime	חותמת זמן היצירה.
`updated_at`	datetime	חותמת זמן העדכון האחרון.

`GET` /shipments/

שליפת משלוח בודד. נפתר על פני כל הרישיונות שבבעלותכם, ולכן אין צורך ב-license_key. אימות: client credentials. רישיון: אופציונלי.

פרמטרים

Path:

שדה	סוג	חובה	תיאור
`shipment`	string	כן	ה-`uuid` של המשלוח, קוד המעקב של חברת השליחויות, או קוד המעקב הקצר.

Query:

שדה	סוג	חובה	תיאור
`license_key`	string	לא	‏`licenses.key` לצמצום החיפוש לחשבון שילוח אחד. אם יישמט, החיפוש משתרע על כל הרישיונות שבבעלותכם.

דוגמת בקשה

bash

curl --location 'https://app.shipos.co.il/api/v2/shipments/9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json'

// Node.js 18+ / דפדפנים — בלי תלויות
const uuid = '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88'

const response = await fetch(`https://app.shipos.co.il/api/v2/shipments/${uuid}`, {
  headers: {
    'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
    'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
    Accept: 'application/json',
  },
})

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data: shipment } = await response.json()
console.log(shipment.tracking_code, shipment.status?.description)

php

<?php
// composer require guzzlehttp/guzzle

$uuid = '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88';

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.shipos.co.il/api/v2/',
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
    ],
]);

$shipment = json_decode(
    $client->get("shipments/{$uuid}")->getBody()->getContents(),
    true,
)['data'];

echo $shipment['tracking_code'], PHP_EOL;

php

<?php

use Illuminate\Support\Facades\Http;

$uuid = '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88';

$shipment = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
])
    ->acceptJson()
    ->get("https://app.shipos.co.il/api/v2/shipments/{$uuid}")
    ->throw()
    ->json('data');

logger()->info($shipment['tracking_code']);

python

# pip install httpx
import os

import httpx

uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88"

response = httpx.get(
    f"https://app.shipos.co.il/api/v2/shipments/{shipment}",
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
    },
)
response.raise_for_status()
shipment = response.json()["data"]

print(shipment["tracking_code"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	uuid := "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88"

	req, _ := http.NewRequest("GET",
		"https://app.shipos.co.il/api/v2/shipments/"+uuid, nil)
	req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
	req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
	req.Header.Set("Accept", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(body)) // {"data":{...}}
}

java

// Java 17+ — java.net.http, בלי תלויות (פרסור עם Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ShipOsGetShipment {
    public static void main(String[] args) throws Exception {
        String uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88";

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.shipos.co.il/api/v2/shipments/" + uuid))
            .header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
            .header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
            .header("Accept", "application/json")
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new RuntimeException("ShipOS error: " + response.body());
        }

        System.out.println(response.body()); // {"data":{...}}
    }
}

csharp

// .NET 8+ — System.Net.Http.Json
using System.Net.Http.Json;
using System.Text.Json;

var uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88";

using var http = new HttpClient
{
    BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));

var payload = await http.GetFromJsonAsync<JsonDocument>($"shipments/{shipment}")
    ?? throw new InvalidOperationException("Empty response");
var shipment = payload.RootElement.GetProperty("data");

Console.WriteLine(shipment.GetProperty("tracking_code").GetString());

ruby

require "net/http"
require "json"

uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88"
uri = URI("https://app.shipos.co.il/api/v2/shipments/#{uuid}")

request = Net::HTTP::Get.new(uri)
request["X-Client-Id"] = ENV.fetch("SHIPOS_CLIENT_ID")
request["X-Client-Secret"] = ENV.fetch("SHIPOS_CLIENT_SECRET")
request["Accept"] = "application/json"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise "ShipOS error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

shipment = JSON.parse(response.body).fetch("data")
puts shipment["tracking_code"]

rust

// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88";

    let payload: Value = reqwest::Client::new()
        .get(format!("https://app.shipos.co.il/api/v2/shipments/{shipment}"))
        .header("X-Client-Id", std::env::var("SHIPOS_CLIENT_ID")?)
        .header("X-Client-Secret", std::env::var("SHIPOS_CLIENT_SECRET")?)
        .header("Accept", "application/json")
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    println!("{}", payload["data"]["tracking_code"]);
    Ok(())
}

תשובה `200`

json

{ "data": { "uuid": "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88", "tracking_code": "66747921", "...": "ראו את אובייקט המשלוח למעלה" } }

שגיאות

סטטוס	קוד	מתי
401	`unauthenticated`	client credentials חסרים או לא תקינים.
403	`forbidden`	הרישיון אינו בבעלות / לא פעיל / פג תוקף, או שאין רישיון פעיל.
404	`not_found`	אין משלוח עם ה-`uuid` הזה תחת הרישיון שנקבע.
422	`validation_failed`	מספר רישיונות ו-`license_key` הושמט.

`GET` /shipments/{shipment}/status

שליפה מחודשת של סטטוס המשלוח בזמן אמת מחברת השילוח והחזרת המשלוח המעודכן. אם השליפה החיה נכשלת, נשמר הסטטוס האחרון הידוע. אימות: client credentials. רישיון: אופציונלי.

פרמטרים

Path:

שדה	סוג	חובה	תיאור
`shipment`	string	כן	ה-`uuid` של המשלוח, קוד המעקב של חברת השליחויות, או קוד המעקב הקצר.

Query:

שדה	סוג	חובה	תיאור
`license_key`	string	לא	‏`licenses.key` לצמצום החיפוש לחשבון שילוח אחד. אם יישמט, החיפוש משתרע על כל הרישיונות שבבעלותכם.

דוגמת בקשה

bash

curl --location 'https://app.shipos.co.il/api/v2/shipments/9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88/status' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json'

// Node.js 18+ / דפדפנים — בלי תלויות
const uuid = '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88'

const response = await fetch(
  `https://app.shipos.co.il/api/v2/shipments/${uuid}/status`,
  {
    headers: {
      'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
      'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
      Accept: 'application/json',
    },
  },
)

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data: shipment } = await response.json()
console.log(shipment.status?.description, shipment.status?.is_delivered)

php

<?php
// composer require guzzlehttp/guzzle

$uuid = '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88';

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.shipos.co.il/api/v2/',
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
    ],
]);

$shipment = json_decode(
    $client->get("shipments/{$uuid}/status")->getBody()->getContents(),
    true,
)['data'];

echo $shipment['status']['description'] ?? 'unknown', PHP_EOL;

php

<?php

use Illuminate\Support\Facades\Http;

$uuid = '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88';

$shipment = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
])
    ->acceptJson()
    ->get("https://app.shipos.co.il/api/v2/shipments/{$uuid}/status")
    ->throw()
    ->json('data');

logger()->info($shipment['status']['description'] ?? 'unknown');

python

# pip install httpx
import os

import httpx

uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88"

response = httpx.get(
    f"https://app.shipos.co.il/api/v2/shipments/{shipment}/status",
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
    },
)
response.raise_for_status()
status = response.json()["data"]["status"] or {}

print(status.get("description"), status.get("is_delivered"))

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	uuid := "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88"

	req, _ := http.NewRequest("GET",
		"https://app.shipos.co.il/api/v2/shipments/"+uuid+"/status", nil)
	req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
	req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
	req.Header.Set("Accept", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(body)) // {"data":{"status":{...},...}}
}

java

// Java 17+ — java.net.http, בלי תלויות (פרסור עם Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ShipOsShipmentStatus {
    public static void main(String[] args) throws Exception {
        String uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88";

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(
                "https://app.shipos.co.il/api/v2/shipments/" + uuid + "/status"))
            .header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
            .header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
            .header("Accept", "application/json")
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new RuntimeException("ShipOS error: " + response.body());
        }

        System.out.println(response.body()); // {"data":{"status":{...},...}}
    }
}

csharp

// .NET 8+ — System.Net.Http.Json
using System.Net.Http.Json;
using System.Text.Json;

var uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88";

using var http = new HttpClient
{
    BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));

var payload = await http.GetFromJsonAsync<JsonDocument>($"shipments/{shipment}/status")
    ?? throw new InvalidOperationException("Empty response");
var status = payload.RootElement.GetProperty("data").GetProperty("status");

Console.WriteLine(status.ValueKind == JsonValueKind.Null
    ? "unknown"
    : status.GetProperty("description").GetString());

ruby

require "net/http"
require "json"

uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88"
uri = URI("https://app.shipos.co.il/api/v2/shipments/#{uuid}/status")

request = Net::HTTP::Get.new(uri)
request["X-Client-Id"] = ENV.fetch("SHIPOS_CLIENT_ID")
request["X-Client-Secret"] = ENV.fetch("SHIPOS_CLIENT_SECRET")
request["Accept"] = "application/json"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise "ShipOS error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

status = JSON.parse(response.body).dig("data", "status") || {}
puts "#{status["description"]} delivered=#{status["is_delivered"]}"

rust

// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88";

    let payload: Value = reqwest::Client::new()
        .get(format!(
            "https://app.shipos.co.il/api/v2/shipments/{shipment}/status"
        ))
        .header("X-Client-Id", std::env::var("SHIPOS_CLIENT_ID")?)
        .header("X-Client-Secret", std::env::var("SHIPOS_CLIENT_SECRET")?)
        .header("Accept", "application/json")
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    let status = &payload["data"]["status"];
    println!("{} {}", status["description"], status["is_delivered"]);
    Ok(())
}

תשובה `200`

מחזירה את אובייקט המשלוח המלא עם בלוק status מרוענן.

json

{
  "data": {
    "uuid": "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88",
    "tracking_code": "66747921",
    "status": { "code": "5", "description": "Delivered", "is_delivered": true },
    "...": "יתר שדות המשלוח"
  }
}

שגיאות

סטטוס	קוד	מתי
401	`unauthenticated`	client credentials חסרים או לא תקינים.
403	`forbidden`	הרישיון אינו בבעלות / לא פעיל / פג תוקף, או שאין רישיון פעיל.
404	`not_found`	אין משלוח עם ה-`uuid` הזה תחת הרישיון שנקבע.
422	`validation_failed`	מספר רישיונות ו-`license_key` הושמט.

`GET` /shipments/{shipment}/label

החזרת מטא-נתוני התווית להדפסה וכתובת ההורדה עבור משלוח בודד. אימות: client credentials. רישיון: אופציונלי.

ה-endpoint הזה אינו מחזיר את הקובץ הבינארי עצמו ואינו מפנה אליו. הוא משיב במעטפת JSON המכילה את מזהה המשלוח, הפורמט (pdf), ו-url המצביע על נתיב הורדת התווית (shipping.label). גשו לכתובת הזו כדי לקבל את ה-PDF.

פרמטרים

Path:

שדה	סוג	חובה	תיאור
`shipment`	string	כן	ה-`uuid` של המשלוח, קוד המעקב של חברת השליחויות, או קוד המעקב הקצר.

Query:

שדה	סוג	חובה	תיאור
`license_key`	string	לא	‏`licenses.key` לצמצום החיפוש לחשבון שילוח אחד. אם יישמט, החיפוש משתרע על כל הרישיונות שבבעלותכם.

דוגמת בקשה

bash

curl --location 'https://app.shipos.co.il/api/v2/shipments/9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88/label' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json'

// Node.js 18+ / דפדפנים — בלי תלויות
const uuid = '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88'

const response = await fetch(
  `https://app.shipos.co.il/api/v2/shipments/${uuid}/label`,
  {
    headers: {
      'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
      'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
      Accept: 'application/json',
    },
  },
)

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data: label } = await response.json()
console.log(label.format, label.url) // fetch label.url for the PDF

php

<?php
// composer require guzzlehttp/guzzle

$uuid = '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88';

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.shipos.co.il/api/v2/',
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
    ],
]);

$label = json_decode(
    $client->get("shipments/{$uuid}/label")->getBody()->getContents(),
    true,
)['data'];

echo $label['format'], ' → ', $label['url'], PHP_EOL;

php

<?php

use Illuminate\Support\Facades\Http;

$uuid = '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88';

$label = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
])
    ->acceptJson()
    ->get("https://app.shipos.co.il/api/v2/shipments/{$uuid}/label")
    ->throw()
    ->json('data');

logger()->info($label['format'].' → '.$label['url']);

python

# pip install httpx
import os

import httpx

uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88"

response = httpx.get(
    f"https://app.shipos.co.il/api/v2/shipments/{shipment}/label",
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
    },
)
response.raise_for_status()
label = response.json()["data"]

print(label["format"], label["url"])  # fetch label["url"] for the PDF

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type labelResponse struct {
	Data struct {
		Format string `json:"format"`
		URL    string `json:"url"`
	} `json:"data"`
}

func main() {
	uuid := "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88"

	req, _ := http.NewRequest("GET",
		"https://app.shipos.co.il/api/v2/shipments/"+uuid+"/label", nil)
	req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
	req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
	req.Header.Set("Accept", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var label labelResponse
	if err := json.NewDecoder(res.Body).Decode(&label); err != nil {
		panic(err)
	}

	fmt.Println(label.Data.Format, label.Data.URL)
}

java

// Java 17+ — java.net.http, בלי תלויות (פרסור עם Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ShipOsShipmentLabel {
    public static void main(String[] args) throws Exception {
        String uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88";

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(
                "https://app.shipos.co.il/api/v2/shipments/" + uuid + "/label"))
            .header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
            .header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
            .header("Accept", "application/json")
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new RuntimeException("ShipOS error: " + response.body());
        }

        System.out.println(response.body()); // {"data":{"format":"pdf","url":"..."}}
    }
}

csharp

// .NET 8+ — System.Net.Http.Json
using System.Net.Http.Json;
using System.Text.Json;

var uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88";

using var http = new HttpClient
{
    BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));

var payload = await http.GetFromJsonAsync<JsonDocument>($"shipments/{shipment}/label")
    ?? throw new InvalidOperationException("Empty response");
var label = payload.RootElement.GetProperty("data");

Console.WriteLine($"{label.GetProperty("format").GetString()} → " +
    label.GetProperty("url").GetString());

ruby

require "net/http"
require "json"

uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88"
uri = URI("https://app.shipos.co.il/api/v2/shipments/#{uuid}/label")

request = Net::HTTP::Get.new(uri)
request["X-Client-Id"] = ENV.fetch("SHIPOS_CLIENT_ID")
request["X-Client-Secret"] = ENV.fetch("SHIPOS_CLIENT_SECRET")
request["Accept"] = "application/json"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise "ShipOS error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

label = JSON.parse(response.body).fetch("data")
puts "#{label["format"]} → #{label["url"]}"

rust

// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88";

    let payload: Value = reqwest::Client::new()
        .get(format!(
            "https://app.shipos.co.il/api/v2/shipments/{shipment}/label"
        ))
        .header("X-Client-Id", std::env::var("SHIPOS_CLIENT_ID")?)
        .header("X-Client-Secret", std::env::var("SHIPOS_CLIENT_SECRET")?)
        .header("Accept", "application/json")
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    let label = &payload["data"];
    println!("{} → {}", label["format"], label["url"]);
    Ok(())
}

תשובה `200`

json

{
  "data": {
    "shipment_id": "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88",
    "format": "pdf",
    "url": "https://app.shipos.co.il/shipping/label/9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88"
  }
}

שגיאות

סטטוס	קוד	מתי
401	`unauthenticated`	client credentials חסרים או לא תקינים.
403	`forbidden`	הרישיון אינו בבעלות / לא פעיל / פג תוקף, או שאין רישיון פעיל.
404	`not_found`	אין משלוח עם ה-`uuid` הזה תחת הרישיון שנקבע.
422	`validation_failed`	מספר רישיונות ו-`license_key` הושמט.

`POST` /shipments/labels

החזרת כתובת URL אחת ל-PDF משולב של תוויות המכסה משלוחים רבים בבת אחת. הערכים ב-uuids יכולים להיות uuid או קודי מעקב. אימות: client credentials. רישיון: אופציונלי.

רק המשלוחים של הקורא עצמו נכללים; uuids לא מוכרים או זרים מושמטים בשקט. כמו ב-endpoint של תווית בודדת, התשובה היא מטא-נתוני JSON עם url (נתיב shipping.bulk_label) — לא הקובץ הבינארי.

פרמטרים

Body:

שדה	סוג	חובה	תיאור
`license_key`	string	לא	‏`licenses.key` לצמצום החיפוש לחשבון שילוח אחד. אם יישמט, החיפוש משתרע על כל הרישיונות שבבעלותכם.
`uuids`	array	כן	uuids של משלוחים לאיחוד. מינימום 1, מקסימום 100. כפילויות מוסרות בצד השרת.
`uuids.*`	string	כן	`uuid` של משלוח.

דוגמת בקשה

bash

curl --location 'https://app.shipos.co.il/api/v2/shipments/labels' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "uuids": [
    "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88",
    "1d5e8a2c-9f0b-4e11-8c33-6a7b8c9d0e12"
  ]
}'

// Node.js 18+ / דפדפנים — בלי תלויות
const response = await fetch('https://app.shipos.co.il/api/v2/shipments/labels', {
  method: 'POST',
  headers: {
    'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
    'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    uuids: [
      '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88',
      '1d5e8a2c-9f0b-4e11-8c33-6a7b8c9d0e12',
    ],
  }),
})

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data: labels } = await response.json()
console.log(labels.count, labels.url) // combined PDF for all labels

php

<?php
// composer require guzzlehttp/guzzle

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.shipos.co.il/api/v2/',
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
    ],
]);

$labels = json_decode($client->post('shipments/labels', [
    'json' => [
        'uuids' => [
            '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88',
            '1d5e8a2c-9f0b-4e11-8c33-6a7b8c9d0e12',
        ],
    ],
])->getBody()->getContents(), true)['data'];

echo $labels['count'], ' → ', $labels['url'], PHP_EOL;

php

<?php

use Illuminate\Support\Facades\Http;

$labels = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
])
    ->acceptJson()
    ->post('https://app.shipos.co.il/api/v2/shipments/labels', [
        'uuids' => [
            '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88',
            '1d5e8a2c-9f0b-4e11-8c33-6a7b8c9d0e12',
        ],
    ])
    ->throw()
    ->json('data');

logger()->info($labels['count'].' → '.$labels['url']);

python

# pip install httpx
import os

import httpx

response = httpx.post(
    "https://app.shipos.co.il/api/v2/shipments/labels",
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
    },
    json={
        "uuids": [
            "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88",
            "1d5e8a2c-9f0b-4e11-8c33-6a7b8c9d0e12",
        ],
    },
)
response.raise_for_status()
labels = response.json()["data"]

print(labels["count"], labels["url"])

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"uuids": []string{
			"9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88",
			"1d5e8a2c-9f0b-4e11-8c33-6a7b8c9d0e12",
		},
	})

	req, _ := http.NewRequest("POST",
		"https://app.shipos.co.il/api/v2/shipments/labels", bytes.NewReader(body))
	req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
	req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(out)) // {"data":{"count":2,"url":"..."}}
}

java

// Java 17+ — java.net.http, בלי תלויות (פרסור עם Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ShipOsBulkLabels {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "uuids": [
                "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88",
                "1d5e8a2c-9f0b-4e11-8c33-6a7b8c9d0e12"
              ]
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.shipos.co.il/api/v2/shipments/labels"))
            .header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
            .header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
            .header("Accept", "application/json")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new RuntimeException("ShipOS error: " + response.body());
        }

        System.out.println(response.body()); // {"data":{"count":2,"url":"..."}}
    }
}

csharp

// .NET 8+ — System.Net.Http.Json
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient
{
    BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));

var response = await http.PostAsJsonAsync("shipments/labels", new
{
    uuids = new[]
    {
        "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88",
        "1d5e8a2c-9f0b-4e11-8c33-6a7b8c9d0e12",
    },
});
response.EnsureSuccessStatusCode();

var payload = await response.Content.ReadFromJsonAsync<JsonDocument>()
    ?? throw new InvalidOperationException("Empty response");
var labels = payload.RootElement.GetProperty("data");

Console.WriteLine($"{labels.GetProperty("count").GetInt32()} → " +
    labels.GetProperty("url").GetString());

ruby

require "net/http"
require "json"

uri = URI("https://app.shipos.co.il/api/v2/shipments/labels")

request = Net::HTTP::Post.new(uri)
request["X-Client-Id"] = ENV.fetch("SHIPOS_CLIENT_ID")
request["X-Client-Secret"] = ENV.fetch("SHIPOS_CLIENT_SECRET")
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request.body = JSON.dump(uuids: [
  "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88",
  "1d5e8a2c-9f0b-4e11-8c33-6a7b8c9d0e12"
])

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise "ShipOS error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

labels = JSON.parse(response.body).fetch("data")
puts "#{labels["count"]} → #{labels["url"]}"

rust

// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let payload: Value = reqwest::Client::new()
        .post("https://app.shipos.co.il/api/v2/shipments/labels")
        .header("X-Client-Id", std::env::var("SHIPOS_CLIENT_ID")?)
        .header("X-Client-Secret", std::env::var("SHIPOS_CLIENT_SECRET")?)
        .header("Accept", "application/json")
        .json(&serde_json::json!({
            "uuids": [
                "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88",
                "1d5e8a2c-9f0b-4e11-8c33-6a7b8c9d0e12"
            ]
        }))
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    let labels = &payload["data"];
    println!("{} → {}", labels["count"], labels["url"]);
    Ok(())
}

תשובה `200`

json

{
  "data": {
    "count": 2,
    "format": "pdf",
    "url": "https://app.shipos.co.il/shipping/bulk-label?ids[]=9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88&ids[]=1d5e8a2c-9f0b-4e11-8c33-6a7b8c9d0e12"
  }
}

שגיאות

סטטוס	קוד	מתי
401	`unauthenticated`	client credentials חסרים או לא תקינים.
403	`forbidden`	הרישיון אינו בבעלות / לא פעיל / פג תוקף, או שאין רישיון פעיל.
404	`not_found`	אף אחד מה-uuids שסופקו לא נפתר למשלוח תחת הרישיון שנקבע.
422	`validation_failed`	`uuids` חסר/ריק/מעל 100, או מספר רישיונות ו-`license_key` הושמט.

`POST` /shipments/{shipment}/cancel

ביטול משלוח מול חברת השילוח. בהצלחה בצד חברת השילוח המשלוח מושבת מקומית (is_active הופך ל-false) ומופעל webhook מסוג shipment.cancelled. המשלוח כבר יודע מי חברת השילוח שלו, ולכן אין צורך ב-license_key. אימות: client credentials. רישיון: אופציונלי.

סטטוס התשובה משקף את תוצאת חברת השילוח: 200 כשהמשלוח בוטל, 424 כשחברת השילוח דחתה את הביטול. בשני המקרים הגוף באותו מבנה.

פרמטרים

Path:

שדה	סוג	חובה	תיאור
`shipment`	string	כן	ה-`uuid` של המשלוח, קוד המעקב של חברת השליחויות, או קוד המעקב הקצר.

Body:

שדה	סוג	חובה	תיאור
`license_key`	string	לא	‏`licenses.key` לצמצום החיפוש לחשבון שילוח אחד. אם יישמט, החיפוש משתרע על כל הרישיונות שבבעלותכם.

דוגמת בקשה

bash

curl --location 'https://app.shipos.co.il/api/v2/shipments/9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88/cancel' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

// Node.js 18+ / דפדפנים — בלי תלויות
const uuid = '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88'

const response = await fetch(
  `https://app.shipos.co.il/api/v2/shipments/${uuid}/cancel`,
  {
    method: 'POST',
    headers: {
      'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
      'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
      Accept: 'application/json',
      'Content-Type': 'application/json',
    },
    // add { license_key } when the account has more than one license
    body: JSON.stringify({}),
  },
)

// 424 is a carrier refusal, not an error envelope
if (!response.ok && response.status !== 424) {
  const { error } = await response.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data: result } = await response.json()
console.log(result.cancelled, result.message)

php

<?php
// composer require guzzlehttp/guzzle

$uuid = '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88';

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.shipos.co.il/api/v2/',
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
    ],
]);

// 424 is a carrier refusal carrying the same data shape
$response = $client->post("shipments/{$uuid}/cancel", [
    'json' => new \stdClass(), // add ['license_key' => '...'] with multiple licenses
    'http_errors' => false,
]);

$result = json_decode($response->getBody()->getContents(), true)['data'];

echo var_export($result['cancelled'], true), ' ', $result['message'], PHP_EOL;

php

<?php

use Illuminate\Support\Facades\Http;

$uuid = '9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88';

$response = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
])
    ->acceptJson()
    ->post("https://app.shipos.co.il/api/v2/shipments/{$uuid}/cancel", [
        // 'license_key' => '...' when the account has more than one license
    ]);

// 424 is a carrier refusal carrying the same data shape
$result = $response->throwIf($response->status() !== 424)->json('data');

logger()->info($result['message'], ['cancelled' => $result['cancelled']]);

python

# pip install httpx
import os

import httpx

uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88"

response = httpx.post(
    f"https://app.shipos.co.il/api/v2/shipments/{shipment}/cancel",
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
    },
    json={},  # add {"license_key": "..."} with multiple licenses
)
# 424 is a carrier refusal carrying the same data shape
if response.status_code != 424:
    response.raise_for_status()
result = response.json()["data"]

print(result["cancelled"], result["message"])

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	uuid := "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88"

	// add {"license_key":"..."} when the account has more than one license
	body := bytes.NewReader([]byte(`{}`))

	req, _ := http.NewRequest("POST",
		"https://app.shipos.co.il/api/v2/shipments/"+uuid+"/cancel", body)
	req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
	req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	// 200 = cancelled, 424 = carrier refused (same data shape)
	fmt.Println(res.StatusCode, string(out))
}

java

// Java 17+ — java.net.http, בלי תלויות (פרסור עם Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ShipOsCancelShipment {
    public static void main(String[] args) throws Exception {
        String uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88";

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(
                "https://app.shipos.co.il/api/v2/shipments/" + uuid + "/cancel"))
            .header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
            .header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
            .header("Accept", "application/json")
            .header("Content-Type", "application/json")
            // add {"license_key":"..."} with more than one license
            .POST(HttpRequest.BodyPublishers.ofString("{}"))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        // 424 is a carrier refusal carrying the same data shape
        if (response.statusCode() != 200 && response.statusCode() != 424) {
            throw new RuntimeException("ShipOS error: " + response.body());
        }

        System.out.println(response.body()); // {"data":{"cancelled":true,...}}
    }
}

csharp

// .NET 8+ — System.Net.Http.Json
using System.Net;
using System.Net.Http.Json;
using System.Text.Json;

var uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88";

using var http = new HttpClient
{
    BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));

// add license_key to the body when the account has more than one license
var response = await http.PostAsJsonAsync($"shipments/{shipment}/cancel", new { });

// 424 is a carrier refusal carrying the same data shape
if (response.StatusCode != HttpStatusCode.FailedDependency)
{
    response.EnsureSuccessStatusCode();
}

var payload = await response.Content.ReadFromJsonAsync<JsonDocument>()
    ?? throw new InvalidOperationException("Empty response");
var result = payload.RootElement.GetProperty("data");

Console.WriteLine($"{result.GetProperty("cancelled").GetBoolean()} " +
    result.GetProperty("message").GetString());

ruby

require "net/http"
require "json"

uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88"
uri = URI("https://app.shipos.co.il/api/v2/shipments/#{uuid}/cancel")

request = Net::HTTP::Post.new(uri)
request["X-Client-Id"] = ENV.fetch("SHIPOS_CLIENT_ID")
request["X-Client-Secret"] = ENV.fetch("SHIPOS_CLIENT_SECRET")
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request.body = JSON.dump({}) # add license_key: "..." with multiple licenses

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

# 424 is a carrier refusal carrying the same data shape
unless response.is_a?(Net::HTTPSuccess) || response.code == "424"
  raise "ShipOS error: #{response.body}"
end

result = JSON.parse(response.body).fetch("data")
puts "#{result["cancelled"]} #{result["message"]}"

rust

// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let uuid = "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88";

    let response = reqwest::Client::new()
        .post(format!(
            "https://app.shipos.co.il/api/v2/shipments/{shipment}/cancel"
        ))
        .header("X-Client-Id", std::env::var("SHIPOS_CLIENT_ID")?)
        .header("X-Client-Secret", std::env::var("SHIPOS_CLIENT_SECRET")?)
        .header("Accept", "application/json")
        // add "license_key" when the account has more than one license
        .json(&serde_json::json!({}))
        .send()
        .await?;

    // 424 is a carrier refusal carrying the same data shape
    let status = response.status();
    let payload: Value = response.json().await?;
    if !status.is_success() && status.as_u16() != 424 {
        return Err(format!("ShipOS error: {payload}").into());
    }

    println!("{} {}", payload["data"]["cancelled"], payload["data"]["message"]);
    Ok(())
}

תשובה `200`

json

{
  "data": {
    "uuid": "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88",
    "cancelled": true,
    "message": "Shipment cancelled."
  }
}

כשחברת השילוח דוחה את הביטול, אותו גוף מוחזר עם cancelled: false וסטטוס 424:

json

{
  "data": {
    "uuid": "9b2c7f1e-3a4d-4c88-9f21-2f0d5a6b7c88",
    "cancelled": false,
    "message": "The carrier could not cancel this shipment."
  }
}

שגיאות

סטטוס	קוד	מתי
401	`unauthenticated`	client credentials חסרים או לא תקינים.
403	`forbidden`	הרישיון אינו בבעלות / לא פעיל / פג תוקף, או שאין רישיון פעיל.
404	`not_found`	אין משלוח עם ה-`uuid` הזה תחת הרישיון שנקבע.
422	`validation_failed`	מספר רישיונות ו-`license_key` הושמט.

הערה: ביטול שנדחה על-ידי חברת השילוח אינו תשובת מעטפת error — הוא מחזיר את מבנה ה-data שלמעלה עם HTTP 424 ו-cancelled: false.

משלוחים ​

GET /shipments ​

פרמטרים ​

דוגמת בקשה ​

תשובה 200 ​

שגיאות ​

POST /shipments ​

פרמטרים ​

דוגמת בקשה ​

תשובה 201 ​

שגיאות ​

אובייקט המשלוח ​

GET /shipments/ ​

פרמטרים ​

דוגמת בקשה ​

תשובה 200 ​

שגיאות ​

GET /shipments/{shipment}/status ​

פרמטרים ​

דוגמת בקשה ​

תשובה 200 ​

שגיאות ​

GET /shipments/{shipment}/label ​

פרמטרים ​

דוגמת בקשה ​

תשובה 200 ​

שגיאות ​

POST /shipments/labels ​

פרמטרים ​

דוגמת בקשה ​

תשובה 200 ​

שגיאות ​

POST /shipments/{shipment}/cancel ​

פרמטרים ​

דוגמת בקשה ​

תשובה 200 ​

שגיאות ​

משלוחים

`GET` /shipments

פרמטרים

דוגמת בקשה

תשובה `200`

שגיאות

`POST` /shipments

פרמטרים

דוגמת בקשה

תשובה `201`

שגיאות

אובייקט המשלוח

`GET` /shipments/

פרמטרים

דוגמת בקשה

תשובה `200`

שגיאות

`GET` /shipments/{shipment}/status

פרמטרים

דוגמת בקשה

תשובה `200`

שגיאות

`GET` /shipments/{shipment}/label

פרמטרים

דוגמת בקשה

תשובה `200`

שגיאות

`POST` /shipments/labels

פרמטרים

דוגמת בקשה

תשובה `200`

שגיאות

`POST` /shipments/{shipment}/cancel

פרמטרים

דוגמת בקשה

תשובה `200`

שגיאות