Kargoya Teslim

Bir siparişin belirtilen kargo firması ve takip numarası ile kargoya verildiğini sisteme kaydeder.

Gerekli yetki: order:write

Endpoint

PUT /integration/shipment/sellers/{sellerId}/shipments

Production
https://api.milagron.com/integration/shipment/sellers/{sellerId}/shipments
Stage
https://stageapi.milagron.com/integration/shipment/sellers/{sellerId}/shipments

İstek Gövdesi

{
  "orderNumber": "#1075399",
  "cargoCompanyCode": "YKMP",
  "trackingNumber": "1234567890123",
  "items": [
    { "barcode": "8690000000001", "quantity": 2 },
    { "barcode": "8690000000002", "quantity": 1 }
  ]
}

Alanlar

AlanTipZorunluAçıklama
orderNumberstringEvetSipariş numarası (# karakteriyle veya karaktersiz gönderilebilir).
cargoCompanyCodestringEvetDesteklenen kargo firması kodu (aşağıdaki tabloya bakınız).
trackingNumberstringEvetKargo takip numarası.
itemsarrayEvetKargoya verilen ürünler (en fazla 250 adet).
items[].barcodestringEvetÜrün barkodu.
items[].quantityintegerEvet1 veya daha büyük olmalıdır.

Desteklenen Kargo Firmaları

Aşağıdaki tabloda, cargoCompanyCode alanı için kullanılabilecek geçerli değerler yer almaktadır.

KodKargo Firması
ARASMPAras Kargo
BOVOMPBovo
CEVAMPCeva Lojistik
CEVATEDARIKCeva Tedarik
DHLECOMMPDHL
FILLOMPFillo Kargo
HEPSIJETMPHepsiJET
HOROZMPHoroz Lojistik
KOLAYGELSINMPKolay Gelsin
MNGMPMNG Kargo
PTTMPPTT
SENDEOMPSendeo
SURATMPSürat Kargo
TNTMPTNT Kargo
UPSMPUPS Kargo
YKMPYurtiçi Kargo

Yanıt (200 OK)

{
  "status": "ok",
  "message": "Shipment created successfully",
  "shippingLogId": 12345,
  "trackingInfo": {
    "company": "Yurtiçi Kargo",
    "code": "YKMP",
    "trackingNumber": "1234567890123",
    "trackingUrl": "https://www.yurticikargo.com/tr/online-servisler/gonderi-sorgula?code=1234567890123"
  },
  "items": [
    { "barcode": "8690000000001", "quantity": 2 },
    { "barcode": "8690000000002", "quantity": 1 }
  ]
}

Alanlar

AlanTipAçıklama
statusstringİşlem sonucu (ok döner).
messagestringAçıklayıcı mesaj.
shippingLogIdintegerKayıt altına alınan kargo log kimliği.
trackingInfo.companystringKargo firması adı.
trackingInfo.codestringKargo firması kodu.
trackingInfo.trackingNumberstringTakip numarası.
trackingInfo.trackingUrlstringTakip için açık URL.
itemsarrayEşleşmiş ve işleme alınmış barkod/adet listesi.
warningsobject(Opsiyonel) Bir kısım item için hata oluştuysa yanıta eklenir.

Davranış

  • Sipariş, orderNumber ve sellerId bilgileri ile eşleştirilir.
  • Item barkodları, sipariş içeriğindeki ürünlerle eşleştirilir.
  • Kısmi kargo desteklenmektedir; tüm item'ların aynı anda gönderilmesi zorunlu değildir.
  • Tamamen tamamlanmış siparişler için 409 Conflict hatası döner.
  • İstenen adet kalan miktardan büyükse 409 Conflict döner.

Stage Ortamı Davranışı

Stage ortamında bu endpoint:
  • Sipariş eşleştirmesini gerçek olarak yürütür (sipariş bulunamazsa 404 döner).
  • Barkod doğrulaması ve kalan miktar kontrolü gerçek olarak uygulanır.
  • Sipariş veritabanında güncellenmez; dış sistemlere çağrı gönderilmez.
  • Simüle edilmiş başarılı yanıt döner (_stage: true alanı içerir).

Kullanım Örnekleri

curl -u "API_KEY:API_SECRET" \
  -X PUT "https://api.milagron.com/integration/shipment/sellers/123/shipments" \
  -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "#1075399",
    "cargoCompanyCode": "YKMP",
    "trackingNumber": "1234567890123",
    "items": [
        {
            "barcode": "8690000000001",
            "quantity": 2
        }
    ]
}'
<?php

