{"openapi":"3.0.3","info":{"title":"Courino API","version":"1.0.0","description":"The Courino customer integration API lets your own systems (online store, ERP, warehouse software)\nget prices, create orders, follow them and receive status changes as they happen. You can try every\noperation on this page directly: enter your key with the **Authorize** button and use\n**Try it out**. Requests run against your real account.\n\n## Getting started\n\n1. **Create a key.** In the customer portal, open **My company details → Integration (API keys)** and create a new\n   API key. The key starts with `kosk_` and is **shown only once**; keep it like a password and never\n   put it in source code or in code that runs in a browser.\n2. **Send it on every request:** `Authorization: Bearer kosk_…`\n3. **Get the district and delivery type IDs:** `GET /me/order-options`. The `districtId` (district)\n   and `deliveryTypeId` (delivery type) values used in price and order requests come from this list.\n   It changes rarely; caching it for a day is fine.\n4. **Get a price:** `POST /pricing/quote` (does not create an order).\n5. **Create the order:** `POST /orders` (with an `Idempotency-Key` header).\n6. **Receive status changes:** register a webhook URL with `POST /me/webhooks`, or read the order\n   with `GET /me/orders/{id}`.\n\nBase URL: `https://client.courino.com/api/v1` (for companies running their own server, the company's\ndomain; the address this page was opened from is always correct).\n\n## Authentication and keys\n\n- A key acts with the permissions of the customer account it belongs to: it only sees orders you\n  placed or pay for. The ID of any other order returns 404.\n- An account can have at most **5 active keys**; a key can optionally be given an expiry date.\n- A revoked key stops working within **30 seconds** at most. Keys also stop working when your account\n  password changes or the account is deactivated.\n- A missing, invalid, expired or revoked key returns **401 `UNAUTHORIZED`**. Endpoints that cannot be\n  used with an API key (staff operations; account operations that need a session and a person, such\n  as saved cards, support tickets or starting a payment) return **403 `FORBIDDEN`**.\n- Apart from the two health-check endpoints below, this document only contains endpoints that can\n  be called with an API key.\n\n## Rate limit\n\n**120 requests per minute** per key. Every response carries:\n\n| Header | Meaning |\n|---|---|\n| `X-RateLimit-Limit` | Per-minute limit (`120`) |\n| `X-RateLimit-Remaining` | Requests left in the current window |\n| `X-RateLimit-Reset` | Seconds until the window resets |\n\nWhen the limit is exceeded you get **429 `TOO_MANY_REQUESTS`** with a `Retry-After` header (seconds);\nwait that long and try again. Use webhooks instead of polling order statuses frequently, and use\n`POST /me/orders/batch` (up to 1000 rows per request) for large numbers of orders.\n\n## Data formats\n\n- **Amounts and decimals are strings:** `\"180.00\"`, `\"2.5\"`. Send and read them as strings, not\n  numbers, to avoid rounding errors. The decimal separator is a dot.\n- **Timestamps** are RFC 3339 (`2027-03-04T09:15:02Z` or `2027-03-04T12:15:02+03:00`); date-only\n  fields use `YYYY-MM-DD`.\n- **Phone numbers** are free format on input (`0532 123 45 67`, `+90532…`) and returned in E.164\n  (`+905321234567`).\n- **IDs** are UUIDs. The order number (`number`) is an increasing number within the company.\n- **Language:** `Accept-Language: tr` or `en` selects the language of error explanations (`detail`)\n  and CSV headers.\n- New fields and new enum values may be added to responses; ignore fields you do not recognise.\n\n## Pagination\n\nLists take `limit` and `offset` and return `{\"items\": [...], \"total\": N}`, where `total` is the number\nof records matching the filters. Example: `GET /me/orders?limit=100&offset=200`. By default orders are\nsorted newest first. The maximum page size of each endpoint is stated on its parameter (200 for orders).\n\n## Search and sorting\n\nThe order, charge, invoice and cash-on-delivery lists also take these common parameters:\n\n- `q`: free-text search (case-insensitive, partial match; at most 200 characters).\n- `minAmount` / `maxAmount`: amount range (both inclusive), e.g. `minAmount=100.00`.\n- `sort`: `field` sorts ascending, `-field` descending, e.g. `sort=-total`. The allowed fields are\n  listed in each endpoint's description; an unknown field returns **422**.\n\nExample: `GET /me/orders?q=kadikoy&minAmount=100&sort=-total&limit=50`.\n\n## Duplicate protection (Idempotency-Key)\n\n`POST /orders` and `POST /me/orders/{id}/cancel` accept an optional `Idempotency-Key` header (e.g. a\nUUID). If you retry with the same key after a network error or timeout, no second order is created:\n\n- The key is scoped to your customer account (all its API keys and users) and the operation, and is kept for **24 hours**.\n- Same key + same body: the first successful response is returned unchanged, with the\n  `Idempotent-Replayed: true` header.\n- Same key + different body: **409 `IDEMPOTENCY_MISMATCH`**.\n- A repeat that arrives while the first request is still being processed: **409\n  `IDEMPOTENCY_IN_PROGRESS`**; wait briefly and retry.\n- Only 2xx responses are stored; a request that failed can be retried with the same key.\n\nIn bulk orders (`POST /me/orders/batch`) a row is skipped if an order with the same reference number\nor parcel barcode already exists, so resending the same batch is safe.\n\n## Order flow\n\n- The **sender** is always the customer that owns the key (`sender.customerId` may be left empty).\n  If no district is given, your registered district is used.\n- The **recipient** and the **pickup point** are given either as a customer from your address book\n  (`customerId`, from `GET /me/customer` → `links`) or with a district (`districtId`) plus\n  name/phone/address.\n- The **paying party** (`payer`) must be you or a customer from your address book.\n- If no **payment method** is given: prepaid credit (wallet) for prepaid customers (deducted from the\n  balance), on account for subscribers, cash otherwise. If the prepaid balance is insufficient (and\n  you are not allowed a negative balance), the order is not created.\n- **Cash on delivery** (`codAmount`) is separate from the delivery fee: it is the price of the goods,\n  collected from the recipient on your behalf. If the company has not enabled it you get 422\n  `COD_DISABLED`.\n- An order can only be edited or cancelled before it is given to a courier (`on_table`,\n  `pending_approval`); after that you get 409 `CONFLICT`. When editing, send the `version` you read;\n  if the order changed in the meantime you get 409 `VERSION_CONFLICT`.\n\nStatuses: `pending_approval` (awaiting company approval) → `on_table` (waiting for a courier) →\n`assigned` (given to a courier) → `picked_up` (on the way) → `delivered`. Others: `return_leg`,\n`delivery_failed`, `returning`, `returned`, `at_hub`, `in_transfer`, `cancelled`.\n\n## Errors\n\nErrors are returned in [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) format as\n`application/problem+json`:\n\n```json\n{\n  \"type\": \"about:blank\",\n  \"title\": \"Unprocessable Entity\",\n  \"status\": 422,\n  \"code\": \"VALIDATION\",\n  \"detail\": \"Validation failed\",\n  \"errors\": [{\"field\": \"recipient.districtId\", \"message\": \"district not found\"}],\n  \"traceId\": \"4bf92f3577b34da6a3ce929d0e0e4736\"\n}\n```\n\nBase your decisions on `status` and `code`; `detail` is meant for people and may change. Include the\n`traceId` in support requests.\n\n| HTTP | `code` | When |\n|---|---|---|\n| 400 | `VALIDATION` | Malformed body or parameter (invalid JSON, wrong type) |\n| 401 | `UNAUTHORIZED` | Key missing, invalid, expired or revoked |\n| 403 | `FORBIDDEN` | This endpoint cannot be used with an API key, or you lack permission |\n| 403 | `AIDAT_PASSIVE`, `TENANT_SUSPENDED` | The courier company's account is restricted; contact the company |\n| 403 | `FEATURE_DISABLED` | The company has turned this feature off |\n| 404 | `NOT_FOUND` | The record does not exist or is not yours |\n| 409 | `CONFLICT` | The record is not in a state that allows this (e.g. order already given to a courier, parcel barcode in use, 5-webhook limit) |\n| 409 | `VERSION_CONFLICT` | The record changed after you read it; read it again |\n| 409 | `IDEMPOTENCY_MISMATCH`, `IDEMPOTENCY_IN_PROGRESS` | See Duplicate protection |\n| 409 | `COD_COLLECTED`, `COD_SETTLED` | Cash on delivery already collected / paid out to you; cannot be changed |\n| 422 | `VALIDATION` | A field value breaks a rule; details in `errors` |\n| 422 | `COD_DISABLED` | The company has not enabled cash on delivery |\n| 429 | `TOO_MANY_REQUESTS` | Rate limit exceeded; wait for `Retry-After` |\n| 500 | `INTERNAL` | Unexpected error; report it with the `traceId` |\n| 503 | `UNAVAILABLE` | Temporarily unavailable; try again shortly |\n\nThe list of codes is open: new codes may be added. Handle a code you do not recognise by its HTTP\nstatus. Retry 5xx and 429 with increasing delays; for `POST /orders`, do so with an\n`Idempotency-Key`.\n\n## Webhooks\n\nA webhook `POST`s order events to your URL as they happen. You can create up to **5 subscriptions**\nwith `POST /me/webhooks`; a subscription only receives events for orders you placed or pay for.\n\n**Events:** `order.created`, `order.approval_requested`, `order.approved`, `order.rejected`,\n`order.assigned`, `order.reassigned`, `order.returned_to_pool`, `order.picked_up`,\n`order.return_leg`, `order.delivered`, `order.delivery_reverted`, `order.delivery_failed`,\n`order.returning`, `order.returned`, `order.return_reverted`, `order.cancelled`, `order.restored`,\n`order.at_hub`, `order.hub_transfer`.\n\n**Request:**\n\n```http\nPOST /kurye/webhook HTTP/1.1\nContent-Type: application/json\nUser-Agent: KOS-Webhook/1\nX-KOS-Event: order.delivered\nX-KOS-Delivery: 0f6d1c9e-6a1b-4f0e-9c5a-2b7d8e9f0a12\nX-KOS-Signature: t=1804151340,v1=5d2c…\n\n{\n  \"id\": \"a3c1e7f0-2b4d-4c6e-8f10-1a2b3c4d5e6f\",\n  \"type\": \"order.delivered\",\n  \"occurredAt\": \"2027-03-04T11:02:20Z\",\n  \"data\": {\n    \"order\": {\n      \"id\": \"2c8e4a6b-9d1f-4b3c-a5e7-6f8a0b2c4d99\",\n      \"number\": 10482,\n      \"status\": \"delivered\",\n      \"createdAt\": \"2027-03-04T09:15:02Z\",\n      \"pickedUpAt\": \"2027-03-04T09:40:11Z\",\n      \"deliveredAt\": \"2027-03-04T11:02:20Z\",\n      \"receiverName\": \"Ayşe Yılmaz\",\n      \"cancelledAt\": null,\n      \"cancelReason\": \"\",\n      \"reference\": \"SIP-2027-00042\",\n      \"paymentMethod\": \"account\",\n      \"total\": \"180.00\",\n      \"currency\": \"TRY\",\n      \"stops\": [\n        {\"role\": \"sender\", \"name\": \"Örnek Çiçekçilik\", \"district\": \"Kadıköy\"},\n        {\"role\": \"recipient\", \"name\": \"Ayşe Yılmaz\", \"district\": \"Beşiktaş\"}\n      ],\n      \"courier\": {\"id\": \"9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a\", \"name\": \"Ali Kaya\"}\n    }\n  }\n}\n```\n\nThe body contains no personal data such as phone numbers; read them with `GET /me/orders/{id}` if\nyou need them. Timestamps that have not happened yet are `null`; `courier` is omitted when there is\nno courier.\n\n**Verifying the signature.** The header is `X-KOS-Signature: t=<unix seconds>,v1=<signature>`. The\nsignature is the HMAC-SHA256 of the text `<t>.<raw body>` (lowercase hex); the key is the secret\n(`whsec_…`) shown once when the subscription was created, **used as-is** (its UTF-8 bytes, not\ndecoded). To verify:\n\n1. Take the body as **raw bytes**, before parsing it as JSON.\n2. Reject the request if `t` differs from the current time by more than 5 minutes (replay protection).\n3. Compute the expected signature and compare it with `v1` in **constant time**.\n4. Answer 401 to a request that does not verify.\n\nCode samples are under the `POST /me/webhooks` operation. If the secret leaks, rotate it immediately\nwith `POST /me/webhooks/{id}/rotate-secret`.\n\n**Delivery and retries.**\n\n- Answer with **2xx** within 10 seconds; queue the work and do it afterwards.\n- Every non-2xx response (including 4xx) and every connection error is retried: **8 attempts** in\n  total with increasing delays (attempt⁴ seconds; about 1.5 hours).\n- If you answer **410 Gone**, that delivery is not retried again (the subscription stays enabled; to\n  stop entirely, disable or delete the subscription).\n- The same event can arrive more than once: `X-KOS-Delivery` is the same on every attempt of a\n  delivery; if you see a value you have already handled, answer 200 and skip it.\n- Events may arrive out of order: look at `occurredAt` and `data.order.status`.\n- The URL must be `http://` or `https://` (https is recommended), must not contain a user name or\n  password, and must be reachable from the internet.\n\n## Health checks\n\nTwo endpoints for your monitoring tools need no key and are served at the root, not under\n`/api/v1` (e.g. `https://client.courino.com/healthz`):\n\n- `GET /healthz` returns `204` with no body while the server is running.\n- `GET /readyz` also checks the database (at most 3 s): `200` and `{\"status\":\"ok\"}` when ready,\n  otherwise `503` and `{\"status\":\"unavailable\",\"failed\":{\"postgres\":\"unavailable\"}}`. A `503` is\n  temporary; retry a little later.\n\nA few checks per minute are enough.\n\n## More\n\n- **Bulk orders:** `POST /me/orders/batch` creates the rows in a background queue; poll\n  `GET /me/orders/imports/{id}` every few seconds until `status` is `done`.\n- **Excel/CSV file:** `POST /me/orders/imports` previews the file; check the rows, then create the\n  orders with `POST /me/orders/imports/{id}/confirm`.\n- **E-commerce:** follow orders from the stores you connected in the portal with\n  `GET /me/ecommerce/orders`; settle the ones awaiting a match with `resolve`, `retry` or `skip`.\n- **Tracking link:** `POST /me/orders/{id}/tracking-link` returns the address of a public tracking\n  page (no sign-in needed) that you can send to the recipient.\n- **Archive:** `GET /me/orders/export` returns CSV (UTF-8 with BOM, semicolon-separated; Excel opens\n  it directly). Up to 20,000 orders at once.\n- **Files:** this document can be downloaded as OpenAPI 3.0 from\n  [openapi.en.yaml](/api/v1/openapi.en.yaml) and [openapi.en.json](/api/v1/openapi.en.json) for use\n  with Postman, Insomnia or code generators.\n"},"servers":[{"description":"Courino API (the domain you are on)","url":"/api/v1"}],"security":[{"apiKey":[]}],"tags":[{"description":"District and delivery type options, price quotes and active discounts.","name":"Pricing and options"},{"description":"Creating orders (one by one or in bulk), listing, editing, cancelling, delivery photos and the CSV archive.","name":"Orders"},{"description":"Live courier tracking for an order and a tracking link to share with the recipient.","name":"Tracking"},{"description":"Signed notification subscriptions that push order events to your system as they happen.","name":"Webhooks"},{"description":"Your customer record, contacts and address book.","name":"Account"},{"description":"Prepaid credit (wallet) activity, order charges and issued invoices.","name":"Payments and invoices"},{"description":"Cash-on-delivery amounts collected from recipients on your behalf, and the payouts made to you.","name":"Cash on delivery"},{"description":"Orders from the stores and marketplaces you connected in the customer portal (WooCommerce, Shopify,\nTrendyol, Hepsiburada…). Adding a connection, changing store details and store authorization are only\ndone in the portal; with the API you monitor status, fix orders awaiting a match, retry or skip them.","name":"E-commerce"},{"description":"Health endpoints for your monitoring tools (uptime checks, load balancers). No API key is required and\nthey are not under `/api/v1`: they live at the root of the domain, e.g. `https://client.courino.com/healthz`.","name":"Health checks"}],"paths":{"/me/order-options":{"get":{"tags":["Pricing and options"],"summary":"Order options (districts and delivery types)","description":"Returns the `districtId` (district) and `deliveryTypeId` (delivery type) values to use in order and\nquote requests. Only active entries are listed; no pricing details are included. If the company has\nbusiness hours configured, they are returned in `businessHours`. The list changes rarely; caching it\nfor a day is fine.","operationId":"getOrderOptions","responses":{"200":{"content":{"application/json":{"example":{"businessHours":{"end":"19:00","openNow":true,"start":"08:30"},"deliveryTypes":[{"fullName":"Normal teslimat","id":"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66","isRoundTrip":false,"name":"Normal"},{"fullName":"Ekspres (60 dk)","id":"e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a77","isRoundTrip":false,"name":"Ekspres"}],"districts":[{"id":"3f1c2a4e-8b7d-4c21-9a55-0e6b1f2d3c41","name":"Kadıköy"},{"id":"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02","name":"Beşiktaş"},{"id":"c4d5e6f7-0a1b-4c2d-8e3f-9a0b1c2d3e43","name":"Ataşehir"}]},"schema":{"$ref":"#/components/schemas/OrderOptions"}}},"description":"Options"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/pricing/quote":{"post":{"tags":["Pricing and options"],"summary":"Calculates a price quote (does not create an order)","description":"Shows the price and its breakdown before you create the order. When the order is created the price\nis recalculated with the same rules and stored on the order unchanged. The sender is always the\ncustomer that owns the API key: `sender.customerId` may be left empty, and if `sender.districtId` is\nomitted your registered district is used. The pickup point and the recipient are given either as a\ncustomer from your address book (`customerId`) or as a district (`districtId`). The paying party\n(`payer`) must be you or a customer from your address book; for `payer: recipient`, for example,\ngive the recipient a `customerId`.","operationId":"quotePrice","requestBody":{"content":{"application/json":{"example":{"deliveryTypeId":"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66","payer":"sender","recipient":{"districtId":"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02"},"sender":{},"weightKg":"2.5"},"schema":{"$ref":"#/components/schemas/QuoteRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"algorithmVersion":"kos-1","calculatedTotal":"180.00","currencyCode":"TRY","currencyRate":"1","deliveryMultiplier":"1","expectedDeliveryMinutes":90,"fromRegion":2,"lines":{"base":"150.00","bridge":"0.00","extra":"0.00","manualAdjustmentNet":"0.00","manualAdjustmentVat":"0.00","serviceNet":"150.00","vat":"30.00","volume":"0.00","wait":"0.00","weight":"0.00"},"nightMultiplier":"1","tier":"subscriber","toRegion":3,"total":"180.00","usesWallet":false,"vatRate":"20","vatScope":"all"},"schema":{"$ref":"#/components/schemas/Quote"}}},"description":"Quote"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -s https://client.courino.com/api/v1/pricing/quote \\\n  -H \"Authorization: Bearer $KOS_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept-Language: tr\" \\\n  -d '{\n    \"sender\": {},\n    \"recipient\": {\"districtId\": \"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02\"},\n    \"deliveryTypeId\": \"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66\",\n    \"payer\": \"sender\",\n    \"weightKg\": \"2.5\"\n  }'\n"},{"label":"Node.js","lang":"JavaScript","source":"// Node.js 18+ (built-in fetch)\nconst BASE = \"https://client.courino.com/api/v1\";\nconst res = await fetch(`${BASE}/pricing/quote`, {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KOS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    sender: {},\n    recipient: { districtId: \"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02\" },\n    deliveryTypeId: \"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66\",\n    payer: \"sender\",\n    weightKg: \"2.5\", // decimals are strings\n  }),\n});\nif (!res.ok) throw new Error(`${res.status} ${(await res.json()).code}`);\nconst quote = await res.json();\nconsole.log(quote.total, quote.currencyCode); // \"180.00\" \"TRY\"\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests  # pip install requests\n\nBASE = \"https://client.courino.com/api/v1\"\ns = requests.Session()\ns.headers[\"Authorization\"] = \"Bearer \" + os.environ[\"KOS_API_KEY\"]\n\nr = s.post(f\"{BASE}/pricing/quote\", json={\n    \"sender\": {},\n    \"recipient\": {\"districtId\": \"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02\"},\n    \"deliveryTypeId\": \"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66\",\n    \"payer\": \"sender\",\n    \"weightKg\": \"2.5\",\n}, timeout=15)\nr.raise_for_status()\nquote = r.json()\nprint(quote[\"total\"], quote[\"currencyCode\"])\n"},{"label":"PHP","lang":"PHP","source":"<?php\n$base = 'https://client.courino.com/api/v1';\n$ch = curl_init(\"$base/pricing/quote\");\ncurl_setopt_array($ch, [\n    CURLOPT_POST => true,\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_TIMEOUT => 15,\n    CURLOPT_HTTPHEADER => [\n        'Authorization: Bearer ' . getenv('KOS_API_KEY'),\n        'Content-Type: application/json',\n    ],\n    CURLOPT_POSTFIELDS => json_encode([\n        'sender' => new stdClass(),\n        'recipient' => ['districtId' => '7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02'],\n        'deliveryTypeId' => 'b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66',\n        'payer' => 'sender',\n        'weightKg' => '2.5',\n    ]),\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);\n$quote = json_decode($body, true);\nif ($status !== 200) {\n    throw new RuntimeException(\"$status {$quote['code']}: {$quote['detail']}\");\n}\necho $quote['total'], ' ', $quote['currencyCode'], PHP_EOL;\n"},{"label":"C#","lang":"C#","source":"// .NET 6+\nusing System.Net.Http.Headers;\nusing System.Net.Http.Json;\nusing System.Text.Json;\n\nvar http = new HttpClient { BaseAddress = new Uri(\"https://client.courino.com/api/v1/\") };\nhttp.DefaultRequestHeaders.Authorization =\n    new AuthenticationHeaderValue(\"Bearer\", Environment.GetEnvironmentVariable(\"KOS_API_KEY\"));\n\nvar res = await http.PostAsJsonAsync(\"pricing/quote\", new {\n    sender = new { },\n    recipient = new { districtId = \"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02\" },\n    deliveryTypeId = \"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66\",\n    payer = \"sender\",\n    weightKg = \"2.5\",\n});\nvar quote = await res.Content.ReadFromJsonAsync<JsonElement>();\nif (!res.IsSuccessStatusCode)\n    throw new Exception($\"{(int)res.StatusCode} {quote.GetProperty(\"code\")}\");\nConsole.WriteLine($\"{quote.GetProperty(\"total\")} {quote.GetProperty(\"currencyCode\")}\");\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"bytes\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\tbody, _ := json.Marshal(map[string]any{\n\t\t\"sender\":         map[string]any{},\n\t\t\"recipient\":      map[string]any{\"districtId\": \"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02\"},\n\t\t\"deliveryTypeId\": \"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66\",\n\t\t\"payer\":          \"sender\",\n\t\t\"weightKg\":       \"2.5\",\n\t})\n\treq, _ := http.NewRequest(http.MethodPost, \"https://client.courino.com/api/v1/pricing/quote\", bytes.NewReader(body))\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KOS_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tvar quote struct {\n\t\tTotal        string `json:\"total\"`\n\t\tCurrencyCode string `json:\"currencyCode\"`\n\t\tCode         string `json:\"code\"`\n\t}\n\t_ = json.NewDecoder(res.Body).Decode(&quote)\n\tif res.StatusCode != http.StatusOK {\n\t\tpanic(fmt.Sprintf(\"%d %s\", res.StatusCode, quote.Code))\n\t}\n\tfmt.Println(quote.Total, quote.CurrencyCode)\n}\n"}]}},"/me/discounts":{"get":{"tags":["Pricing and options"],"summary":"My active and upcoming discounts","description":"Cancelled, expired and used-up discounts are not returned. A matching discount is applied\nautomatically when the order is created and appears as `discount` in the quote response.","operationId":"listMyDiscounts","responses":{"200":{"content":{"application/json":{"example":[{"campaignId":"1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d55","createdAt":"2027-02-01T09:00:00Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","customerName":"Örnek Çiçekçilik","id":"0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c44","kind":"percent","label":"Sevgililer Günü indirimi","maxUses":20,"source":"campaign","status":"active","used":3,"validFrom":"2027-02-10","validUntil":"2027-02-15","value":"10"}],"schema":{"items":{"$ref":"#/components/schemas/CustomerDiscount"},"type":"array"}}},"description":"Discounts"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/orders":{"post":{"tags":["Orders"],"summary":"Creates an order","description":"The price is calculated with the same rules as the quote and stored on the order unchanged. The\nsender is the customer that owns the API key. If the payment method is prepaid credit (wallet), the\namount is deducted from the balance in the same transaction; if the balance is insufficient (and you\nare not allowed a negative balance), the order is not created.\n\nTo retry safely after a network error, send an `Idempotency-Key` header: a repeated request with the\nsame key and the same body does not create a new order and returns the first response with the\n`Idempotent-Replayed: true` header.","operationId":"createOrder","parameters":[{"$ref":"#/components/parameters/OrderIdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"deliveryTypeId":"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66","notes":"Kapıda arayın.","parcels":[{"barcode":"PKT-00042-1","description":"Çiçek buketi"}],"payer":"sender","paymentMethod":"account","recipient":{"address":"Sinanpaşa Mah. Ihlamurdere Cad. No:5 D:3, Beşiktaş","districtId":"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02","name":"Ayşe Yılmaz","phone":"0532 123 45 67"},"reference":"SIP-2027-00042","sender":{"address":"Caferağa Mah. Moda Cad. No:12, Kadıköy","phone":"0216 555 12 34"},"weightKg":"2.5"},"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"branchId":"8e9f0a1b-2c3d-4e4f-9a5b-6c7d8e9f0a11","createdAt":"2027-03-04T09:15:02Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","deliveryTypeId":"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66","id":"2c8e4a6b-9d1f-4b3c-a5e7-6f8a0b2c4d99","isRoundTrip":false,"notes":"Kapıda arayın.","number":10482,"parcels":[{"barcode":"PKT-00042-1","description":"Çiçek buketi","external":true,"id":"4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f88","seq":1}],"payer":"sender","payerCustomerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","paymentMethod":"account","plannedPickupAt":"2027-03-04T09:15:02Z","price":{"algorithmVersion":"kos-1","calculatedTotal":"180.00","currencyCode":"TRY","currencyRate":"1","deliveryMultiplier":"1","expectedDeliveryMinutes":90,"fromRegion":2,"lines":{"base":"150.00","bridge":"0.00","extra":"0.00","manualAdjustmentNet":"0.00","manualAdjustmentVat":"0.00","serviceNet":"150.00","vat":"30.00","volume":"0.00","wait":"0.00","weight":"0.00"},"nightMultiplier":"1","tier":"subscriber","toRegion":3,"total":"180.00","usesWallet":false,"vatRate":"20","vatScope":"all"},"reference":"SIP-2027-00042","source":"api","status":"on_table","stops":[{"address":"Caferağa Mah. Moda Cad. No:12, Kadıköy","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","districtId":"3f1c2a4e-8b7d-4c21-9a55-0e6b1f2d3c41","districtName":"Kadıköy","name":"Örnek Çiçekçilik","phone":"+902165551234","regionNo":2,"role":"sender"},{"address":"Sinanpaşa Mah. Ihlamurdere Cad. No:5 D:3, Beşiktaş","districtId":"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02","districtName":"Beşiktaş","name":"Ayşe Yılmaz","phone":"+905321234567","regionNo":3,"role":"recipient"}],"version":1,"volumeM3":"0","waitMinutes":"0","weightKg":"2.5"},"schema":{"$ref":"#/components/schemas/Order"}}},"description":"Order created","headers":{"Idempotent-Replayed":{"description":"This response is a replay of the response previously given for the same Idempotency-Key (no new order was created).","schema":{"enum":["true"],"type":"string"}}}},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"# 1) Districts and delivery types (cache for a day)\ncurl -s https://client.courino.com/api/v1/me/order-options \\\n  -H \"Authorization: Bearer $KOS_API_KEY\"\n\n# 2) Create the order. The same Idempotency-Key makes a retry safe.\ncurl -s https://client.courino.com/api/v1/orders \\\n  -H \"Authorization: Bearer $KOS_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $(uuidgen)\" \\\n  -d '{\n    \"sender\": {\"phone\": \"0216 555 12 34\", \"address\": \"Moda Cad. No:12, Kadıköy\"},\n    \"recipient\": {\n      \"districtId\": \"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02\",\n      \"name\": \"Ayşe Yılmaz\",\n      \"phone\": \"0532 123 45 67\",\n      \"address\": \"Ihlamurdere Cad. No:5 D:3, Beşiktaş\"\n    },\n    \"deliveryTypeId\": \"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66\",\n    \"payer\": \"sender\",\n    \"reference\": \"SIP-2027-00042\",\n    \"weightKg\": \"2.5\"\n  }'\n"},{"label":"Node.js","lang":"JavaScript","source":"// Node.js 18+ (built-in fetch)\nimport { randomUUID } from \"node:crypto\";\n\nconst BASE = \"https://client.courino.com/api/v1\";\nconst headers = {\n  Authorization: `Bearer ${process.env.KOS_API_KEY}`,\n  \"Content-Type\": \"application/json\",\n};\n\nasync function call(method, path, body, extra = {}) {\n  const res = await fetch(BASE + path, {\n    method, headers: { ...headers, ...extra },\n    body: body && JSON.stringify(body),\n  });\n  const data = await res.json();\n  if (!res.ok) throw Object.assign(new Error(data.detail), { status: res.status, code: data.code });\n  return data;\n}\n\nconst order = {\n  sender: { phone: \"0216 555 12 34\", address: \"Moda Cad. No:12, Kadıköy\" },\n  recipient: {\n    districtId: \"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02\",\n    name: \"Ayşe Yılmaz\", phone: \"0532 123 45 67\",\n    address: \"Ihlamurdere Cad. No:5 D:3, Beşiktaş\",\n  },\n  deliveryTypeId: \"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66\",\n  payer: \"sender\",\n  reference: \"SIP-2027-00042\",\n  weightKg: \"2.5\",\n};\n\n// 1) Price quote (the same rules are applied when the order is created)\nconst quote = await call(\"POST\", \"/pricing/quote\", {\n  sender: {}, recipient: { districtId: order.recipient.districtId },\n  deliveryTypeId: order.deliveryTypeId, payer: order.payer, weightKg: order.weightKg,\n});\nconsole.log(\"price\", quote.total);\n\n// 2) Create; keep the key and reuse it if you retry after a network error\nconst key = randomUUID();\nconst created = await call(\"POST\", \"/orders\", order, { \"Idempotency-Key\": key });\nconsole.log(\"order\", created.number, created.status);\n"},{"label":"Python","lang":"Python","source":"import os\nimport uuid\nimport requests  # pip install requests\n\nBASE = \"https://client.courino.com/api/v1\"\ns = requests.Session()\ns.headers[\"Authorization\"] = \"Bearer \" + os.environ[\"KOS_API_KEY\"]\n\norder = {\n    \"sender\": {\"phone\": \"0216 555 12 34\", \"address\": \"Moda Cad. No:12, Kadıköy\"},\n    \"recipient\": {\n        \"districtId\": \"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02\",\n        \"name\": \"Ayşe Yılmaz\",\n        \"phone\": \"0532 123 45 67\",\n        \"address\": \"Ihlamurdere Cad. No:5 D:3, Beşiktaş\",\n    },\n    \"deliveryTypeId\": \"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66\",\n    \"payer\": \"sender\",\n    \"reference\": \"SIP-2027-00042\",\n    \"weightKg\": \"2.5\",\n}\n\n# 1) Price quote\nq = s.post(f\"{BASE}/pricing/quote\", json={\n    \"sender\": {},\n    \"recipient\": {\"districtId\": order[\"recipient\"][\"districtId\"]},\n    \"deliveryTypeId\": order[\"deliveryTypeId\"],\n    \"payer\": order[\"payer\"],\n    \"weightKg\": order[\"weightKg\"],\n}, timeout=15)\nq.raise_for_status()\nprint(\"price\", q.json()[\"total\"])\n\n# 2) Create, retrying network errors with the same Idempotency-Key\nkey = str(uuid.uuid4())\nfor attempt in range(3):\n    try:\n        r = s.post(f\"{BASE}/orders\", json=order,\n                   headers={\"Idempotency-Key\": key}, timeout=30)\n        break\n    except requests.ConnectionError:\n        if attempt == 2:\n            raise\nif r.status_code != 201:\n    p = r.json()\n    raise RuntimeError(f\"{r.status_code} {p['code']}: {p.get('detail')}\")\ncreated = r.json()\nprint(\"order\", created[\"number\"], created[\"status\"])\n"},{"label":"PHP","lang":"PHP","source":"<?php\nconst BASE = 'https://client.courino.com/api/v1';\n\nfunction kos(string $method, string $path, ?array $body = null, array $headers = []): array {\n    $ch = curl_init(BASE . $path);\n    curl_setopt_array($ch, [\n        CURLOPT_CUSTOMREQUEST => $method,\n        CURLOPT_RETURNTRANSFER => true,\n        CURLOPT_TIMEOUT => 30,\n        CURLOPT_HTTPHEADER => array_merge([\n            'Authorization: Bearer ' . getenv('KOS_API_KEY'),\n            'Content-Type: application/json',\n        ], $headers),\n        CURLOPT_POSTFIELDS => $body === null ? null : json_encode($body),\n    ]);\n    $data = json_decode(curl_exec($ch), true);\n    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);\n    if ($status >= 400) {\n        throw new RuntimeException(\"$status {$data['code']}: {$data['detail']}\");\n    }\n    return $data;\n}\n\n$order = [\n    'sender' => ['phone' => '0216 555 12 34', 'address' => 'Moda Cad. No:12, Kadıköy'],\n    'recipient' => [\n        'districtId' => '7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02',\n        'name' => 'Ayşe Yılmaz',\n        'phone' => '0532 123 45 67',\n        'address' => 'Ihlamurdere Cad. No:5 D:3, Beşiktaş',\n    ],\n    'deliveryTypeId' => 'b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66',\n    'payer' => 'sender',\n    'reference' => 'SIP-2027-00042',\n    'weightKg' => '2.5',\n];\n\n// 1) Price quote\n$quote = kos('POST', '/pricing/quote', [\n    'sender' => new stdClass(),\n    'recipient' => ['districtId' => $order['recipient']['districtId']],\n    'deliveryTypeId' => $order['deliveryTypeId'],\n    'payer' => $order['payer'],\n    'weightKg' => $order['weightKg'],\n]);\necho 'price ', $quote['total'], PHP_EOL;\n\n// 2) Create (reuse the same key when retrying)\n$key = bin2hex(random_bytes(16));\n$created = kos('POST', '/orders', $order, [\"Idempotency-Key: $key\"]);\necho 'order ', $created['number'], ' ', $created['status'], PHP_EOL;\n"},{"label":"C#","lang":"C#","source":"// .NET 6+\nusing System.Net.Http.Headers;\nusing System.Net.Http.Json;\nusing System.Text.Json;\n\nvar http = new HttpClient { BaseAddress = new Uri(\"https://client.courino.com/api/v1/\") };\nhttp.DefaultRequestHeaders.Authorization =\n    new AuthenticationHeaderValue(\"Bearer\", Environment.GetEnvironmentVariable(\"KOS_API_KEY\"));\n\nvar order = new {\n    sender = new { phone = \"0216 555 12 34\", address = \"Moda Cad. No:12, Kadıköy\" },\n    recipient = new {\n        districtId = \"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02\",\n        name = \"Ayşe Yılmaz\", phone = \"0532 123 45 67\",\n        address = \"Ihlamurdere Cad. No:5 D:3, Beşiktaş\",\n    },\n    deliveryTypeId = \"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66\",\n    payer = \"sender\",\n    reference = \"SIP-2027-00042\",\n    weightKg = \"2.5\",\n};\n\n// 1) Price quote\nvar q = await http.PostAsJsonAsync(\"pricing/quote\", new {\n    sender = new { }, recipient = new { order.recipient.districtId },\n    order.deliveryTypeId, order.payer, order.weightKg,\n});\nvar quote = await q.Content.ReadFromJsonAsync<JsonElement>();\nConsole.WriteLine($\"price {quote.GetProperty(\"total\")}\");\n\n// 2) Create (reuse the same key when retrying)\nvar req = new HttpRequestMessage(HttpMethod.Post, \"orders\") { Content = JsonContent.Create(order) };\nreq.Headers.Add(\"Idempotency-Key\", Guid.NewGuid().ToString());\nvar res = await http.SendAsync(req);\nvar created = await res.Content.ReadFromJsonAsync<JsonElement>();\nif (!res.IsSuccessStatusCode)\n    throw new Exception($\"{(int)res.StatusCode} {created.GetProperty(\"code\")}\");\nConsole.WriteLine($\"order {created.GetProperty(\"number\")} {created.GetProperty(\"status\")}\");\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"bytes\"\n\t\"crypto/rand\"\n\t\"encoding/hex\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"net/http\"\n\t\"os\"\n)\n\nconst base = \"https://client.courino.com/api/v1\"\n\nfunc call(method, path string, in, out any, hdr map[string]string) error {\n\tb, _ := json.Marshal(in)\n\treq, _ := http.NewRequest(method, base+path, bytes.NewReader(b))\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KOS_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tfor k, v := range hdr {\n\t\treq.Header.Set(k, v)\n\t}\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\treturn err\n\t}\n\tdefer res.Body.Close()\n\tif res.StatusCode >= 400 {\n\t\tvar p struct{ Code, Detail string }\n\t\t_ = json.NewDecoder(res.Body).Decode(&p)\n\t\treturn fmt.Errorf(\"%d %s: %s\", res.StatusCode, p.Code, p.Detail)\n\t}\n\treturn json.NewDecoder(res.Body).Decode(out)\n}\n\nfunc main() {\n\trecipient := map[string]any{\n\t\t\"districtId\": \"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02\",\n\t\t\"name\":       \"Ayşe Yılmaz\",\n\t\t\"phone\":      \"0532 123 45 67\",\n\t\t\"address\":    \"Ihlamurdere Cad. No:5 D:3, Beşiktaş\",\n\t}\n\torder := map[string]any{\n\t\t\"sender\":         map[string]any{\"phone\": \"0216 555 12 34\", \"address\": \"Moda Cad. No:12, Kadıköy\"},\n\t\t\"recipient\":      recipient,\n\t\t\"deliveryTypeId\": \"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66\",\n\t\t\"payer\":          \"sender\",\n\t\t\"reference\":      \"SIP-2027-00042\",\n\t\t\"weightKg\":       \"2.5\",\n\t}\n\n\t// 1) Price quote\n\tvar quote struct{ Total string }\n\terr := call(http.MethodPost, \"/pricing/quote\", map[string]any{\n\t\t\"sender\":         map[string]any{},\n\t\t\"recipient\":      map[string]any{\"districtId\": recipient[\"districtId\"]},\n\t\t\"deliveryTypeId\": order[\"deliveryTypeId\"],\n\t\t\"payer\":          order[\"payer\"],\n\t\t\"weightKg\":       order[\"weightKg\"],\n\t}, &quote, nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Println(\"price\", quote.Total)\n\n\t// 2) Create (reuse the same key when retrying)\n\tk := make([]byte, 16)\n\t_, _ = rand.Read(k)\n\tvar created struct {\n\t\tNumber int64\n\t\tStatus string\n\t}\n\tif err := call(http.MethodPost, \"/orders\", order, &created,\n\t\tmap[string]string{\"Idempotency-Key\": hex.EncodeToString(k)}); err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Println(\"order\", created.Number, created.Status)\n}\n"}]}},"/me/orders/batch":{"post":{"tags":["Orders"],"summary":"Creates orders in bulk (up to 1000 rows)","description":"The same validation and duplicate rules as the Excel/CSV upload apply. The district is given with\n`areaId` or by name with `area` (+ `district`/`province`), the delivery type with `deliveryTypeId`\nor by name with `deliveryType`. `dryRun=true` only validates (preview; no orders are created).\nOtherwise, if there are valid rows, the orders are created in a background queue; follow progress\nand per-row results with `GET /me/orders/imports/{id}`. A row is skipped if an order with the same\nreference number or parcel barcode already exists, so resending the same batch is safe.","operationId":"createMyOrderBatch","requestBody":{"content":{"application/json":{"example":{"dryRun":false,"rows":[{"address":"Sinanpaşa Mah. Ihlamurdere Cad. No:5 D:3","areaId":"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02","deliveryTypeId":"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66","parcels":1,"recipientName":"Ayşe Yılmaz","recipientPhone":"0532 123 45 67","reference":"SIP-2027-00043","weightKg":"1.2"},{"address":"Atatürk Mah. Ertuğrul Gazi Sok. No:8","area":"Atatürk","barcodes":["PKT-00044-1","PKT-00044-2"],"deliveryType":"Ekspres","district":"Ataşehir","parcels":2,"province":"İstanbul","recipientName":"Mehmet Demir","recipientPhone":"0533 987 65 43","reference":"SIP-2027-00044"}]},"schema":{"properties":{"dryRun":{"default":false,"description":"If true, rows are only validated and no orders are created.","type":"boolean"},"rows":{"description":"Order rows (1–1000).","items":{"$ref":"#/components/schemas/OrderBatchRow"},"maxItems":1000,"minItems":1,"type":"array"}},"required":["rows"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"createdAt":"2027-03-04T09:20:00Z","createdRows":0,"customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","customerName":"Örnek Çiçekçilik","error":"","failedRows":0,"filename":"api","id":"6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c22","skippedRows":0,"source":"api","status":"queued","totalRows":2,"validRows":2},"schema":{"$ref":"#/components/schemas/OrderImport"}}},"description":"Upload record (preview or queued)"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/orders/imports/{id}":{"get":{"tags":["Orders"],"summary":"Status and row results of a bulk upload","description":"Poll every few seconds until `status` is `done`. The per-row status (`created`, `skipped`, `failed`,\n`invalid`), the created order number and the error reason are in `rows`.","operationId":"getMyOrderImport","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"content":{"application/json":{"example":{"createdAt":"2027-03-04T09:20:00Z","createdRows":1,"customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","customerName":"Örnek Çiçekçilik","error":"","failedRows":0,"filename":"api","finishedAt":"2027-03-04T09:20:03Z","id":"6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c22","rows":[{"address":"Sinanpaşa Mah. Ihlamurdere Cad. No:5 D:3","area":"Beşiktaş","areaId":"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02","barcodes":[],"deliveryTypeId":"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66","deliveryTypeName":"Normal","issues":[],"message":"","no":1,"notes":"","orderId":"3d9f5b7c-0e2a-4c4d-b6f8-7a9b1c3d5e00","orderNumber":10483,"parcels":1,"recipientName":"Ayşe Yılmaz","recipientPhone":"+905321234567","reference":"SIP-2027-00043","status":"created","weightKg":"1.2"},{"address":"Atatürk Mah. Ertuğrul Gazi Sok. No:8","area":"Atatürk","areaId":"c4d5e6f7-0a1b-4c2d-8e3f-9a0b1c2d3e43","barcodes":["PKT-00044-1","PKT-00044-2"],"deliveryTypeId":"e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a77","deliveryTypeName":"Ekspres","district":"Ataşehir","duplicateOrderNumber":10470,"issues":[],"message":"Aynı referans numarasıyla sipariş var","no":2,"notes":"","parcels":2,"province":"İstanbul","recipientName":"Mehmet Demir","recipientPhone":"+905339876543","reference":"SIP-2027-00044","status":"skipped","weightKg":""}],"skippedRows":1,"source":"api","startedAt":"2027-03-04T09:20:01Z","status":"done","totalRows":2,"validRows":2},"schema":{"$ref":"#/components/schemas/OrderImport"}}},"description":"Upload"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]},"delete":{"tags":["Orders"],"summary":"Discards an upload in preview","description":"A confirmed (queued or finished) upload cannot be undone; cancel the created orders one by one.","operationId":"discardMyOrderImport","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"204":{"description":"Discarded"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/orders/imports":{"get":{"tags":["Orders"],"summary":"My bulk uploads (newest first)","description":"Row details are not included; read a single upload for them.","operationId":"listMyOrderImports","parameters":[{"description":"Maximum number of records to return","example":20,"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":[{"createdAt":"2027-03-04T09:20:00Z","createdRows":0,"customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","customerName":"Örnek Çiçekçilik","error":"","failedRows":0,"filename":"api","id":"6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c22","skippedRows":0,"source":"api","status":"queued","totalRows":2,"validRows":2}],"schema":{"items":{"$ref":"#/components/schemas/OrderImport"},"type":"array"}}},"description":"Uploads"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]},"post":{"tags":["Orders"],"summary":"Uploads and previews an Excel/CSV bulk shipment file (no orders are created)","description":"The file (.xlsx or .csv; at most 5 MB, 1000 rows) is parsed, the rows are validated (recipient name,\nphone, province/district/area, address, delivery type, parcel count, barcode, reference no) and saved\nas a preview. Invalid rows are returned in `issues`; rows that clash with an existing reference no /\nbarcode are flagged with `duplicateOrderNumber` and skipped on import. Orders are only created in the\nqueue after `POST /me/orders/imports/{id}/confirm`. To send JSON instead of a file, use\n`POST /me/orders/batch`.","operationId":"uploadMyOrderImport","requestBody":{"content":{"multipart/form-data":{"example":{"file":"siparisler.xlsx"},"schema":{"properties":{"file":{"description":".xlsx or .csv; at most 5 MB","format":"binary","type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"createdAt":"2027-03-04T08:50:00Z","createdRows":0,"customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","customerName":"Örnek Çiçekçilik","error":"","failedRows":0,"filename":"siparisler.xlsx","id":"8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d33","skippedRows":0,"source":"customer","status":"preview","totalRows":40,"validRows":38},"schema":{"$ref":"#/components/schemas/OrderImport"}}},"description":"Preview"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/orders":{"get":{"tags":["Orders"],"summary":"My orders (placed or paid by me)","description":"By default the newest orders come first. Filters can be combined; `total` is the number of records\nmatching the filters. Paginate with `limit`/`offset`.\n\n- `q`: searches recipient/sender name, phone, address, reference and note.\n- `minAmount`/`maxAmount`: order total range (VAT included).\n- `sort`: `createdAt` (default, descending), `number`, `total`, `status`, `deliveredAt`, `plannedPickupAt`;\n  prefix with `-` for descending (e.g. `-total`).","operationId":"listMyOrders","parameters":[{"description":"One or more statuses, comma-separated (e.g. `assigned,picked_up`)","example":["assigned","picked_up"],"explode":false,"in":"query","name":"status","schema":{"items":{"$ref":"#/components/schemas/OrderStatus"},"type":"array"},"style":"form"},{"description":"Order number","in":"query","name":"number","schema":{"format":"int64","type":"integer"}},{"description":"Your reference number (case-insensitive exact match)","in":"query","name":"reference","schema":{"maxLength":100,"type":"string"}},{"description":"Parcel barcode (case-insensitive exact match)","in":"query","name":"barcode","schema":{"maxLength":40,"type":"string"}},{"description":"Created at or after","example":"2027-03-01T00:00:00+03:00","in":"query","name":"from","schema":{"format":"date-time","type":"string"}},{"description":"Created before (exclusive)","example":"2027-04-01T00:00:00+03:00","in":"query","name":"to","schema":{"format":"date-time","type":"string"}},{"description":"Planned pickup at or after","in":"query","name":"plannedFrom","schema":{"format":"date-time","type":"string"}},{"description":"Planned pickup before (exclusive)","in":"query","name":"plannedTo","schema":{"format":"date-time","type":"string"}},{"description":"Sender or pickup point district","in":"query","name":"fromDistrictId","schema":{"format":"uuid","type":"string"}},{"description":"Recipient district","in":"query","name":"toDistrictId","schema":{"format":"uuid","type":"string"}},{"description":"Delivery type","in":"query","name":"deliveryTypeId","schema":{"format":"uuid","type":"string"}},{"description":"Payment method","in":"query","name":"paymentMethod","schema":{"$ref":"#/components/schemas/PaymentMethod"}},{"description":"Page size","example":50,"in":"query","name":"limit","schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},{"description":"Number of records to skip","in":"query","name":"offset","schema":{"default":0,"minimum":0,"type":"integer"}},{"$ref":"#/components/parameters/ListQ"},{"$ref":"#/components/parameters/MinAmount"},{"$ref":"#/components/parameters/MaxAmount"},{"$ref":"#/components/parameters/ListSort"}],"responses":{"200":{"content":{"application/json":{"example":{"items":[{"branchId":"8e9f0a1b-2c3d-4e4f-9a5b-6c7d8e9f0a11","createdAt":"2027-03-04T09:15:02Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","deliveryTypeId":"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66","id":"2c8e4a6b-9d1f-4b3c-a5e7-6f8a0b2c4d99","isRoundTrip":false,"notes":"Kapıda arayın.","number":10482,"parcels":[{"barcode":"PKT-00042-1","description":"Çiçek buketi","external":true,"id":"4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f88","seq":1}],"payer":"sender","payerCustomerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","paymentMethod":"account","plannedPickupAt":"2027-03-04T09:15:02Z","price":{"algorithmVersion":"kos-1","calculatedTotal":"180.00","currencyCode":"TRY","currencyRate":"1","deliveryMultiplier":"1","expectedDeliveryMinutes":90,"fromRegion":2,"lines":{"base":"150.00","bridge":"0.00","extra":"0.00","manualAdjustmentNet":"0.00","manualAdjustmentVat":"0.00","serviceNet":"150.00","vat":"30.00","volume":"0.00","wait":"0.00","weight":"0.00"},"nightMultiplier":"1","tier":"subscriber","toRegion":3,"total":"180.00","usesWallet":false,"vatRate":"20","vatScope":"all"},"reference":"SIP-2027-00042","source":"api","status":"on_table","stops":[{"address":"Caferağa Mah. Moda Cad. No:12, Kadıköy","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","districtId":"3f1c2a4e-8b7d-4c21-9a55-0e6b1f2d3c41","districtName":"Kadıköy","name":"Örnek Çiçekçilik","phone":"+902165551234","regionNo":2,"role":"sender"},{"address":"Sinanpaşa Mah. Ihlamurdere Cad. No:5 D:3, Beşiktaş","districtId":"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02","districtName":"Beşiktaş","name":"Ayşe Yılmaz","phone":"+905321234567","regionNo":3,"role":"recipient"}],"version":1,"volumeM3":"0","waitMinutes":"0","weightKg":"2.5"}],"total":1},"schema":{"$ref":"#/components/schemas/OrderPage"}}},"description":"Orders"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/orders/{id}":{"get":{"tags":["Orders"],"summary":"Reads an order","description":"Returns an order you placed or pay for; any other order returns 404.","operationId":"getMyOrder","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"content":{"application/json":{"example":{"branchId":"8e9f0a1b-2c3d-4e4f-9a5b-6c7d8e9f0a11","createdAt":"2027-03-04T09:15:02Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","deliveryTypeId":"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66","id":"2c8e4a6b-9d1f-4b3c-a5e7-6f8a0b2c4d99","isRoundTrip":false,"notes":"Kapıda arayın.","number":10482,"parcels":[{"barcode":"PKT-00042-1","description":"Çiçek buketi","external":true,"id":"4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f88","seq":1}],"payer":"sender","payerCustomerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","paymentMethod":"account","plannedPickupAt":"2027-03-04T09:15:02Z","price":{"algorithmVersion":"kos-1","calculatedTotal":"180.00","currencyCode":"TRY","currencyRate":"1","deliveryMultiplier":"1","expectedDeliveryMinutes":90,"fromRegion":2,"lines":{"base":"150.00","bridge":"0.00","extra":"0.00","manualAdjustmentNet":"0.00","manualAdjustmentVat":"0.00","serviceNet":"150.00","vat":"30.00","volume":"0.00","wait":"0.00","weight":"0.00"},"nightMultiplier":"1","tier":"subscriber","toRegion":3,"total":"180.00","usesWallet":false,"vatRate":"20","vatScope":"all"},"reference":"SIP-2027-00042","source":"api","status":"on_table","stops":[{"address":"Caferağa Mah. Moda Cad. No:12, Kadıköy","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","districtId":"3f1c2a4e-8b7d-4c21-9a55-0e6b1f2d3c41","districtName":"Kadıköy","name":"Örnek Çiçekçilik","phone":"+902165551234","regionNo":2,"role":"sender"},{"address":"Sinanpaşa Mah. Ihlamurdere Cad. No:5 D:3, Beşiktaş","districtId":"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02","districtName":"Beşiktaş","name":"Ayşe Yılmaz","phone":"+905321234567","regionNo":3,"role":"recipient"}],"version":1,"volumeM3":"0","waitMinutes":"0","weightKg":"2.5"},"schema":{"$ref":"#/components/schemas/Order"}}},"description":"Order"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]},"put":{"tags":["Orders"],"summary":"Edits my order before it is given to a courier","description":"Only orders you created whose status is `on_table` or `pending_approval` can be edited; once the\norder has been given to a courier you get 409 `CONFLICT`. Send the complete order (`order`) and the\n`version` you read; if the order changed in the meantime you get 409 `VERSION_CONFLICT` — read the\norder again and retry. The price is recalculated.","operationId":"updateMyOrder","parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"content":{"application/json":{"example":{"order":{"deliveryTypeId":"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66","notes":"Kapıda arayın.","parcels":[{"barcode":"PKT-00042-1","description":"Çiçek buketi"}],"payer":"sender","paymentMethod":"account","recipient":{"address":"Sinanpaşa Mah. Ihlamurdere Cad. No:5 D:3, Beşiktaş","districtId":"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02","name":"Ayşe Yılmaz","phone":"0532 123 45 67"},"reference":"SIP-2027-00042","sender":{"address":"Caferağa Mah. Moda Cad. No:12, Kadıköy","phone":"0216 555 12 34"},"weightKg":"2.5"},"version":1},"schema":{"$ref":"#/components/schemas/UpdateOrderRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"branchId":"8e9f0a1b-2c3d-4e4f-9a5b-6c7d8e9f0a11","createdAt":"2027-03-04T09:15:02Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","deliveryTypeId":"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66","id":"2c8e4a6b-9d1f-4b3c-a5e7-6f8a0b2c4d99","isRoundTrip":false,"notes":"Kapıda arayın.","number":10482,"parcels":[{"barcode":"PKT-00042-1","description":"Çiçek buketi","external":true,"id":"4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f88","seq":1}],"payer":"sender","payerCustomerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","paymentMethod":"account","plannedPickupAt":"2027-03-04T09:15:02Z","price":{"algorithmVersion":"kos-1","calculatedTotal":"180.00","currencyCode":"TRY","currencyRate":"1","deliveryMultiplier":"1","expectedDeliveryMinutes":90,"fromRegion":2,"lines":{"base":"150.00","bridge":"0.00","extra":"0.00","manualAdjustmentNet":"0.00","manualAdjustmentVat":"0.00","serviceNet":"150.00","vat":"30.00","volume":"0.00","wait":"0.00","weight":"0.00"},"nightMultiplier":"1","tier":"subscriber","toRegion":3,"total":"180.00","usesWallet":false,"vatRate":"20","vatScope":"all"},"reference":"SIP-2027-00042","source":"api","status":"on_table","stops":[{"address":"Caferağa Mah. Moda Cad. No:12, Kadıköy","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","districtId":"3f1c2a4e-8b7d-4c21-9a55-0e6b1f2d3c41","districtName":"Kadıköy","name":"Örnek Çiçekçilik","phone":"+902165551234","regionNo":2,"role":"sender"},{"address":"Sinanpaşa Mah. Ihlamurdere Cad. No:5 D:3, Beşiktaş","districtId":"7a2e9c10-4d3b-4f8a-b1c2-5e6f7a8b9c02","districtName":"Beşiktaş","name":"Ayşe Yılmaz","phone":"+905321234567","regionNo":3,"role":"recipient"}],"version":1,"volumeM3":"0","waitMinutes":"0","weightKg":"2.5"},"schema":{"$ref":"#/components/schemas/Order"}}},"description":"Updated order"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/orders/{id}/cancel":{"post":{"tags":["Orders"],"summary":"Cancels my order before it is given to a courier","description":"Only orders with status `on_table` or `pending_approval` can be cancelled; once the order has been\ngiven to a courier you get 409 `CONFLICT` (contact the company). If it was paid with prepaid credit,\nthe amount is refunded to your balance. Safe to retry with `Idempotency-Key`.","operationId":"cancelMyOrder","parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/OrderIdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"reason":"Alıcı siparişten vazgeçti"},"schema":{"$ref":"#/components/schemas/CancelRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"branchId":"8e9f0a1b-2c3d-4e4f-9a5b-6c7d8e9f0a11","cancelReason":"Alıcı siparişten vazgeçti","cancelledAt":"2027-03-04T09:31:40Z","createdAt":"2027-03-04T09:15:02Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","deliveryTypeId":"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66","id":"2c8e4a6b-9d1f-4b3c-a5e7-6f8a0b2c4d99","isRoundTrip":false,"notes":"Kapıda arayın.","number":10482,"payer":"sender","paymentMethod":"account","plannedPickupAt":"2027-03-04T09:15:02Z","price":{"algorithmVersion":"kos-1","calculatedTotal":"180.00","currencyCode":"TRY","currencyRate":"1","deliveryMultiplier":"1","expectedDeliveryMinutes":90,"fromRegion":2,"lines":{"base":"150.00","bridge":"0.00","extra":"0.00","manualAdjustmentNet":"0.00","manualAdjustmentVat":"0.00","serviceNet":"150.00","vat":"30.00","volume":"0.00","wait":"0.00","weight":"0.00"},"nightMultiplier":"1","tier":"subscriber","toRegion":3,"total":"180.00","usesWallet":false,"vatRate":"20","vatScope":"all"},"reference":"SIP-2027-00042","source":"api","status":"cancelled","stops":[{"address":"Caferağa Mah. Moda Cad. No:12, Kadıköy","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","districtName":"Kadıköy","name":"Örnek Çiçekçilik","regionNo":2,"role":"sender"},{"address":"Sinanpaşa Mah. Ihlamurdere Cad. No:5 D:3, Beşiktaş","districtName":"Beşiktaş","name":"Ayşe Yılmaz","regionNo":3,"role":"recipient"}],"version":2,"volumeM3":"0","waitMinutes":"0","weightKg":"2.5"},"schema":{"$ref":"#/components/schemas/Order"}}},"description":"Cancelled order","headers":{"Idempotent-Replayed":{"description":"This response is a replay of the response previously given for the same Idempotency-Key.","schema":{"enum":["true"],"type":"string"}}}},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/orders/{id}/attachments":{"get":{"tags":["Orders"],"summary":"Delivery photos and signature of an order","description":"Photos taken by the courier at pickup/delivery and the recipient's signature (if any). Download the image itself from the separate endpoint.","operationId":"listMyOrderAttachments","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"content":{"application/json":{"example":[{"accuracy":8,"capturedAt":"2027-03-04T11:02:10Z","contentType":"image/jpeg","createdAt":"2027-03-04T11:02:14Z","height":960,"id":"7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a33","kind":"delivery","lat":41.0438,"lng":29.0094,"size":184233,"width":1280},{"contentType":"image/png","createdAt":"2027-03-04T11:02:20Z","height":240,"id":"8f9a0b1c-2d3e-4f4a-9b5c-6d7e8f9a0b44","kind":"signature","size":9120,"width":600}],"schema":{"items":{"$ref":"#/components/schemas/OrderAttachment"},"type":"array"}}},"description":"Attachments"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/orders/{id}/attachments/{attachmentId}":{"get":{"tags":["Orders"],"summary":"Downloads an attachment image","description":"The image is returned as binary (JPEG or PNG).","operationId":"getMyOrderAttachment","parameters":[{"$ref":"#/components/parameters/Id"},{"description":"Attachment ID (from the attachment list)","example":"7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a33","in":"path","name":"attachmentId","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"image/jpeg":{"schema":{"format":"binary","type":"string"}},"image/png":{"schema":{"format":"binary","type":"string"}}},"description":"Image"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/orders/export":{"get":{"tags":["Orders"],"summary":"My order archive (CSV)","description":"Filters, search (`q`), amount range and sorting (`sort`) are the same as for the order list. Up to\n20,000 orders are exported at once; beyond that you get 422 — narrow the date range.","operationId":"exportMyOrders","parameters":[{"description":"One or more statuses, comma-separated","explode":false,"in":"query","name":"status","schema":{"items":{"$ref":"#/components/schemas/OrderStatus"},"type":"array"},"style":"form"},{"description":"Order number","in":"query","name":"number","schema":{"format":"int64","type":"integer"}},{"description":"Your reference number (case-insensitive exact match)","in":"query","name":"reference","schema":{"maxLength":100,"type":"string"}},{"description":"Parcel barcode (case-insensitive exact match)","in":"query","name":"barcode","schema":{"maxLength":40,"type":"string"}},{"description":"Created at or after","example":"2027-03-01T00:00:00+03:00","in":"query","name":"from","schema":{"format":"date-time","type":"string"}},{"description":"Created before (exclusive)","example":"2027-04-01T00:00:00+03:00","in":"query","name":"to","schema":{"format":"date-time","type":"string"}},{"description":"Sender or pickup point district","in":"query","name":"fromDistrictId","schema":{"format":"uuid","type":"string"}},{"description":"Recipient district","in":"query","name":"toDistrictId","schema":{"format":"uuid","type":"string"}},{"description":"Delivery type","in":"query","name":"deliveryTypeId","schema":{"format":"uuid","type":"string"}},{"description":"Payment method","in":"query","name":"paymentMethod","schema":{"$ref":"#/components/schemas/PaymentMethod"}},{"$ref":"#/components/parameters/ListQ"},{"$ref":"#/components/parameters/MinAmount"},{"$ref":"#/components/parameters/MaxAmount"},{"$ref":"#/components/parameters/ListSort"}],"responses":{"200":{"content":{"text/csv":{"example":"Sipariş No;Oluşturma;Durum;Gönderen;Gönderen semti;Alım noktası;Alım semti;Alıcı;Alıcı semti;Gidiş tipi;Gidiş-dönüş;Kurye;Alındı;Teslim;Teslim alan;Ödeme şekli;Referans no;Tutar;Para birimi;Not;İptal nedeni;Teslim kodu;Konum sonucu;Konum mesafesi (m)\n10482;04.03.2027 12:15;Teslim edildi;Örnek Çiçekçilik;Kadıköy;;;Ayşe Yılmaz;Beşiktaş;Normal;;Ali Kaya;04.03.2027 12:40;04.03.2027 14:02;Ayşe Yılmaz;Açık cari;SIP-2027-00042;180,00;TRY;Kapıda arayın.;;;Adreste;12\n","schema":{"format":"binary","type":"string"}}},"description":"CSV file"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/orders/imports/template":{"get":{"tags":["Orders"],"summary":"Bulk shipment template (with a sample row)","description":"Empty template with column headers and one sample row; choose xlsx or csv with `format`.","operationId":"getMyOrderImportTemplate","parameters":[{"description":"File format (default xlsx)","in":"query","name":"format","schema":{"default":"xlsx","enum":["xlsx","csv"],"type":"string"}},{"description":"Header language (empty: the request language)","in":"query","name":"lang","schema":{"enum":["tr","en"],"type":"string"}}],"responses":{"200":{"content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"format":"binary","type":"string"}},"text/csv":{"schema":{"format":"binary","type":"string"}}},"description":"Template"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/orders/imports/{id}/confirm":{"post":{"tags":["Orders"],"summary":"Creates orders from the valid rows of an upload in preview","description":"Only an upload in `preview` status can be confirmed; invalid and duplicate rows are skipped. The orders\nare created in a queue; follow progress and per-row results with `GET /me/orders/imports/{id}`.","operationId":"confirmMyOrderImport","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"content":{"application/json":{"example":{"createdAt":"2027-03-04T08:50:00Z","createdRows":0,"customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","customerName":"Örnek Çiçekçilik","error":"","failedRows":0,"filename":"siparisler.xlsx","id":"8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d33","skippedRows":0,"source":"customer","status":"queued","totalRows":40,"validRows":38},"schema":{"$ref":"#/components/schemas/OrderImport"}}},"description":"Queued upload"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/orders/imports/{id}/report":{"get":{"tags":["Orders"],"summary":"Result report of an upload (CSV)","description":"Status, created order number and error message per row.","operationId":"getMyOrderImportReport","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"content":{"text/csv":{"schema":{"format":"binary","type":"string"}}},"description":"CSV"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/orders/{id}/tracking":{"get":{"tags":["Tracking"],"summary":"Live courier tracking for an order","description":"The courier's name is returned from the moment the order is given to a courier until delivery. The\ncourier's location is returned only while the shipment is on the way (`picked_up` / `return_leg`) and\nthe location is less than 15 minutes old. Polling every 30–60 seconds for an order on the way is\nenough; receiving status changes via webhooks is recommended.","operationId":"getMyOrderTracking","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"content":{"application/json":{"example":{"companyPhone":"+902165550000","courierName":"Ali Kaya","expectedAt":"2027-03-04T11:05:00Z","location":{"at":"2027-03-04T10:48:31Z","lat":41.0391,"lng":29.0021},"status":"picked_up"},"schema":{"$ref":"#/components/schemas/MyOrderTracking"}}},"description":"Tracking information"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/orders/{id}/tracking-link":{"post":{"tags":["Tracking"],"summary":"Tracking link to share with the recipient","description":"Returns the address of the public tracking page, which can be viewed without signing in. The link is\ncreated on the first request and stays the same afterwards; you can send it to the recipient by SMS,\ne-mail or through your own app.","operationId":"createMyOrderTrackingLink","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"content":{"application/json":{"example":{"url":"https://ornekkurye.courino.com/t/Xk3pQ9vB2mLs"},"schema":{"properties":{"url":{"description":"Full address of the tracking page","type":"string"}},"required":["url"],"type":"object"}}},"description":"Link"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/webhooks":{"get":{"tags":["Webhooks"],"summary":"My webhook subscriptions","description":"The `secret` is not returned in the list; it is shown only once, when the subscription is created or the secret is rotated.","operationId":"listMyWebhooks","responses":{"200":{"content":{"application/json":{"example":[{"createdAt":"2027-03-01T08:00:00Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","description":"Sipariş durumları","enabled":true,"events":["order.assigned","order.picked_up","order.delivered","order.delivery_failed","order.cancelled"],"format":"kos","id":"1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9","url":"https://ornek.com.tr/kurye/webhook"}],"schema":{"items":{"$ref":"#/components/schemas/Webhook"},"type":"array"}}},"description":"Subscriptions"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]},"post":{"tags":["Webhooks"],"summary":"Creates a webhook subscription (up to 5)","description":"The subscription only receives events for orders you placed or pay for. The URL must be `http://` or\n`https://` (https is recommended) and must not contain a user name or password. The `secret` in the\nresponse is used to verify signatures and is shown **only once**; store it somewhere safe. The\nsignature and delivery rules are in the Webhooks section of the guide.","operationId":"createMyWebhook","requestBody":{"content":{"application/json":{"example":{"description":"Sipariş durumları","enabled":true,"events":["order.assigned","order.picked_up","order.delivered","order.delivery_failed","order.cancelled"],"format":"kos","url":"https://ornek.com.tr/kurye/webhook"},"schema":{"$ref":"#/components/schemas/WebhookInput"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"secret":"whsec_q8Yb3nR2vT7kL0pW5sZ1xC4mJ9hF6dG2aE8uI3oN5yQ","webhook":{"createdAt":"2027-03-01T08:00:00Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","description":"Sipariş durumları","enabled":true,"events":["order.assigned","order.picked_up","order.delivered","order.delivery_failed","order.cancelled"],"format":"kos","id":"1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9","url":"https://ornek.com.tr/kurye/webhook"}},"schema":{"properties":{"secret":{"description":"Signing secret (`whsec_…`); shown only in this response","type":"string"},"webhook":{"$ref":"#/components/schemas/Webhook"}},"required":["webhook","secret"],"type":"object"}}},"description":"Subscription created"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -s https://client.courino.com/api/v1/me/webhooks \\\n  -H \"Authorization: Bearer $KOS_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"url\": \"https://example.com/kurye/webhook\",\n    \"events\": [\"order.picked_up\", \"order.delivered\", \"order.delivery_failed\", \"order.cancelled\"],\n    \"enabled\": true\n  }'\n# Store the \"secret\" (whsec_...) from the response; it is shown only once.\n"},{"label":"Node.js (verify)","lang":"JavaScript","source":"// Express: verify X-KOS-Signature on the RAW body, then answer 2xx quickly.\nimport express from \"express\";\nimport crypto from \"node:crypto\";\n\nconst SECRET = process.env.KOS_WEBHOOK_SECRET; // whsec_... (used as-is)\nconst TOLERANCE = 300; // seconds\nconst seen = new Set(); // use a database/cache in production\n\nfunction verify(raw, header) {\n  const parts = Object.fromEntries(header.split(\",\").map((p) => p.split(\"=\", 2)));\n  const t = Number(parts.t);\n  if (!t || Math.abs(Date.now() / 1000 - t) > TOLERANCE) return false;\n  const expected = crypto.createHmac(\"sha256\", SECRET).update(`${t}.`).update(raw).digest();\n  const given = Buffer.from(parts.v1 || \"\", \"hex\");\n  return given.length === expected.length && crypto.timingSafeEqual(given, expected);\n}\n\nconst app = express();\napp.post(\"/kurye/webhook\", express.raw({ type: \"application/json\" }), (req, res) => {\n  if (!verify(req.body, req.get(\"X-KOS-Signature\") || \"\")) return res.sendStatus(401);\n  const delivery = req.get(\"X-KOS-Delivery\");\n  if (seen.has(delivery)) return res.sendStatus(200); // retry of a delivery already handled\n  seen.add(delivery);\n  const event = JSON.parse(req.body);\n  console.log(event.type, event.data.order.number, event.data.order.status);\n  res.sendStatus(204);\n});\napp.listen(3000);\n"},{"label":"Python (verify)","lang":"Python","source":"# Flask: verify X-KOS-Signature on the RAW body, then answer 2xx quickly.\nimport hashlib\nimport hmac\nimport os\nimport time\nfrom flask import Flask, abort, request\n\nSECRET = os.environ[\"KOS_WEBHOOK_SECRET\"].encode()  # whsec_... (used as-is)\nTOLERANCE = 300  # seconds\napp = Flask(__name__)\nseen = set()  # use a database/cache in production\n\ndef verify(raw: bytes, header: str) -> bool:\n    parts = dict(p.split(\"=\", 1) for p in header.split(\",\") if \"=\" in p)\n    try:\n        t = int(parts[\"t\"])\n    except (KeyError, ValueError):\n        return False\n    if abs(time.time() - t) > TOLERANCE:\n        return False\n    expected = hmac.new(SECRET, f\"{t}.\".encode() + raw, hashlib.sha256).hexdigest()\n    return hmac.compare_digest(expected, parts.get(\"v1\", \"\"))\n\n@app.post(\"/kurye/webhook\")\ndef kos_webhook():\n    if not verify(request.get_data(), request.headers.get(\"X-KOS-Signature\", \"\")):\n        abort(401)\n    delivery = request.headers[\"X-KOS-Delivery\"]\n    if delivery in seen:\n        return \"\", 200\n    seen.add(delivery)\n    event = request.get_json()\n    print(event[\"type\"], event[\"data\"][\"order\"][\"number\"])\n    return \"\", 204\n"},{"label":"PHP (verify)","lang":"PHP","source":"<?php\n// Verify X-KOS-Signature on the RAW body, then answer 2xx quickly.\n$secret = getenv('KOS_WEBHOOK_SECRET'); // whsec_... (used as-is)\n$raw = file_get_contents('php://input');\n$header = $_SERVER['HTTP_X_KOS_SIGNATURE'] ?? '';\n\n$parts = [];\nforeach (explode(',', $header) as $p) {\n    [$k, $v] = array_pad(explode('=', $p, 2), 2, '');\n    $parts[$k] = $v;\n}\n$t = (int)($parts['t'] ?? 0);\n$expected = hash_hmac('sha256', $t . '.' . $raw, $secret);\nif ($t === 0 || abs(time() - $t) > 300 || !hash_equals($expected, $parts['v1'] ?? '')) {\n    http_response_code(401);\n    exit;\n}\n\n$delivery = $_SERVER['HTTP_X_KOS_DELIVERY'] ?? '';\n// if (alreadyHandled($delivery)) { http_response_code(200); exit; }\n$event = json_decode($raw, true);\nerror_log($event['type'] . ' ' . $event['data']['order']['number']);\nhttp_response_code(204);\n"},{"label":"C# (verify)","lang":"C#","source":"// ASP.NET Core minimal API: verify X-KOS-Signature on the RAW body.\nusing System.Security.Cryptography;\nusing System.Text;\n\nvar secret = Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable(\"KOS_WEBHOOK_SECRET\")!);\nvar app = WebApplication.Create(args);\n\napp.MapPost(\"/kurye/webhook\", async (HttpRequest req) =>\n{\n    using var ms = new MemoryStream();\n    await req.Body.CopyToAsync(ms);\n    var raw = ms.ToArray();\n\n    var parts = req.Headers[\"X-KOS-Signature\"].ToString().Split(',')\n        .Select(p => p.Split('=', 2)).Where(p => p.Length == 2)\n        .ToDictionary(p => p[0], p => p[1]);\n    if (!parts.TryGetValue(\"t\", out var ts) || !long.TryParse(ts, out var t) ||\n        Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > 300)\n        return Results.Unauthorized();\n\n    var signed = Encoding.UTF8.GetBytes($\"{t}.\").Concat(raw).ToArray();\n    var expected = HMACSHA256.HashData(secret, signed);\n    byte[] given;\n    try { given = Convert.FromHexString(parts.GetValueOrDefault(\"v1\", \"\")); }\n    catch (FormatException) { return Results.Unauthorized(); }\n    if (!CryptographicOperations.FixedTimeEquals(expected, given))\n        return Results.Unauthorized();\n\n    var delivery = req.Headers[\"X-KOS-Delivery\"].ToString(); // dedupe on this\n    return Results.NoContent();\n});\napp.Run();\n"},{"label":"Go (verify)","lang":"Go","source":"package main\n\nimport (\n\t\"crypto/hmac\"\n\t\"crypto/sha256\"\n\t\"encoding/hex\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strconv\"\n\t\"strings\"\n\t\"time\"\n)\n\nvar secret = []byte(os.Getenv(\"KOS_WEBHOOK_SECRET\")) // whsec_... (used as-is)\n\n// verify checks X-KOS-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<body>\")>.\nfunc verify(body []byte, header string) bool {\n\tvar ts, v1 string\n\tfor _, p := range strings.Split(header, \",\") {\n\t\tk, v, _ := strings.Cut(p, \"=\")\n\t\tswitch k {\n\t\tcase \"t\":\n\t\t\tts = v\n\t\tcase \"v1\":\n\t\t\tv1 = v\n\t\t}\n\t}\n\tt, err := strconv.ParseInt(ts, 10, 64)\n\tif err != nil || time.Since(time.Unix(t, 0)).Abs() > 5*time.Minute {\n\t\treturn false\n\t}\n\tgiven, err := hex.DecodeString(v1)\n\tif err != nil {\n\t\treturn false\n\t}\n\tmac := hmac.New(sha256.New, secret)\n\tmac.Write([]byte(ts + \".\"))\n\tmac.Write(body)\n\treturn hmac.Equal(given, mac.Sum(nil))\n}\n\nfunc main() {\n\thttp.HandleFunc(\"/kurye/webhook\", func(w http.ResponseWriter, r *http.Request) {\n\t\tbody, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))\n\t\tif err != nil || !verify(body, r.Header.Get(\"X-KOS-Signature\")) {\n\t\t\tw.WriteHeader(http.StatusUnauthorized)\n\t\t\treturn\n\t\t}\n\t\t_ = r.Header.Get(\"X-KOS-Delivery\") // dedupe on this; stays the same across retries\n\t\tw.WriteHeader(http.StatusNoContent)\n\t})\n\t_ = http.ListenAndServe(\":3000\", nil)\n}\n"}]}},"/me/webhooks/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"put":{"tags":["Webhooks"],"summary":"Updates a webhook subscription","description":"The URL, events, description, format and enabled flag can be changed; the secret stays the same.","operationId":"updateMyWebhook","requestBody":{"content":{"application/json":{"example":{"description":"Sipariş durumları","enabled":true,"events":["order.assigned","order.picked_up","order.delivered","order.delivery_failed","order.cancelled"],"format":"kos","url":"https://ornek.com.tr/kurye/webhook"},"schema":{"$ref":"#/components/schemas/WebhookInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"createdAt":"2027-03-01T08:00:00Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","description":"Sipariş durumları","enabled":true,"events":["order.assigned","order.picked_up","order.delivered","order.delivery_failed","order.cancelled"],"format":"kos","id":"1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9","url":"https://ornek.com.tr/kurye/webhook"},"schema":{"$ref":"#/components/schemas/Webhook"}}},"description":"Updated subscription"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]},"delete":{"tags":["Webhooks"],"summary":"Deletes a webhook subscription","description":"The subscription is deleted permanently; if you create it again you get a new secret.","operationId":"deleteMyWebhook","responses":{"204":{"description":"Deleted"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/webhooks/{id}/rotate-secret":{"parameters":[{"$ref":"#/components/parameters/Id"}],"post":{"tags":["Webhooks"],"summary":"Rotates the webhook secret","description":"The new secret takes effect immediately; subsequent requests are signed with it. Use it if your\nsecret has leaked or for regular rotation. The new secret is shown only in this response.","operationId":"rotateMyWebhookSecret","responses":{"200":{"content":{"application/json":{"example":{"secret":"whsec_Zr4Tq1Wm8Ky2Nb6Vc3Xl9Hs5Jd0Pf7Ga4Ue1Io8Ow2Ry"},"schema":{"properties":{"secret":{"description":"New signing secret (`whsec_…`)","type":"string"}},"required":["secret"],"type":"object"}}},"description":"New secret"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/customer":{"get":{"tags":["Account"],"summary":"My customer record, contacts and address book","description":"`links` are the customers in your address book (linked to you); they can be used as the pickup point\nor recipient with `customerId`. `contacts` are your contacts who receive notifications.","operationId":"getMyCustomer","responses":{"200":{"content":{"application/json":{"example":{"contacts":[{"email":"zeynep@ornek.com.tr","id":"2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c66","mobilePhone":"+905441112233","name":"Zeynep Arslan","notifyEmail":true,"notifySms":true,"status":"active"}],"customer":{"account":"active","address":"Caferağa Mah. Moda Cad. No:12, Kadıköy","code":"M0042","deliveryCodePolicy":"inherit","districtId":"3f1c2a4e-8b7d-4c21-9a55-0e6b1f2d3c41","email":"siparis@ornek.com.tr","id":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","isVip":false,"name":"Örnek Çiçekçilik","notifyEmail":true,"notifySms":false,"phone":"+902165551234","requiresApproval":false,"status":"active","taxNumber":"1234567890","taxOffice":"Kadıköy"},"links":[{"address":"Bağdat Cad. No:210, Kadıköy","code":"M0057","districtId":"3f1c2a4e-8b7d-4c21-9a55-0e6b1f2d3c41","id":"5d7e8f90-1a2b-4c3d-9e8f-7a6b5c4d3e21","name":"Moda Butik","status":"active"}],"specialDates":[{"day":14,"id":"3b4c5d6e-7f8a-4b9c-8d0e-1f2a3b4c5d77","label":"Kuruluş yıl dönümü","month":5,"year":2009}]},"schema":{"$ref":"#/components/schemas/CustomerProfile"}}},"description":"Customer profile"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/customer/contacts":{"post":{"tags":["Account"],"summary":"Adds a contact who receives notifications","description":"If `notifySms` / `notifyEmail` is on, the contact receives the notifications for your orders. Saved\ncontacts are in the `contacts` field of the `GET /me/customer` response.","operationId":"createMyContact","requestBody":{"content":{"application/json":{"example":{"email":"zeynep@ornek.com.tr","mobilePhone":"+905441112233","name":"Zeynep Arslan","notifyEmail":true,"notifySms":true,"status":"active"},"schema":{"$ref":"#/components/schemas/CustomerContactInput"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"email":"zeynep@ornek.com.tr","id":"2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c66","mobilePhone":"+905441112233","name":"Zeynep Arslan","notifyEmail":true,"notifySms":true,"status":"active"},"schema":{"$ref":"#/components/schemas/CustomerContact"}}},"description":"Added contact"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/customer/contacts/{contactId}":{"put":{"tags":["Account"],"summary":"Updates or deactivates a contact","description":"Contacts are not deleted; send `status: inactive` to stop notifications.","operationId":"updateMyContact","parameters":[{"description":"Contact ID (`GET /me/customer` → `contacts`)","example":"2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c66","in":"path","name":"contactId","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"email":"zeynep@ornek.com.tr","mobilePhone":"+905441112233","name":"Zeynep Arslan","notifyEmail":true,"notifySms":false,"status":"active"},"schema":{"$ref":"#/components/schemas/CustomerContactInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"email":"zeynep@ornek.com.tr","id":"2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c66","mobilePhone":"+905441112233","name":"Zeynep Arslan","notifyEmail":true,"notifySms":false,"status":"active"},"schema":{"$ref":"#/components/schemas/CustomerContact"}}},"description":"Updated contact"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/customer/special-dates":{"put":{"tags":["Account"],"summary":"Replaces my special dates with the given list (at most 20)","description":"The list is replaced as a whole: records not sent are deleted, an empty list deletes all. The company\nmay send you a greeting or reminder on these days. The current list is also in the `GET /me/customer`\nresponse.","operationId":"replaceMyCustomerSpecialDates","requestBody":{"content":{"application/json":{"example":{"items":[{"day":14,"label":"Kuruluş yıl dönümü","month":5,"year":2009},{"day":10,"label":"Anneler Günü kampanyası","month":5}]},"schema":{"$ref":"#/components/schemas/CustomerSpecialDatesInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":[{"day":14,"id":"3b4c5d6e-7f8a-4b9c-8d0e-1f2a3b4c5d77","label":"Kuruluş yıl dönümü","month":5,"year":2009},{"day":10,"id":"4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e81","label":"Anneler Günü kampanyası","month":5}],"schema":{"items":{"$ref":"#/components/schemas/CustomerSpecialDate"},"type":"array"}}},"description":"Current list"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/customer/messages":{"get":{"tags":["Account"],"summary":"SMS, e-mail and notifications sent to you and your contacts","description":"Messages sent to you, your contacts and your app accounts about your orders (newest first). In push\nrows the recipient is the name of the app account the notification went to.","operationId":"listMyMessages","parameters":[{"description":"Channel filter","example":"sms","in":"query","name":"channel","schema":{"enum":["sms","email","push","whatsapp"],"type":"string"}},{"description":"Maximum number of records to return","in":"query","name":"limit","schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},{"description":"Number of records to skip","in":"query","name":"offset","schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"items":[{"body":"10482 numaralı gönderiniz teslim edildi.","channel":"sms","createdAt":"2027-03-04T11:42:10Z","id":"9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e44","orderId":"2c8e4a6b-9d1f-4b3c-a5e7-6f8a0b2c4d99","recipient":"+905441112233","sentAt":"2027-03-04T11:42:12Z","status":"sent","subject":""}],"total":1},"schema":{"$ref":"#/components/schemas/CustomerMessagePage"}}},"description":"Messages"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/wallet":{"get":{"tags":["Payments and invoices"],"summary":"My prepaid credit balance and recent activity","description":"For prepaid (wallet) customers; returns the balance, the last 100 transactions and the negative balance rule.","operationId":"getMyWallet","responses":{"200":{"content":{"application/json":{"example":{"balance":"1250.00","entries":[{"amount":"-180.00","createdAt":"2027-03-04T09:15:02Z","id":"4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e88","kind":"order_charge","note":"","orderId":"2c8e4a6b-9d1f-4b3c-a5e7-6f8a0b2c4d99"},{"amount":"1000.00","createdAt":"2027-03-01T10:00:00Z","id":"5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f99","kind":"topup","note":"Havale"}],"lowBalance":false,"lowBalanceThreshold":"200.00","policy":{"allowsNegative":false,"availableBalance":"1250.00","negative":"inherit"}},"schema":{"$ref":"#/components/schemas/Wallet"}}},"description":"Prepaid credit balance"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/customer/charges":{"get":{"tags":["Payments and invoices"],"summary":"Order charges I pay for","description":"Per-order fee breakdown, payment status and the invoice it was included in. `sumTotal` and\n`sumUnpaid` are totals over all records matching the filters.\n\n- `q`: searches order reference and sender/recipient/payer name.\n- `minAmount`/`maxAmount`: order total range.\n- `sort`: `createdAt` (default, descending), `number`, `total`, `deliveredAt`, `paidAt`; prefix with `-` for descending.","operationId":"listMyCharges","parameters":[{"description":"Payment status","example":"unpaid","in":"query","name":"status","schema":{"$ref":"#/components/schemas/PaymentStatus"}},{"description":"Start date","example":"2027-03-01","in":"query","name":"from","schema":{"format":"date","type":"string"}},{"description":"End date","example":"2027-03-31","in":"query","name":"to","schema":{"format":"date","type":"string"}},{"description":"Page size","in":"query","name":"limit","schema":{"default":50,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Number of records to skip","in":"query","name":"offset","schema":{"default":0,"minimum":0,"type":"integer"}},{"$ref":"#/components/parameters/MinAmount"},{"$ref":"#/components/parameters/MaxAmount"},{"$ref":"#/components/parameters/ListQ"},{"in":"query","name":"paymentMethod","schema":{"$ref":"#/components/schemas/PaymentMethod"}},{"description":"true: an e-invoice has been issued; false: not yet issued","in":"query","name":"einvoiced","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/ListSort"}],"responses":{"200":{"content":{"application/json":{"example":{"items":[{"algorithmVersion":"kos-1","bridge":"0.00","createdAt":"2027-03-04T09:15:02Z","currencyCode":"TRY","deliveredAt":"2027-03-04T11:02:20Z","description":"Normal","manualNet":"0.00","number":10482,"orderId":"2c8e4a6b-9d1f-4b3c-a5e7-6f8a0b2c4d99","orderStatus":"delivered","payer":"sender","payerCustomerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","payerName":"Örnek Çiçekçilik","paymentStatus":"unpaid","recipient":"Ayşe Yılmaz","sender":"Örnek Çiçekçilik","serviceNet":"150.00","total":"180.00","usesWallet":false,"vat":"30.00","vatRate":"20","volume":"0.00","wait":"0.00","weight":"0.00"}],"sumTotal":"180.00","sumUnpaid":"180.00","total":1},"schema":{"$ref":"#/components/schemas/ChargePage"}}},"description":"Charges"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/einvoices":{"get":{"tags":["Payments and invoices"],"summary":"My issued invoices (e-Invoice / e-Archive)","description":"By default the newest invoices come first.\n\n- `q`: searches invoice number and company name.\n- `minAmount`/`maxAmount`: invoice total range.\n- `sort`: `createdAt` (default, descending), `issuedAt`, `total`, `status`; prefix with `-` for descending.","operationId":"listMyEInvoices","parameters":[{"description":"Page size","example":20,"in":"query","name":"limit","schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},{"description":"Number of records to skip","in":"query","name":"offset","schema":{"default":0,"minimum":0,"type":"integer"}},{"description":"Lower bound of the creation time","in":"query","name":"from","schema":{"format":"date-time","type":"string"}},{"description":"Upper bound of the creation time (exclusive)","in":"query","name":"to","schema":{"format":"date-time","type":"string"}},{"description":"Order number on the invoice","in":"query","name":"orderNumber","schema":{"format":"int64","minimum":1,"type":"integer"}},{"$ref":"#/components/parameters/MinAmount"},{"$ref":"#/components/parameters/MaxAmount"},{"$ref":"#/components/parameters/ListQ"},{"$ref":"#/components/parameters/ListSort"}],"responses":{"200":{"content":{"application/json":{"example":{"items":[{"createdAt":"2027-04-01T06:00:00Z","currencyCode":"TRY","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","customerName":"Örnek Çiçekçilik","error":"","id":"6e7f8a9b-0c1d-4e2f-9a3b-4c5d6e7f8a00","issuedAt":"2027-04-01T06:00:41Z","kind":"e_invoice","net":"1500.00","orderIds":["2c8e4a6b-9d1f-4b3c-a5e7-6f8a0b2c4d99"],"orderNumbers":[10482],"status":"issued","total":"1800.00","vat":"300.00"}],"total":1},"schema":{"$ref":"#/components/schemas/EInvoicePage"}}},"description":"Invoices"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/einvoices/{id}/pdf":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"tags":["Payments and invoices"],"summary":"Invoice PDF link","description":"Available once the invoice has been issued (`issued`). The link is short-lived; do not store it, request it again when needed.","operationId":"myEInvoicePdf","responses":{"200":{"content":{"application/json":{"example":{"url":"https://files.courino.com/einvoice/6e7f8a9b.pdf?expires=1806300000&signature=3f9a"},"schema":{"properties":{"url":{"description":"PDF address","type":"string"}},"required":["url"],"type":"object"}}},"description":"Short-lived PDF link"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/customer/statement":{"get":{"tags":["Payments and invoices"],"summary":"Account statement for a period (PDF)","description":"Charges, payments and balance in the given date range, as a PDF.","operationId":"myStatement","parameters":[{"description":"Period start (inclusive)","in":"query","name":"from","required":true,"schema":{"format":"date","type":"string"}},{"description":"Period end (inclusive)","in":"query","name":"to","required":true,"schema":{"format":"date","type":"string"}}],"responses":{"200":{"content":{"application/pdf":{"schema":{"format":"binary","type":"string"}}},"description":"PDF","headers":{"Content-Disposition":{"schema":{"type":"string"}}}},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/customer/charges/{id}/document":{"get":{"tags":["Payments and invoices"],"summary":"Service breakdown of an order (PDF)","description":"Only available for an order whose fee you are paying.","operationId":"myChargeDocument","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"content":{"application/pdf":{"schema":{"format":"binary","type":"string"}}},"description":"PDF","headers":{"Content-Disposition":{"schema":{"type":"string"}}}},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/customer/payments":{"get":{"tags":["Payments and invoices"],"summary":"My online payments","description":"Online card payments you made (newest first). `q` searches the provider reference, description and\nerror message. Sorting (`sort`): createdAt (default, descending), amount, status, completedAt. A new\npayment can only be started from the customer portal.","operationId":"listMyPayments","parameters":[{"description":"Maximum number of records to return","in":"query","name":"limit","schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},{"description":"Number of records to skip","in":"query","name":"offset","schema":{"default":0,"minimum":0,"type":"integer"}},{"description":"Status filter","in":"query","name":"status","schema":{"$ref":"#/components/schemas/OnlinePaymentStatus"}},{"description":"Lower bound of the creation time","in":"query","name":"from","schema":{"format":"date-time","type":"string"}},{"description":"Upper bound of the creation time (exclusive)","in":"query","name":"to","schema":{"format":"date-time","type":"string"}},{"$ref":"#/components/parameters/MinAmount"},{"$ref":"#/components/parameters/MaxAmount"},{"$ref":"#/components/parameters/ListQ"},{"$ref":"#/components/parameters/ListSort"}],"responses":{"200":{"content":{"application/json":{"example":{"items":[{"amount":"360.00","checkoutExpiresAt":"2027-03-05T10:30:00Z","collector":"firm","completedAt":"2027-03-05T10:02:41Z","createdAt":"2027-03-05T10:00:00Z","currency":"TRY","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","description":"Mart 2027 sipariş ücretleri","id":"0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f55","installments":1,"kind":"charges","orderIds":["2c8e4a6b-9d1f-4b3c-a5e7-6f8a0b2c4d99"],"paidAmount":"360.00","provider":"paytr","providerRef":"P-0D1E2F3A","refundedAmount":"0.00","status":"succeeded","storedCard":false,"test":false}],"total":1},"schema":{"$ref":"#/components/schemas/PaymentPage"}}},"description":"Payments"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/customer/payments/{id}":{"get":{"tags":["Payments and invoices"],"summary":"Details of an online payment","description":"Status, paid and refunded amounts and the orders it covers.","operationId":"getMyPayment","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"content":{"application/json":{"example":{"amount":"360.00","checkoutExpiresAt":"2027-03-05T10:30:00Z","collector":"firm","completedAt":"2027-03-05T10:02:41Z","createdAt":"2027-03-05T10:00:00Z","currency":"TRY","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","description":"Mart 2027 sipariş ücretleri","id":"0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f55","installments":1,"kind":"charges","orderIds":["2c8e4a6b-9d1f-4b3c-a5e7-6f8a0b2c4d99"],"paidAmount":"360.00","provider":"paytr","providerRef":"P-0D1E2F3A","refundedAmount":"0.00","status":"succeeded","storedCard":false,"test":false},"schema":{"$ref":"#/components/schemas/Payment"}}},"description":"Payment"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/cod":{"get":{"tags":["Cash on delivery"],"summary":"My cash-on-delivery balance","description":"Summary of the amounts collected on your behalf and waiting to be paid out to you.","operationId":"getMyCod","responses":{"200":{"content":{"application/json":{"example":{"awaiting":"450.00","currency":"TRY","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","customerName":"Örnek Çiçekçilik","lastRemittedOn":"2027-03-01","oldestDueOn":"2027-03-08","overdue":"0.00","pending":"1200.00","pendingCount":3,"pendingFee":"30.00","ready":"800.00","readyCount":2,"readyFee":"20.00","remitted":"15400.00","withCourier":"0.00"},"schema":{"$ref":"#/components/schemas/CodBalance"}}},"description":"Balance"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/cod/orders":{"get":{"tags":["Cash on delivery"],"summary":"My cash-on-delivery orders","description":"Collection status, due date and payout information per order.\n\n- `q`: searches order number, reference, recipient name/phone and courier name.\n- `minAmount`/`maxAmount`: collection amount range.\n- `sort`: `collectedAt` (default, descending), `number`, `amount`, `dueOn`, `status`; prefix with `-` for descending.","operationId":"listMyCodOrders","parameters":[{"$ref":"#/components/parameters/CodQStatus"},{"$ref":"#/components/parameters/CodQFrom"},{"$ref":"#/components/parameters/CodQTo"},{"$ref":"#/components/parameters/CodQOverdue"},{"$ref":"#/components/parameters/CodQRemittance"},{"description":"Page size","example":50,"in":"query","name":"limit","schema":{"maximum":500,"minimum":1,"type":"integer"}},{"description":"Number of records to skip","in":"query","name":"offset","schema":{"minimum":0,"type":"integer"}},{"$ref":"#/components/parameters/ListQ"},{"$ref":"#/components/parameters/MinAmount"},{"$ref":"#/components/parameters/MaxAmount"},{"$ref":"#/components/parameters/ListSort"}],"responses":{"200":{"content":{"application/json":{"example":{"items":[{"amount":"400.00","collectedAt":"2027-03-04T11:02:20Z","courierName":"Ali Kaya","currency":"TRY","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","customerName":"Örnek Çiçekçilik","dueOn":"2027-03-08","fee":"10.00","handoverAt":"2027-03-04T19:10:00Z","method":"cash","number":10482,"orderCreatedAt":"2027-03-04T09:15:02Z","orderId":"2c8e4a6b-9d1f-4b3c-a5e7-6f8a0b2c4d99","orderStatus":"delivered","recipientName":"Ayşe Yılmaz","status":"pending"}],"total":1},"schema":{"$ref":"#/components/schemas/CodOrderPage"}}},"description":"Cash-on-delivery orders"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/cod/orders/export":{"get":{"tags":["Cash on delivery"],"summary":"My cash on delivery statement (CSV)","description":"Takes the same filters as `GET /me/cod/orders`. `q`: order no, reference, customer, recipient\nname/phone, courier. `sort`: collectedAt, number, amount, dueOn, customer, status (- descending;\ndefault -collectedAt).","operationId":"exportMyCodOrders","parameters":[{"$ref":"#/components/parameters/CodQStatus"},{"$ref":"#/components/parameters/CodQFrom"},{"$ref":"#/components/parameters/CodQTo"},{"$ref":"#/components/parameters/CodQOverdue"},{"$ref":"#/components/parameters/CodQRemittance"},{"$ref":"#/components/parameters/ListQ"},{"$ref":"#/components/parameters/MinAmount"},{"$ref":"#/components/parameters/MaxAmount"},{"$ref":"#/components/parameters/ListSort"}],"responses":{"200":{"content":{"text/csv":{"schema":{"format":"binary","type":"string"}}},"description":"CSV"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/cod/remittances":{"get":{"tags":["Cash on delivery"],"summary":"Cash-on-delivery payouts made to me","description":"Payments the company made to you; gross amount, deductions and the net amount paid.","operationId":"listMyCodRemittances","parameters":[{"description":"Page size","example":50,"in":"query","name":"limit","schema":{"maximum":500,"minimum":1,"type":"integer"}},{"description":"Number of records to skip","in":"query","name":"offset","schema":{"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"items":[{"createdAt":"2027-03-01T14:00:00Z","currency":"TRY","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","customerName":"Örnek Çiçekçilik","feeTotal":"120.00","gross":"4800.00","id":"7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b11","method":"bank_transfer","net":"4680.00","note":"","number":31,"offsetTotal":"0.00","orderCount":12,"paidOn":"2027-03-01","reference":"EFT-20270301-0042"}],"total":1},"schema":{"$ref":"#/components/schemas/CodRemittancePage"}}},"description":"Payouts"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/cod/remittances/{id}/receipt":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"tags":["Cash on delivery"],"summary":"Cash on delivery transfer receipt (PDF)","description":"Receipt of a transfer the company made to you; lists the orders it covers.","operationId":"myCodRemittanceReceipt","responses":{"200":{"content":{"application/pdf":{"schema":{"format":"binary","type":"string"}}},"description":"PDF","headers":{"Content-Disposition":{"schema":{"type":"string"}}}},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/ecommerce/connections":{"get":{"tags":["E-commerce"],"summary":"My store connections","description":"Store credentials are not included in the response.","operationId":"listMyEcommerceConnections","responses":{"200":{"content":{"application/json":{"example":[{"branchId":null,"branchName":"","cancelManualCount":0,"createdAt":"2027-01-10T12:00:00Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","customerName":"Örnek Çiçekçilik","errorCount":0,"failedCount":0,"id":"1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a66","importedCount":214,"lastError":"","lastSyncAt":"2027-03-04T09:00:00Z","name":"Web mağazası","needsAuthorization":false,"pendingCount":1,"platform":"woocommerce","settings":{"autoImport":true,"cancelSync":true,"carriers":[],"codEnabled":true,"codMethods":["cod"],"deliveryTypeId":"b5d1e2f3-6a7b-4c8d-9e0f-1a2b3c4d5e66","notifyCustomer":false,"parcelCount":1,"parcelMode":"single","payRecipient":false,"pickupAddress":"","pickupDistrictId":null,"triggerStatuses":["processing"],"writeback":true},"status":"active","storeUrl":"https://magaza.ornek.com.tr","updatedAt":"2027-03-04T09:00:00Z","webhookRegistered":true}],"schema":{"items":{"$ref":"#/components/schemas/EcommerceConnection"},"type":"array"}}},"description":"Connections"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/ecommerce/connections/{id}/test":{"parameters":[{"$ref":"#/components/parameters/Id"}],"post":{"tags":["E-commerce"],"summary":"Tests a saved connection","description":"Tries to connect to the store with the saved details; an error is returned with a 422 message.","operationId":"testMyEcommerceConnection","responses":{"204":{"description":"Connection succeeded"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/ecommerce/connections/{id}/sync":{"parameters":[{"$ref":"#/components/parameters/Id"}],"post":{"tags":["E-commerce"],"summary":"Syncs now","description":"Queues a poll for new orders in the store; the result is written to the connection log.","operationId":"syncMyEcommerceConnection","responses":{"202":{"description":"Queued"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/ecommerce/connections/{id}/events":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"tags":["E-commerce"],"summary":"Connection log (last 90 days)","operationId":"listMyEcommerceEvents","parameters":[{"description":"Maximum number of records to return","example":50,"in":"query","name":"limit","schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":[{"createdAt":"2027-03-04T09:00:05Z","id":"2f3a4b5c-6d7e-4f8a-9b0c-1d2e3f4a5b77","kind":"import","level":"info","message":"#1057 içe alındı (sipariş 10482)","recordId":"3a4b5c6d-7e8f-4a9b-8c0d-1e2f3a4b5c88"}],"schema":{"items":{"$ref":"#/components/schemas/EcommerceEvent"},"type":"array"}}},"description":"Log"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/ecommerce/orders":{"get":{"tags":["E-commerce"],"summary":"Orders received from my stores","description":"Use `status=pending` for orders awaiting a match. `q`: store order no/ID, Courino order no, store\nname, issue text. `sort`: createdAt, updatedAt, externalNumber, orderNumber, status, codAmount\n(- descending; default -createdAt).","operationId":"listMyEcommerceOrders","parameters":[{"description":"Status filter","example":["pending"],"explode":true,"in":"query","name":"status","schema":{"items":{"$ref":"#/components/schemas/EcommerceOrderStatus"},"type":"array"},"style":"form"},{"description":"Connection filter","in":"query","name":"connectionId","schema":{"format":"uuid","type":"string"}},{"description":"Store cancellation state (manual: awaiting a manual decision)","in":"query","name":"cancelState","schema":{"$ref":"#/components/schemas/EcommerceCancelState"}},{"description":"Issue type (area: outside the service area, cannot be given to a courier)","in":"query","name":"issueKind","schema":{"enum":["address","validation","error","area"],"type":"string"}},{"description":"Maximum number of records to return","in":"query","name":"limit","schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},{"description":"Number of records to skip","in":"query","name":"offset","schema":{"default":0,"minimum":0,"type":"integer"}},{"description":"Lower bound of the creation time","in":"query","name":"from","schema":{"format":"date-time","type":"string"}},{"description":"Upper bound of the creation time (exclusive)","in":"query","name":"to","schema":{"format":"date-time","type":"string"}},{"$ref":"#/components/parameters/ListQ"},{"$ref":"#/components/parameters/ListSort"}],"responses":{"200":{"content":{"application/json":{"example":{"items":[{"attempts":1,"cancelState":"","codAmount":"450.00","connectionId":"1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a66","connectionName":"Web mağazası","createdAt":"2027-03-04T09:10:00Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","districtId":null,"externalId":"1058","externalNumber":"1058","id":"4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d99","issue":"Semt bulunamadı (Kadikoy / Caferaga)","issueKind":"address","orderId":null,"orderNumber":null,"platform":"woocommerce","status":"pending","store":{"address":"Caferağa Mah. Moda Cad. No:5","city":"Kadikoy","currency":"TRY","gateway":"cod","items":2,"name":"Elif Kaya","phone":"+905321234567","province":"Istanbul","status":"processing","total":"450.00"},"updatedAt":"2027-03-04T09:10:02Z","writebackError":"","writebackStage":""}],"serviceProvinces":["İstanbul"],"total":1},"schema":{"$ref":"#/components/schemas/EcommerceOrderPage"}}},"description":"Records"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/ecommerce/orders/{id}/resolve":{"parameters":[{"$ref":"#/components/parameters/Id"}],"post":{"tags":["E-commerce"],"summary":"Fixes an order awaiting a match and imports it","description":"The district (and optionally name/phone/address) correction is saved and the order is imported right\naway. With `remember=true` this province/district/area spelling is remembered (later orders match\nautomatically).","operationId":"resolveMyEcommerceOrder","requestBody":{"content":{"application/json":{"example":{"districtId":"3f1c2a4e-8b7d-4c21-9a55-0e6b1f2d3c41","remember":true},"schema":{"$ref":"#/components/schemas/EcommerceResolveInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"attempts":2,"cancelState":"","codAmount":"450.00","connectionId":"1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a66","connectionName":"Web mağazası","createdAt":"2027-03-04T09:10:00Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","districtId":"3f1c2a4e-8b7d-4c21-9a55-0e6b1f2d3c41","externalId":"1058","externalNumber":"1058","fix":{"districtId":"3f1c2a4e-8b7d-4c21-9a55-0e6b1f2d3c41"},"id":"4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d99","issue":"","issueKind":"","orderId":"5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e01","orderNumber":10483,"platform":"woocommerce","status":"imported","store":{"address":"Caferağa Mah. Moda Cad. No:5","city":"Kadikoy","currency":"TRY","gateway":"cod","items":2,"name":"Elif Kaya","phone":"+905321234567","province":"Istanbul","status":"processing","total":"450.00"},"updatedAt":"2027-03-04T09:25:00Z","writebackError":"","writebackStage":""},"schema":{"$ref":"#/components/schemas/EcommerceOrder"}}},"description":"Result"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/ecommerce/orders/{id}/retry":{"parameters":[{"$ref":"#/components/parameters/Id"}],"post":{"tags":["E-commerce"],"summary":"Retries importing a failed order","operationId":"retryMyEcommerceOrder","responses":{"200":{"content":{"application/json":{"example":{"attempts":2,"cancelState":"","codAmount":"450.00","connectionId":"1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a66","connectionName":"Web mağazası","createdAt":"2027-03-04T09:10:00Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","districtId":"3f1c2a4e-8b7d-4c21-9a55-0e6b1f2d3c41","externalId":"1058","externalNumber":"1058","fix":{"districtId":"3f1c2a4e-8b7d-4c21-9a55-0e6b1f2d3c41"},"id":"4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d99","issue":"","issueKind":"","orderId":"5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e01","orderNumber":10483,"platform":"woocommerce","status":"imported","store":{"address":"Caferağa Mah. Moda Cad. No:5","city":"Kadikoy","currency":"TRY","gateway":"cod","items":2,"name":"Elif Kaya","phone":"+905321234567","province":"Istanbul","status":"processing","total":"450.00"},"updatedAt":"2027-03-04T09:25:00Z","writebackError":"","writebackStage":""},"schema":{"$ref":"#/components/schemas/EcommerceOrder"}}},"description":"Result"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/me/ecommerce/orders/{id}/skip":{"parameters":[{"$ref":"#/components/parameters/Id"}],"post":{"tags":["E-commerce"],"summary":"Skips the order (no Courino order is created)","operationId":"skipMyEcommerceOrder","responses":{"200":{"content":{"application/json":{"example":{"attempts":1,"cancelState":"","codAmount":"450.00","connectionId":"1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a66","connectionName":"Web mağazası","createdAt":"2027-03-04T09:10:00Z","customerId":"9b2f6c1e-3a4d-4e5f-8a7b-1c2d3e4f5a60","districtId":null,"externalId":"1058","externalNumber":"1058","id":"4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d99","issue":"Semt bulunamadı (Kadikoy / Caferaga)","issueKind":"address","orderId":null,"orderNumber":null,"platform":"woocommerce","status":"skipped","store":{"address":"Caferağa Mah. Moda Cad. No:5","city":"Kadikoy","currency":"TRY","gateway":"cod","items":2,"name":"Elif Kaya","phone":"+905321234567","province":"Istanbul","status":"processing","total":"450.00"},"updatedAt":"2027-03-04T09:25:00Z","writebackError":"","writebackStage":""},"schema":{"$ref":"#/components/schemas/EcommerceOrder"}}},"description":"Skipped"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}]}},"/healthz":{"get":{"tags":["Health checks"],"summary":"Liveness check","description":"Always returns 204 while the server process is up; it does not check the database. No authentication required.","operationId":"getHealthz","responses":{"204":{"description":"Server is running (no body)"}},"security":[],"servers":[{"url":"/"}]}},"/readyz":{"get":{"tags":["Health checks"],"summary":"Readiness check (includes the database)","description":"Tells whether the server is ready to serve requests by probing its dependencies (the database); the\nprobes take at most 3 seconds in total. No authentication required. No error details are returned:\nonly the name of the component that is not ready.","operationId":"getReadyz","responses":{"200":{"content":{"application/json":{"example":{"status":"ok"},"schema":{"properties":{"status":{"description":"Always `ok`","enum":["ok"],"type":"string"}},"required":["status"],"type":"object"}}},"description":"Ready"},"503":{"content":{"application/json":{"example":{"failed":{"postgres":"unavailable"},"status":"unavailable"},"schema":{"properties":{"failed":{"additionalProperties":{"enum":["unavailable"],"type":"string"},"description":"Components that did not respond (e.g. `postgres`) → `unavailable`","type":"object"},"status":{"description":"Always `unavailable`","enum":["unavailable"],"type":"string"}},"required":["status","failed"],"type":"object"}}},"description":"Not ready; retry shortly"}},"security":[],"servers":[{"url":"/"}]}}},"components":{"parameters":{"CodQFrom":{"description":"Collected at or after (for uncollected entries, the order's creation time)","in":"query","name":"from","schema":{"format":"date-time","type":"string"}},"CodQOverdue":{"description":"Only overdue collections that have not been paid out","in":"query","name":"overdue","schema":{"type":"boolean"}},"CodQRemittance":{"description":"Only the orders of this payout","in":"query","name":"remittanceId","schema":{"format":"uuid","type":"string"}},"CodQStatus":{"description":"Collection status","in":"query","name":"status","schema":{"$ref":"#/components/schemas/CodStatus"}},"CodQTo":{"description":"Before this time (exclusive)","in":"query","name":"to","schema":{"format":"date-time","type":"string"}},"Id":{"description":"Record ID (UUID)","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},"ListQ":{"description":"Free-text search (case-insensitive, partial match)","in":"query","name":"q","schema":{"maxLength":200,"type":"string"}},"ListSort":{"description":"Sort order: \"field\" ascending, \"-field\" descending; allowed fields are listed in the operation description. An unknown field returns 422.","in":"query","name":"sort","schema":{"maxLength":40,"pattern":"^-?[a-zA-Z]{1,39}$","type":"string"}},"MaxAmount":{"description":"Upper bound of the amount (inclusive)","in":"query","name":"maxAmount","schema":{"$ref":"#/components/schemas/Decimal"}},"MinAmount":{"description":"Lower bound of the amount (inclusive)","in":"query","name":"minAmount","schema":{"$ref":"#/components/schemas/Decimal"}},"OrderIdempotencyKey":{"description":"Optional duplicate-protection key (e.g. a UUID). A request repeated with the same key and the same\nbody is not executed again; the first successful response is returned with the\n`Idempotent-Replayed: true` header (so you can safely retry after a network error). The key is\nscoped to the company, the caller (customer or user) and the operation, and is kept for 24 hours.","in":"header","name":"Idempotency-Key","schema":{"maxLength":200,"type":"string"}}},"responses":{"IdempotencyConflict":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Idempotency-Key conflict: `IDEMPOTENCY_MISMATCH` — the key was used for a different request (body\nor path); generate a new key for a new request. `IDEMPOTENCY_IN_PROGRESS` — the first request with\nthe same key is still being processed; retry shortly with the same key. Returned only when the\nheader is sent."},"Problem":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Error (RFC 7807 problem+json)"}},"schemas":{"AppliedDiscount":{"description":"Discount applied to the price; `amount` is the deducted amount including VAT.","properties":{"amount":{"$ref":"#/components/schemas/Decimal"},"id":{"format":"uuid","type":"string"},"kind":{"$ref":"#/components/schemas/DiscountKind"},"label":{"description":"Discount name","type":"string"},"value":{"$ref":"#/components/schemas/Decimal"}},"required":["id","label","kind","value","amount"],"type":"object"},"BusinessHours":{"description":"The company's business hours (if configured); orders created outside them are handled at the start of the next business hours.","properties":{"end":{"example":"18:00","type":"string"},"openNow":{"description":"Whether it is currently within business hours","type":"boolean"},"start":{"example":"09:00","type":"string"}},"required":["start","end","openNow"],"type":"object"},"CancelRequest":{"properties":{"reason":{"description":"Cancellation reason","maxLength":500,"minLength":1,"type":"string"}},"required":["reason"],"type":"object"},"Charge":{"description":"The fee and payment status of an order.","properties":{"algorithmVersion":{"description":"Version of the pricing algorithm that calculated the price","type":"string"},"bridge":{"$ref":"#/components/schemas/Decimal"},"createdAt":{"format":"date-time","type":"string"},"currencyCode":{"type":"string"},"deliveredAt":{"format":"date-time","type":"string"},"description":{"type":"string"},"einvoiceId":{"description":"The invoice the order was included in (e-Invoice/e-Archive)","format":"uuid","type":"string"},"einvoiceStatus":{"$ref":"#/components/schemas/EInvoiceStatus"},"manualNet":{"$ref":"#/components/schemas/Decimal"},"number":{"description":"Order number","format":"int64","type":"integer"},"orderId":{"format":"uuid","type":"string"},"orderStatus":{"$ref":"#/components/schemas/OrderStatus"},"paidAt":{"description":"When it was paid","format":"date-time","type":"string"},"payer":{"description":"The paying party","enum":["sender","pickup","recipient"],"type":"string"},"payerCustomerId":{"format":"uuid","type":"string"},"payerName":{"type":"string"},"paymentStatus":{"$ref":"#/components/schemas/PaymentStatus"},"recipient":{"type":"string"},"sender":{"type":"string"},"serviceNet":{"$ref":"#/components/schemas/Decimal"},"total":{"$ref":"#/components/schemas/Decimal"},"usesWallet":{"type":"boolean"},"vat":{"$ref":"#/components/schemas/Decimal"},"vatRate":{"$ref":"#/components/schemas/Decimal"},"volume":{"$ref":"#/components/schemas/Decimal"},"wait":{"$ref":"#/components/schemas/Decimal"},"weight":{"$ref":"#/components/schemas/Decimal"}},"required":["orderId","number","createdAt","orderStatus","payer","payerName","sender","recipient","algorithmVersion","currencyCode","serviceNet","wait","weight","volume","bridge","manualNet","vat","vatRate","total","usesWallet","paymentStatus","description"],"type":"object"},"ChargePage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/Charge"},"type":"array"},"sumTotal":{"$ref":"#/components/schemas/Decimal"},"sumUnpaid":{"$ref":"#/components/schemas/Decimal"},"total":{"description":"Number of records matching the filters","type":"integer"}},"required":["items","total","sumTotal","sumUnpaid"],"type":"object"},"CodBalance":{"properties":{"awaiting":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Cash on delivery of orders awaiting delivery"},"currency":{"type":"string"},"customerId":{"format":"uuid","type":"string"},"customerName":{"type":"string"},"lastRemittedOn":{"format":"date","type":"string"},"oldestDueOn":{"description":"Oldest due date not yet paid out","format":"date","type":"string"},"overdue":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Overdue, not yet paid out"},"pending":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Collected, not yet paid out (including amounts held by couriers; gross)"},"pendingCount":{"type":"integer"},"pendingFee":{"$ref":"#/components/schemas/Decimal"},"ready":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Can be paid out now (gross)"},"readyCount":{"type":"integer"},"readyFee":{"$ref":"#/components/schemas/Decimal"},"remitted":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Paid out to date (gross)"},"withCourier":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Cash collected, not yet handed over to the company by the courier"}},"required":["customerId","customerName","currency","awaiting","withCourier","pending","pendingFee","pendingCount","ready","readyFee","readyCount","overdue","remitted"],"type":"object"},"CodMethod":{"description":"cash: cash; card: card via POS at the door; link: online card payment via payment link / QR","enum":["cash","card","link"],"type":"string"},"CodOrder":{"properties":{"amount":{"$ref":"#/components/schemas/Decimal"},"branchId":{"format":"uuid","type":"string"},"collectedAt":{"description":"When it was collected","format":"date-time","type":"string"},"courierId":{"format":"uuid","type":"string"},"courierName":{"type":"string"},"currency":{"type":"string"},"customerId":{"format":"uuid","type":"string"},"customerName":{"type":"string"},"dueOn":{"description":"Due date of the payout to you","format":"date","type":"string"},"fee":{"$ref":"#/components/schemas/Decimal"},"handoverAt":{"format":"date-time","type":"string"},"method":{"$ref":"#/components/schemas/CodMethod"},"number":{"format":"int64","type":"integer"},"orderCreatedAt":{"format":"date-time","type":"string"},"orderId":{"format":"uuid","type":"string"},"orderStatus":{"$ref":"#/components/schemas/OrderStatus"},"recipientName":{"type":"string"},"remittanceId":{"format":"uuid","type":"string"},"remittanceNumber":{"format":"int64","type":"integer"},"status":{"$ref":"#/components/schemas/CodStatus"}},"required":["orderId","number","orderStatus","customerId","customerName","recipientName","amount","currency","fee","status","orderCreatedAt"],"type":"object"},"CodOrderPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CodOrder"},"type":"array"},"total":{"type":"integer"}},"required":["items","total"],"type":"object"},"CodRemittance":{"description":"A cash-on-delivery payout the company made to you.","properties":{"cancelReason":{"type":"string"},"cancelledAt":{"format":"date-time","type":"string"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"format":"uuid","type":"string"},"currency":{"type":"string"},"customerId":{"format":"uuid","type":"string"},"customerName":{"type":"string"},"feeTotal":{"$ref":"#/components/schemas/Decimal"},"gross":{"$ref":"#/components/schemas/Decimal"},"id":{"format":"uuid","type":"string"},"method":{"enum":["bank_transfer","cash","other"],"type":"string"},"net":{"$ref":"#/components/schemas/Decimal"},"note":{"type":"string"},"number":{"format":"int64","type":"integer"},"offsetTotal":{"$ref":"#/components/schemas/Decimal"},"orderCount":{"type":"integer"},"paidOn":{"description":"Payment date","format":"date","type":"string"},"reference":{"description":"Bank receipt / reference number","type":"string"}},"required":["id","number","customerId","customerName","currency","gross","feeTotal","offsetTotal","net","orderCount","method","paidOn","reference","note","createdAt"],"type":"object"},"CodRemittancePage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CodRemittance"},"type":"array"},"total":{"type":"integer"}},"required":["items","total"],"type":"object"},"CodStatus":{"description":"awaiting: the order has not been delivered yet; not_collected: cancelled/returned, will not be collected; with_courier: cash collected, not yet handed over to the company by the courier; pending: awaiting payout to you; remitted: paid out.","enum":["awaiting","not_collected","with_courier","pending","remitted"],"type":"string"},"CreateOrderRequest":{"description":"Order body. The sender is the customer that owns the API key.","properties":{"codAmount":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Cash-on-delivery amount: the price of the goods to be collected from the recipient on your behalf.\nIt is separate from the delivery fee and not part of the price. If the company has not enabled cash\non delivery you get 422 `COD_DISABLED`. If omitted on update it does not change; \"0\" removes it. It\ncannot be changed after it has been collected (409 `COD_COLLECTED`)."},"deliveryTypeId":{"description":"Delivery type (`GET /me/order-options`)","format":"uuid","type":"string"},"notes":{"description":"Note for the courier","maxLength":1000,"type":"string"},"parcels":{"description":"Parcels. If omitted, a single parcel is created. If omitted on update the parcels do not change; if\ngiven they are rewritten (409 if a parcel has already been scanned). A parcel left without a barcode\ngets the system barcode `<order number>-<sequence>`.","items":{"$ref":"#/components/schemas/ParcelInput"},"maxItems":99,"type":"array"},"payer":{"description":"The paying party","enum":["sender","pickup","recipient"],"type":"string"},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"},"pickup":{"$ref":"#/components/schemas/OrderParty"},"plannedPickupAt":{"description":"Planned pickup time; immediately if omitted","format":"date-time","type":"string"},"recipient":{"$ref":"#/components/schemas/OrderParty"},"reference":{"description":"Your own reference / tracking number; you can search orders by it","maxLength":100,"type":"string"},"requireDeliveryCode":{"description":"Whether a one-time code is required from the recipient at delivery. If omitted, the setting on your\ncustomer record or the company's setting applies. Through the API it can only be turned on (`false`\nis ignored).","type":"boolean"},"sender":{"$ref":"#/components/schemas/OrderParty"},"volumeM3":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Volume (m³)"},"waitMinutes":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Expected waiting time (minutes)"},"weightKg":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Weight (kg)"}},"required":["payer","sender","recipient","deliveryTypeId"],"type":"object"},"Customer":{"description":"Your customer record.","properties":{"account":{"$ref":"#/components/schemas/CustomerAccountState"},"address":{"type":"string"},"birthDate":{"format":"date","type":"string"},"code":{"description":"Customer code","type":"string"},"customerTypeId":{"description":"Customer type","format":"uuid","type":"string"},"deliveryCodePolicy":{"$ref":"#/components/schemas/DeliveryCodePolicy"},"districtId":{"description":"Default district","format":"uuid","type":"string"},"email":{"type":"string"},"id":{"format":"uuid","type":"string"},"isVip":{"type":"boolean"},"legalKind":{"$ref":"#/components/schemas/CustomerLegalKind"},"marketingConsent":{"description":"Consent to marketing messages (commercial electronic messages)","type":"boolean"},"marketingConsentAt":{"format":"date-time","type":"string"},"marketingConsentSource":{"description":"Channel through which the consent last changed","type":"string"},"mobilePhone":{"type":"string"},"name":{"type":"string"},"notifyEmail":{"type":"boolean"},"notifySms":{"type":"boolean"},"phone":{"type":"string"},"priceListId":{"description":"Price list","format":"uuid","type":"string"},"requiresApproval":{"description":"Orders you create are given to a courier after the company approves them","type":"boolean"},"status":{"$ref":"#/components/schemas/CustomerStatus"},"taxNumber":{"type":"string"},"taxOffice":{"type":"string"}},"required":["id","name","address","notifySms","notifyEmail","isVip","status"],"type":"object"},"CustomerAccountState":{"description":"Sign-in account: active (can sign in), pending (invited, password not set yet), none (no account)","enum":["active","pending","none"],"type":"string"},"CustomerContact":{"allOf":[{"$ref":"#/components/schemas/CustomerContactInput"},{"properties":{"id":{"format":"uuid","type":"string"}},"required":["id"],"type":"object"}]},"CustomerContactInput":{"properties":{"birthDate":{"description":"The contact's date of birth","format":"date","type":"string"},"email":{"maxLength":200,"type":"string"},"mobilePhone":{"$ref":"#/components/schemas/Phone"},"name":{"maxLength":200,"minLength":1,"type":"string"},"notifyEmail":{"description":"Receives delivery notifications by e-mail","type":"boolean"},"notifySms":{"description":"Receives delivery notifications by SMS","type":"boolean"},"status":{"$ref":"#/components/schemas/Status"}},"required":["name","notifySms","notifyEmail","status"],"type":"object"},"CustomerDiscount":{"description":"A discount defined for you.","properties":{"campaignId":{"format":"uuid","type":"string"},"cancelledAt":{"format":"date-time","type":"string"},"createdAt":{"format":"date-time","type":"string"},"customerId":{"format":"uuid","type":"string"},"customerName":{"type":"string"},"id":{"format":"uuid","type":"string"},"kind":{"$ref":"#/components/schemas/DiscountKind"},"label":{"type":"string"},"maxUses":{"description":"Number of uses allowed (unlimited if empty)","type":"integer"},"ruleId":{"format":"uuid","type":"string"},"source":{"enum":["manual","campaign","rule"],"type":"string"},"status":{"enum":["active","cancelled"],"type":"string"},"used":{"description":"Times used","type":"integer"},"validFrom":{"format":"date","type":"string"},"validUntil":{"format":"date","type":"string"},"value":{"$ref":"#/components/schemas/Decimal"}},"required":["id","customerId","customerName","kind","value","validFrom","validUntil","used","source","label","status","createdAt"],"type":"object"},"CustomerLegalKind":{"description":"The customer's legal kind: `individual` (Turkish ID number optional), `sole_proprietor` (Turkish ID number and\ntax office required), `limited` / `joint_stock` / `other` (tax ID (VKN) and tax office required). Empty = not\nchosen (older record; only the format is checked). If omitted on update, it does not change.","enum":["individual","sole_proprietor","limited","joint_stock","other"],"type":"string"},"CustomerMessage":{"description":"A message as shown to the customer; provider details and error text are not included.","properties":{"body":{"type":"string"},"channel":{"enum":["sms","email","push","whatsapp"],"type":"string"},"createdAt":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"orderId":{"format":"uuid","type":"string"},"recipient":{"type":"string"},"sentAt":{"format":"date-time","type":"string"},"status":{"enum":["pending","sent","failed"],"type":"string"},"subject":{"type":"string"}},"required":["id","channel","recipient","subject","body","status","createdAt"],"type":"object"},"CustomerMessagePage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CustomerMessage"},"type":"array"},"total":{"type":"integer"}},"required":["items","total"],"type":"object"},"CustomerProfile":{"properties":{"contacts":{"description":"Contacts","items":{"$ref":"#/components/schemas/CustomerContact"},"type":"array"},"customer":{"$ref":"#/components/schemas/Customer"},"links":{"description":"Address book (customers linked to you)","items":{"$ref":"#/components/schemas/CustomerSummary"},"type":"array"},"specialDates":{"description":"Special dates","items":{"$ref":"#/components/schemas/CustomerSpecialDate"},"type":"array"}},"required":["customer","contacts","links"],"type":"object"},"CustomerSpecialDate":{"allOf":[{"$ref":"#/components/schemas/CustomerSpecialDateInput"},{"properties":{"id":{"format":"uuid","type":"string"}},"required":["id"],"type":"object"}]},"CustomerSpecialDateInput":{"properties":{"day":{"maximum":31,"minimum":1,"type":"integer"},"label":{"description":"E.g. Company anniversary","maxLength":100,"minLength":1,"type":"string"},"month":{"maximum":12,"minimum":1,"type":"integer"},"year":{"description":"First year, if known","maximum":2200,"minimum":1900,"type":"integer"}},"required":["label","month","day"],"type":"object"},"CustomerSpecialDatesInput":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CustomerSpecialDateInput"},"maxItems":20,"type":"array"}},"required":["items"],"type":"object"},"CustomerStatus":{"description":"active: active; inactive: inactive; pending: awaiting company approval (cannot place orders)","enum":["active","inactive","pending"],"type":"string"},"CustomerSummary":{"properties":{"address":{"type":"string"},"code":{"type":"string"},"districtId":{"format":"uuid","type":"string"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/CustomerStatus"}},"required":["id","name","status"],"type":"object"},"Decimal":{"description":"Decimal number as a string (to avoid rounding errors), e.g. \"12.50\"","example":"12.50","pattern":"^-?[0-9]{1,10}(\\.[0-9]{1,6})?$","type":"string"},"DeliveryAttempt":{"description":"A failed delivery record.","properties":{"accuracy":{"format":"float","type":"number"},"at":{"format":"date-time","type":"string"},"byUser":{"format":"uuid","type":"string"},"courierId":{"format":"uuid","type":"string"},"lat":{"format":"double","type":"number"},"lng":{"format":"double","type":"number"},"note":{"type":"string"},"reason":{"$ref":"#/components/schemas/DeliveryFailReason"},"recordedAt":{"description":"When it reached the server (may be later than `at` for offline records)","format":"date-time","type":"string"},"seq":{"type":"integer"}},"required":["seq","at","reason","note"],"type":"object"},"DeliveryCodePolicy":{"description":"Delivery code rule: inherit uses the company setting, on always required, off not required.","enum":["inherit","on","off"],"type":"string"},"DeliveryCodeState":{"description":"Delivery code status. The code itself never appears in any response; it is sent only to the recipient by SMS/e-mail.","properties":{"attemptsLeft":{"type":"integer"},"failedAttempts":{"type":"integer"},"lastSentAt":{"format":"date-time","type":"string"},"override":{"$ref":"#/components/schemas/VerifyOverride"},"required":{"type":"boolean"},"sentCount":{"description":"Total sends (including the first code)","type":"integer"},"status":{"enum":["none","pending","sent","locked","verified","overridden"],"type":"string"},"verifiedAt":{"format":"date-time","type":"string"}},"required":["required","status","sentCount","failedAttempts","attemptsLeft"],"type":"object"},"DeliveryFailReason":{"description":"recipient_absent: recipient not present; wrong_address: wrong address; refused: refused delivery; unreachable: could not be reached; closed: business closed; other: other","enum":["recipient_absent","wrong_address","refused","unreachable","closed","other"],"type":"string"},"DeliveryTypeOption":{"description":"Delivery type.","properties":{"fullName":{"type":"string"},"id":{"format":"uuid","type":"string"},"isRoundTrip":{"description":"Round trip (has a return leg from the recipient)","type":"boolean"},"name":{"type":"string"}},"required":["id","name","isRoundTrip"],"type":"object"},"DiscountKind":{"description":"percent: percentage of the VAT-inclusive total; amount: fixed VAT-inclusive amount (cannot exceed the total)","enum":["percent","amount"],"type":"string"},"DistrictOption":{"description":"District.","properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"}},"required":["id","name"],"type":"object"},"EInvoice":{"description":"An issued invoice.","properties":{"createdAt":{"format":"date-time","type":"string"},"currencyCode":{"type":"string"},"customerId":{"format":"uuid","type":"string"},"customerName":{"type":"string"},"error":{"description":"Reason, if it could not be issued","type":"string"},"id":{"format":"uuid","type":"string"},"issuedAt":{"format":"date-time","type":"string"},"kind":{"description":"e-Invoice or e-Archive","enum":["e_invoice","e_archive"],"type":"string"},"net":{"$ref":"#/components/schemas/Decimal"},"orderIds":{"items":{"format":"uuid","type":"string"},"type":"array"},"orderNumbers":{"items":{"format":"int64","type":"integer"},"type":"array"},"status":{"$ref":"#/components/schemas/EInvoiceStatus"},"total":{"$ref":"#/components/schemas/Decimal"},"vat":{"$ref":"#/components/schemas/Decimal"}},"required":["id","customerId","customerName","orderIds","orderNumbers","status","currencyCode","net","vat","total","error","createdAt"],"type":"object"},"EInvoicePage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/EInvoice"},"type":"array"},"total":{"type":"integer"}},"required":["items","total"],"type":"object"},"EInvoiceStatus":{"description":"queued: queued; processing: being issued; issued: issued; failed: could not be issued","enum":["queued","processing","issued","failed"],"type":"string"},"EcommerceCancelState":{"description":"Store cancellation: '' no cancellation; pending cancellation of the Courino order is queued; cancelled\nthe Courino order was cancelled (or was never created); manual the courier had picked up the parcel or\nthe cancellation was refused, decide manually (`issue`); finished the Courino order had already been\ndelivered / returned to sender (unchanged); off cancelled while sync was off (Courino order unchanged).","enum":["","pending","cancelled","manual","finished","off"],"type":"string"},"EcommerceConnection":{"properties":{"branchId":{"description":"Branch of the connection; null = company-wide","format":"uuid","nullable":true,"type":"string"},"branchName":{"description":"Branch name (empty when company-wide)","type":"string"},"cancelManualCount":{"description":"Cancelled in the store and awaiting a manual decision (cancelState=manual)","type":"integer"},"createdAt":{"format":"date-time","type":"string"},"customerId":{"format":"uuid","type":"string"},"customerName":{"type":"string"},"errorCount":{"description":"Number of consecutive failed syncs","type":"integer"},"failedCount":{"type":"integer"},"id":{"format":"uuid","type":"string"},"importedCount":{"type":"integer"},"lastError":{"type":"string"},"lastSyncAt":{"format":"date-time","nullable":true,"type":"string"},"name":{"type":"string"},"needsAuthorization":{"description":"Store authorization (IdeaSoft) is pending or has become invalid: no orders are received; authorize from the customer portal","type":"boolean"},"pendingCount":{"type":"integer"},"platform":{"$ref":"#/components/schemas/EcommercePlatform"},"settings":{"$ref":"#/components/schemas/EcommerceSettings"},"status":{"enum":["active","paused"],"type":"string"},"storeUrl":{"type":"string"},"updatedAt":{"format":"date-time","type":"string"},"webhookRegistered":{"type":"boolean"}},"required":["id","customerId","customerName","platform","name","storeUrl","status","settings","webhookRegistered","needsAuthorization","lastError","errorCount","pendingCount","failedCount","importedCount","cancelManualCount","createdAt","updatedAt"],"type":"object"},"EcommerceEvent":{"properties":{"createdAt":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"kind":{"enum":["webhook","poll","import","writeback","test","setup","cancel"],"type":"string"},"level":{"description":"info | error","type":"string"},"message":{"type":"string"},"recordId":{"format":"uuid","nullable":true,"type":"string"}},"required":["id","level","kind","message","createdAt"],"type":"object"},"EcommerceFix":{"properties":{"address":{"maxLength":500,"type":"string"},"districtId":{"format":"uuid","nullable":true,"type":"string"},"name":{"maxLength":200,"type":"string"},"phone":{"maxLength":30,"type":"string"}},"type":"object"},"EcommerceOrder":{"properties":{"attempts":{"type":"integer"},"branchId":{"description":"Branch of the connection (null = company-wide)","format":"uuid","nullable":true,"type":"string"},"cancelState":{"$ref":"#/components/schemas/EcommerceCancelState"},"cancelledAt":{"description":"When the cancellation in the store was seen","format":"date-time","nullable":true,"type":"string"},"codAmount":{"description":"Cash on delivery amount (written to the order note)","nullable":true,"type":"string"},"connectionId":{"format":"uuid","type":"string"},"connectionName":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"customerId":{"format":"uuid","type":"string"},"districtId":{"format":"uuid","nullable":true,"type":"string"},"externalId":{"type":"string"},"externalNumber":{"type":"string"},"fix":{"$ref":"#/components/schemas/EcommerceFix"},"id":{"format":"uuid","type":"string"},"issue":{"type":"string"},"issueKind":{"description":"'' | address | validation | error | area (recipient is outside the company's service area; no Courino order is created)","type":"string"},"orderId":{"format":"uuid","nullable":true,"type":"string"},"orderNumber":{"format":"int64","nullable":true,"type":"integer"},"payloadPurgedAt":{"description":"If set, the parsed data of the store order was deleted because the retention period (default 90 days)\nended: the `store` fields are empty and only `districtId` remains in `fix`. resolve/retry returns 409\nfor such a record.","format":"date-time","nullable":true,"type":"string"},"platform":{"$ref":"#/components/schemas/EcommercePlatform"},"status":{"$ref":"#/components/schemas/EcommerceOrderStatus"},"store":{"$ref":"#/components/schemas/EcommerceStoreOrder"},"updatedAt":{"format":"date-time","type":"string"},"writebackError":{"type":"string"},"writebackStage":{"enum":["","picked_up","delivered"],"type":"string"}},"required":["id","connectionId","connectionName","platform","customerId","externalId","externalNumber","status","issueKind","issue","store","attempts","writebackStage","writebackError","cancelState","createdAt","updatedAt"],"type":"object"},"EcommerceOrderPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/EcommerceOrder"},"type":"array"},"serviceProvinces":{"description":"Provinces the company delivers to. Empty: unknown; then no province check is made.","items":{"type":"string"},"type":"array"},"total":{"type":"integer"}},"required":["items","total","serviceProvinces"],"type":"object"},"EcommerceOrderStatus":{"enum":["received","importing","imported","pending","failed","skipped"],"type":"string"},"EcommercePlatform":{"description":"Platform of the store.","enum":["woocommerce","shopify","trendyol","hepsiburada","n11","ciceksepeti","sentos","entegra","ideasoft","ikas","ticimax"],"type":"string"},"EcommerceResolveInput":{"properties":{"address":{"maxLength":500,"type":"string"},"districtId":{"format":"uuid","nullable":true,"type":"string"},"name":{"maxLength":200,"type":"string"},"phone":{"maxLength":30,"type":"string"},"remember":{"description":"Remember this province/district/area spelling for the customer","type":"boolean"}},"type":"object"},"EcommerceSettings":{"description":"Mapping settings (changed in the customer portal). `triggerStatuses`: store statuses to import.\nWith `autoImport=false` every order goes to awaiting match and is confirmed manually. Cash on delivery\n(`codMethods` payment methods) is written to the order note as the amount to collect. `writeback`:\npicked up / delivered is written back to the store. `carriers`: only parcels assigned to this carrier\nare imported (marketplaces; empty = all).","properties":{"autoImport":{"type":"boolean"},"cancelSync":{"description":"Store cancellation sync: an order cancelled in the store is also cancelled in Courino if the courier has not picked up the parcel; otherwise a manual decision warning (cancelState=manual) is written to the record.","type":"boolean"},"carriers":{"description":"Carrier filter (contains match; empty = all)","items":{"maxLength":100,"type":"string"},"maxItems":10,"type":"array"},"codEnabled":{"type":"boolean"},"codMethods":{"items":{"maxLength":100,"type":"string"},"maxItems":10,"type":"array"},"deliveryTypeId":{"format":"uuid","type":"string"},"notifyCustomer":{"description":"Shopify: e-mail the store customer on fulfillment","type":"boolean"},"parcelCount":{"maximum":99,"minimum":1,"type":"integer"},"parcelMode":{"description":"single | per_item | fixed","type":"string"},"payRecipient":{"description":"The recipient pays the fee","type":"boolean"},"paymentMethod":{"enum":["","cash","bank_transfer","card","wallet","account"],"type":"string"},"pickupAddress":{"description":"If empty, the customer's saved address","maxLength":500,"type":"string"},"pickupDistrictId":{"description":"If empty, the customer's saved district","format":"uuid","nullable":true,"type":"string"},"triggerStatuses":{"items":{"maxLength":100,"type":"string"},"maxItems":10,"type":"array"},"writeback":{"type":"boolean"},"writebackStatus":{"maxLength":40,"type":"string"}},"required":["triggerStatuses","autoImport","deliveryTypeId","payRecipient","parcelMode","parcelCount","codEnabled","codMethods","writeback","notifyCustomer"],"type":"object"},"EcommerceStoreOrder":{"description":"Summary of the order in the store (recipient and address)","properties":{"address":{"type":"string"},"city":{"type":"string"},"currency":{"type":"string"},"email":{"type":"string"},"gateway":{"type":"string"},"items":{"type":"integer"},"name":{"type":"string"},"note":{"type":"string"},"phone":{"type":"string"},"postcode":{"type":"string"},"province":{"type":"string"},"status":{"type":"string"},"total":{"type":"string"}},"required":["status","gateway","total","currency","name","phone","address","city","province","items"],"type":"object"},"ImportIssue":{"description":"A validation issue in a row.","properties":{"field":{"description":"Column: recipient_name, recipient_phone, province, district, area, address, delivery_type, parcels, barcodes, reference, weight_kg, notes","type":"string"},"message":{"type":"string"}},"required":["field","message"],"type":"object"},"LocationCheck":{"description":"Location check at the courier's pickup/delivery step.","properties":{"accuracy":{"format":"float","type":"number"},"at":{"format":"date-time","type":"string"},"courierId":{"format":"uuid","type":"string"},"distanceM":{"type":"integer"},"lat":{"format":"double","type":"number"},"lng":{"format":"double","type":"number"},"mode":{"$ref":"#/components/schemas/LocationCheckMode"},"overridden":{"description":"Accepted through a company exception","type":"boolean"},"radiusM":{"type":"integer"},"result":{"$ref":"#/components/schemas/LocationResult"},"source":{"description":"Source of the location (sent with the step, or the last known location)","enum":["step","last_known","none"],"type":"string"},"step":{"enum":["pickup","delivery"],"type":"string"},"targetLat":{"format":"double","type":"number"},"targetLng":{"format":"double","type":"number"}},"required":["step","at","mode","result","radiusM","source","overridden"],"type":"object"},"LocationCheckMode":{"description":"Location check: off disabled; warn warns; block blocks the step outside the radius.","enum":["off","warn","block"],"type":"string"},"LocationResult":{"description":"ok: within the radius; outside: outside it; low_accuracy: within it but location accuracy is low; no_location: no courier location; no_coords: the address has no coordinates (check skipped)","enum":["ok","outside","low_accuracy","no_location","no_coords"],"type":"string"},"MyOrderTracking":{"description":"Live tracking information for an order.","properties":{"companyPhone":{"description":"The courier company's phone number","type":"string"},"courierName":{"description":"The courier's full name (if given to a courier and not yet delivered)","type":"string"},"expectedAt":{"description":"Estimated delivery (if the company has enabled this feature)","format":"date-time","type":"string"},"location":{"description":"The courier's latest location (only while the shipment is on the way and the location is recent)","properties":{"at":{"format":"date-time","type":"string"},"lat":{"format":"double","type":"number"},"lng":{"format":"double","type":"number"}},"required":["lat","lng","at"],"type":"object"},"status":{"$ref":"#/components/schemas/OrderStatus"}},"required":["status","companyPhone"],"type":"object"},"NotificationEvent":{"description":"Webhook event: order.created (created), order.assigned (given to a courier), order.reassigned (courier\nchanged), order.returned_to_pool (taken back from the courier), order.picked_up (picked up),\norder.return_leg (on the return leg), order.delivered (delivered), order.delivery_reverted (delivery\nundone), order.cancelled (cancelled), order.restored (restored after cancellation),\norder.delivery_failed (delivery failed), order.returning (being returned), order.returned (returned),\norder.return_reverted (return undone), order.approval_requested (awaiting approval), order.approved\n(approved), order.rejected (rejected), order.at_hub (at the hub), order.hub_transfer (in transfer\nbetween hubs).","enum":["order.created","order.assigned","order.reassigned","order.returned_to_pool","order.picked_up","order.return_leg","order.delivered","order.delivery_reverted","order.cancelled","order.restored","order.delivery_failed","order.returning","order.returned","order.return_reverted","order.approval_requested","order.approved","order.rejected","order.at_hub","order.hub_transfer"],"type":"string"},"OnlinePaymentStatus":{"enum":["pending","succeeded","failed","expired"],"type":"string"},"Order":{"description":"Order.","properties":{"assignedAt":{"description":"When it was given to a courier","format":"date-time","type":"string"},"branchId":{"description":"The order's branch","format":"uuid","type":"string"},"cancelReason":{"description":"Cancellation reason","type":"string"},"cancelledAt":{"description":"When it was cancelled","format":"date-time","type":"string"},"cod":{"$ref":"#/components/schemas/OrderCod"},"courierId":{"description":"The courier carrying the order","format":"uuid","type":"string"},"createdAt":{"format":"date-time","type":"string"},"customerId":{"description":"Sending customer","format":"uuid","type":"string"},"customerTypeId":{"description":"Customer type used for pricing","format":"uuid","type":"string"},"deliveredAt":{"description":"When it was delivered","format":"date-time","type":"string"},"deliveryAttempts":{"description":"Failed delivery records (in order)","items":{"$ref":"#/components/schemas/DeliveryAttempt"},"type":"array"},"deliveryCode":{"$ref":"#/components/schemas/DeliveryCodeState"},"deliveryTypeId":{"format":"uuid","type":"string"},"firstLegDeliveredAt":{"description":"Delivery time of the outbound leg of a round trip","format":"date-time","type":"string"},"firstLegReceiver":{"description":"Who received the outbound leg","type":"string"},"hubAt":{"description":"When it entered the hub (left it, for transfers)","format":"date-time","type":"string"},"hubId":{"description":"The hub the order is at or last passed through","format":"uuid","type":"string"},"hubShelf":{"description":"Shelf at the hub","type":"string"},"id":{"format":"uuid","type":"string"},"isRoundTrip":{"description":"Round trip","type":"boolean"},"locationChecks":{"description":"Location checks of the pickup/delivery steps","items":{"$ref":"#/components/schemas/LocationCheck"},"type":"array"},"locationFlag":{"$ref":"#/components/schemas/LocationResult"},"locationOverride":{"$ref":"#/components/schemas/VerifyOverride"},"notes":{"type":"string"},"number":{"description":"Order number (increasing within the company)","format":"int64","type":"integer"},"parcels":{"description":"Parcels (may be empty for very old orders)","items":{"$ref":"#/components/schemas/Parcel"},"type":"array"},"payer":{"description":"The paying party","enum":["sender","pickup","recipient"],"type":"string"},"payerCustomerId":{"description":"Paying customer","format":"uuid","type":"string"},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"},"pickedUpAt":{"description":"When the courier picked up the shipment","format":"date-time","type":"string"},"pickupCourierId":{"description":"For hub deliveries, the courier who picked up the shipment and dropped it at the hub","format":"uuid","type":"string"},"plannedPickupAt":{"description":"Planned pickup time","format":"date-time","type":"string"},"price":{"$ref":"#/components/schemas/Quote"},"priceListId":{"description":"Price list used for pricing","format":"uuid","type":"string"},"receiverCompany":{"description":"Receiving company","type":"string"},"receiverName":{"description":"Person who received it","type":"string"},"reference":{"description":"Your reference number","type":"string"},"source":{"description":"How the order was created (never changes): panel (company staff), portal (customer portal/app), api (API key), ecommerce (e-commerce import), import (bulk upload), legacy (migrated from the old system), schedule (scheduled job)","enum":["panel","portal","api","ecommerce","import","legacy","schedule"],"readOnly":true,"type":"string"},"status":{"$ref":"#/components/schemas/OrderStatus"},"stops":{"description":"Stops: sender, pickup point (if any) and recipient","items":{"$ref":"#/components/schemas/OrderStop"},"type":"array"},"version":{"description":"Version; send it back when editing (concurrent change check)","type":"integer"},"volumeM3":{"$ref":"#/components/schemas/Decimal"},"waitMinutes":{"$ref":"#/components/schemas/Decimal"},"weightKg":{"$ref":"#/components/schemas/Decimal"}},"required":["id","number","status","version","payer","deliveryTypeId","isRoundTrip","plannedPickupAt","waitMinutes","weightKg","volumeM3","notes","paymentMethod","reference","createdAt","stops","price","branchId","source"],"type":"object"},"OrderAttachment":{"description":"An image attached to the order.","properties":{"accuracy":{"description":"Location accuracy (metres)","format":"float","type":"number"},"capturedAt":{"description":"When it was taken","format":"date-time","type":"string"},"contentType":{"type":"string"},"createdAt":{"description":"When it was uploaded to the server","format":"date-time","type":"string"},"height":{"type":"integer"},"id":{"format":"uuid","type":"string"},"kind":{"description":"pickup: pickup; delivery: delivery; signature: signature; failure: failed delivery; other: other","enum":["pickup","delivery","signature","failure","other"],"type":"string"},"lat":{"description":"Latitude where it was taken","format":"double","type":"number"},"lng":{"description":"Longitude where it was taken","format":"double","type":"number"},"size":{"description":"Bytes","type":"integer"},"uploadedBy":{"format":"uuid","type":"string"},"width":{"type":"integer"}},"required":["id","kind","contentType","size","width","height","createdAt"],"type":"object"},"OrderBatchRow":{"description":"One row (recipient) of a bulk order.","properties":{"address":{"maxLength":500,"type":"string"},"area":{"description":"District name (if there is no `areaId`); disambiguate districts with the same name using `district`/`province`","maxLength":200,"type":"string"},"areaId":{"description":"District ID (`GET /me/order-options`)","format":"uuid","type":"string"},"barcodes":{"description":"Your parcel barcodes (in parcel order)","items":{"maxLength":40,"type":"string"},"maxItems":99,"type":"array"},"deliveryType":{"description":"Delivery type name (if there is no `deliveryTypeId`)","maxLength":100,"type":"string"},"deliveryTypeId":{"description":"Delivery type ID","format":"uuid","type":"string"},"district":{"description":"Town (ilçe)","maxLength":100,"type":"string"},"notes":{"maxLength":1000,"type":"string"},"parcels":{"description":"Number of parcels (default 1)","maximum":99,"minimum":1,"type":"integer"},"province":{"description":"Province (il)","maxLength":100,"type":"string"},"recipientName":{"maxLength":200,"type":"string"},"recipientPhone":{"maxLength":40,"type":"string"},"reference":{"description":"Your reference number; the row is skipped if an order with the same number exists","maxLength":100,"type":"string"},"weightKg":{"description":"Weight (kg) as a decimal string (e.g. \"2.5\")","maxLength":20,"type":"string"}},"required":["recipientName","recipientPhone","address"],"type":"object"},"OrderCod":{"description":"Cash on delivery for the order (separate from the delivery fee, collected on your behalf).","properties":{"amount":{"$ref":"#/components/schemas/Decimal"},"collectedAt":{"format":"date-time","type":"string"},"currency":{"type":"string"},"dueOn":{"description":"Due date of the payout to you","format":"date","type":"string"},"fee":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Cash on delivery service fee"},"linkAvailable":{"description":"The recipient can pay by card via a payment link (QR)","type":"boolean"},"method":{"$ref":"#/components/schemas/CodMethod"},"status":{"$ref":"#/components/schemas/CodStatus"}},"required":["amount","currency","status","fee"],"type":"object"},"OrderImport":{"description":"A bulk order upload.","properties":{"createdAt":{"format":"date-time","type":"string"},"createdRows":{"description":"Rows for which an order was created","type":"integer"},"customerId":{"format":"uuid","type":"string"},"customerName":{"type":"string"},"error":{"type":"string"},"failedRows":{"description":"Rows that could not be created","type":"integer"},"filename":{"type":"string"},"finishedAt":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"rows":{"description":"Rows (only when reading a single upload)","items":{"$ref":"#/components/schemas/OrderImportRow"},"type":"array"},"skippedRows":{"description":"Rows skipped as duplicates","type":"integer"},"source":{"enum":["staff","customer","api"],"type":"string"},"startedAt":{"format":"date-time","type":"string"},"status":{"description":"preview: preview (dryRun); queued: queued; running: creating; done: finished; failed: failed; discarded: discarded","enum":["preview","queued","running","done","failed","discarded"],"type":"string"},"totalRows":{"type":"integer"},"validRows":{"description":"Valid rows","type":"integer"}},"required":["id","customerId","customerName","source","filename","status","totalRows","validRows","createdRows","skippedRows","failedRows","error","createdAt"],"type":"object"},"OrderImportRow":{"description":"The result of one row of an upload.","properties":{"address":{"type":"string"},"area":{"type":"string"},"areaId":{"format":"uuid","type":"string"},"areaLabel":{"type":"string"},"barcodes":{"items":{"type":"string"},"type":"array"},"deliveryTypeId":{"format":"uuid","type":"string"},"deliveryTypeName":{"type":"string"},"district":{"type":"string"},"duplicateOrderNumber":{"description":"Existing order with the same reference/barcode (the row is skipped)","format":"int64","type":"integer"},"issues":{"description":"Validation issues","items":{"$ref":"#/components/schemas/ImportIssue"},"type":"array"},"message":{"description":"Reason the row was not created / was skipped","type":"string"},"no":{"description":"Row number (starts at 1 in the array you sent; in a file, the header is row 1)","type":"integer"},"notes":{"type":"string"},"orderId":{"format":"uuid","type":"string"},"orderNumber":{"description":"Number of the created order","format":"int64","type":"integer"},"parcels":{"type":"integer"},"province":{"type":"string"},"recipientName":{"type":"string"},"recipientPhone":{"type":"string"},"reference":{"type":"string"},"status":{"description":"invalid: invalid; pending: waiting; created: created; skipped: skipped; failed: could not be created","enum":["invalid","pending","created","skipped","failed"],"type":"string"},"weightKg":{"type":"string"}},"required":["no","status","recipientName","recipientPhone","area","address","parcels","barcodes","reference","weightKg","notes","issues","message"],"type":"object"},"OrderOptions":{"description":"Order options.","properties":{"businessHours":{"$ref":"#/components/schemas/BusinessHours"},"deliveryTypes":{"description":"Active delivery types","items":{"$ref":"#/components/schemas/DeliveryTypeOption"},"type":"array"},"districts":{"description":"Active districts","items":{"$ref":"#/components/schemas/DistrictOption"},"type":"array"}},"required":["districts","deliveryTypes"],"type":"object"},"OrderPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/Order"},"type":"array"},"total":{"description":"Total number of records matching the filters","type":"integer"}},"required":["items","total"],"type":"object"},"OrderParty":{"allOf":[{"$ref":"#/components/schemas/QuoteParty"},{"properties":{"address":{"description":"Full address","maxLength":500,"type":"string"},"lat":{"description":"Latitude of the address (optional; together with `lng`)","format":"double","maximum":90,"minimum":-90,"type":"number"},"lng":{"description":"Longitude of the address","format":"double","maximum":180,"minimum":-180,"type":"number"},"name":{"description":"Full name / company name; defaults to the customer's name if `customerId` is given","maxLength":200,"type":"string"},"notifyContactIds":{"description":"Contacts who receive delivery notifications for this party. If omitted, all active contacts; if an empty list is sent, none.","items":{"format":"uuid","type":"string"},"maxItems":50,"type":"array"},"phone":{"$ref":"#/components/schemas/Phone"}},"type":"object"}],"description":"One party of the order (sender, pickup point or recipient)."},"OrderStatus":{"description":"pending_approval: awaiting company approval; on_table: waiting for a courier; assigned: given to a\ncourier; picked_up: picked up, on the way; return_leg: on the return leg of a round trip; delivered:\ndelivered; cancelled: cancelled; delivery_failed: delivery failed; returning: being returned;\nreturned: returned; at_hub: at the hub; in_transfer: in transfer between hubs","enum":["pending_approval","on_table","assigned","picked_up","return_leg","delivered","cancelled","delivery_failed","returning","returned","at_hub","in_transfer"],"type":"string"},"OrderStop":{"description":"A stop of the order.","properties":{"address":{"type":"string"},"contactIds":{"description":"Contacts who receive notifications","items":{"format":"uuid","type":"string"},"type":"array"},"customerId":{"format":"uuid","type":"string"},"districtId":{"description":"District (may be empty for very old orders)","format":"uuid","type":"string"},"districtName":{"description":"District name","type":"string"},"lat":{"format":"double","type":"number"},"lng":{"format":"double","type":"number"},"name":{"type":"string"},"phone":{"type":"string"},"regionNo":{"description":"Pricing region number","type":"integer"},"role":{"description":"sender: sender; pickup: pickup point; recipient: recipient","enum":["sender","pickup","recipient"],"type":"string"}},"required":["role","name","address","districtName","regionNo"],"type":"object"},"Parcel":{"description":"Parcel.","properties":{"barcode":{"type":"string"},"deliveryScannedAt":{"description":"When the courier scanned it at delivery","format":"date-time","type":"string"},"description":{"type":"string"},"external":{"description":"The barcode is yours (not generated by the system)","type":"boolean"},"id":{"format":"uuid","type":"string"},"pickupScannedAt":{"description":"When the courier scanned it at pickup","format":"date-time","type":"string"},"seq":{"description":"Parcel sequence (starts at 1)","type":"integer"}},"required":["id","seq","barcode","external","description"],"type":"object"},"ParcelInput":{"properties":{"barcode":{"description":"Your own barcode (unique within the company; the `<number>-<number>` format is reserved for the system)","pattern":"^[A-Za-z0-9._/-]{3,40}$","type":"string"},"description":{"description":"Parcel contents / description","maxLength":200,"type":"string"}},"type":"object"},"Payment":{"properties":{"amount":{"$ref":"#/components/schemas/Decimal"},"autopayFallback":{"description":"The primary card was declined, so it was charged to your other saved card with your backup card consent","type":"boolean"},"checkoutExpiresAt":{"format":"date-time","type":"string"},"checkoutUrl":{"description":"Page of the pending payment","type":"string"},"codOrderId":{"description":"kind=cod: ID of the order paid by card at the door","format":"uuid","type":"string"},"collector":{"description":"Who collected: firm the company, platform Courino","enum":["firm","platform"],"type":"string"},"completedAt":{"format":"date-time","type":"string"},"createdAt":{"format":"date-time","type":"string"},"currency":{"type":"string"},"customerFee":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Card payment service fee charged to you; `amount` includes it. Omitted if there is none."},"customerId":{"format":"uuid","type":"string"},"description":{"type":"string"},"failureCode":{"type":"string"},"failureMessage":{"type":"string"},"id":{"format":"uuid","type":"string"},"installments":{"type":"integer"},"kind":{"enum":["charges","wallet_topup","cod"],"type":"string"},"orderIds":{"items":{"format":"uuid","type":"string"},"type":"array"},"paidAmount":{"$ref":"#/components/schemas/Decimal"},"provider":{"type":"string"},"providerOrderId":{"description":"Order number at the payment institution (only for Courino collections)","type":"string"},"providerPaymentId":{"description":"ID at the payment service (only for Courino collections)","type":"string"},"providerRef":{"description":"Courino payment number","type":"string"},"refundedAmount":{"$ref":"#/components/schemas/Decimal"},"refunds":{"items":{"$ref":"#/components/schemas/PaymentRefund"},"type":"array"},"status":{"$ref":"#/components/schemas/OnlinePaymentStatus"},"storedCard":{"description":"Charged to your saved card (without a payment page)","type":"boolean"},"test":{"type":"boolean"}},"required":["id","kind","customerId","provider","amount","currency","status","paidAmount","refundedAmount","installments","test","description","orderIds","checkoutExpiresAt","createdAt"],"type":"object"},"PaymentMethod":{"description":"cash: cash (on delivery); bank_transfer: bank transfer; card: credit card; wallet: prepaid credit\n(wallet); account: on account (invoiced later). If omitted: prepaid credit for prepaid customers, on\naccount for subscribers, cash otherwise. Prepaid credit is only valid for prepaid customers, and\nrequired for them.","enum":["cash","bank_transfer","card","wallet","account"],"type":"string"},"PaymentPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/Payment"},"type":"array"},"total":{"type":"integer"}},"required":["items","total"],"type":"object"},"PaymentRefund":{"properties":{"amount":{"$ref":"#/components/schemas/Decimal"},"completedAt":{"format":"date-time","type":"string"},"createdAt":{"format":"date-time","type":"string"},"failureMessage":{"type":"string"},"id":{"format":"uuid","type":"string"},"reason":{"type":"string"},"status":{"enum":["pending","succeeded","failed"],"type":"string"}},"required":["id","amount","status","reason","createdAt"],"type":"object"},"PaymentStatus":{"description":"paid: paid; unpaid: unpaid","enum":["paid","unpaid"],"type":"string"},"Phone":{"description":"Free format on input (0532 123 45 67, +90532…); E.164 in responses (+905321234567)","maxLength":30,"type":"string"},"Problem":{"description":"Error body (RFC 7807).","properties":{"code":{"description":"Machine-readable error code. It is an open set; handle codes you do not recognise by their HTTP status.","type":"string"},"detail":{"description":"Human-readable explanation (in the Accept-Language language)","type":"string"},"details":{"additionalProperties":true,"description":"Additional machine-readable details specific to the error","type":"object"},"error":{"description":"Short error key (external contract). `support_session`: the action is blocked in a cockpit\n\"connect to account\" session (403; password, contact details, API keys, account deletion, card, payment).","type":"string"},"errors":{"description":"Field-level validation issues","items":{"properties":{"field":{"type":"string"},"message":{"type":"string"}},"required":["field","message"],"type":"object"},"type":"array"},"status":{"description":"HTTP status code","type":"integer"},"title":{"type":"string"},"traceId":{"description":"Include it in support requests; it lets us find the request in our logs","type":"string"},"type":{"type":"string"}},"required":["type","title","status","code"],"type":"object"},"Quote":{"description":"Price quote and breakdown.","properties":{"algorithmVersion":{"description":"Version of the pricing algorithm that calculated the price","type":"string"},"calculatedTotal":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Total before discount"},"currencyCode":{"type":"string"},"currencyRate":{"$ref":"#/components/schemas/Decimal"},"deliveryMultiplier":{"$ref":"#/components/schemas/Decimal"},"discount":{"allOf":[{"$ref":"#/components/schemas/AppliedDiscount"}],"description":"Applied discount (if any). `total` is the discounted total."},"expectedDeliveryMinutes":{"description":"Expected delivery time (if the company has enabled this feature)","type":"integer"},"fromRegion":{"description":"Origin pricing region","type":"integer"},"lines":{"$ref":"#/components/schemas/QuoteLines"},"nightMultiplier":{"$ref":"#/components/schemas/Decimal"},"tier":{"$ref":"#/components/schemas/Tier"},"toRegion":{"description":"Destination pricing region","type":"integer"},"total":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Total payable, VAT included"},"usesWallet":{"description":"The amount will be deducted from the prepaid credit balance","type":"boolean"},"vatRate":{"$ref":"#/components/schemas/Decimal"},"vatScope":{"description":"VAT scope: all for all items; service_only for the service fee only","enum":["all","service_only"],"type":"string"}},"required":["algorithmVersion","tier","fromRegion","toRegion","deliveryMultiplier","nightMultiplier","vatRate","vatScope","currencyCode","currencyRate","lines","calculatedTotal","total"],"type":"object"},"QuoteLines":{"description":"Price lines (excluding VAT, except `vat`).","properties":{"base":{"$ref":"#/components/schemas/Decimal"},"bridge":{"$ref":"#/components/schemas/Decimal"},"extra":{"$ref":"#/components/schemas/Decimal"},"manualAdjustmentNet":{"$ref":"#/components/schemas/Decimal"},"manualAdjustmentVat":{"$ref":"#/components/schemas/Decimal"},"returnFeeNet":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Return fee (excluding VAT; orders only, included in the total)"},"returnFeeVat":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"VAT on the return fee"},"serviceNet":{"$ref":"#/components/schemas/Decimal"},"vat":{"$ref":"#/components/schemas/Decimal"},"volume":{"$ref":"#/components/schemas/Decimal"},"wait":{"$ref":"#/components/schemas/Decimal"},"weight":{"$ref":"#/components/schemas/Decimal"}},"required":["base","extra","serviceNet","wait","weight","volume","bridge","vat","manualAdjustmentNet","manualAdjustmentVat"],"type":"object"},"QuoteParty":{"description":"A party is given either as a customer from your address book (`customerId`) or as a district\n(`districtId`). If `customerId` is given without a district, the customer's registered district is\nused. The sender is always you: `sender.customerId` may be left empty or must be your own ID.","properties":{"customerId":{"description":"A customer from your address book (`GET /me/customer` → `links`)","format":"uuid","type":"string"},"districtId":{"description":"District (`GET /me/order-options`)","format":"uuid","type":"string"}},"type":"object"},"QuoteRequest":{"description":"Quote request.","properties":{"deliveryTypeId":{"description":"Delivery type (`GET /me/order-options`)","format":"uuid","type":"string"},"payer":{"description":"The paying party: sender, pickup (pickup point) or recipient","enum":["sender","pickup","recipient"],"type":"string"},"pickup":{"$ref":"#/components/schemas/QuoteParty"},"plannedPickupAt":{"description":"Planned pickup time; now if omitted (the night tariff is determined from it)","format":"date-time","type":"string"},"recipient":{"$ref":"#/components/schemas/QuoteParty"},"sender":{"$ref":"#/components/schemas/QuoteParty"},"volumeM3":{"$ref":"#/components/schemas/Decimal"},"waitMinutes":{"$ref":"#/components/schemas/Decimal"},"weightKg":{"$ref":"#/components/schemas/Decimal"}},"required":["payer","sender","recipient","deliveryTypeId"],"type":"object"},"Status":{"enum":["active","inactive"],"type":"string"},"Tier":{"description":"cash: pay as you go; subscriber: subscriber","enum":["cash","subscriber"],"type":"string"},"UpdateOrderRequest":{"properties":{"order":{"allOf":[{"$ref":"#/components/schemas/CreateOrderRequest"}],"description":"The complete new version of the order"},"version":{"description":"The `version` of the order you read","type":"integer"}},"required":["version","order"],"type":"object"},"VerifyOverride":{"properties":{"at":{"format":"date-time","type":"string"},"byUser":{"format":"uuid","type":"string"},"reason":{"type":"string"}},"required":["reason","at"],"type":"object"},"Wallet":{"description":"Prepaid credit (wallet) account.","properties":{"balance":{"$ref":"#/components/schemas/Decimal"},"entries":{"description":"Last 100 transactions","items":{"$ref":"#/components/schemas/WalletEntry"},"type":"array"},"lowBalance":{"description":"The balance is below the company's low-balance threshold","type":"boolean"},"lowBalanceThreshold":{"$ref":"#/components/schemas/Decimal"},"policy":{"$ref":"#/components/schemas/WalletPolicy"}},"required":["balance","entries"],"type":"object"},"WalletEntry":{"properties":{"amount":{"$ref":"#/components/schemas/Decimal"},"createdAt":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"kind":{"description":"topup: top-up; order_charge: order charge; order_refund: refund; adjustment: adjustment; opening_balance: opening balance","enum":["topup","order_charge","order_refund","adjustment","opening_balance"],"type":"string"},"note":{"type":"string"},"orderId":{"format":"uuid","type":"string"}},"required":["id","amount","kind","note","createdAt"],"type":"object"},"WalletNegative":{"description":"Negative balance rule: inherit uses the company setting, allow allowed, deny not allowed","enum":["inherit","allow","deny"],"type":"string"},"WalletPolicy":{"properties":{"allowsNegative":{"description":"Whether the balance may go negative (effective rule)","type":"boolean"},"availableBalance":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Amount available for orders (balance + negative limit); absent when an unlimited negative balance is allowed"},"creditLimit":{"allOf":[{"$ref":"#/components/schemas/Decimal"}],"description":"Negative limit (absolute value); unlimited if absent"},"negative":{"$ref":"#/components/schemas/WalletNegative"}},"required":["negative","allowsNegative"],"type":"object"},"Webhook":{"description":"Webhook subscription.","properties":{"createdAt":{"format":"date-time","type":"string"},"customerId":{"description":"Customer the subscription belongs to","format":"uuid","type":"string"},"description":{"type":"string"},"enabled":{"description":"Whether it is enabled","type":"boolean"},"events":{"description":"Subscribed events","items":{"$ref":"#/components/schemas/NotificationEvent"},"type":"array"},"format":{"$ref":"#/components/schemas/WebhookFormat"},"id":{"format":"uuid","type":"string"},"url":{"description":"URL the events are sent to","type":"string"}},"required":["id","url","events","description","enabled","createdAt","format"],"type":"object"},"WebhookFormat":{"description":"kos: signed JSON (recommended, default). legacy: request compatible with the old system — multipart/form-data with a single field, orderId (the order number).","enum":["kos","legacy"],"type":"string"},"WebhookInput":{"properties":{"description":{"description":"Your own note","maxLength":500,"type":"string"},"enabled":{"description":"If false, no events are sent","type":"boolean"},"events":{"description":"Events to subscribe to (at least one)","items":{"$ref":"#/components/schemas/NotificationEvent"},"minItems":1,"type":"array"},"format":{"$ref":"#/components/schemas/WebhookFormat"},"url":{"description":"The https URL to send events to","maxLength":2000,"type":"string"}},"required":["url","events","enabled"],"type":"object"}},"securitySchemes":{"apiKey":{"bearerFormat":"kosk_…","description":"An API key created in the customer portal under **My company details → Integration (API keys)** (starts with\n`kosk_`). Send it on every request as `Authorization: Bearer kosk_…`.","scheme":"bearer","type":"http"}}}}