טיפול בהחזרות

החזרה היא בסך הכול משלוח עם סוג שירות איסוף: השליח אוסף את החבילה מהלקוח שלכם במקום למסור לו. אין endpoint נפרד להחזרות — יוצרים אותה עם POST /shipments, ומציינים בעצמכם ship_data.type = "2" (איסוף) ו-ship_data.return = "2" (הלוך ושוב). שני השדות נדרשים בכל משלוח, לכן יש לציין אותם במפורש.

כל מה שאחרי היצירה עובר דרך ה-endpoints הרגילים של משלוחים: שליפה, סטטוס, תווית וביטול משתמשים כולם ב-/shipments/{shipment}, כאשר {shipment} מקבל את ה-uuid, את קוד המעקב של חברת השליחויות או את קוד המעקב הקצר. ראו את מדריך העזר למשלוחים.

שלב 1 — יצירת החזרה

קראו ל-POST /shipments עם ship_data.type = "2" ו-ship_data.return = "2". איש הקשר והכתובת ב-ship_data הם הלקוח שממנו אתם אוספים — לשם השליח מגיע. בלוק ה-order מפנה להזמנה המקורית שהלקוח מחזיר.

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

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: 7c3e9f2b-1a5d-4b8c-9e6f-0d2a4b6c8e1f' \
--data '{
  "license_key": "a1b2c3d4e5f6",
  "ship_data": {
    "contact_name": "ישראל ישראלי",
    "contact_phone": "0521234567",
    "contact_mail": "israel@example.co.il",
    "street": "הרצל",
    "number": "10",
    "city": "תל אביב",
    "floor": "3",
    "apartment": "12",
    "type": "2",
    "return": "2",
    "packages": 1,
    "note": "החזרה של הזמנה 1042 - לאסוף מהלקוח"
  },
  "order": {
    "id": "1042",
    "number": "1042",
    "currency": "ILS",
    "total": 179.90,
    "source": "api",
    "shipping": {
      "first_name": "ישראל",
      "last_name": "ישראלי",
      "phone": "0521234567",
      "email": "israel@example.co.il",
      "address_1": "הרצל",
      "address_2": "10",
      "city": "תל אביב",
      "postcode": "6688312",
      "country": "IL"
    },
    "order_items": [
      {
        "sku": "TSHIRT-M-BLK",
        "name": "חולצת טי כותנה (M, שחור)",
        "quantity": 2,
        "price": 89.95,
        "total": 179.90
      }
    ]
  }
}'

// Node.js 18+ / דפדפנים — ללא תלויות
const res = 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': '7c3e9f2b-1a5d-4b8c-9e6f-0d2a4b6c8e1f',
  },
  body: JSON.stringify({
    license_key: 'a1b2c3d4e5f6',
    ship_data: {
      contact_name: 'ישראל ישראלי',
      contact_phone: '0521234567',
      contact_mail: 'israel@example.co.il',
      street: 'הרצל',
      number: '10',
      city: 'תל אביב',
      floor: '3',
      apartment: '12',
      type: "2",
      return: "2",
      packages: 1,
      note: 'החזרה של הזמנה 1042 - לאסוף מהלקוח',
    },
    order: {
      id: '1042',
      number: '1042',
      currency: 'ILS',
      total: 179.9,
      source: 'api',
      shipping: {
        first_name: 'ישראל',
        last_name: 'ישראלי',
        phone: '0521234567',
        email: 'israel@example.co.il',
        address_1: 'הרצל',
        address_2: '10',
        city: 'תל אביב',
        postcode: '6688312',
        country: 'IL',
      },
      order_items: [
        { sku: 'TSHIRT-M-BLK', name: 'חולצת טי כותנה (M, שחור)', quantity: 2, price: 89.95, total: 179.9 },
      ],
    },
  }),
})

const { data: returnShipment } = await res.json() // res.status === 201

php

<?php
// composer require guzzlehttp/guzzle

$client = new \GuzzleHttp\Client(['base_uri' => 'https://app.shipos.co.il/api/v2/']);

