Reverse-geocode a coordinate to a human-readable address.

Persian purpose: تبدیل مختصات جغرافیایی به آدرس. On-Demand, requires an access_token. Maps to GET /api/v2/locations?latlng=<lat>,<lng>.

Args: lat: Latitude (-90..90). lng: Longitude (-180..180). instance: Configured instance to use (default when omitted).

Autocomplete address suggestions for a free-text query.

Persian purpose: پیشنهاد آدرس بر اساس متن جست‌وجو. On-Demand, requires an access_token. Maps to GET /api/v2/locations?input=<query>&location=<latlng?>.

Args: input: The partial address / place name to search for. latlng: Optional "lat,lng" bias to rank nearby results first. instance: Configured instance to use (default when omitted).

Calculate the price for a delivery between stops (read-only).

Persian purpose: محاسبه قیمت یک سفارش. On-Demand, requires an access_token. This does NOT create an order. Maps to POST /api/v2/orders/price/calc. The response includes status, price, credit, distance, duration, user_credit, and price_with_return.

Args: transport_type: Vehicle class (e.g. motorbike, motor_taxi, cargo, cargo_s, car). See alopeyk_transport_types. addresses: Ordered stops, each {type, lat, lng} — one type="origin" followed by one or more type="destination". has_return: Whether the courier returns to the origin (default false). cashed: Whether the delivery is cash-on-delivery (default false). optimize: Whether to optimize the multi-stop route (default false). instance: Configured instance to use (default when omitted).

Calculate prices for up to 15 orders in one call (read-only).

Persian purpose: محاسبه قیمت گروهی چند سفارش. On-Demand, requires an access_token. This does NOT create orders. Maps to POST /api/v2/orders/batch-price.

Args: orders: A list (max 15) of order objects, each shaped like the body of alopeyk_get_price (transport_type + addresses + flags). instance: Configured instance to use (default when omitted).

Create a REAL delivery order — WARNING: this is billable.

Persian purpose: ثبت یک سفارش واقعی. On-Demand, requires an access_token AND enable_ordering=true (and read_only=false) on the instance; otherwise it returns {"error": "ordering_disabled", ...} without contacting the API. Maps to POST /api/v2/orders.

Dispatches a courier and charges the account. Confirm the addresses, transport type, and price (via alopeyk_get_price) before calling.

Args: transport_type: Vehicle class (motorbike, motor_taxi, cargo, cargo_s, car). addresses: Ordered stops, each {type, lat, lng} — one origin and one or more destinations. has_return: Whether the courier returns to origin (default false). cashed: Whether the delivery is cash-on-delivery (default false). scheduled_at: Optional ISO timestamp to schedule the pickup. discount_coupon: Optional discount coupon code to apply. instance: Configured instance to use (default when omitted).

Get one order with rich columns (status, courier, ETA) — read-only.

Persian purpose: مشخصات کامل یک سفارش. On-Demand, requires an access_token. Maps to GET /api/v2/orders/{id} with a rich columns set (addresses, progress, courier_info, eta_minimal, ...).

Args: order_id: Numeric id of the order to fetch. instance: Configured instance to use (default when omitted).

Cancel an order — WARNING: this changes a real delivery.

Persian purpose: لغو یک سفارش. On-Demand, requires an access_token AND enable_ordering=true (and read_only=false); otherwise it returns {"error": "ordering_disabled", ...} without contacting the API. Maps to GET /api/v2/orders/{id}/cancel?comment=<c>.

Args: order_id: Numeric id of the order to cancel. comment: Reason / note for the cancellation (required by Alopeyk). instance: Configured instance to use (default when omitted).

Finish/close an order, optionally rating it — WARNING: real delivery.

Persian purpose: اتمام و امتیازدهی به یک سفارش. On-Demand, requires an access_token AND enable_ordering=true (and read_only=false); otherwise it returns {"error": "ordering_disabled", ...} without contacting the API. Maps to POST /api/v2/orders/{id}/finish with body {comment, rate}.

Args: order_id: Numeric id of the order to finish. comment: Optional free-text comment about the delivery. rate: Optional courier rating (typically 1-5). instance: Configured instance to use (default when omitted).

Get the On-Demand service configuration (read-only).

Persian purpose: دریافت تنظیمات سرویس آن‌دیمند. Requires an access_token. Maps to GET /api/v2/config. Returns service-wide settings (pricing params, supported types, limits, ...).

Args: instance: Configured instance to use (default when omitted).

Get the authenticated user's profile and wallet credit (read-only).

Persian purpose: دریافت پروفایل و اعتبار کاربر. Requires an access_token. Maps to GET /api/v2/show-profile?columns=*,credit.

Args: instance: Configured instance to use (default when omitted).

Validate a discount coupon code (read-only).

Persian purpose: بررسی اعتبار کد تخفیف. Requires an access_token. Maps to POST /api/v2/coupons with body {code}.