$ch = curl_init('https://api.milagron.com/integration/shipment/sellers/123/shipments');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD        => 'API_KEY:API_SECRET',
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
    'orderNumber' => '#1075399',
    'cargoCompanyCode' => 'YKMP',
    'trackingNumber' => '1234567890123',
    'items' => [
        [
            'barcode' => '8690000000001',
            'quantity' => 2
        ]
    ]
]),
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
const auth = Buffer.from('API_KEY:API_SECRET').toString('base64');

const res = await fetch('https://api.milagron.com/integration/shipment/sellers/123/shipments', {
    method: 'PUT',
    headers: {
        'Authorization': `Basic ${auth}`,
        'Content-Type':  'application/json'
    },
    body: JSON.stringify({
    orderNumber: '#1075399',
    cargoCompanyCode: 'YKMP',
    trackingNumber: '1234567890123',
    items: [
        {
            barcode: '8690000000001',
            quantity: 2
        }
    ]
})
});

const data = await res.json();
import requests

response = requests.put(
    'https://api.milagron.com/integration/shipment/sellers/123/shipments',
    auth=('API_KEY', 'API_SECRET'),
    json={
    'orderNumber': '#1075399',
    'cargoCompanyCode': 'YKMP',
    'trackingNumber': '1234567890123',
    'items': [
        {
            'barcode': '8690000000001',
            'quantity': 2
        }
    ]
}
)

response.raise_for_status()
data = response.json()
package main

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

func main() {
    payload, _ := json.Marshal(map[string]interface{}{
    "orderNumber": "#1075399",
    "cargoCompanyCode": "YKMP",
    "trackingNumber": "1234567890123",
    "items": []interface{}{
        map[string]interface{}{
            "barcode": "8690000000001",
            "quantity": 2,
        },
    },
})
    req, _ := http.NewRequest("PUT", "https://api.milagron.com/integration/shipment/sellers/123/shipments", bytes.NewBuffer(payload))
    req.SetBasicAuth("API_KEY", "API_SECRET")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
}
import java.net.URI;
import java.net.http.*;
import java.util.Base64;

HttpClient client = HttpClient.newHttpClient();

String auth = Base64.getEncoder()
    .encodeToString("API_KEY:API_SECRET".getBytes());

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.milagron.com/integration/shipment/sellers/123/shipments"))
    .header("Authorization", "Basic " + auth)
    .header("Content-Type", "application/json")
    .PUT(HttpRequest.BodyPublishers.ofString("{\"orderNumber\":\"#1075399\",\"cargoCompanyCode\":\"YKMP\",\"trackingNumber\":\"1234567890123\",\"items\":[{\"barcode\":\"8690000000001\",\"quantity\":2}]}"))
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());
require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.milagron.com/integration/shipment/sellers/123/shipments')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Put.new(uri.request_uri)
request.basic_auth('API_KEY', 'API_SECRET')
request['Content-Type'] = 'application/json'
request.body = {
  orderNumber: '#1075399',
  cargoCompanyCode: 'YKMP',
  trackingNumber: '1234567890123',
  items: [
    {
      barcode: '8690000000001',
      quantity: 2
    }
  ]
}.to_json

response = http.request(request)
data = JSON.parse(response.body)
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var client = new HttpClient();

var auth = Convert.ToBase64String(
    Encoding.UTF8.GetBytes("API_KEY:API_SECRET"));
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Basic", auth);

var content = new StringContent(
    "{\"orderNumber\":\"#1075399\",\"cargoCompanyCode\":\"YKMP\",\"trackingNumber\":\"1234567890123\",\"items\":[{\"barcode\":\"8690000000001\",\"quantity\":2}]}",
    Encoding.UTF8,
    "application/json");

var response = await client.PutAsync("https://api.milagron.com/integration/shipment/sellers/123/shipments", content);
var data = await response.Content.ReadAsStringAsync();

Hata Kodları

KodSebep
400Zorunlu alan eksik, items dizisi boş ya da 250 limitini aşmış.
401 / 403Kimlik doğrulama veya yetki problemi.
404Sipariş, kargo firması veya eşleşen barkod bulunamadı.
409Sipariş zaten tamamlanmış ya da istenen adet kalan miktardan büyük.
422Fulfillment işlemi başarısız oldu.