$response = $client->post('returns', [
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
        'Idempotency-Key' => '7c3e9f2b-1a5d-4b8c-9e6f-0d2a4b6c8e1f',
    ],
    'json' => [
        'license_key' => 'a1b2c3d4e5f6',
        'ship_data' => [
            'contact_name' => 'ישראל ישראלי',
            'contact_phone' => '0521234567',
            'contact_mail' => 'israel@example.co.il',
            'street' => 'הרצל',
            'number' => '10',
            'city' => 'תל אביב',
            'floor' => '3',
            'apartment' => '12',
            'type' => '2',
            'return' => '2',
            'packages' => 1,
            'note' => 'החזרה של הזמנה 1042 - לאסוף מהלקוח',
        ],
        'order' => [
            'id' => '1042',
            'number' => '1042',
            'currency' => 'ILS',
            'total' => 179.90,
            'source' => 'api',
            'shipping' => [
                'first_name' => 'ישראל',
                'last_name' => 'ישראלי',
                'phone' => '0521234567',
                'email' => 'israel@example.co.il',
                'address_1' => 'הרצל',
                'address_2' => '10',
                'city' => 'תל אביב',
                'postcode' => '6688312',
                'country' => 'IL',
            ],
            'order_items' => [
                ['sku' => 'TSHIRT-M-BLK', 'name' => 'חולצת טי כותנה (M, שחור)', 'quantity' => 2, 'price' => 89.95, 'total' => 179.90],
            ],
        ],
    ],
]);

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

php

<?php

use Illuminate\Support\Facades\Http;

$return = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
    'Idempotency-Key' => '7c3e9f2b-1a5d-4b8c-9e6f-0d2a4b6c8e1f',
])
    ->acceptJson()
    ->post('https://app.shipos.co.il/api/v2/shipments', [
        'license_key' => 'a1b2c3d4e5f6',
        'ship_data' => [
            'contact_name' => 'ישראל ישראלי',
            'contact_phone' => '0521234567',
            'contact_mail' => 'israel@example.co.il',
            'street' => 'הרצל',
            'number' => '10',
            'city' => 'תל אביב',
            'floor' => '3',
            'apartment' => '12',
            'type' => '2',
            'return' => '2',
            'packages' => 1,
            'note' => 'החזרה של הזמנה 1042 - לאסוף מהלקוח',
        ],
        'order' => [
            'id' => '1042',
            'number' => '1042',
            'currency' => 'ILS',
            'total' => 179.90,
            'source' => 'api',
            'shipping' => [
                'first_name' => 'ישראל',
                'last_name' => 'ישראלי',
                'phone' => '0521234567',
                'email' => 'israel@example.co.il',
                'address_1' => 'הרצל',
                'address_2' => '10',
                'city' => 'תל אביב',
                'postcode' => '6688312',
                'country' => 'IL',
            ],
            'order_items' => [
                ['sku' => 'TSHIRT-M-BLK', 'name' => 'חולצת טי כותנה (M, שחור)', 'quantity' => 2, 'price' => 89.95, 'total' => 179.90],
            ],
        ],
    ])
    ->throw()
    ->json('data');

python

# pip install httpx
import os

import httpx

payload = {
    "license_key": "a1b2c3d4e5f6",
    "ship_data": {
        "contact_name": "ישראל ישראלי",
        "contact_phone": "0521234567",
        "contact_mail": "israel@example.co.il",
        "street": "הרצל",
        "number": "10",
        "city": "תל אביב",
        "floor": "3",
        "apartment": "12",
        "type": "2",
        "return": "2",
        "packages": 1,
        "note": "החזרה של הזמנה 1042 - לאסוף מהלקוח",
    },
    "order": {
        "id": "1042",
        "number": "1042",
        "currency": "ILS",
        "total": 179.90,
        "source": "api",
        "shipping": {
            "first_name": "ישראל",
            "last_name": "ישראלי",
            "phone": "0521234567",
            "email": "israel@example.co.il",
            "address_1": "הרצל",
            "address_2": "10",
            "city": "תל אביב",
            "postcode": "6688312",
            "country": "IL",
        },
        "order_items": [
            {"sku": "TSHIRT-M-BLK", "name": "חולצת טי כותנה (M, שחור)", "quantity": 2, "price": 89.95, "total": 179.90},
        ],
    },
}