Args: code: The coupon code to validate. instance: Configured instance to use (default when omitted).

List loyalty products, or buy one — buying is gated by enable_ordering.

Persian purpose: مشاهده محصولات وفاداری یا خرید یک محصول. Requires an access_token. Listing (buy=false) maps to GET /api/v2/loyalty/customer/products/{id?}. Buying (buy=true) maps to POST /api/v2/loyalty/customer/products/{id} and spends loyalty points/credit — it requires enable_ordering=true (and read_only=false), otherwise it returns {"error": "ordering_disabled", ...} without contacting the API.

Args: product_id: Optional loyalty product id (required when buy=true). buy: When true, purchase the product (a real, gated action). instance: Configured instance to use (default when omitted).

Build the public tracking URL for an order token (no network call).

Persian purpose: ساخت لینک رهگیری سفارش. Returns <tracking>#/<token> where the tracking base comes from the instance's environment (production vs sandbox). No request is sent.

Args: order_token: The order's tracking token (from a created order). instance: Configured instance whose tracking base URL to use.

Build the printable invoice URL for an order (no network call).

Persian purpose: ساخت لینک چاپ فاکتور سفارش. Returns a URL on the On-Demand host for printing the order's invoice. No request is sent.

Args: order_id: Numeric id of the order. order_token: The order's token. instance: Configured instance whose On-Demand base URL to use.

Build a wallet top-up payment route URL (no network call).

Persian purpose: ساخت مسیر پرداخت برای شارژ کیف پول. Returns a payment URL on the On-Demand host for the chosen gateway. No request is sent.

