{ "openapi": "3.1.0", "info": { "title": "JetDiji Servis", "version": "2.0.0", "description": "JetDiji **gönderi entegrasyon servisi (v2)**: gönderi oluşturma, güncelleme, hazırlık, durum sorgulama ve iptal.\n\n| Ortam | Taban adres |\n|---|---|\n| Preprod (test) | `https://api.preprod.jetdiji.com` |\n| Canlı | `https://api.jetdiji.com` |\n\n**3 adımda başla**\n1. `POST /api/integration/v1/oauth/token` (form: `grant_type=client_credentials`, `client_id`, `client_secret`) → yanıttaki `access_token`'ı saklayın (varsayılan 900 sn).\n2. `POST /api/integration/v2/shipments` ile gönderi oluşturun: `Authorization: Bearer ` ve `X-Idempotency-Key: ` başlıklarıyla.\n3. `GET /api/integration/v2/shipments/{trackingNumber}` ile durumu sorgulayın; hareketler için `?include=movements`.\n\n**Idempotency:** Tüm yazma uçlarında (POST/PATCH/PUT) `X-Idempotency-Key` zorunludur. Tekrar denerken aynı anahtarı kullanın; yanıtta `replayed: true` döner.\n\n**Hata biçimi** (yalnız `error.code`'a bakın):\n`{ \"success\": false, \"error\": { \"code\": \"SHIPMENT_NOT_FOUND\", \"message\": \"…\", \"details\": null }, \"requestId\": \"REQ-…\", \"correlationId\": null }`\n\nToken ucu OAuth biçiminde döner: `{ \"error\": \"invalid_client\", \"error_description\": \"…\" }`.\n\nUçlar iş akışı sırasıyla gruplanmıştır. Her uç açıklaması aynı sırayı izler: özet → Ne zaman kullanılır → Yetki → Akıştaki yeri → Önemli kurallar.\n\nAyrıntılı rehber, uç kartları, kod sözlüğü ve v1'den geçiş: [Entegrasyon Rehberi](./customer-guide.html)\n\nİl ve ilçe kodları: `GET /api/integration/v2/reference/cities` ve `…/cities/{cityCode}/districts`.", "contact": { "name": "JetDiji", "email": "info@jetlogi.com", "url": "https://panel.jetdiji.com" } }, "servers": [ { "url": "https://api.preprod.jetdiji.com", "description": "Preprod (test)" }, { "url": "https://api.jetdiji.com", "description": "Canlı" }, { "url": "/", "description": "Aynı origin (dokümanın sunulduğu sunucu)" } ], "tags": [ { "name": "1 · Kimlik Doğrulama", "description": "İstemci kimliğiyle (client credentials) Bearer token alma." }, { "name": "2 · Referans Veriler", "description": "Adreslerde kullanılan il (`cityCode`) ve ilçe (`districtCode`) kodlarının listesi. Gönderi oluşturma ve adres güncelleme bu kodları kabul eder." }, { "name": "3 · Gönderi Oluşturma", "description": "Yeni gönderi açma. Ürünün iş akışı bu çağrıyla başlar." }, { "name": "4 · Gönderi Güncelleme", "description": "Oluşturulmuş gönderide alıcı, adres, ürün listesi ve müşteri referansı değişikliği." }, { "name": "5 · Hazırlık ve Evrak", "description": "Gönderi için gerekli evraklar ve onay bekleyen gönderide hazırlık kararı." }, { "name": "6 · Durum ve Hareket Sorgulama", "description": "Takip numarası, müşteri referansı ya da işlem numarasıyla durum sorgulama; hareket geçmişi." }, { "name": "7 · İptal", "description": "Takip numarası ya da işlem numarasıyla müşteri talebi iptali." } ], "paths": { "/api/integration/v1/oauth/token": { "post": { "operationId": "issueAccessToken", "tags": [ "1 · Kimlik Doğrulama" ], "summary": "Erişim token'ı al", "description": "İstemci kimliğiyle (client credentials) kısa süreli bir Bearer token alır.\n\n- **Ne zaman kullanılır:** Her oturumun başında ve token süresi dolunca.\n- **Yetki (scope):** Gerekmez. `client_id` + `client_secret` ile kimlik doğrulanır.\n- **Akıştaki yeri:** İlk adım. Dönen `access_token` diğer tüm uçlarda `Authorization: Bearer …` olarak gönderilir.\n- **Önemli kurallar:**\n - `Content-Type: application/x-www-form-urlencoded` zorunlu; değilse `415`.\n - Kimlik ya `Authorization: Basic base64(client_id:client_secret)` ya da form alanlarıyla gönderilir; ikisi çelişirse `401`.\n - Süre varsayılan 900 sn (istemciye göre 60–3600). Yenileme ucu yoktur; süre dolunca yeniden token alın.\n - Hata biçimi OAuth standardıdır: `{ error, error_description }`.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" }, "examples": { "formFields": { "summary": "Kimlik form alanlarında", "value": { "grant_type": "client_credentials", "client_id": "", "client_secret": "***", "scope": "shipment.create shipment.read shipment.update shipment.events.read shipment.cancel" } }, "basicHeader": { "summary": "Kimlik Basic başlığında (gövdede yalnız grant_type)", "value": { "grant_type": "client_credentials" } } } } } }, "responses": { "200": { "description": "Token verildi. Yanıt `Cache-Control: no-store` ile döner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" }, "example": { "access_token": "eyJhbGciOiJIUzI1NiJ9.***.***", "token_type": "Bearer", "expires_in": 900, "scope": "shipment.create shipment.read" } } } }, "400": { "description": "Gövde okunamadı, `grant_type` desteklenmiyor ya da istenen scope tanımlı değil.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "examples": { "invalid_request": { "summary": "Gövde okunamadı", "value": { "error": "invalid_request", "error_description": "The token request body is invalid." } }, "unsupported_grant_type": { "summary": "grant_type yanlış", "value": { "error": "unsupported_grant_type", "error_description": "Only grant_type=client_credentials is supported." } }, "invalid_scope": { "summary": "Scope tanımlı değil", "value": { "error": "invalid_scope", "error_description": "One or more requested scopes are not granted to this client." } } } } } }, "401": { "description": "Kimlik hatalı ya da istemci pasif / geçerlilik dışı. `WWW-Authenticate: Basic` döner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "example": { "error": "invalid_client", "error_description": "Client authentication failed." } } } }, "415": { "description": "`Content-Type` form-urlencoded değil.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "example": { "error": "invalid_request", "error_description": "Token requests must use application/x-www-form-urlencoded." } } } }, "503": { "description": "Sunucu yapılandırması geçici olarak kullanılamıyor. Biraz sonra tekrar deneyin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "example": { "error": "server_error", "error_description": "" } } } } } } }, "/api/integration/v2/shipments": { "post": { "operationId": "createShipment", "tags": [ "3 · Gönderi Oluşturma" ], "summary": "Gönderi oluştur", "description": "Yeni bir gönderi açar ve ürünün iş akışını başlatır.\n\n- **Ne zaman kullanılır:** Siparişiniz JetDiji'ye teslim edilmeye hazır olduğunda.\n- **Yetki (scope):** `shipment.create`\n- **Akıştaki yeri:** Token'dan sonra ilk iş çağrısı. Sonra durum sorgulama veya güncelleme uçları gelir.\n- **Önemli kurallar:**\n - `X-Idempotency-Key` zorunlu. Aynı anahtar + aynı `customerReference` → mevcut gönderi `201`, `replayed: true`.\n - `customerReference`, `transactionId`, `externalReference` müşteri içinde tekil olmalı (`409`).\n - İl/ilçe yalnız kodla verilir (`cityCode`, `districtCode`).\n - Ürüne özel kurallar (ör. Kuveyt HGS `transactionId` int32) rehberde.", "security": [ { "oauth2ClientCredentials": [ "shipment.create" ] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/XIdempotencyKey" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShipmentRequest" }, "examples": { "minimal": { "summary": "En az alanla", "value": { "customerReference": "SIP-2026-000123", "productCode": "<ürün kodu>", "recipient": { "name": "", "phone": "<05XXXXXXXXX>" }, "destinationAddress": { "countryCode": "TR", "cityCode": "34", "districtCode": "1421", "neighborhood": "", "addressLine": "" } } }, "full": { "summary": "Ürün, koli ve gönderici bilgisiyle", "value": { "customerReference": "SIP-2026-000124", "transactionId": "123456790", "externalReference": "DIS-REF-000124", "productCode": "<ürün kodu>", "recipient": { "name": "", "phone": "<05XXXXXXXXX>", "email": "alici@example.com" }, "destinationAddress": { "countryCode": "TR", "cityCode": "34", "districtCode": "1421", "neighborhood": "", "addressLine": "", "branchCode": "<şube kodu>" }, "shipFrom": { "company": "", "contactName": "", "phone": "<02XXXXXXXXX>", "address": { "countryCode": "TR", "cityCode": "34", "districtCode": "1663", "addressLine": "" } }, "packages": [ { "barcode": "PKG-000124-1", "desi": 2, "weightKg": 1.2 } ], "products": [ { "name": "<Ürün adı>", "barcode": "PRD-000124-1" } ], "additionalData": { "kanal": "web" }, "shipmentChargeType": "ACCOUNT_OWNER", "packageCount": 1, "totalWeight": 1.2, "plannedDeliveryAt": "2026-10-10T09:00:00+03:00", "additionalDescription": "Mesai saatlerinde teslim.", "labelRequest": { "format": "PDF", "includeReturnLabel": false } } }, "kuveytHgs": { "summary": "Kuveyt HGS (transactionId int32 metni)", "value": { "customerReference": "SIP-2026-000125", "transactionId": "2147483000", "productCode": "KUVEYT_HGS", "recipient": { "name": "", "phone": "<05XXXXXXXXX>" }, "destinationAddress": { "countryCode": "TR", "cityCode": "34", "districtCode": "1421", "neighborhood": "", "addressLine": "" } } } } } } }, "responses": { "201": { "description": "Gönderi oluşturuldu ya da aynı anahtarla daha önce oluşturulan döndü (`replayed`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShipmentResponse" }, "examples": { "created": { "summary": "Yeni gönderi", "value": { "success": true, "replayed": false, "data": { "shipmentNumber": "100245", "trackingNumber": null, "customerReference": "SIP-2026-000123", "transactionId": null, "trackingUrl": null, "label": null, "returnLabel": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "replayed": { "summary": "Aynı anahtarla tekrar", "value": { "success": true, "replayed": true, "data": { "shipmentNumber": "100245", "trackingNumber": null, "customerReference": "SIP-2026-000123", "transactionId": null, "trackingUrl": null, "label": null, "returnLabel": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequestWrite" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.create` yok ya da ürün bu istemciye açık değil.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_API_SCOPE_FORBIDDEN": { "summary": "Scope eksik", "value": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "The access token does not grant the required scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "PRODUCT_NOT_ALLOWED_FOR_CLIENT": { "summary": "Ürün istemciye kapalı", "value": { "success": false, "error": { "code": "PRODUCT_NOT_ALLOWED_FOR_CLIENT", "message": "This API client is not authorized for the requested productCode.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "404": { "description": "Müşteri, ürün ya da sözleşme bulunamadı.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_NOT_FOUND": { "summary": "Müşteri yok", "value": { "success": false, "error": { "code": "CUSTOMER_NOT_FOUND", "message": "Customer was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "PRODUCT_NOT_FOUND": { "summary": "Ürün tanımlı değil", "value": { "success": false, "error": { "code": "PRODUCT_NOT_FOUND", "message": "The requested product is not configured for this customer.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "CONTRACT_NOT_FOUND": { "summary": "Sözleşme kodu yok", "value": { "success": false, "error": { "code": "CONTRACT_NOT_FOUND", "message": "The requested contractCode was not found for this customer.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "409": { "description": "Tekil alan çakışması, anahtar çakışması, kart eşleşmesi ya da ürün iş akışı hazır değil.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_REFERENCE_DUPLICATE": { "summary": "customerReference kullanılmış", "value": { "success": false, "error": { "code": "CUSTOMER_REFERENCE_DUPLICATE", "message": "customerReference already exists for this customer.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "TRANSACTION_ID_DUPLICATE": { "summary": "transactionId kullanılmış", "value": { "success": false, "error": { "code": "TRANSACTION_ID_DUPLICATE", "message": "transactionId already exists for this customer.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "EXTERNAL_REFERENCE_DUPLICATE": { "summary": "externalReference kullanılmış", "value": { "success": false, "error": { "code": "EXTERNAL_REFERENCE_DUPLICATE", "message": "externalReference already exists for this customer.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "PRODUCT_BARCODE_DUPLICATE": { "summary": "Barkod başka gönderide", "value": { "success": false, "error": { "code": "PRODUCT_BARCODE_DUPLICATE", "message": "The product barcode is already registered.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "IDEMPOTENCY_KEY_REUSE_CONFLICT": { "summary": "Anahtar başka istekte kullanılmış", "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REUSE_CONFLICT", "message": "X-Idempotency-Key was already used for another request.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "CARD_INTAKE_MATCH_REQUIRED": { "summary": "Kart depoda eşleşmedi (Kart ürünü)", "value": { "success": false, "error": { "code": "CARD_INTAKE_MATCH_REQUIRED", "message": "", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "PRODUCT_PUBLISHED_WORKFLOW_NOT_FOUND": { "summary": "Ürün akışı yayında değil", "value": { "success": false, "error": { "code": "PRODUCT_PUBLISHED_WORKFLOW_NOT_FOUND", "message": "A published workflow is required for the product.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "PRODUCT_WORKFLOW_NOT_CONFIGURED": { "summary": "Akış başlatılamadı (diğer kodlar: WORKFLOW_DEFINITION_NOT_FOUND, WORKFLOW_INITIAL_STEP_NOT_FOUND, WORKFLOW_ALREADY_STARTED, REQUIRED_FIELDS)", "value": { "success": false, "error": { "code": "PRODUCT_WORKFLOW_NOT_CONFIGURED", "message": "Shipment workflow could not be started for the requested product.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "422": { "description": "Gövde şemaya uymuyor ya da alan değeri geçersiz.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "Şema doğrulaması", "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "The request body does not match CreateShipmentRequest.", "details": [ { "path": "recipient.phone", "message": "Invalid input: expected string, received undefined" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "DESTINATION_GEOGRAPHY_INVALID": { "summary": "İl/ilçe kodu geçersiz", "value": { "success": false, "error": { "code": "DESTINATION_GEOGRAPHY_INVALID", "message": "cityCode and districtCode do not resolve to an active JetLogi geography pair.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "ORIGIN_GEOGRAPHY_INVALID": { "summary": "Gönderici il/ilçe kodu geçersiz", "value": { "success": false, "error": { "code": "ORIGIN_GEOGRAPHY_INVALID", "message": "shipFrom.address cityCode and districtCode are invalid.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "PLANNED_DELIVERY_AT_INVALID": { "summary": "Tarih biçimi geçersiz", "value": { "success": false, "error": { "code": "PLANNED_DELIVERY_AT_INVALID", "message": "plannedDeliveryAt must be a valid date-time.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "PRODUCT_CODE_REQUIRED": { "summary": "Ürün kodu boş", "value": { "success": false, "error": { "code": "PRODUCT_CODE_REQUIRED", "message": "productCode is required.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "KUVEYT_HGS_TRANSACTION_ID_INT32_REQUIRED": { "summary": "HGS: transactionId int32 değil", "value": { "success": false, "error": { "code": "KUVEYT_HGS_TRANSACTION_ID_INT32_REQUIRED", "message": "Kuveyt HGS Transaction ID zorunludur; -2147483648 ile 2147483647 arasında, başında sıfır olmayan bir tam sayı girin.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "500": { "description": "Beklenmeyen sunucu hatası. Aynı `X-Idempotency-Key` ile tekrar deneyin; sürerse `requestId` ile bildirin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_CREATE_FAILED", "message": "Shipment creation failed.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/integration/v2/shipments/{trackingNumber}": { "patch": { "operationId": "updateShipment", "tags": [ "4 · Gönderi Güncelleme" ], "summary": "Alıcı ve adresi güncelle", "description": "Alıcı bilgisini (ad, telefon, e-posta) ve/veya teslim adresini kısmi olarak günceller.\n\n- **Ne zaman kullanılır:** Alıcı bilgisi ya da adresi değiştiğinde. Eski `Update` ucunun karşılığı.\n- **Yetki (scope):** `shipment.update`\n- **Akıştaki yeri:** Oluşturmadan sonra, teslimden önce.\n- **Önemli kurallar:**\n - Gönderilmeyen alan değişmez; `recipient` ve `destinationAddress`'ten en az biri gerekir.\n - `recipient.email: null` e-postayı siler.\n - Adres doğrudan (il/ilçe kodu) ya da `{ branchCode }` olarak verilir.\n - Aynı anahtar + aynı gövde → `replayed: true`; farklı gövde → `409`.", "security": [ { "oauth2ClientCredentials": [ "shipment.update" ] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TrackingNumber" }, { "$ref": "#/components/parameters/XIdempotencyKey" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShipmentRequest" }, "examples": { "recipientOnly": { "summary": "Yalnız alıcı telefonu", "value": { "recipient": { "phone": "<05XXXXXXXXX>" } } }, "recipientAndAddress": { "summary": "Alıcı ve doğrudan adres", "value": { "recipient": { "name": "", "email": null }, "destinationAddress": { "countryCode": "TR", "cityCode": "34", "districtCode": "1421", "neighborhood": "", "addressLine": "" } } }, "branch": { "summary": "Adresi şubeye çevir", "value": { "destinationAddress": { "branchCode": "<şube kodu>" } } } } } } }, "responses": { "200": { "description": "İşlem uygulandı ya da aynı anahtarla daha önce uygulanmıştı (`replayed: true`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentMutationResponse" }, "example": { "success": true, "replayed": false, "data": { "shipmentNumber": "100245", "trackingNumber": "100245", "customerReference": "SIP-2026-000123", "transactionId": "123456789" }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "400": { "$ref": "#/components/responses/BadRequestWrite" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.update` scope'u yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "The access token does not grant the required scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "404": { "description": "Gönderi bulunamadı (ya da ürün kapsamınız dışında).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "SHIPMENT_NOT_FOUND": { "summary": "Gönderi yok ya da size kapalı", "value": { "success": false, "error": { "code": "SHIPMENT_NOT_FOUND", "message": "Shipment was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "BRANCH_NOT_FOUND": { "summary": "Şube kodu bulunamadı", "value": { "success": false, "error": { "code": "BRANCH_NOT_FOUND", "message": "branchCode was not found in the active customer branch master data.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "409": { "description": "Çakışma: anahtar başka istekte kullanılmış ya da işlem gönderinin durumuna uygun değil.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "IDEMPOTENCY_KEY_REUSE_CONFLICT": { "summary": "Anahtar başka istekte kullanılmış", "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REUSE_CONFLICT", "message": "X-Idempotency-Key was already used for another request.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "BRANCH_CODE_AMBIGUOUS": { "summary": "Şube kodu birden çok konuma denk geliyor", "value": { "success": false, "error": { "code": "BRANCH_CODE_AMBIGUOUS", "message": "branchCode resolves to more than one active customer location.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "BRANCH_GEOGRAPHY_INCOMPLETE": { "summary": "Şube adresinde il/ilçe eksik", "value": { "success": false, "error": { "code": "BRANCH_GEOGRAPHY_INCOMPLETE", "message": "The resolved branch does not have complete city/district master data.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "CUSTOMER_PARTY_BINDING_REQUIRED": { "summary": "Müşteri şube kaydına bağlı değil", "value": { "success": false, "error": { "code": "CUSTOMER_PARTY_BINDING_REQUIRED", "message": "The customer does not have an active party binding for branch resolution.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "422": { "description": "Gövde şemaya uymuyor ya da alan değeri geçersiz.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "Şema doğrulaması", "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "The request body does not match UpdateShipmentRequest.", "details": [ { "path": "", "message": "Unrecognized key: \"foo\"" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "TRACKING_NUMBER_REQUIRED": { "summary": "Takip numarası boş", "value": { "success": false, "error": { "code": "TRACKING_NUMBER_REQUIRED", "message": "trackingNumber is required.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "DESTINATION_GEOGRAPHY_INVALID": { "summary": "İl/ilçe kodu geçersiz", "value": { "success": false, "error": { "code": "DESTINATION_GEOGRAPHY_INVALID", "message": "cityCode and districtCode do not resolve to an active JetLogi geography pair.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "500": { "description": "Beklenmeyen sunucu hatası. Aynı `X-Idempotency-Key` ile tekrar deneyin; sürerse `requestId` ile bildirin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_SHIPMENT_UPDATE_FAILED", "message": "Shipment update failed.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "get": { "operationId": "getShipment", "tags": [ "6 · Durum ve Hareket Sorgulama" ], "summary": "Takip numarasıyla durum sorgula", "description": "Gönderinin güncel durumunu, alt durumunu ve nedenini döner.\n\n- **Ne zaman kullanılır:** Durum takibi için. Eski `ShipmentState` ucunun karşılığı.\n- **Yetki (scope):** `shipment.read` (+ `include=movements` için `shipment.events.read`)\n- **Akıştaki yeri:** Oluşturmadan sonra herhangi bir anda; periyodik takip.\n- **Önemli kurallar:**\n - Yol parametresi takip numarasıyla ya da gönderi numarasıyla (`shipmentNumber`) eşleşir.\n - `?include=movements` hareket geçmişini aynı yanıta ekler; ek olarak `shipment.events.read` ister.\n - Durum kodları kanonik JetDiji kodlarıdır (rehberdeki sözlük).\n - `outputNumber`, `productNumber`, `appointmentDate` şimdilik `null`.", "security": [ { "oauth2ClientCredentials": [ "shipment.read" ] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TrackingNumber" }, { "$ref": "#/components/parameters/Include" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "responses": { "200": { "description": "Gönderinin güncel durumu.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentDetailResponse" }, "examples": { "withoutMovements": { "summary": "include olmadan", "value": { "success": true, "data": { "shipmentNumber": "100245", "trackingNumber": "100245", "customerReference": "SIP-2026-000123", "transactionId": "123456789", "outputNumber": null, "productCode": "<ürün kodu>", "productNumber": null, "status": { "code": "4020", "name": "Dağıtımda", "fullCode": "4021", "fullName": "Dağıtıma Çıktı" }, "reason": { "code": "9117", "name": "Normal" }, "deliveryDate": null, "appointmentDate": null, "recipient": "", "movements": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "withMovements": { "summary": "?include=movements ile", "value": { "success": true, "data": { "shipmentNumber": "100245", "trackingNumber": "100245", "customerReference": "SIP-2026-000123", "transactionId": "123456789", "outputNumber": null, "productCode": "<ürün kodu>", "productNumber": null, "status": { "code": "4020", "name": "Dağıtımda", "fullCode": "4021", "fullName": "Dağıtıma Çıktı" }, "reason": { "code": "9117", "name": "Normal" }, "deliveryDate": null, "appointmentDate": null, "recipient": "", "movements": [ { "occurredAt": "2026-10-01T07:12:45.000Z", "statusCode": "1010", "statusName": "Sipariş Alındı", "fullStatusCode": null, "fullStatusName": null, "reasonCode": null, "reasonName": null }, { "occurredAt": "2026-10-02T06:30:10.000Z", "statusCode": "4010", "statusName": "Teslimat Şubesinde", "fullStatusCode": "4012", "fullStatusName": "Kurye Ataması Bekliyor", "reasonCode": null, "reasonName": null }, { "occurredAt": "2026-10-02T08:05:00.000Z", "statusCode": "4020", "statusName": "Dağıtımda", "fullStatusCode": "4021", "fullStatusName": "Dağıtıma Çıktı", "reasonCode": "9117", "reasonName": "Normal" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.read` yok ya da `include=movements` için `shipment.events.read` yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "readScopeMissing": { "summary": "shipment.read eksik", "value": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "The access token does not grant the required scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "eventsScopeMissing": { "summary": "include=movements için shipment.events.read eksik", "value": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "include=movements requires the shipment.events.read scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "404": { "description": "Gönderi bulunamadı (ya da ürün kapsamınız dışında).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "SHIPMENT_NOT_FOUND", "message": "Shipment was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "500": { "description": "Gönderi verisi eksik (durum çevirisi ya da müşteri referansı). `requestId` ile bildirin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_CONTRACT_DATA_INCOMPLETE", "message": "Canonical status translation is missing.", "details": [ { "field": "status.name", "statusCode": "4020" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/integration/v2/shipments/{trackingNumber}/address": { "patch": { "operationId": "updateShipmentAddress", "tags": [ "4 · Gönderi Güncelleme" ], "summary": "Teslim adresini değiştir", "description": "Gönderinin teslim adresini doğrudan adresle ya da şube koduyla değiştirir.\n\n- **Ne zaman kullanılır:** Yalnız adres değiştiğinde. Eski `UpdateAddress` ucunun karşılığı.\n- **Yetki (scope):** `shipment.update`\n- **Akıştaki yeri:** Oluşturmadan sonra, teslimden önce. İşlem numaranız varsa önce `GET …/lookup/transaction/{transactionId}` ile takip numarasını bulun.\n- **Önemli kurallar:**\n - Gövde iki biçimden biri: doğrudan adres ya da `{ branchCode }`.\n - Bu uçta aynı anahtar + aynı gönderi → `replayed: true`; gövde karşılaştırılmaz.\n - Durum kısıtı yoktur.", "security": [ { "oauth2ClientCredentials": [ "shipment.update" ] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TrackingNumber" }, { "$ref": "#/components/parameters/XIdempotencyKey" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShipmentAddressRequest" }, "examples": { "direct": { "summary": "Doğrudan adres", "value": { "countryCode": "TR", "cityCode": "34", "districtCode": "1421", "neighborhood": "", "addressLine": "" } }, "branch": { "summary": "Şube kodu", "value": { "branchCode": "<şube kodu>" } } } } } }, "responses": { "200": { "description": "İşlem uygulandı ya da aynı anahtarla daha önce uygulanmıştı (`replayed: true`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentMutationResponse" }, "example": { "success": true, "replayed": false, "data": { "shipmentNumber": "100245", "trackingNumber": "100245", "customerReference": "SIP-2026-000123", "transactionId": "123456789" }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "400": { "$ref": "#/components/responses/BadRequestWrite" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.update` scope'u yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "The access token does not grant the required scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "404": { "description": "Gönderi bulunamadı (ya da ürün kapsamınız dışında).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "SHIPMENT_NOT_FOUND": { "summary": "Gönderi yok ya da size kapalı", "value": { "success": false, "error": { "code": "SHIPMENT_NOT_FOUND", "message": "Shipment was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "BRANCH_NOT_FOUND": { "summary": "Şube kodu bulunamadı", "value": { "success": false, "error": { "code": "BRANCH_NOT_FOUND", "message": "branchCode was not found in the active customer branch master data.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "409": { "description": "Çakışma: anahtar başka istekte kullanılmış ya da işlem gönderinin durumuna uygun değil.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "IDEMPOTENCY_KEY_REUSE_CONFLICT": { "summary": "Anahtar başka istekte kullanılmış", "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REUSE_CONFLICT", "message": "X-Idempotency-Key was already used for another request.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "BRANCH_CODE_AMBIGUOUS": { "summary": "Şube kodu birden çok konuma denk geliyor", "value": { "success": false, "error": { "code": "BRANCH_CODE_AMBIGUOUS", "message": "branchCode resolves to more than one active customer location.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "BRANCH_GEOGRAPHY_INCOMPLETE": { "summary": "Şube adresinde il/ilçe eksik", "value": { "success": false, "error": { "code": "BRANCH_GEOGRAPHY_INCOMPLETE", "message": "The resolved branch does not have complete city/district master data.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "CUSTOMER_PARTY_BINDING_REQUIRED": { "summary": "Müşteri şube kaydına bağlı değil", "value": { "success": false, "error": { "code": "CUSTOMER_PARTY_BINDING_REQUIRED", "message": "The customer does not have an active party binding for branch resolution.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "422": { "description": "Gövde şemaya uymuyor ya da alan değeri geçersiz.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "Şema doğrulaması", "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "The request body does not match UpdateShipmentAddressRequest.", "details": [ { "path": "", "message": "Unrecognized key: \"foo\"" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "TRACKING_NUMBER_REQUIRED": { "summary": "Takip numarası boş", "value": { "success": false, "error": { "code": "TRACKING_NUMBER_REQUIRED", "message": "trackingNumber is required.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "DESTINATION_GEOGRAPHY_INVALID": { "summary": "İl/ilçe kodu geçersiz", "value": { "success": false, "error": { "code": "DESTINATION_GEOGRAPHY_INVALID", "message": "cityCode and districtCode do not resolve to an active JetLogi geography pair.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "500": { "description": "Beklenmeyen sunucu hatası. Aynı `X-Idempotency-Key` ile tekrar deneyin; sürerse `requestId` ile bildirin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_ADDRESS_UPDATE_FAILED", "message": "Shipment address update failed.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/integration/v2/shipments/{trackingNumber}/products": { "put": { "operationId": "replaceShipmentProducts", "tags": [ "4 · Gönderi Güncelleme" ], "summary": "Ürün listesini değiştir", "description": "Gönderinin ürün listesini gönderilen listeyle tamamen değiştirir.\n\n- **Ne zaman kullanılır:** Gönderideki ürün veya barkod değiştiğinde. Eski `UpdateProduct` ucunun karşılığı.\n- **Yetki (scope):** `shipment.update`\n- **Akıştaki yeri:** Oluşturmadan sonra, hazırlıktan önce.\n- **Önemli kurallar:**\n - Liste tamamen yenilenir (PUT); en çok 100 ürün, `[]` listeyi temizler.\n - Barkod başka bir gönderide güncelse `409 PRODUCT_BARCODE_DUPLICATE`.\n - Aynı anahtar + aynı gövde → `replayed: true`; farklı gövde → `409`.", "security": [ { "oauth2ClientCredentials": [ "shipment.update" ] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TrackingNumber" }, { "$ref": "#/components/parameters/XIdempotencyKey" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceShipmentProductsRequest" }, "examples": { "replace": { "summary": "İki ürünle değiştir", "value": { "products": [ { "name": "<Ürün adı 1>", "barcode": "PRD-000123-1" }, { "name": "<Ürün adı 2>", "barcode": "PRD-000123-2" } ] } }, "clear": { "summary": "Listeyi temizle", "value": { "products": [] } } } } } }, "responses": { "200": { "description": "İşlem uygulandı ya da aynı anahtarla daha önce uygulanmıştı (`replayed: true`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentMutationResponse" }, "example": { "success": true, "replayed": false, "data": { "shipmentNumber": "100245", "trackingNumber": "100245", "customerReference": "SIP-2026-000123", "transactionId": "123456789" }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "400": { "$ref": "#/components/responses/BadRequestWrite" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.update` scope'u yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "The access token does not grant the required scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "404": { "description": "Gönderi bulunamadı (ya da ürün kapsamınız dışında).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "SHIPMENT_NOT_FOUND", "message": "Shipment was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "409": { "description": "Çakışma: anahtar başka istekte kullanılmış ya da işlem gönderinin durumuna uygun değil.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "IDEMPOTENCY_KEY_REUSE_CONFLICT": { "summary": "Anahtar başka istekte kullanılmış", "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REUSE_CONFLICT", "message": "X-Idempotency-Key was already used for another request.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "PRODUCT_BARCODE_DUPLICATE": { "summary": "Barkod başka gönderide", "value": { "success": false, "error": { "code": "PRODUCT_BARCODE_DUPLICATE", "message": "The product barcode is already registered on another shipment.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "422": { "description": "Gövde şemaya uymuyor ya da alan değeri geçersiz.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "Şema doğrulaması", "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "The request body does not match ReplaceShipmentProductsRequest.", "details": [ { "path": "", "message": "Unrecognized key: \"foo\"" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "TRACKING_NUMBER_REQUIRED": { "summary": "Takip numarası boş", "value": { "success": false, "error": { "code": "TRACKING_NUMBER_REQUIRED", "message": "trackingNumber is required.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "500": { "description": "Beklenmeyen sunucu hatası. Aynı `X-Idempotency-Key` ile tekrar deneyin; sürerse `requestId` ile bildirin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_PRODUCTS_UPDATE_FAILED", "message": "Shipment products update failed.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/integration/v2/shipments/{trackingNumber}/customer-reference": { "put": { "operationId": "updateShipmentCustomerReference", "tags": [ "4 · Gönderi Güncelleme" ], "summary": "Müşteri referansını değiştir", "description": "Gönderinin müşteri referansını (`customerReference`) yeni değerle değiştirir.\n\n- **Ne zaman kullanılır:** Kendi sisteminizde sipariş numarası değiştiğinde. Eski `UpdateCustomerUniq` ucunun karşılığı.\n- **Yetki (scope):** `shipment.update`\n- **Akıştaki yeri:** Oluşturmadan sonra herhangi bir anda. Sonraki referans aramaları yeni değerle yapılır.\n- **Önemli kurallar:**\n - Yeni değer müşteri içinde tekil olmalı; değilse `409 CUSTOMER_REFERENCE_DUPLICATE`.\n - Yanıttaki `data.customerReference` yeni değeri taşır.\n - Aynı anahtar + aynı gövde → `replayed: true`; farklı gövde → `409`.", "security": [ { "oauth2ClientCredentials": [ "shipment.update" ] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TrackingNumber" }, { "$ref": "#/components/parameters/XIdempotencyKey" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerReferenceRequest" }, "example": { "customerReference": "SIP-2026-000123-B" } } } }, "responses": { "200": { "description": "İşlem uygulandı ya da aynı anahtarla daha önce uygulanmıştı (`replayed: true`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentMutationResponse" }, "example": { "success": true, "replayed": false, "data": { "shipmentNumber": "100245", "trackingNumber": "100245", "customerReference": "SIP-2026-000123-B", "transactionId": "123456789" }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "400": { "$ref": "#/components/responses/BadRequestWrite" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.update` scope'u yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "The access token does not grant the required scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "404": { "description": "Gönderi bulunamadı (ya da ürün kapsamınız dışında).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "SHIPMENT_NOT_FOUND", "message": "Shipment was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "409": { "description": "Çakışma: anahtar başka istekte kullanılmış ya da işlem gönderinin durumuna uygun değil.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "IDEMPOTENCY_KEY_REUSE_CONFLICT": { "summary": "Anahtar başka istekte kullanılmış", "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REUSE_CONFLICT", "message": "X-Idempotency-Key was already used for another request.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "CUSTOMER_REFERENCE_DUPLICATE": { "summary": "Referans kullanılmış", "value": { "success": false, "error": { "code": "CUSTOMER_REFERENCE_DUPLICATE", "message": "customerReference already exists for this customer.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "422": { "description": "Gövde şemaya uymuyor ya da alan değeri geçersiz.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "Şema doğrulaması", "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "The request body does not match UpdateCustomerReferenceRequest.", "details": [ { "path": "", "message": "Unrecognized key: \"foo\"" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "TRACKING_NUMBER_REQUIRED": { "summary": "Takip numarası boş", "value": { "success": false, "error": { "code": "TRACKING_NUMBER_REQUIRED", "message": "trackingNumber is required.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "500": { "description": "Beklenmeyen sunucu hatası. Aynı `X-Idempotency-Key` ile tekrar deneyin; sürerse `requestId` ile bildirin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_CUSTOMER_REFERENCE_UPDATE_FAILED", "message": "customerReference update failed.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/integration/v2/shipments/{trackingNumber}/required-documents": { "get": { "operationId": "getShipmentRequiredDocuments", "tags": [ "5 · Hazırlık ve Evrak" ], "summary": "Gerekli evrakları listele", "description": "Gönderi için zorunlu olan evrakları listeler.\n\n- **Ne zaman kullanılır:** Hazırlık öncesinde hangi evrakın toplanacağını öğrenmek için. Eski `RequiredDocumentList` ucunun karşılığı.\n- **Yetki (scope):** `shipment.read`\n- **Akıştaki yeri:** Oluşturmadan sonra; hazırlık kararından önce.\n- **Önemli kurallar:**\n - Yalnız zorunlu ve iptal edilmemiş evraklar döner; sıra evrak sırasıdır.\n - `contentBase64` yalnız içerik açıkça tanımlıysa dolar; operasyon görüntüleri dönmez.\n - Evrak yoksa `data: []`.", "security": [ { "oauth2ClientCredentials": [ "shipment.read" ] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TrackingNumber" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "responses": { "200": { "description": "Evrak listesi.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequiredDocumentsResponse" }, "example": { "success": true, "data": [ { "documentId": "8f1c2d3e-0000-4000-8000-000000000001", "documentCode": "SOZLESME", "name": "Sözleşme", "description": "Alıcıya imzalatılacak sözleşme.", "contentBase64": null } ], "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "404": { "description": "Gönderi bulunamadı (ya da ürün kapsamınız dışında).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "SHIPMENT_NOT_FOUND", "message": "Shipment was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/integration/v2/shipments/{trackingNumber}/preparation-status": { "post": { "operationId": "submitShipmentPreparationStatus", "tags": [ "5 · Hazırlık ve Evrak" ], "summary": "Hazırlık kararı gönder", "description": "Onay bekleyen gönderi için onay ya da ret kararını iletir.\n\n- **Ne zaman kullanılır:** Gönderi `2041 Onay Bekleniyor` aşamasındayken. Eski `UpdateStatus` ucunun karşılığı (`statusID` 1/2/5).\n- **Yetki (scope):** `shipment.update`\n- **Akıştaki yeri:** Hazırlık aşaması. `APPROVE` sonrası akış dağıtıma ilerler; ret kararlarında ürün stoğa döner.\n- **Önemli kurallar:**\n - `APPROVE` = 1, `REJECT_REMATCH` = 2, `REJECT_RELEASE` = 5.\n - Gönderi onay beklemiyorsa `409 PREPARATION_STATUS_NOT_ALLOWED`. Pratikte Kuveyt HGS onay akışında kullanılır.\n - Aynı karar tekrar gönderilirse `replayed: true` döner.", "security": [ { "oauth2ClientCredentials": [ "shipment.update" ] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TrackingNumber" }, { "$ref": "#/components/parameters/XIdempotencyKey" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparationStatusRequest" }, "examples": { "approve": { "summary": "Onayla (eski statusID 1)", "value": { "decision": "APPROVE" } }, "rematch": { "summary": "Reddet, yeniden eşle (eski statusID 2)", "value": { "decision": "REJECT_REMATCH" } }, "release": { "summary": "Reddet, serbest bırak (eski statusID 5)", "value": { "decision": "REJECT_RELEASE" } } } } } }, "responses": { "200": { "description": "İşlem uygulandı ya da aynı anahtarla daha önce uygulanmıştı (`replayed: true`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentMutationResponse" }, "example": { "success": true, "replayed": false, "data": { "shipmentNumber": "100245", "trackingNumber": "100245", "customerReference": "SIP-2026-000123", "transactionId": "123456789" }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "400": { "$ref": "#/components/responses/BadRequestWrite" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.update` scope'u yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "The access token does not grant the required scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "404": { "description": "Gönderi bulunamadı (ya da ürün kapsamınız dışında).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "SHIPMENT_NOT_FOUND", "message": "Shipment was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "409": { "description": "Çakışma: anahtar başka istekte kullanılmış ya da işlem gönderinin durumuna uygun değil.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "IDEMPOTENCY_KEY_REUSE_CONFLICT": { "summary": "Anahtar başka istekte kullanılmış", "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REUSE_CONFLICT", "message": "X-Idempotency-Key was already used for another request.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "PREPARATION_STATUS_NOT_ALLOWED": { "summary": "Onay beklemiyor", "value": { "success": false, "error": { "code": "PREPARATION_STATUS_NOT_ALLOWED", "message": "The shipment is not awaiting a preparation decision.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "EXTERNAL_APPROVAL_REQUEST_NOT_FOUND": { "summary": "Onay talebi yok", "value": { "success": false, "error": { "code": "EXTERNAL_APPROVAL_REQUEST_NOT_FOUND", "message": "No external approval request exists for this shipment.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "PREPARATION_DECISION_FAILED": { "summary": "Karar uygulanamadı (akış/onay hata kodları da bu statüde döner)", "value": { "success": false, "error": { "code": "PREPARATION_DECISION_FAILED", "message": "Preparation status could not be processed.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "422": { "description": "Gövde şemaya uymuyor ya da alan değeri geçersiz.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "Şema doğrulaması", "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "The request body does not match PreparationStatusRequest.", "details": [ { "path": "", "message": "Unrecognized key: \"foo\"" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "TRACKING_NUMBER_REQUIRED": { "summary": "Takip numarası boş", "value": { "success": false, "error": { "code": "TRACKING_NUMBER_REQUIRED", "message": "trackingNumber is required.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "500": { "description": "Beklenmeyen sunucu hatası. Aynı `X-Idempotency-Key` ile tekrar deneyin; sürerse `requestId` ile bildirin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_PREPARATION_STATUS_FAILED", "message": "Preparation status could not be processed.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/integration/v2/shipments/lookup/customer-reference/{customerReference}": { "get": { "operationId": "getShipmentByCustomerReference", "tags": [ "6 · Durum ve Hareket Sorgulama" ], "summary": "Müşteri referansıyla durum sorgula", "description": "Gönderiyi sizin sipariş numaranızla (`customerReference`) bulur ve durumunu döner.\n\n- **Ne zaman kullanılır:** Takip numarasını saklamıyorsanız. Eski `ShipmentStatebyCustomerUniqNumber` ve `BaseShipmentStatebyCustomerUniqNumber` uçlarının karşılığı.\n- **Yetki (scope):** `shipment.read` (+ `include=movements` için `shipment.events.read`)\n- **Akıştaki yeri:** Oluşturmadan sonra herhangi bir anda.\n- **Önemli kurallar:**\n - Referans güncellendiyse yeni değerle arayın; büyük/küçük harf duyarsız eşleşme de denenir.\n - `?include=movements` hareket geçmişini aynı yanıta ekler; ek olarak `shipment.events.read` ister.\n - Durum kodları kanonik JetDiji kodlarıdır (rehberdeki sözlük).\n - `outputNumber`, `productNumber`, `appointmentDate` şimdilik `null`.", "security": [ { "oauth2ClientCredentials": [ "shipment.read" ] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/CustomerReference" }, { "$ref": "#/components/parameters/Include" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "responses": { "200": { "description": "Gönderinin güncel durumu.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentDetailResponse" }, "examples": { "withoutMovements": { "summary": "include olmadan", "value": { "success": true, "data": { "shipmentNumber": "100245", "trackingNumber": "100245", "customerReference": "SIP-2026-000123", "transactionId": "123456789", "outputNumber": null, "productCode": "<ürün kodu>", "productNumber": null, "status": { "code": "4020", "name": "Dağıtımda", "fullCode": "4021", "fullName": "Dağıtıma Çıktı" }, "reason": { "code": "9117", "name": "Normal" }, "deliveryDate": null, "appointmentDate": null, "recipient": "", "movements": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "withMovements": { "summary": "?include=movements ile", "value": { "success": true, "data": { "shipmentNumber": "100245", "trackingNumber": "100245", "customerReference": "SIP-2026-000123", "transactionId": "123456789", "outputNumber": null, "productCode": "<ürün kodu>", "productNumber": null, "status": { "code": "4020", "name": "Dağıtımda", "fullCode": "4021", "fullName": "Dağıtıma Çıktı" }, "reason": { "code": "9117", "name": "Normal" }, "deliveryDate": null, "appointmentDate": null, "recipient": "", "movements": [ { "occurredAt": "2026-10-01T07:12:45.000Z", "statusCode": "1010", "statusName": "Sipariş Alındı", "fullStatusCode": null, "fullStatusName": null, "reasonCode": null, "reasonName": null }, { "occurredAt": "2026-10-02T06:30:10.000Z", "statusCode": "4010", "statusName": "Teslimat Şubesinde", "fullStatusCode": "4012", "fullStatusName": "Kurye Ataması Bekliyor", "reasonCode": null, "reasonName": null }, { "occurredAt": "2026-10-02T08:05:00.000Z", "statusCode": "4020", "statusName": "Dağıtımda", "fullStatusCode": "4021", "fullStatusName": "Dağıtıma Çıktı", "reasonCode": "9117", "reasonName": "Normal" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.read` yok ya da `include=movements` için `shipment.events.read` yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "readScopeMissing": { "summary": "shipment.read eksik", "value": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "The access token does not grant the required scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "eventsScopeMissing": { "summary": "include=movements için shipment.events.read eksik", "value": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "include=movements requires the shipment.events.read scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "404": { "description": "Gönderi bulunamadı (ya da ürün kapsamınız dışında).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "SHIPMENT_NOT_FOUND", "message": "Shipment was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "500": { "description": "Gönderi verisi eksik (durum çevirisi ya da müşteri referansı). `requestId` ile bildirin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_CONTRACT_DATA_INCOMPLETE", "message": "Canonical status translation is missing.", "details": [ { "field": "status.name", "statusCode": "4020" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/integration/v2/shipments/lookup/transaction/{transactionId}": { "get": { "operationId": "getShipmentByTransactionId", "tags": [ "6 · Durum ve Hareket Sorgulama" ], "summary": "İşlem numarasıyla durum sorgula", "description": "Gönderiyi işlem numaranızla (`transactionId`) bulur ve durumunu döner.\n\n- **Ne zaman kullanılır:** İşlem numarasıyla çalışıyorsanız. Eski `ShipmentStatebyTransactionID` ucunun karşılığı.\n- **Yetki (scope):** `shipment.read` (+ `include=movements` için `shipment.events.read`)\n- **Akıştaki yeri:** Oluşturmadan sonra; güncelleme uçlarından önce takip numarasını bulmak için de kullanılır.\n- **Önemli kurallar:**\n - Eski uçtaki `6020` dış kodu dönmez; kanonik kod döner.\n - `?include=movements` hareket geçmişini aynı yanıta ekler; ek olarak `shipment.events.read` ister.\n - Durum kodları kanonik JetDiji kodlarıdır (rehberdeki sözlük).\n - `outputNumber`, `productNumber`, `appointmentDate` şimdilik `null`.", "security": [ { "oauth2ClientCredentials": [ "shipment.read" ] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TransactionId" }, { "$ref": "#/components/parameters/Include" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "responses": { "200": { "description": "Gönderinin güncel durumu.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentDetailResponse" }, "examples": { "withoutMovements": { "summary": "include olmadan", "value": { "success": true, "data": { "shipmentNumber": "100245", "trackingNumber": "100245", "customerReference": "SIP-2026-000123", "transactionId": "123456789", "outputNumber": null, "productCode": "<ürün kodu>", "productNumber": null, "status": { "code": "4020", "name": "Dağıtımda", "fullCode": "4021", "fullName": "Dağıtıma Çıktı" }, "reason": { "code": "9117", "name": "Normal" }, "deliveryDate": null, "appointmentDate": null, "recipient": "", "movements": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "withMovements": { "summary": "?include=movements ile", "value": { "success": true, "data": { "shipmentNumber": "100245", "trackingNumber": "100245", "customerReference": "SIP-2026-000123", "transactionId": "123456789", "outputNumber": null, "productCode": "<ürün kodu>", "productNumber": null, "status": { "code": "4020", "name": "Dağıtımda", "fullCode": "4021", "fullName": "Dağıtıma Çıktı" }, "reason": { "code": "9117", "name": "Normal" }, "deliveryDate": null, "appointmentDate": null, "recipient": "", "movements": [ { "occurredAt": "2026-10-01T07:12:45.000Z", "statusCode": "1010", "statusName": "Sipariş Alındı", "fullStatusCode": null, "fullStatusName": null, "reasonCode": null, "reasonName": null }, { "occurredAt": "2026-10-02T06:30:10.000Z", "statusCode": "4010", "statusName": "Teslimat Şubesinde", "fullStatusCode": "4012", "fullStatusName": "Kurye Ataması Bekliyor", "reasonCode": null, "reasonName": null }, { "occurredAt": "2026-10-02T08:05:00.000Z", "statusCode": "4020", "statusName": "Dağıtımda", "fullStatusCode": "4021", "fullStatusName": "Dağıtıma Çıktı", "reasonCode": "9117", "reasonName": "Normal" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.read` yok ya da `include=movements` için `shipment.events.read` yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "readScopeMissing": { "summary": "shipment.read eksik", "value": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "The access token does not grant the required scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "eventsScopeMissing": { "summary": "include=movements için shipment.events.read eksik", "value": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "include=movements requires the shipment.events.read scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "404": { "description": "Gönderi bulunamadı (ya da ürün kapsamınız dışında).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "SHIPMENT_NOT_FOUND", "message": "Shipment was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "500": { "description": "Gönderi verisi eksik (durum çevirisi ya da müşteri referansı). `requestId` ile bildirin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_CONTRACT_DATA_INCOMPLETE", "message": "Canonical status translation is missing.", "details": [ { "field": "status.name", "statusCode": "4020" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/integration/v2/shipments/{trackingNumber}/movements": { "get": { "operationId": "getShipmentMovements", "tags": [ "6 · Durum ve Hareket Sorgulama" ], "summary": "Hareket geçmişini listele", "description": "Gönderinin durum hareketlerini eski tarihten yeniye listeler.\n\n- **Ne zaman kullanılır:** Durum geçmişini göstermek için. Eskideki `stateHistory` alanının karşılığı.\n- **Yetki (scope):** `shipment.events.read`\n- **Akıştaki yeri:** Durum sorgulamanın yanında; aynı veri `?include=movements` ile de alınabilir.\n- **Önemli kurallar:**\n - Yalnız durum kodu taşıyan hareketler listelenir; güncelleme ve iptal kayıtları görünmez.\n - Taşıyıcıya özel iç olaylar gösterilmez.", "security": [ { "oauth2ClientCredentials": [ "shipment.events.read" ] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TrackingNumber" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "responses": { "200": { "description": "Hareket listesi.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentMovementsResponse" }, "example": { "success": true, "data": [ { "occurredAt": "2026-10-01T07:12:45.000Z", "statusCode": "1010", "statusName": "Sipariş Alındı", "fullStatusCode": null, "fullStatusName": null, "reasonCode": null, "reasonName": null }, { "occurredAt": "2026-10-02T06:30:10.000Z", "statusCode": "4010", "statusName": "Teslimat Şubesinde", "fullStatusCode": "4012", "fullStatusName": "Kurye Ataması Bekliyor", "reasonCode": null, "reasonName": null }, { "occurredAt": "2026-10-02T08:05:00.000Z", "statusCode": "4020", "statusName": "Dağıtımda", "fullStatusCode": "4021", "fullStatusName": "Dağıtıma Çıktı", "reasonCode": "9117", "reasonName": "Normal" } ], "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.events.read` yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "The access token does not grant the required scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "404": { "description": "Gönderi bulunamadı (ya da ürün kapsamınız dışında).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "SHIPMENT_NOT_FOUND", "message": "Shipment was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/integration/v2/shipments/{trackingNumber}/cancel": { "post": { "operationId": "cancelShipment", "tags": [ "7 · İptal" ], "summary": "Gönderiyi iptal et", "description": "Gönderiyi müşteri talebiyle iptal eder.\n\n- **Ne zaman kullanılır:** Sipariş sizin tarafınızda iptal edildiğinde. Eski `ShipmentCancel` ucunun karşılığı.\n- **Yetki (scope):** `shipment.cancel`\n- **Akıştaki yeri:** Teslimden önce herhangi bir aşamada (akış izin veriyorsa).\n- **Önemli kurallar:**\n - `shipment.cancel` gerekir; `shipment.update` iptal yetkisi vermez.\n - Gövde boş ya da `{}`. İptal `9425 Müşteri Talebi` nedeniyle uygulanır.\n - Gönderinin mevcut adımından iptal yolu yoksa `409 CANCELLATION_NOT_CANONICALLY_AVAILABLE`.\n - İki iptal ucu aynı anahtar alanını paylaşır; aynı gönderi + aynı anahtar → `replayed: true`.", "security": [ { "oauth2ClientCredentials": [ "shipment.cancel" ] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TrackingNumber" }, { "$ref": "#/components/parameters/XIdempotencyKey" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelShipmentRequest" }, "example": {} } } }, "responses": { "200": { "description": "İptal kabul edildi ya da gönderi zaten iptal (`replayed` ya da başarılı).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentMutationResponse" }, "example": { "success": true, "replayed": false, "data": { "shipmentNumber": "100245", "trackingNumber": "100245", "customerReference": "SIP-2026-000123", "transactionId": "123456789" }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "400": { "$ref": "#/components/responses/BadRequestWrite" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.cancel` scope'u yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "The access token does not grant the required scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "404": { "description": "Gönderi bulunamadı (ya da ürün kapsamınız dışında).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "SHIPMENT_NOT_FOUND", "message": "Shipment was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "409": { "description": "Çakışma: anahtar başka istekte kullanılmış ya da işlem gönderinin durumuna uygun değil.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "IDEMPOTENCY_KEY_REUSE_CONFLICT": { "summary": "Anahtar başka istekte kullanılmış", "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REUSE_CONFLICT", "message": "X-Idempotency-Key was already used for another request.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "CANCELLATION_NOT_CANONICALLY_AVAILABLE": { "summary": "Bu aşamada iptal edilemez", "value": { "success": false, "error": { "code": "CANCELLATION_NOT_CANONICALLY_AVAILABLE", "message": "The shipment cannot be cancelled in its current state.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "WORKFLOW_NOT_FOUND": { "summary": "Gönderi akışı yok", "value": { "success": false, "error": { "code": "WORKFLOW_NOT_FOUND", "message": "Shipment workflow was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "CANCELLATION_FAILED": { "summary": "İptal uygulanamadı", "value": { "success": false, "error": { "code": "CANCELLATION_FAILED", "message": "Shipment cancellation failed.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "422": { "description": "Gövde şemaya uymuyor ya da alan değeri geçersiz.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "Şema doğrulaması", "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "The request body does not match CancelShipmentRequest.", "details": [ { "path": "", "message": "Unrecognized key: \"foo\"" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "TRACKING_NUMBER_REQUIRED": { "summary": "Takip numarası boş", "value": { "success": false, "error": { "code": "TRACKING_NUMBER_REQUIRED", "message": "trackingNumber is required.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "500": { "description": "Beklenmeyen sunucu hatası. Aynı `X-Idempotency-Key` ile tekrar deneyin; sürerse `requestId` ile bildirin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_CANCEL_FAILED", "message": "Shipment cancellation failed.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/integration/v2/shipments/lookup/transaction/{transactionId}/cancel": { "post": { "operationId": "cancelShipmentByTransactionId", "tags": [ "7 · İptal" ], "summary": "İşlem numarasıyla iptal et", "description": "Gönderiyi işlem numaranızla (`transactionId`) bulur ve iptal eder.\n\n- **Ne zaman kullanılır:** Takip numarası yerine işlem numarasıyla çalışıyorsanız. Eski `ShipmentCancelbyTransactionID` ucunun karşılığı.\n- **Yetki (scope):** `shipment.cancel`\n- **Akıştaki yeri:** Teslimden önce herhangi bir aşamada (akış izin veriyorsa).\n- **Önemli kurallar:**\n - `shipment.cancel` gerekir; `shipment.update` iptal yetkisi vermez.\n - Gövde boş ya da `{}`. İptal `9425 Müşteri Talebi` nedeniyle uygulanır.\n - Gönderinin mevcut adımından iptal yolu yoksa `409 CANCELLATION_NOT_CANONICALLY_AVAILABLE`.\n - İki iptal ucu aynı anahtar alanını paylaşır; aynı gönderi + aynı anahtar → `replayed: true`.", "security": [ { "oauth2ClientCredentials": [ "shipment.cancel" ] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TransactionId" }, { "$ref": "#/components/parameters/XIdempotencyKey" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelShipmentRequest" }, "example": {} } } }, "responses": { "200": { "description": "İptal kabul edildi ya da gönderi zaten iptal (`replayed` ya da başarılı).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentMutationResponse" }, "example": { "success": true, "replayed": false, "data": { "shipmentNumber": "100245", "trackingNumber": "100245", "customerReference": "SIP-2026-000123", "transactionId": "123456789" }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "400": { "$ref": "#/components/responses/BadRequestWrite" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.cancel` scope'u yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "The access token does not grant the required scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "404": { "description": "Gönderi bulunamadı (ya da ürün kapsamınız dışında).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "SHIPMENT_NOT_FOUND", "message": "Shipment was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "409": { "description": "Çakışma: anahtar başka istekte kullanılmış ya da işlem gönderinin durumuna uygun değil.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "IDEMPOTENCY_KEY_REUSE_CONFLICT": { "summary": "Anahtar başka istekte kullanılmış", "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REUSE_CONFLICT", "message": "X-Idempotency-Key was already used for another request.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "CANCELLATION_NOT_CANONICALLY_AVAILABLE": { "summary": "Bu aşamada iptal edilemez", "value": { "success": false, "error": { "code": "CANCELLATION_NOT_CANONICALLY_AVAILABLE", "message": "The shipment cannot be cancelled in its current state.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "WORKFLOW_NOT_FOUND": { "summary": "Gönderi akışı yok", "value": { "success": false, "error": { "code": "WORKFLOW_NOT_FOUND", "message": "Shipment workflow was not found.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "CANCELLATION_FAILED": { "summary": "İptal uygulanamadı", "value": { "success": false, "error": { "code": "CANCELLATION_FAILED", "message": "Shipment cancellation failed.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "422": { "description": "Gövde şemaya uymuyor ya da alan değeri geçersiz.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_ERROR": { "summary": "Şema doğrulaması", "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "The request body does not match CancelShipmentRequest.", "details": [ { "path": "", "message": "Unrecognized key: \"foo\"" } ] }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "TRANSACTION_ID_REQUIRED": { "summary": "İşlem numarası boş", "value": { "success": false, "error": { "code": "TRANSACTION_ID_REQUIRED", "message": "transactionId is required.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "500": { "description": "Beklenmeyen sunucu hatası. Aynı `X-Idempotency-Key` ile tekrar deneyin; sürerse `requestId` ile bildirin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_CANCEL_FAILED", "message": "Shipment cancellation failed.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/integration/v2/reference/cities": { "get": { "tags": [ "2 · Referans Veriler" ], "security": [ { "oauth2ClientCredentials": [ "shipment.read" ] }, { "bearerAuth": [] } ], "operationId": "listReferenceCities", "summary": "İlleri listele", "description": "Adreste kullanılabilecek aktif illeri `code` + `name` olarak döner. `code`, gönderi adresindeki `cityCode` alanıdır (plaka kodu, baştaki sıfır olmadan: `1`, `34`).\n\n- **Ne zaman kullanılır:** Adres formunu doldururken ya da kodları kendi sisteminizle eşlerken.\n- **Yetki (scope):** `shipment.read`\n- **Akıştaki yeri:** Token'dan sonra, gönderi oluşturmadan önce. Sonra `GET …/reference/cities/{cityCode}/districts`.\n- **Önemli kurallar:**\n - Liste plaka sırasıyla gelir.\n - Yanıtı önbelleğe alın; her gönderide tekrar çağırmanız gerekmez.", "parameters": [ { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "responses": { "200": { "description": "Başarılı. Liste nadiren değişir; yanıt 1 saat önbelleğe alınabilir (`Cache-Control: private, max-age=3600`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferenceListResponse" }, "example": { "success": true, "data": [ { "code": "1", "name": "Adana" }, { "code": "34", "name": "İstanbul" } ], "requestId": "REQ-…", "correlationId": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.read` yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "Required scope is missing.", "details": null }, "requestId": "REQ-…", "correlationId": null } } } }, "500": { "description": "Liste yüklenemedi. `requestId` ile bildirin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "City list could not be loaded.", "details": null }, "requestId": "REQ-…", "correlationId": null } } } } } } }, "/api/integration/v2/reference/cities/{cityCode}/districts": { "get": { "tags": [ "2 · Referans Veriler" ], "security": [ { "oauth2ClientCredentials": [ "shipment.read" ] }, { "bearerAuth": [] } ], "operationId": "listReferenceDistricts", "summary": "İlçeleri listele", "description": "Bir ilin aktif ilçelerini `code` + `name` olarak döner. `code`, gönderi adresindeki `districtCode` alanıdır (JetDiji ilçe kodu; ör. Kadıköy `1421`).\n\n- **Ne zaman kullanılır:** İl seçildikten sonra ilçe listesini doldurmak ya da ilçe kodlarını eşlemek için.\n- **Yetki (scope):** `shipment.read`\n- **Akıştaki yeri:** `GET …/reference/cities` sonrasında; dönen kodlar `POST /shipments` ve adres güncellemede kullanılır.\n- **Önemli kurallar:**\n - Listede görünen her `cityCode` + `districtCode` çifti gönderide kabul edilir; listede olmayan çift `422 DESTINATION_GEOGRAPHY_INVALID` döner.\n - Liste ilçe adına göre sıralıdır. Yanıtı önbelleğe alın.", "parameters": [ { "name": "cityCode", "in": "path", "required": true, "description": "İl kodu (`GET …/reference/cities` yanıtındaki `code`).", "schema": { "type": "string", "minLength": 1 }, "example": "34" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/XRequestId" } ], "responses": { "200": { "description": "Başarılı. Liste nadiren değişir; yanıt 1 saat önbelleğe alınabilir (`Cache-Control: private, max-age=3600`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferenceListResponse" }, "example": { "success": true, "data": [ { "code": "1421", "name": "Kadıköy" }, { "code": "1708", "name": "Üsküdar" } ], "requestId": "REQ-…", "correlationId": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Token'da `shipment.read` yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "Required scope is missing.", "details": null }, "requestId": "REQ-…", "correlationId": null } } } }, "404": { "description": "İl kodu bulunamadı.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CITY_NOT_FOUND", "message": "City code was not found.", "details": null }, "requestId": "REQ-…", "correlationId": null } } } }, "500": { "description": "Liste yüklenemedi. `requestId` ile bildirin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "District list could not be loaded.", "details": null }, "requestId": "REQ-…", "correlationId": null } } } } } } } }, "components": { "securitySchemes": { "oauth2ClientCredentials": { "type": "oauth2", "description": "OAuth 2.0 client credentials. Token ucu: `POST /api/integration/v1/oauth/token`. Swagger'da **Authorize** → client_id/secret ile token alınır.", "flows": { "clientCredentials": { "tokenUrl": "/api/integration/v1/oauth/token", "scopes": { "shipment.create": "Gönderi oluşturma", "shipment.read": "Gönderi durumu ve gerekli evrak okuma", "shipment.update": "Gönderi güncelleme ve hazırlık kararı", "shipment.events.read": "Hareket geçmişi okuma", "shipment.cancel": "Gönderi iptali" } } } }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Elle aldığınız `access_token`'ı yapıştırın. Gerekli scope'lar yine token'da olmalıdır." } }, "parameters": { "TrackingNumber": { "name": "trackingNumber", "in": "path", "required": true, "description": "Gönderi kimliği. Takip numarası (`trackingNumber`) ya da gönderi numarası (`shipmentNumber`) verilebilir. Oluşturma yanıtındaki `shipmentNumber` her zaman geçerlidir; `trackingNumber` sonradan (ör. kart barkodu eşlenince) dolabilir. Kendi işlem numaranız (`transactionId`) ya da müşteri referansınız (`customerReference`) bu alana verilmez; onlar için `lookup` uçlarını kullanın.", "schema": { "type": "string", "minLength": 1 }, "example": "100245" }, "CustomerReference": { "name": "customerReference", "in": "path", "required": true, "description": "Sizin sipariş numaranız (oluştururken verdiğiniz `customerReference`).", "schema": { "type": "string", "minLength": 1, "maxLength": 191 }, "example": "SIP-2026-000123" }, "TransactionId": { "name": "transactionId", "in": "path", "required": true, "description": "İşlem numaranız (oluştururken verdiğiniz `transactionId`).", "schema": { "type": "string", "minLength": 1, "maxLength": 191 }, "example": "123456789" }, "Include": { "name": "include", "in": "query", "required": false, "description": "Ek veri. `movements`: hareket geçmişini ekler (`shipment.events.read` ister). Virgülle ayrılabilir ya da tekrarlanabilir; bilinmeyen değerler yok sayılır.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "movements" ] } }, "style": "form", "explode": false }, "XIdempotencyKey": { "name": "X-Idempotency-Key", "in": "header", "required": true, "description": "İşlem başına tekil anahtar (UUID önerilir). Tekrar denemede aynı anahtarı gönderin.", "schema": { "type": "string", "minLength": 1 }, "example": "7d0f4c4e-1b2a-4f7e-9c3d-5a6b7c8d9e0f" }, "XCorrelationId": { "name": "X-Correlation-Id", "in": "header", "required": false, "description": "Kendi izleme kimliğiniz (isteğe bağlı). Yanıtta ve kayıtlarda geri döner.", "schema": { "type": "string" } }, "XRequestId": { "name": "X-Request-Id", "in": "header", "required": false, "description": "İstek kimliği (isteğe bağlı). Yoksa sunucu `REQ-` üretir.", "schema": { "type": "string" } } }, "headers": { "X-Request-Id": { "description": "İstek kimliği. Destek talebinde iletin.", "schema": { "type": "string" } }, "X-Correlation-Id": { "description": "İstekte gönderdiyseniz aynı değer.", "schema": { "type": "string" } } }, "responses": { "BadRequestWrite": { "description": "`X-Idempotency-Key` başlığı yok ya da gövde geçerli bir JSON nesnesi değil.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "IDEMPOTENCY_KEY_REQUIRED": { "summary": "Anahtar başlığı yok", "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REQUIRED", "message": "X-Idempotency-Key is required.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "INVALID_JSON": { "summary": "Gövde JSON değil", "value": { "success": false, "error": { "code": "INVALID_JSON", "message": "The request body is not valid JSON.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "Unauthorized": { "description": "Token yok, geçersiz ya da iptal edilmiş. Yeni token alın. `WWW-Authenticate: Bearer` döner.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_API_BEARER_REQUIRED": { "summary": "Authorization başlığı yok", "value": { "success": false, "error": { "code": "CUSTOMER_API_BEARER_REQUIRED", "message": "A valid Bearer access token is required.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "CUSTOMER_API_TOKEN_INVALID": { "summary": "Token geçersiz ya da süresi dolmuş", "value": { "success": false, "error": { "code": "CUSTOMER_API_TOKEN_INVALID", "message": "The Bearer access token is invalid or expired.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "CUSTOMER_API_TOKEN_REVOKED": { "summary": "Token iptal edilmiş", "value": { "success": false, "error": { "code": "CUSTOMER_API_TOKEN_REVOKED", "message": "The Bearer access token is no longer valid.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } }, "ForbiddenRead": { "description": "Token'da `shipment.read` scope'u yok.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CUSTOMER_API_SCOPE_FORBIDDEN", "message": "The access token does not grant the required scope.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } }, "ServiceUnavailable": { "description": "Kimlik doğrulama geçici olarak kullanılamıyor. Biraz sonra tekrar deneyin.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CUSTOMER_API_AUTH_UNAVAILABLE": { "summary": "İstemci kaydı okunamadı", "value": { "success": false, "error": { "code": "CUSTOMER_API_AUTH_UNAVAILABLE", "message": "Customer API authorization state is unavailable.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } }, "CUSTOMER_API_AUTH_CONFIGURATION_ERROR": { "summary": "Yapılandırma hatası", "value": { "success": false, "error": { "code": "CUSTOMER_API_AUTH_CONFIGURATION_ERROR", "message": "Customer API token validation is not configured.", "details": null }, "requestId": "REQ-3f6c2a9e-8d1b-4c57-9a0e-1b2c3d4e5f60", "correlationId": null } } } } } } }, "schemas": { "ErrorDetail": { "type": "object", "description": "Hata ayrıntısı. `VALIDATION_ERROR`'da her sorun için `path` + `message`; diğer kodlarda ek bağlam alanları olabilir.", "properties": { "path": { "type": "string", "description": "Hatalı alanın yolu, nokta ile (ör. `recipient.phone`)." }, "message": { "type": "string", "description": "Sorunun açıklaması (İngilizce)." } }, "additionalProperties": true }, "ErrorResponse": { "type": "object", "description": "Tüm v2 uçlarının hata zarfı. Dallanmayı yalnız `error.code` + HTTP durumuyla yapın; `message` metni değişebilir.", "required": [ "success", "error", "requestId", "correlationId" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "object", "required": [ "code", "message", "details" ], "properties": { "code": { "type": "string", "description": "Makine okunur hata kodu (ör. `SHIPMENT_NOT_FOUND`).", "examples": [ "SHIPMENT_NOT_FOUND" ] }, "message": { "type": [ "string", "null" ], "description": "İnsan okunur açıklama (İngilizce)." }, "details": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ErrorDetail" }, "description": "Ek ayrıntı; yoksa `null`." } } }, "requestId": { "type": "string", "description": "İstek kimliği. `X-Request-Id` gönderdiyseniz aynısı, yoksa sunucunun ürettiği `REQ-`. Destek talebinde iletin." }, "correlationId": { "type": [ "string", "null" ], "description": "`X-Correlation-Id` gönderdiyseniz aynısı; yoksa `null`." } } }, "OAuthTokenRequest": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "Yalnız `client_credentials` desteklenir." }, "client_id": { "type": "string", "description": "İstemci kimliği. Basic başlığı kullanmıyorsanız zorunlu." }, "client_secret": { "type": "string", "format": "password", "description": "İstemci sırrı. Basic başlığı kullanmıyorsanız zorunlu." }, "scope": { "type": "string", "description": "Boşlukla ayrılmış scope listesi. Boşsa istemciye tanımlı tüm scope'lar verilir.", "examples": [ "shipment.create shipment.read" ] } } }, "OAuthTokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "scope" ], "properties": { "access_token": { "type": "string", "description": "JWT erişim token'ı. `Authorization: Bearer ` olarak gönderin." }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "integer", "minimum": 60, "maximum": 3600, "description": "Geçerlilik süresi (saniye). Varsayılan 900; istemciye göre 60–3600." }, "scope": { "type": "string", "description": "Verilen scope'lar, boşlukla ayrılmış." } } }, "OAuthError": { "type": "object", "description": "Token ucunun hata biçimi (RFC 6749).", "required": [ "error", "error_description" ], "properties": { "error": { "type": "string", "enum": [ "invalid_request", "unsupported_grant_type", "invalid_scope", "invalid_client", "server_error" ] }, "error_description": { "type": "string", "description": "Açıklama (İngilizce)." } } }, "Recipient": { "type": "object", "additionalProperties": false, "required": [ "name", "phone" ], "description": "Alıcı bilgisi.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Alıcının adı soyadı." }, "phone": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Alıcının cep telefonu." }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 320, "description": "Alıcının e-postası (isteğe bağlı)." } } }, "Address": { "type": "object", "additionalProperties": false, "required": [ "countryCode", "cityCode", "districtCode", "addressLine" ], "description": "Adres. İl ve ilçe **kodla** verilir; ad kabul edilmez.", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Ülke kodu, 2 harf (ör. `TR`)." }, "cityCode": { "type": "string", "minLength": 1, "maxLength": 50, "description": "İl kodu (plaka kodu, ör. `34`)." }, "districtCode": { "type": "string", "minLength": 1, "maxLength": 50, "description": "İlçe kodu (JetDiji ilçe kodu, ör. Kadıköy için `1421`). Liste JetDiji ekibinden alınır." }, "neighborhood": { "type": [ "string", "null" ], "maxLength": 150, "description": "Mahalle adı (isteğe bağlı)." }, "addressLine": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Açık adres (cadde, sokak, no, daire)." }, "branchCode": { "type": [ "string", "null" ], "maxLength": 100, "description": "Müşteri şube kodu (isteğe bağlı). Create'te adresle birlikte saklanır." } } }, "ShipFrom": { "type": [ "object", "null" ], "additionalProperties": false, "description": "Gönderici bilgisi (isteğe bağlı).", "properties": { "company": { "type": [ "string", "null" ], "maxLength": 250, "description": "Gönderici firma adı." }, "contactName": { "type": [ "string", "null" ], "maxLength": 200, "description": "Yetkili kişi." }, "phone": { "type": [ "string", "null" ], "maxLength": 50, "description": "Gönderici telefonu." }, "taxNumber": { "type": [ "string", "null" ], "maxLength": 50, "description": "Vergi numarası." }, "taxOffice": { "type": [ "string", "null" ], "maxLength": 120, "description": "Vergi dairesi." }, "address": { "$ref": "#/components/schemas/Address", "description": "Gönderici adresi. Verilirse il/ilçe kodları geçerli olmalı (`ORIGIN_GEOGRAPHY_INVALID`)." } } }, "Package": { "type": "object", "additionalProperties": false, "properties": { "barcode": { "type": [ "string", "null" ], "maxLength": 191, "description": "Koli barkodu." }, "desi": { "type": [ "number", "null" ], "minimum": 0, "description": "Desi." }, "weightKg": { "type": [ "number", "null" ], "minimum": 0, "description": "Ağırlık (kg)." } } }, "ShipmentDocumentInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Dosya adı." }, "barcode": { "type": [ "string", "null" ], "maxLength": 191, "description": "Evrak barkodu." }, "contentBase64": { "type": [ "string", "null" ], "maxLength": 10000000, "description": "Dosya içeriği, Base64 (en çok 10.000.000 karakter)." } } }, "ShipmentProduct": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Ürün adı." }, "barcode": { "type": [ "string", "null" ], "maxLength": 191, "description": "Ürün barkodu. Başka bir gönderide güncel olamaz (`PRODUCT_BARCODE_DUPLICATE`)." } } }, "LabelRequest": { "type": [ "object", "null" ], "additionalProperties": false, "description": "Etiket tercihi. Şu an yanıtta etiket dönmez (`label: null`).", "properties": { "format": { "type": "string", "enum": [ "PDF", "ZPL" ], "description": "Etiket biçimi." }, "includeReturnLabel": { "type": "boolean", "description": "İade etiketi de istensin mi." } } }, "CreateShipmentRequest": { "type": "object", "additionalProperties": false, "required": [ "customerReference", "productCode", "recipient", "destinationAddress" ], "description": "Gönderi oluşturma isteği. Bilinmeyen alan gönderilirse `422 VALIDATION_ERROR`.", "properties": { "customerReference": { "type": "string", "minLength": 1, "maxLength": 191, "description": "Sizin sipariş/gönderi numaranız. Müşteri içinde tekil olmalı." }, "transactionId": { "type": [ "string", "null" ], "maxLength": 191, "description": "İşlem numaranız. Müşteri içinde tekil. `KUVEYT_HGS` ürününde int32 tam sayı metni zorunlu." }, "externalReference": { "type": [ "string", "null" ], "maxLength": 191, "description": "Ek dış referans. Müşteri içinde tekil." }, "productCode": { "type": "string", "minLength": 1, "maxLength": 100, "description": "JetDiji ürün kodu. İstemcinize tanımlı olmalı." }, "productBarcode": { "type": [ "string", "null" ], "maxLength": 191, "description": "Ürün barkodu (tek ürün). Başka gönderide güncel olamaz." }, "identityNumber": { "type": [ "string", "null" ], "maxLength": 50, "description": "Alıcının kimlik numarası (ürün gerektiriyorsa)." }, "recipient": { "$ref": "#/components/schemas/Recipient" }, "destinationAddress": { "$ref": "#/components/schemas/Address" }, "shipFrom": { "$ref": "#/components/schemas/ShipFrom" }, "packages": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Package" }, "description": "Koli listesi." }, "documents": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ShipmentDocumentInput" }, "description": "Gönderiyle gelen evraklar." }, "products": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ShipmentProduct" }, "description": "Ürün listesi." }, "additionalData": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Serbest anahtar–değer bilgisi; değerler metin olmalı." }, "shipmentChargeType": { "type": [ "string", "null" ], "enum": [ "ACCOUNT_OWNER", "RECIPIENT", "SENDER_ADDRESS", null ], "description": "Ödeme tipi: hesap sahibi, alıcı, gönderici adresi." }, "contractCode": { "type": [ "string", "null" ], "maxLength": 100, "description": "Sözleşme kodu. Verilirse müşteride bulunmalı (`CONTRACT_NOT_FOUND`)." }, "packageCount": { "type": "integer", "minimum": 1, "description": "Koli adedi." }, "totalWeight": { "type": [ "number", "null" ], "minimum": 0, "description": "Toplam ağırlık (kg)." }, "plannedDeliveryAt": { "type": [ "string", "null" ], "maxLength": 100, "description": "Planlanan teslim zamanı, ISO 8601 (ör. `2026-10-10T09:00:00+03:00`)." }, "priorityCode": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Öncelik kodu. Verilmezse `NORMAL`." }, "additionalDescription": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Ek açıklama." }, "labelRequest": { "$ref": "#/components/schemas/LabelRequest" } } }, "CreateShipmentResult": { "type": "object", "required": [ "shipmentNumber", "trackingNumber", "customerReference", "transactionId", "trackingUrl", "label", "returnLabel" ], "properties": { "shipmentNumber": { "type": "string", "description": "JetDiji gönderi numarası. Takip numarası yokken yol parametresinde kullanılabilir." }, "trackingNumber": { "type": [ "string", "null" ], "description": "Takip numarası. Oluşturma anında boş olabilir." }, "customerReference": { "type": "string", "description": "Gönderdiğiniz müşteri referansı." }, "transactionId": { "type": [ "string", "null" ], "description": "Gönderdiğiniz işlem numarası." }, "trackingUrl": { "type": "null", "description": "Şimdilik her zaman `null`." }, "label": { "type": "null", "description": "Şimdilik her zaman `null`." }, "returnLabel": { "type": "null", "description": "Şimdilik her zaman `null`." } } }, "CreateShipmentResponse": { "type": "object", "required": [ "success", "replayed", "data", "requestId", "correlationId" ], "properties": { "success": { "type": "boolean", "const": true }, "replayed": { "type": "boolean", "description": "`true`: aynı `X-Idempotency-Key` ile daha önce oluşturulan gönderi döndü; yeni kayıt açılmadı." }, "data": { "$ref": "#/components/schemas/CreateShipmentResult" }, "requestId": { "type": "string" }, "correlationId": { "type": [ "string", "null" ] } } }, "DirectAddressUpdate": { "type": "object", "title": "Doğrudan adres", "additionalProperties": false, "required": [ "countryCode", "cityCode", "districtCode", "addressLine" ], "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Ülke kodu, 2 harf." }, "cityCode": { "type": "string", "minLength": 1, "maxLength": 50, "description": "İl kodu (plaka kodu)." }, "districtCode": { "type": "string", "minLength": 1, "maxLength": 50, "description": "İlçe kodu." }, "neighborhood": { "type": [ "string", "null" ], "maxLength": 150, "description": "Mahalle adı." }, "addressLine": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Açık adres." } } }, "BranchAddressUpdate": { "type": "object", "title": "Şube adresi", "additionalProperties": false, "required": [ "branchCode" ], "properties": { "branchCode": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Müşteri şube kodu. Adres, şubenin kayıtlı adresinden alınır." } } }, "UpdateShipmentAddressRequest": { "description": "İki biçimden biri: doğrudan adres **ya da** `{ branchCode }`. İkisi karışık gönderilemez.", "oneOf": [ { "$ref": "#/components/schemas/DirectAddressUpdate" }, { "$ref": "#/components/schemas/BranchAddressUpdate" } ] }, "RecipientUpdate": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "En az bir alan dolu olmalı. Gönderilmeyen alan değişmez.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Yeni alıcı adı soyadı." }, "phone": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Yeni alıcı telefonu." }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 320, "description": "Yeni e-posta. `null` e-postayı siler." } } }, "UpdateShipmentRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Kısmi güncelleme. `recipient` ve `destinationAddress`'ten en az biri gerekir.", "properties": { "recipient": { "$ref": "#/components/schemas/RecipientUpdate" }, "destinationAddress": { "$ref": "#/components/schemas/UpdateShipmentAddressRequest" } } }, "ReplaceShipmentProductsRequest": { "type": "object", "additionalProperties": false, "required": [ "products" ], "properties": { "products": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/ShipmentProduct" }, "description": "Yeni ürün listesinin tamamı (en çok 100). `[]` listeyi temizler." } } }, "UpdateCustomerReferenceRequest": { "type": "object", "additionalProperties": false, "required": [ "customerReference" ], "properties": { "customerReference": { "type": "string", "minLength": 1, "maxLength": 191, "description": "Yeni müşteri referansı. Müşteri içinde tekil olmalı." } } }, "PreparationStatusRequest": { "type": "object", "additionalProperties": false, "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "APPROVE", "REJECT_REMATCH", "REJECT_RELEASE" ], "description": "`APPROVE`: onayla, akış devam eder. `REJECT_REMATCH`: reddet, ürün stoğa döner ve yeniden eşlenir. `REJECT_RELEASE`: reddet, ürün ayrı sonuçlanır, etiket serbest kalır." } } }, "CancelShipmentRequest": { "type": "object", "additionalProperties": false, "maxProperties": 0, "description": "Gövde boş bırakılır ya da `{}` gönderilir. Alan gönderilirse `422`." }, "ShipmentMutationResult": { "type": "object", "required": [ "shipmentNumber", "trackingNumber", "customerReference", "transactionId" ], "description": "İşlemden sonraki gönderi kimlikleri.", "properties": { "shipmentNumber": { "type": "string", "description": "JetDiji gönderi numarası." }, "trackingNumber": { "type": [ "string", "null" ], "description": "Takip numarası." }, "customerReference": { "type": [ "string", "null" ], "description": "Güncel müşteri referansı." }, "transactionId": { "type": [ "string", "null" ], "description": "İşlem numarası." } } }, "ShipmentMutationResponse": { "type": "object", "required": [ "success", "replayed", "data", "requestId", "correlationId" ], "properties": { "success": { "type": "boolean", "const": true }, "replayed": { "type": "boolean", "description": "`true`: aynı anahtarla aynı işlem daha önce uygulanmıştı; tekrar uygulanmadı, `data` güncel değerlerdir." }, "data": { "$ref": "#/components/schemas/ShipmentMutationResult" }, "requestId": { "type": "string" }, "correlationId": { "type": [ "string", "null" ] } } }, "ShipmentStatus": { "type": "object", "required": [ "code", "name", "fullCode", "fullName" ], "description": "Güncel durum. Kodlar kanonik JetDiji kodlarıdır (rehberdeki sözlüğe bakın).", "properties": { "code": { "type": "string", "description": "Ana durum kodu, 4 hane (ör. `4020` Dağıtımda)." }, "name": { "type": "string", "description": "Ana durum adı (Türkçe)." }, "fullCode": { "type": [ "string", "null" ], "description": "Alt durum kodu (ör. `4021` Dağıtıma Çıktı)." }, "fullName": { "type": [ "string", "null" ], "description": "Alt durum adı." } } }, "ShipmentReason": { "type": [ "object", "null" ], "required": [ "code", "name" ], "description": "Durumun nedeni (ör. teslim edilemedi nedeni, teslim alan tipi). Yoksa `null`.", "properties": { "code": { "type": "string", "description": "Neden kodu (ör. `9301`)." }, "name": { "type": [ "string", "null" ], "description": "Neden adı (müşteriye gösterilen ad)." } } }, "ShipmentMovement": { "type": "object", "required": [ "occurredAt", "statusCode", "statusName", "fullStatusCode", "fullStatusName", "reasonCode", "reasonName" ], "description": "Bir durum hareketi.", "properties": { "occurredAt": { "type": "string", "format": "date-time", "description": "Hareket zamanı (ISO 8601, UTC)." }, "statusCode": { "type": "string", "description": "Ana durum kodu." }, "statusName": { "type": [ "string", "null" ], "description": "Ana durum adı." }, "fullStatusCode": { "type": [ "string", "null" ], "description": "Alt durum kodu." }, "fullStatusName": { "type": [ "string", "null" ], "description": "Alt durum adı." }, "reasonCode": { "type": [ "string", "null" ], "description": "Neden kodu." }, "reasonName": { "type": [ "string", "null" ], "description": "Neden adı." } } }, "ShipmentDetail": { "type": "object", "required": [ "shipmentNumber", "trackingNumber", "customerReference", "transactionId", "outputNumber", "productCode", "productNumber", "status", "reason", "deliveryDate", "appointmentDate", "recipient", "movements" ], "properties": { "shipmentNumber": { "type": "string", "description": "JetDiji gönderi numarası." }, "trackingNumber": { "type": [ "string", "null" ], "description": "Takip numarası." }, "customerReference": { "type": "string", "description": "Müşteri referansı." }, "transactionId": { "type": [ "string", "null" ], "description": "İşlem numarası." }, "outputNumber": { "type": "null", "description": "Şimdilik her zaman `null`." }, "productCode": { "type": [ "string", "null" ], "description": "Ürün kodu." }, "productNumber": { "type": "null", "description": "Şimdilik her zaman `null`." }, "status": { "$ref": "#/components/schemas/ShipmentStatus" }, "reason": { "$ref": "#/components/schemas/ShipmentReason" }, "deliveryDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Teslim zamanı; teslim edilmediyse `null`." }, "appointmentDate": { "type": "null", "description": "Şimdilik her zaman `null`." }, "recipient": { "type": [ "string", "null" ], "description": "Alıcı adı." }, "movements": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ShipmentMovement" }, "description": "Yalnız `?include=movements` ile dolar; yoksa `null`. Eski tarihten yeniye sıralı." } } }, "ShipmentDetailResponse": { "type": "object", "required": [ "success", "data", "requestId", "correlationId" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/ShipmentDetail" }, "requestId": { "type": "string" }, "correlationId": { "type": [ "string", "null" ] } } }, "ShipmentMovementsResponse": { "type": "object", "required": [ "success", "data", "requestId", "correlationId" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentMovement" }, "description": "Hareketler, `occurredAt` artan sırada." }, "requestId": { "type": "string" }, "correlationId": { "type": [ "string", "null" ] } } }, "RequiredDocument": { "type": "object", "required": [ "documentId", "documentCode", "name", "description", "contentBase64" ], "properties": { "documentId": { "type": "string", "description": "Evrak kimliği (eski `docGuid`)." }, "documentCode": { "type": [ "string", "null" ], "description": "Evrak kodu (eski `customerDocCode`)." }, "name": { "type": [ "string", "null" ], "description": "Evrak veya dosya adı." }, "description": { "type": [ "string", "null" ], "description": "Evrak açıklaması." }, "contentBase64": { "type": [ "string", "null" ], "description": "Evrak içeriği (Base64). Yalnız içerik açıkça tanımlandıysa dolar." } } }, "RequiredDocumentsResponse": { "type": "object", "required": [ "success", "data", "requestId", "correlationId" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RequiredDocument" } }, "requestId": { "type": "string" }, "correlationId": { "type": [ "string", "null" ] } } }, "ReferenceItem": { "type": "object", "required": [ "code", "name" ], "properties": { "code": { "type": "string", "description": "Adreste gönderilecek kod.", "example": "1421" }, "name": { "type": "string", "description": "Görünen ad.", "example": "Kadıköy" } } }, "ReferenceListResponse": { "type": "object", "required": [ "success", "data", "requestId" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReferenceItem" } }, "requestId": { "type": "string" }, "correlationId": { "type": [ "string", "null" ] } } } } } }