PHPackages tcgunel/omniship-yurtici - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. tcgunel/omniship-yurtici ActiveLibrary[API Development](/categories/api) tcgunel/omniship-yurtici ======================== Yurtiçi Kargo carrier for Omniship v0.0.3(3mo ago)0127MITPHPPHP ^8.2 Since Mar 12Pushed 3mo agoCompare [ Source](https://github.com/tcgunel/omniship-yurtici)[ Packagist](https://packagist.org/packages/tcgunel/omniship-yurtici)[ RSS](/packages/tcgunel-omniship-yurtici/feed)WikiDiscussions main Synced 3w ago READMEChangelogDependencies (10)Versions (4)Used By (0) Omniship Yurtiçi Kargo ====================== [](#omniship-yurtiçi-kargo) Yurtiçi Kargo carrier driver for [Omniship](https://github.com/tcgunel/omniship-common). Uses the **Giden Kargo** (outbound) SOAP API via `ShippingOrderDispatcherServices` WSDL. Installation ------------ [](#installation) ``` composer require tcgunel/omniship-yurtici ``` Quick Start ----------- [](#quick-start) ``` use Omniship\Omniship; use Omniship\Common\Address; use Omniship\Common\Package; $carrier = Omniship::create('Yurtici'); $carrier->initialize([ 'username' => 'YKTEST', // Test credentials 'password' => 'YK', 'userLanguage' => 'TR', // TR or EN 'testMode' => true, ]); ``` > **Note:** Payment type is not sent as a parameter — different users (credentials) are assigned to different payment types (Sender Pays, Receiver Pays, COD Cash, COD Credit Card). Your integration must support multiple credentials. Operations ---------- [](#operations) ### Create Shipment [](#create-shipment) Two working modes are supported: #### Invoice-Based (Fatura Bazlı) [](#invoice-based-fatura-bazlı) One record per shipment. Each `cargoKey` = one shipment. YK branch handles piece count and desi manually. ``` $response = $carrier->createShipment([ 'cargoKey' => 'ORDER-001', // Required, unique, YK branch scans this barcode 'invoiceKey' => 'INV-001', // Required, unique per shipment 'shipTo' => new Address( name: 'Mehmet Yılmaz', // Min 5 chars, min 4 letters street1: 'Eski Büyükdere Cad. No:3', // Min 5 chars, max 200. Do NOT include city/district here city: 'Istanbul', district: 'Maslak', phone: '02123652426', // 10 digits with area code email: 'mehmet@example.com', ), 'packages' => [ new Package(weight: 2.5, desi: 3), ], 'description' => 'Elektronik ürün', 'waybillNo' => 'IRN-001', // Waybill number (required for commercial shipments) 'specialField1' => '1$134096$', // Custom fields (see Special Fields section) ])->send(); if ($response->isSuccessful()) { echo $response->getShipmentId(); // jobId echo $response->getTrackingNumber(); // cargoKey } ``` #### Package-Based (Kargo Bazlı) [](#package-based-kargo-bazlı) For multi-piece shipments. Each piece gets a unique `cargoKey`, all sharing the same `invoiceKey`. ``` // 3-piece shipment: each piece has unique cargoKey, same invoiceKey $response = $carrier->createShipment([ // Piece 1 ['cargoKey' => '10012', 'invoiceKey' => 'A123456', 'cargoCount' => 3, 'shipTo' => $address, 'waybillNo' => 'A123456'], // Piece 2 ['cargoKey' => '10013', 'invoiceKey' => 'A123456', 'cargoCount' => 3, 'shipTo' => $address, 'waybillNo' => 'A123456'], // Piece 3 ['cargoKey' => '10014', 'invoiceKey' => 'A123456', 'cargoCount' => 3, 'shipTo' => $address, 'waybillNo' => 'A123456'], ])->send(); ``` > YK branch scans each piece barcode individually, printing a YK barcode for each. The shipping document is generated after the last piece is scanned. ### Cash on Delivery (Tahsilatlı Teslimat) [](#cash-on-delivery-tahsilatlı-teslimat) #### Cash COD (Nakit) [](#cash-cod-nakit) ``` $response = $carrier->createShipment([ 'cargoKey' => 'COD-001', 'invoiceKey' => 'INV-COD', 'shipTo' => $address, 'packages' => [new Package(weight: 1.0)], 'cashOnDelivery' => true, 'codAmount' => 45.35, // ttInvoiceAmount - separator must be "." 'codCollectionType' => '0', // 0 = Cash 'codDocumentId' => '5146846', // ttDocumentId - invoice number 'codDocumentSaveType' => '0', // 0 = Same invoice, 1 = Separate invoice ])->send(); ``` #### Credit Card COD (Kredi Kartı) [](#credit-card-cod-kredi-kartı) ``` $response = $carrier->createShipment([ 'cargoKey' => 'COD-CC-001', 'invoiceKey' => 'INV-CC', 'shipTo' => $address, 'packages' => [new Package(weight: 1.0)], 'cashOnDelivery' => true, 'codAmount' => 45.35, 'codCollectionType' => '1', // 1 = Credit Card 'codDocumentId' => '5146846', 'codDocumentSaveType' => '0', 'dcSelectedCredit' => 5, // Installment count 'dcCreditRule' => 1, // 0 = Customer choice required, 1 = Allow single payment ])->send(); ``` ### Track Shipment (queryShipment) [](#track-shipment-queryshipment) Query shipment status and movement history. Rate limited: repeated queries within 1 minute are blocked. ``` $response = $carrier->getTrackingStatus([ 'trackingNumber' => 'ORDER-001', 'keyType' => 0, // 0 = cargoKey (default), 1 = invoiceKey 'addHistoricalData' => true, // Include transport movement history 'onlyTracking' => false, // Only return tracking link ])->send(); if ($response->isSuccessful()) { $info = $response->getTrackingInfo(); echo $info->trackingNumber; // docId (YK shipment number) echo $info->status->name; // DELIVERED, IN_TRANSIT, etc. foreach ($info->events as $event) { echo $event->occurredAt->format('Y-m-d H:i'); echo $event->description; // "Kargo Indirildi" echo $event->location; // "AFSIN IRTIBAT" echo $event->status->name; } } ``` #### queryShipment Response Fields [](#queryshipment-response-fields) The response includes detailed shipment information: FieldDescription`docid`YK shipment number`operationCode/Status`Current status (see status codes below)`deliveryDate/Time`Delivery date/time (YYYYMMDD / HHMMSS)`totalDesi`Total desi`totalKg`Total weight`totalAmount`Total charge`totalPrice`Transport fee`totalVat`VAT amount`trackingUrl`Self-service tracking link`receiverInfo`Delivery confirmation info`rejectStatus`Return status (see below)`returnStatus`Return delivery status (see below)#### Transport Movement History (invDocCargoVOArray) [](#transport-movement-history-invdoccargovoarray) When `addHistoricalData=true`, each movement event includes: FieldDescriptionExample`unitId`YK unit code8070`unitName`YK unit nameAFSIN IRTIBAT`eventId`Event codeYK`eventName`Event descriptionKargo Indirildi`reasonId`Reason codeOK`reasonName`Reason descriptionSorun Yok`eventDate`Event date20110711`eventTime`Event time082304`cityName`CityKahramanmaras`townName`DistrictAfsin### Cancel Shipment (cancelDispatch) [](#cancel-shipment-canceldispatch) Cancellation is only possible before the shipment is dispatched (invoice not yet issued). ``` $response = $carrier->cancelShipment([ 'cargoKeys' => 'ORDER-001', ])->send(); if ($response->isSuccessful() && $response->isCancelled()) { echo 'Shipment cancelled'; } ``` #### Cancel Operation Statuses [](#cancel-operation-statuses) operationCodeoperationStatusDescription0NOPShipment not processed1INDShipment in delivery2ISRShipment processed, invoice not yet issued3CNLShipment dispatch blocked (cancelled)4ISCShipment was already cancelled5DLVShipment delivered### Return Shipment Code (saveReturnShipmentCode) [](#return-shipment-code-savereturnshipmentcode) Create RMA return codes that customers can use at YK branches. ``` // Parameters: fieldName=16 (use 53 or 3 in test), returnCode, startDate, endDate, maxCount ``` ParameterDescriptionExample`fieldName`Special field ID (16 for returns, use 53/3 in test)16`returnCode`Your return code21312312`startDate`Code validity start (YYYYMMDD)20231003`endDate`Code validity end (YYYYMMDD)20231103`maxCount`Maximum uses1API Reference ------------- [](#api-reference) ### WSDL Endpoints [](#wsdl-endpoints) EnvironmentURLTest`http://testwebservices.yurticikargo.com:9090/KOPSWebServices/ShippingOrderDispatcherServices?wsdl`Production`https://ws.yurticikargo.com/KOPSWebServices/ShippingOrderDispatcherServices?wsdl`> **IP Whitelisting Required:** You must provide your outgoing IP to Yurtiçi Kargo IT team for access authorization. ### Test Credentials [](#test-credentials) FieldValueUsername`YKTEST`Password`YK`Payment TypeSender PaysLanguage`TR`### SOAP Methods [](#soap-methods) MethodSOAP ActionDescription`createShipment``ship:createShipment`Create shipment(s) via ShippingOrderVO array`queryShipment``ship:queryShipment`Query shipment status (ShippingDeliveryVO)`cancelShipment``ship:cancelDispatch`Cancel pending shipment(s) by cargoKey`saveReturnShipmentCode``ship:saveReturnShipmentCode`Create RMA return code`cancelReturnShipmentCode``ship:cancelReturnShipmentCode`Cancel RMA return code### createShipment Parameters (ShippingOrderVO) [](#createshipment-parameters-shippingordervo) #### Required Fields [](#required-fields) ParameterTypeDescriptionExample`cargoKey`String(20)Unique shipment key (barcode on package)222012345`invoiceKey`String(20)Unique invoice keyAB00113`receiverCustName`String(200)Receiver name (min 5 chars, min 4 letters)MEHMET YILMAZ`receiverAddress`String(500)Receiver address (exclude city/district, min 5, max 200 chars)Eski Büyükdere Cad. No:3`receiverPhone1`String(20)Phone with area code (10 digits)02123652426#### Optional Fields [](#optional-fields) ParameterTypeDescription`receiverPhone2/3`String(20)Additional phone numbers`cityName`String(40)City name`townName`String(40)District name`desi`Double(9,3)Volumetric weight (if authorized)`kg`Double(9,3)Weight in kg (if authorized)`cargoCount`Integer(4)Number of pieces in shipment`waybillNo`String(20)Waybill number (required for commercial)`description`String(255)Description`emailAddress`String(200)Receiver email`taxNumber`String(11)Tax number (11 digits for individuals, 10 for companies)`taxOfficeId`Long(8)Tax office code`taxOfficeName`String(60)Tax office name`orgReceiverCustId`String(50)Receiver customer code`orgGeoCode`String(20)Customer address code`privilegeOrder`String(10)Destination priority order`custProdId`StringProduct code`specialField1`String(200)Custom field 1 (see format below)`specialField2`String(100)Custom field 2`specialField3`String(100)Custom field 3#### COD Fields [](#cod-fields) ParameterTypeDescription`ttCollectionType`String(1)0 = Cash, 1 = Credit Card`ttInvoiceAmount`Double(18,2)Collection amount (separator: ".")`ttDocumentId`Long(12)Invoice number`ttDocumentSaveType`String(1)0 = Same invoice, 1 = Separate invoice`dcSelectedCredit`Long(2)Installment count (credit card only)`dcCreditRule`Long(2)0 = Customer choice required, 1 = Allow single payment### Special Fields (specialField1) [](#special-fields-specialfield1) Multiple custom values can be sent in `specialField1` using this format: ``` {fieldId}${value}#{fieldId}${value}# ``` Example: `1$426031#2$397427#` - `$` marks start of field value - `#` marks end of field value fieldNameDescriptionfieldNameDescription2Customer Serial No12Cost Code4Pouch No13Product5Package No14Customer Cargo Ref Code6Customer ID No16Return Approval Code7Customer Name51Desi Type8Region52Representative No9Department/Personnel54Waybill No10Mobile Phone55Receiver Tax No11Policy No56Team Leader Rep No### Tracking Status Codes (operationCode) [](#tracking-status-codes-operationcode) CodeStatusDescription (TR)Description (EN)0NOPKargo İşlem GörmemişNot processed1INDKargo TeslimattadırIn delivery2ISRFaturası henüz düzenlenmemiştirProcessed, invoice pending3CNLKargo Çıkışı EngellendiDispatch blocked4ISCDaha önceden iptal edilmiştirAlready cancelled5DLVKargo teslim edilmiştirDelivered6BIFatura şube tarafından iptal edilmiştirInvoice cancelled by branch### Return Status (returnStatus) [](#return-status-returnstatus) ValueDescription0Not delivered, return invoice not issued1Delivered, return invoice not issued2Delivered, return invoice issued3Returned to sender### Reject Status (rejectStatus) [](#reject-status-rejectstatus) ValueDescription0Return request made1Departure branch approved2Region approved3Customer approved4Awaiting return7Delivery cancelled8Billing cancelled9Return completed10Return finalized11Return not approved> Values 0, 1, 2, 3, 9, 10 = cargo is in return process. Values 4, 7, 8, 11 = return was initiated but cancelled, normal process resumed. ### Return Reason Descriptions (reasonDesc) [](#return-reason-descriptions-reasondesc) ReasonAdres Yanlış / YetersizAlıcı Müşteriye UlaşılamıyorÇalışma Alanı Olmayan AdresHasarlı Kargo İadesiAlıcı Tarafından Kabul EdilmediÜcretinden Dolayı Kabul EdilmediMüşteri Adresi YokMüşteri Taşınıyor/Ayrılmış/TatildeMüşteri İsteğiNot Bırakıldığı Halde AlınmadıVarış Merkezi Hatası### Response Format [](#response-format) All responses include: - `outFlag`: `0` = at least one success, `1` = all errors, `2` = unexpected error - `outResult`: Human-readable result message - Per-shipment detail VO with `errCode` and `errMessage` (errCode=0 for success) ### Error Codes [](#error-codes) #### createShipment Errors [](#createshipment-errors) CodeConstantDescription0—Success936—Unexpected error (contact YK IT)80859ERR\_INTG\_CARGO\_KEY\_PARAM\_NOT\_FOUNDcargoKey missing82500ERR\_INTG\_CARGO\_KEY\_PARAM\_LENGHTcargoKey too long60020ERR\_EXIST\_CARGO\_KEY\_PARAMcargoKey already exists80057MSG\_JOB\_ID\_NOT\_FOUNDjobId not found60017ERR\_INTG\_INVOICE\_KEY\_PARAM\_NOT\_FOUNDinvoiceKey missing82501ERR\_INTG\_INVOICE\_KEY\_PARAM\_LENGHTinvoiceKey too long60018ERR\_INTG\_RECEIVER\_CUST\_NAME\_PARAM\_NOT\_FOUNDReceiver name missing82503ERR\_INTG\_RECEIVER\_CUST\_NAME\_PARAM\_LENGHTReceiver name too long60019ERR\_INTG\_RECEIVER\_ADDRESS\_PARAM\_NOT\_FOUNDReceiver address missing82502ERR\_INTG\_RECEIVER\_ADDRESS\_PARAM\_LENGHTReceiver address too long82505ERR\_INTG\_TT\_INVOICE\_AMOUNT\_PARAM\_NOT\_FOUNDCOD amount missing82506ERR\_INTG\_TT\_INVOICE\_AMOUNT\_PARAM\_LENGHTCOD amount too long82507ERR\_INTG\_TT\_DOCUMENT\_ID\_PARAM\_NOT\_FOUNDCOD document ID missing82508ERR\_INTG\_TT\_DOCUMENT\_ID\_PARAM\_LENGHTCOD document ID too long82509ERR\_INTG\_DC\_SELECTED\_CREDIT\_NOT\_FOUNDInstallment count missing82510ERR\_INTG\_DC\_SELECTED\_CREDIT\_LENGHTInstallment count too long82511ERR\_INTG\_DC\_CREDIT\_RULE\_NOT\_FOUNDCredit rule missing82512ERR\_INTG\_DC\_COLL\_CC\_WRONG\_PARAMETERPayment type mismatch with contract82513ERR\_INTG\_TT\_COLL\_TYPEInvalid COD type (must be 0 or 1)82514ERR\_INTG\_TT\_DOC\_SAVE\_TYPEInvalid document save type (must be 0 or 1)82515ERR\_INTG\_EMAIL\_ADDRESS\_INVALID\_PARAMETERInvalid email address82516ERR\_INTG\_RECEIVER\_PHONE\_INVALID\_PARAMETERInvalid phone number82517ERR\_INTG\_INVALID\_PARAMETERInvalid format82518ERR\_INTG\_DC\_CREDIT\_RULE\_WRONG\_PARAMETERInvalid credit rule value#### cancelShipment Errors [](#cancelshipment-errors) CodeConstantDescription82519ERR\_INTG\_CARGO\_KEY\_NOT\_FOUNDcargoKey not found for this user82520ERR\_INTG\_CARGO\_KEY\_OPERATION\_CANCELLEDcargoKey already cancelled#### queryShipment Errors [](#queryshipment-errors) CodeConstantDescription82526ERR\_INTG\_KEYS\_NOT\_FOUNDkeys parameter missing82527ERR\_INTG\_KEY\_TYPE\_NOT\_FOUNDkeyType parameter invalid### Parametric Tracking Links [](#parametric-tracking-links) You can build tracking URLs for customers using: ``` https://selfservis.yurticikargo.com/reports/SavReportsFromParamFields.aspx?ssfldvn={fieldId}&sskurkod={customerCode}&refnumber={value}&date={dd.mm.yyyy} ``` ParameterDescription`ssfldvn`Field type ID (see Special Fields table, 99 for waybill)`sskurkod`YK customer code`refnumber`Reference value to search`date`Shipment date (dd.mm.yyyy, +/-5 day tolerance)Integration Flow ---------------- [](#integration-flow) 1. Complete development and test in test environment 2. Send `createShipment` data to test, share `cargo_key` with YK IT for verification 3. YK dispatches test shipment, you query with `queryShipment` to verify tracking 4. Test `cancelShipment` to verify cancellation works 5. Request production credentials from your regional sales representative Notes ----- [](#notes) - **Two working modes**: Invoice-based (one cargoKey per shipment) and Package-based (one cargoKey per piece, shared invoiceKey) - The `cargoKey` barcode must be physically present on the package for YK branch to scan - `queryShipment` uses `wsLanguage` parameter (not `userLanguage` like other methods) - Barcode/tracking number (`docId`) is only available after `queryShipment`, not at creation time - Batch operations supported: pass multiple ShippingOrderVO items - Rate limiting on `queryShipment`: 1-minute cooldown on repeated queries - Cancellation only works before the shipment invoice is issued by YK branch Testing ------- [](#testing) ``` vendor/bin/pest ``` License ------- [](#license) MIT ### Health Score 37 — LowBetter than 81% of packages Maintenance82 Actively maintained with recent releases Popularity13 Limited adoption so far Community6 Small or concentrated contributor base Maturity39 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~6 days Total 3 Last Release 96d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/36dffe883e88aeef07c26067af3d6a7eda1c2a81f1ae45fdd430b721665131da?d=identicon)[Mobius Studio](/maintainers/Mobius%20Studio) --- Top Contributors [![tcgunel](https://avatars.githubusercontent.com/u/3923425?v=4)](https://github.com/tcgunel "tcgunel (6 commits)") ### Code Quality TestsPest Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/tcgunel-omniship-yurtici/health.svg) ``` [![Health](https://phpackages.com/badges/tcgunel-omniship-yurtici/health.svg)](https://phpackages.com/packages/tcgunel-omniship-yurtici) ``` ### Alternatives [exsyst/swagger A php library to manipulate Swagger specifications 35816.3M7](/packages/exsyst-swagger)[hubspot/api-client Hubspot API client 24015.5M18](/packages/hubspot-api-client)[pocketmine/bedrock-protocol An implementation of the Minecraft: Bedrock Edition protocol in PHP 172437.8k11](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram Telegram driver for BotMan 93452.6k6](/packages/botman-driver-telegram) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)