response = httpx.post(
    "https://app.shipos.co.il/api/v2/shipments",
    json=payload,
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
        "Idempotency-Key": "7c3e9f2b-1a5d-4b8c-9e6f-0d2a4b6c8e1f",
    },
)
response.raise_for_status()
return_shipment = response.json()["data"]  # 201 Created

package main

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

func main() {
	payload, _ := json.Marshal(map[string]any{
		"license_key": "a1b2c3d4e5f6",
		"ship_data": map[string]any{
			"contact_name":  "ישראל ישראלי",
			"contact_phone": "0521234567",
			"contact_mail":  "israel@example.co.il",
			"street":        "הרצל",
			"number":        "10",
			"city":          "תל אביב",
			"floor":         "3",
			"apartment":     "12",
			"type":          "2",
			"return":        "2",
			"packages":      1,
			"note":          "החזרה של הזמנה 1042 - לאסוף מהלקוח",
		},
		"order": map[string]any{
			"id":       "1042",
			"number":   "1042",
			"currency": "ILS",
			"total":    179.90,
			"source":   "api",
			"shipping": map[string]any{
				"first_name": "ישראל", "last_name": "ישראלי",
				"phone": "0521234567", "email": "israel@example.co.il",
				"address_1": "הרצל", "address_2": "10",
				"city": "תל אביב", "postcode": "6688312", "country": "IL",
			},
			"order_items": []map[string]any{{
				"sku": "TSHIRT-M-BLK", "name": "חולצת טי כותנה (M, שחור)",
				"quantity": 2, "price": 89.95, "total": 179.90,
			}},
		},
	})

	req, _ := http.NewRequest("POST", "https://app.shipos.co.il/api/v2/shipments", bytes.NewReader(payload))
	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("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Idempotency-Key", "7c3e9f2b-1a5d-4b8c-9e6f-0d2a4b6c8e1f")

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

	var created struct {
		Data struct {
			UUID         string `json:"uuid"`
			TrackingCode string `json:"tracking_code"`
		} `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&created); err != nil {
		panic(err)
	}

	fmt.Println(created.Data.UUID, created.Data.TrackingCode)
}

java

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

public class ShipOsCreateReturn {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "license_key": "a1b2c3d4e5f6",
              "ship_data": {
                "contact_name": "ישראל ישראלי",
                "contact_phone": "0521234567",
                "contact_mail": "israel@example.co.il",
                "street": "הרצל",
                "number": "10",
                "city": "תל אביב",
                "floor": "3",
                "apartment": "12",
                "type": "2",
                "return": "2",
                "packages": 1,
                "note": "החזרה של הזמנה 1042 - לאסוף מהלקוח"
              },
              "order": {
                "id": "1042",
                "number": "1042",
                "currency": "ILS",
                "total": 179.90,
                "source": "api",
                "shipping": {
                  "first_name": "ישראל",
                  "last_name": "ישראלי",
                  "phone": "0521234567",
                  "email": "israel@example.co.il",
                  "address_1": "הרצל",
                  "address_2": "10",
                  "city": "תל אביב",
                  "postcode": "6688312",
                  "country": "IL"
                },
                "order_items": [
                  {"sku": "TSHIRT-M-BLK", "name": "חולצת טי כותנה (M, שחור)",
                   "quantity": 2, "price": 89.95, "total": 179.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("Content-Type", "application/json")
            .header("Accept", "application/json")
            .header("Idempotency-Key", "7c3e9f2b-1a5d-4b8c-9e6f-0d2a4b6c8e1f")
            .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":{"uuid":...}}
    }
}

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",
    "7c3e9f2b-1a5d-4b8c-9e6f-0d2a4b6c8e1f");

var payload = new
{
    license_key = "a1b2c3d4e5f6",
    ship_data = new
    {
        contact_name = "ישראל ישראלי",
        contact_phone = "0521234567",
        contact_mail = "israel@example.co.il",
        street = "הרצל",
        number = "10",
        city = "תל אביב",
        floor = "3",
        apartment = "12",
        type = "2",
        @return = "2",
        packages = 1,
        note = "החזרה של הזמנה 1042 - לאסוף מהלקוח",
    },
    order = new
    {
        id = "1042",
        number = "1042",
        currency = "ILS",
        total = 179.90,
        source = "api",
        shipping = new
        {
            first_name = "ישראל", last_name = "ישראלי",
            phone = "0521234567", email = "israel@example.co.il",
            address_1 = "הרצל", address_2 = "10",
            city = "תל אביב", postcode = "6688312", country = "IL",
        },
        order_items = new[]
        {
            new { sku = "TSHIRT-M-BLK", name = "חולצת טי כותנה (M, שחור)", quantity = 2, price = 89.95, total = 179.90 },
        },
    },
};

var response = await http.PostAsJsonAsync("returns", payload);
response.EnsureSuccessStatusCode();

var created = (await response.Content.ReadFromJsonAsync<JsonDocument>())!
    .RootElement.GetProperty("data");

Console.WriteLine(created.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"] = "7c3e9f2b-1a5d-4b8c-9e6f-0d2a4b6c8e1f"
request.body = JSON.dump(
  license_key: "a1b2c3d4e5f6",
  ship_data: {
    contact_name: "ישראל ישראלי",
    contact_phone: "0521234567",
    contact_mail: "israel@example.co.il",
    street: "הרצל",
    number: "10",
    city: "תל אביב",
    floor: "3",
    apartment: "12",
    type: "2",
    return: "2",
    packages: 1,
    note: "החזרה של הזמנה 1042 - לאסוף מהלקוח"
  },
  order: {
    id: "1042",
    number: "1042",
    currency: "ILS",
    total: 179.90,
    source: "api",
    shipping: {
      first_name: "ישראל", last_name: "ישראלי",
      phone: "0521234567", email: "israel@example.co.il",
      address_1: "הרצל", address_2: "10",
      city: "תל אביב", postcode: "6688312", country: "IL"
    },
    order_items: [
      { sku: "TSHIRT-M-BLK", name: "חולצת טי כותנה (M, שחור)",
        quantity: 2, price: 89.95, total: 179.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)

return_shipment = JSON.parse(response.body).fetch("data")

rust

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let payload = json!({
        "license_key": "a1b2c3d4e5f6",
        "ship_data": {
            "contact_name": "ישראל ישראלי",
            "contact_phone": "0521234567",
            "contact_mail": "israel@example.co.il",
            "street": "הרצל",
            "number": "10",
            "city": "תל אביב",
            "floor": "3",
            "apartment": "12",
            "type": "2",
            "return": "2",
            "packages": 1,
            "note": "החזרה של הזמנה 1042 - לאסוף מהלקוח"
        },
        "order": {
            "id": "1042",
            "number": "1042",
            "currency": "ILS",
            "total": 179.90,
            "source": "api",
            "shipping": {
                "first_name": "ישראל", "last_name": "ישראלי",
                "phone": "0521234567", "email": "israel@example.co.il",
                "address_1": "הרצל", "address_2": "10",
                "city": "תל אביב", "postcode": "6688312", "country": "IL"
            },
            "order_items": [{
                "sku": "TSHIRT-M-BLK", "name": "חולצת טי כותנה (M, שחור)",
                "quantity": 2, "price": 89.95, "total": 179.90
            }]
        }
    });

    let created: 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", "7c3e9f2b-1a5d-4b8c-9e6f-0d2a4b6c8e1f")
        .json(&payload)
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

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

תגובת 201 Created מחזירה אובייקט משלוח סטנדרטי — שימו לב ש-service_type הוא "2":

json

{
  "data": {
    "uuid": "5e8a1d3c-6f2b-4a97-8c4e-1b9d0e7f2a35",
    "tracking_code": "66812345",
    "carrier": { "id": 4, "name": "HFD" },
    "status": null,
    "service_type": "2",
    "is_active": true,
    "recipient": {
      "name": "ישראל ישראלי",
      "phone": "0521234567",
      "company": null,
      "address": {
        "street": "הרצל",
        "number": "10",
        "city": "תל אביב",
        "state": null,
        "zip": "6688312",
        "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-29T10:02:00.000000Z",
    "updated_at": "2026-07-29T10:02:00.000000Z"
  }
}

שמרו את ה-uuid (לקריאות המשך) ואת ה-tracking_code (עבור הלקוח שלכם), בדיוק כמו במשלוח רגיל.

היצירה חולקת את אותם מצבי כשל כמו POST /shipments — ‏422 validation_failed, ‏403 package_limit_reached, ‏424 carrier_error, ‏409 idempotency_key_conflict — ראו את מדריך השגיאות.

שלב 2 — רשימת ההחזרות שלכם

GET /shipments?filter[type]=2 מציג רק משלוחי איסוף — כלומר את ההחזרות — עם עימוד (pagination). ‏license_key הוא אופציונלי כאן: קריאות משתרעות על כל הרישיונות שלכם אלא אם תעבירו אחד כדי לצמצם. ‏per_page הוא 25 כברירת מחדל ומוגבל ל-100:

bash

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

// Node.js 18+ / דפדפנים — ללא תלויות
const query = new URLSearchParams({ license_key: 'a1b2c3d4e5f6', per_page: '25' })

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

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

const { data: returns, meta } = await res.json()

console.log(`${returns.length} of ${meta.total} returns`)
for (const ret of returns) {
  console.log(ret.uuid, ret.tracking_code, ret.status)
}

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',
    ],
]);

$response = $client->get('returns', [
    'query' => ['license_key' => 'a1b2c3d4e5f6', 'per_page' => 25],
]);

$payload = json_decode($response->getBody()->getContents(), true);

foreach ($payload['data'] as $return) {
    echo $return['uuid'], ' ', $return['tracking_code'], 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', [
        'license_key' => 'a1b2c3d4e5f6',
        'per_page' => 25,
    ])
    ->throw()
    ->json();

foreach ($payload['data'] as $return) {
    logger()->info($return['uuid'].' '.$return['tracking_code']);
}

python

# pip install httpx
import os

import httpx

response = httpx.get(
    "https://app.shipos.co.il/api/v2/shipments",
    params={"license_key": "a1b2c3d4e5f6", "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(f"{len(payload['data'])} of {payload['meta']['total']} returns")
for ret in payload["data"]:
    print(ret["uuid"], ret["tracking_code"], ret["status"])

package main

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

type returnsResponse struct {
	Data []struct {
		UUID         string `json:"uuid"`
		TrackingCode string `json:"tracking_code"`
	} `json:"data"`
	Meta struct {
		Total int `json:"total"`
	} `json:"meta"`
}

func main() {
	query := url.Values{"license_key": {"a1b2c3d4e5f6"}, "per_page": {"25"}}
	req, _ := http.NewRequest("GET", "https://app.shipos.co.il/api/v2/shipments?"+query.Encode(), 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 payload returnsResponse
	if err := json.NewDecoder(res.Body).Decode(&payload); err != nil {
		panic(err)
	}

	fmt.Printf("%d of %d returns\n", len(payload.Data), payload.Meta.Total)
	for _, ret := range payload.Data {
		fmt.Println(ret.UUID, ret.TrackingCode)
	}
}

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 ShipOsListReturns {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(
                "https://app.shipos.co.il/api/v2/shipments?license_key=a1b2c3d4e5f6&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":[...],"links":{...},"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>(
        "returns?license_key=a1b2c3d4e5f6&per_page=25")
    ?? throw new InvalidOperationException("Empty response");

Console.WriteLine(payload.RootElement.GetProperty("meta").GetProperty("total").GetInt32());
foreach (var ret in payload.RootElement.GetProperty("data").EnumerateArray())
{
    Console.WriteLine(
        $"{ret.GetProperty("uuid").GetString()} {ret.GetProperty("tracking_code").GetString()}");
}

ruby

require "net/http"
require "json"

uri = URI("https://app.shipos.co.il/api/v2/shipments")
uri.query = URI.encode_www_form(license_key: "a1b2c3d4e5f6", 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")} returns"
payload["data"].each { |ret| puts "#{ret["uuid"]} #{ret["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()
        .get("https://app.shipos.co.il/api/v2/shipments")
        .query(&[("license_key", "a1b2c3d4e5f6"), ("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?;

    println!("{} returns", payload["meta"]["total"]);
    if let Some(returns) = payload["data"].as_array() {
        for ret in returns {
            println!("{} {}", ret["uuid"], ret["tracking_code"]);
        }
    }
    Ok(())
}

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

מידע

אותן החזרות מופיעות גם ברשימה הלא-מסוננת של GET /shipments — ‏filter[type]=2 הוא תצוגה על משלוחים, לא משאב נפרד.

שלב 3 — מעקב וניהול של ההחזרה כמו כל משלוח

אין endpoints ייעודיים להחזרות מעבר ליצירה ולרשימה. השתמשו ב-endpoints של משלוחים עם ה-uuid של ההחזרה:

פעולה	Endpoint
שליפה	`GET /shipments/{shipment}`
רענון סטטוס מהמוביל	`GET /shipments/{shipment}/status`
תווית (תווית האיסוף שהשליח סורק)	`GET /shipments/{shipment}/label`
ביטול	`POST /shipments/{shipment}/cancel`
מעקב ללא פרטים אישיים (דורש אימות)	`GET /tracking/{shipping_code}`

לדוגמה, כדי לבדוק אם השליח כבר אסף את החבילה:

bash

curl --location 'https://app.shipos.co.il/api/v2/shipments/5e8a1d3c-6f2b-4a97-8c4e-1b9d0e7f2a35/status' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json'

// Node.js 18+ / דפדפנים — ללא תלויות
const uuid = '5e8a1d3c-6f2b-4a97-8c4e-1b9d0e7f2a35'

const res = 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 (!res.ok) {
  const { error } = await res.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data: status } = await res.json()

console.log(status.status, status.collection_status, status.collected_at)

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',
    ],
]);

$uuid = '5e8a1d3c-6f2b-4a97-8c4e-1b9d0e7f2a35';

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

echo $status['status'], ' / ', $status['collection_status'] ?? 'null', PHP_EOL;

php

<?php

use Illuminate\Support\Facades\Http;

$uuid = '5e8a1d3c-6f2b-4a97-8c4e-1b9d0e7f2a35';

$status = 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($status['status'], ['collected_at' => $status['collected_at']]);

python

# pip install httpx
import os

import httpx

uuid = "5e8a1d3c-6f2b-4a97-8c4e-1b9d0e7f2a35"

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"]

print(status["status"], status["collection_status"], status["collected_at"])

package main

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

type statusResponse struct {
	Data struct {
		Status           string  `json:"status"`
		CollectionStatus *string `json:"collection_status"`
		CollectedAt      *string `json:"collected_at"`
	} `json:"data"`
}

func main() {
	uuid := "5e8a1d3c-6f2b-4a97-8c4e-1b9d0e7f2a35"

	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()

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

	fmt.Println(payload.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 ShipOsReturnStatus {
    public static void main(String[] args) throws Exception {
        String uuid = "5e8a1d3c-6f2b-4a97-8c4e-1b9d0e7f2a35";

        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;

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 uuid = "5e8a1d3c-6f2b-4a97-8c4e-1b9d0e7f2a35";

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

Console.WriteLine(status.GetProperty("status").GetString());
Console.WriteLine(status.GetProperty("collection_status").ToString());

ruby

require "net/http"
require "json"

uuid = "5e8a1d3c-6f2b-4a97-8c4e-1b9d0e7f2a35"

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).fetch("data")

puts "#{status["status"]} / #{status["collection_status"].inspect}"

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 = "5e8a1d3c-6f2b-4a97-8c4e-1b9d0e7f2a35";

    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"];
    println!("{} {}", status["status"], status["collection_status"]);
    Ok(())
}

כל אלה מתועדים במדריך העזר למשלוחים ובמדריך העזר למעקב.

טיפול בהחזרות ​

שלב 1 — יצירת החזרה ​

שלב 2 — רשימת ההחזרות שלכם ​

שלב 3 — מעקב וניהול של ההחזרה כמו כל משלוח ​

טיפול בהחזרות

שלב 1 — יצירת החזרה

שלב 2 — רשימת ההחזרות שלכם

שלב 3 — מעקב וניהול של ההחזרה כמו כל משלוח