Args: user_id: Numeric id of the user to credit. amount: Amount to top up (in the account's currency unit). gateway: Payment gateway, saman or zarinpal (default saman). instance: Configured instance whose On-Demand base URL to use.

List the available transport (vehicle) types (static, no network).

Persian purpose: فهرست انواع وسیله نقلیه. Returns the known transport types used by the pricing/order tools. No request is sent.

Args: instance: Accepted for symmetry; ignored (static data).

List the cities served by Alopeyk On-Demand (static, no network).

Persian purpose: فهرست شهرهای تحت پوشش. Returns the static list of supported city slugs. No request is sent.

Args: instance: Accepted for symmetry; ignored (static data).

Log in to Alonomic and cache the token (no token leaked).

Persian purpose: ورود به سرویس الونومیک و کش‌کردن توکن. Runs the email/password login (POST /business-service/api/v1/login) and caches the returned token in memory for subsequent Alonomic calls. If the instance is configured with a pre-issued alonomic_token instead, it simply reports success. The token value is NEVER returned.

Args: instance: Configured instance to log in (default when omitted).

Returns: {authenticated: true, instance, method} on success, where method is "alonomic_token" or "login"; otherwise a structured error.

Get the Alonomic business account profile and credit (read-only).

Persian purpose: دریافت اطلاعات حساب کاربری الونومیک. Logs in implicitly if needed. Maps to GET /business-service/api/v1/me. Returns {id, name, phone_number, email, credit, final_credit}.

Args: instance: Configured instance to use (default when omitted).

Get today/tomorrow working pickup days (read-only).

Persian purpose: دریافت روزهای کاری امروز و فردا. Maps to GET /business-service/api/v1/days.

Args: instance: Configured instance to use (default when omitted).

Get the next 7 days with same/next-day availability (read-only).

Persian purpose: تقویم ۷ روز آینده با امکان ارسال همان‌روز/روز بعد. Maps to GET /business-service/api/v1/days/index. Each day is shaped like {same: bool, next: bool}.

Args: instance: Configured instance to use (default when omitted).

Create a REAL business parcel — WARNING: this is billable.

Persian purpose: ثبت یک مرسوله واقعی. Requires Alonomic credentials AND enable_ordering=true (and read_only=false); otherwise it returns {"error": "ordering_disabled", ...} without contacting the API. Maps to POST /business-service/api/v1/parcels.

Args: drop: Drop-off, {address: {province, city, lat, lng, address, person_name, person_phone, plate_number, unit_number, postal_code, description}}. parcel: Parcel details, {size:int, barcode?, invoice?, value:int, weight:int, is_packaging_required:0/1, is_label_required:0/1}. pickup: Pickup, {date, date_type:"same"|"next", address: {lat, lng, address, person_name, person_phone, postal_code}}. delivery_proofs: Optional {code, image, signature}. parcel_extra_params: Optional {custom_field_1, custom_field_2}. instance: Configured instance to use (default when omitted).

Get one business parcel by id (read-only).

Persian purpose: دریافت مشخصات یک مرسوله. Maps to GET /business-service/api/v1/parcels/{id}.

Args: parcel_id: Numeric id of the parcel. instance: Configured instance to use (default when omitted).

Update a parcel before final send — WARNING: changes a real parcel.

Persian purpose: ویرایش یک مرسوله پیش از ارسال نهایی. Requires Alonomic credentials AND enable_ordering=true (and read_only=false); otherwise it returns {"error": "ordering_disabled", ...} without contacting the API. Maps to PUT /business-service/api/v1/parcels/{id}. Only fields you pass are sent.

Args: parcel_id: Numeric id of the parcel to update. drop: Optional updated drop-off object. parcel: Optional updated parcel details object. pickup: Optional updated pickup object. delivery_proofs: Optional updated {code, image, signature}. parcel_extra_params: Optional {custom_field_1, custom_field_2}. instance: Configured instance to use (default when omitted).

Cancel a parcel before pickup — WARNING: changes a real parcel.

Persian purpose: لغو یک مرسوله پیش از جمع‌آوری. Requires Alonomic credentials AND enable_ordering=true (and read_only=false); otherwise it returns {"error": "ordering_disabled", ...} without contacting the API. Maps to DELETE /business-service/api/v1/parcels/{id} (HTTP 204 on success).

Args: parcel_id: Numeric id of the parcel to cancel. instance: Configured instance to use (default when omitted).

Estimate a parcel's price and dimensions (read-only).

Persian purpose: محاسبه هزینه و ابعاد یک مرسوله. Does NOT create a parcel. Maps to POST /business-service/api/v1/parcels/calc. The response includes id, length, width, height, worth.

Args: drop: Drop-off, {address: {province, city}} (route end). parcel: {size, value, weight, is_packaging_required?, is_label_required?}. pickup: Optional {date_type, date, address: {province, city}}. instance: Configured instance to use (default when omitted).

List the standard parcel box sizes (read-only).

Persian purpose: فهرست اندازه‌های استاندارد جعبه. Maps to GET /business-service/api/v1/parcels/size (12 box sizes with dimensions).

Args: instance: Configured instance to use (default when omitted).

List saved pickup addresses (read-only).

Persian purpose: فهرست آدرس‌های پیکاپ ذخیره‌شده. Maps to GET /business-service/api/v1/pickup-saved-addresses.

Args: instance: Configured instance to use (default when omitted).

Save a new pickup address.

Persian purpose: افزودن یک آدرس پیکاپ جدید. Maps to POST /business-service/api/v1/pickup-saved-addresses. This manages your address book (not a delivery), so it is NOT gated by enable_ordering.

Args: title: A label for the saved address. lat: Latitude (-90..90). lng: Longitude (-180..180). address: Free-text street address. person_name: Optional contact name at the address. person_phone: Optional contact phone. plate_number: Optional building plate number. unit_number: Optional unit number. postal_code: Optional postal code. instance: Configured instance to use (default when omitted).

Delete a saved pickup address.

Persian purpose: حذف یک آدرس پیکاپ ذخیره‌شده. Maps to DELETE /business-service/api/v1/pickup-saved-addresses/{id} (HTTP 204 on success). Manages the address book, so it is NOT gated by enable_ordering.

Args: address_id: Numeric id of the saved address to delete. instance: Configured instance to use (default when omitted).

List Alonomic parcel status codes and Persian labels (static).

Persian purpose: فهرست وضعیت‌های مرسوله و معنای فارسی آن‌ها. Returns a static map of status code -> Persian label. No request is sent.

Args: instance: Accepted for symmetry; ignored (static data).

Check that Alopeyk is reachable via a lightweight On-Demand call.

Persian purpose: بررسی در دسترس بودن الوپیک. Calls the On-Demand GET /api/v2/config endpoint and reports whether the API responded. Requires an access_token (config is an authenticated endpoint). Returns {reachable: true} on success or a structured error otherwise.

Args: instance: Name of the configured Alopeyk instance. Defaults to the configured default instance when omitted.

List the configured Alopeyk instances (no secrets).

Persian purpose: فهرست نمونه‌های پیکربندی‌شده. Useful for discovering which instance values the other tools accept, which environment each targets, and which credentials/flags are set. Credential values (access_token, email, password, alonomic_token) are NEVER returned — only booleans saying whether they are configured.

Returns: {default_instance, instances: [{name, environment, ondemand_base_url, business_base_url, tracking_url, has_ondemand_credentials, has_alonomic_credentials, alonomic_auth_method, enable_ordering, read_only, ordering_allowed, verify_ssl}]}.

Return offline documentation about both Alopeyk services and the tools.

Persian purpose: راهنمای آفلاین الوپیک و ابزارها. Use this to learn what Alopeyk offers across its On-Demand and Alonomic services and how each tool maps to the underlying API, without making any network call. Links point to https://docs.alopeyk.com.

Args: topic: Optional tool name (e.g. alopeyk_get_price or alonomic_create_parcel) to fetch docs for a single tool. When omitted, returns the service overview plus the full tool list.

Returns: A dict with service metadata and matching tool documentation.