# ProShip Autokey: order intake API Autokey reads delivery orders and keys them into a seller's ProShip account, so nobody retypes them. This page tells you how to hand Autokey an order from your own system or AI assistant. Base URL: https://autokey.proship.co.th ## What the API can and cannot do It can create an order and read an order's status. It cannot edit, cancel or send an order: the seller does those on the Autokey dashboard. ## Authenticate The seller gives you one API key. It looks like `ak_` followed by 40 characters. Send it on every request: `Authorization: Bearer `. A key belongs to one shop and only sees that shop's orders. Keep it secret and never put it in a URL. If a key is missing, wrong or revoked you get 401, and the three cases look the same. ## Send an order as text (POST https://autokey.proship.co.th/api/v1/orders) Send the order exactly as a person would type it in a chat: name, phone, address and a payment line. Autokey reads it with the same reader it uses for the seller's LINE group, in the seller's order format. curl -X POST https://autokey.proship.co.th/api/v1/orders \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"text": "คุณสมชาย ใจดี\n0812345678\n99/1 ถนนสุขุมวิท แขวงคลองเตย เขตคลองเตย กรุงเทพมหานคร 10110\nCOD 450", "client_ref": ""}' Request body: {"text": "คุณสมชาย ใจดี\n0812345678\n99/1 ถนนสุขุมวิท แขวงคลองเตย เขตคลองเตย กรุงเทพมหานคร 10110\nCOD 450", "client_ref": ""} `text` is one order, at most 5000 characters. It may use line breaks and tabs but no other control characters. `client_ref` is optional but strongly advised (see Idempotency). ## Send an order as fields (POST https://autokey.proship.co.th/api/v1/orders) Same endpoint, a different body. Use this when your system already has the parts. curl -X POST https://autokey.proship.co.th/api/v1/orders \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"order": {"name": "สมชาย ใจดี", "phone": "0812345678", "address": "99/1 ถนนสุขุมวิท แขวงคลองเตย เขตคลองเตย กรุงเทพมหานคร 10110", "cod_amount": 450, "products": "2 shirts", "note": "call before delivery"}, "client_ref": ""}' Request body: {"order": {"name": "สมชาย ใจดี", "phone": "0812345678", "address": "99/1 ถนนสุขุมวิท แขวงคลองเตย เขตคลองเตย กรุงเทพมหานคร 10110", "cod_amount": 450, "products": "2 shirts", "note": "call before delivery"}, "client_ref": ""} - `name`, `phone`, `address`: strings. The name is kept as you send it, with whitespace collapsed to single spaces. A name with no letters, or with a phone number or a payment word (COD, ปลายทาง, โอน) in it, goes to review (`name_unclear`). - `phone`: phone numbers only. Other text in the field (for example an extension or a house number) goes to review (`phone_field_has_text`) and is not added to the address. - `cod_amount`: an integer in baht, 0 to 99999. Use 0 when the customer already paid. - `products` and `note`: optional strings. `note` is delivery notes. - Control characters are refused with 400. Zero-width and text-direction characters are removed. - Everything else is checked as for text: one phone number, an address that resolves to one place, a zipcode that agrees. A phone that is not valid, an address that cannot be resolved or is ambiguous, or a COD outside 0 to 99999 does not fail: the order goes to review. ## Response (201 Created) {"reference": "AK-1A2B3C4D", "status": "waiting", "missing": [], "reasons": [], "review_url": "https://autokey.proship.co.th/o/AK-1A2B3C4D"} - `reference`: the order's id. Keep it. - `status`: `waiting` or `needs_review` (all values below). - `missing`: fields Autokey could not read. Empty when nothing is missing. - `reasons`: why the order went to review (codes below). Empty when `status` is `waiting`. - `review_url`: opens the order on the seller's Autokey dashboard. It needs the seller's login, so give it to the seller, not to the customer. ## Check an order (GET https://autokey.proship.co.th/api/v1/orders/) curl https://autokey.proship.co.th/api/v1/orders/AK-1A2B3C4D -H "Authorization: Bearer " {"reference": "AK-1A2B3C4D", "status": "waiting", "tracking_no": null, "created_at": 1790000000} `tracking_no` is null until there is one. `created_at` is unix seconds. A reference that does not exist or belongs to another shop gives 404 with the same body in both cases. ## Status values - `waiting`: read correctly and ready. It is held until the seller sends it. If the seller turned on automatic sending, Autokey sends it by itself. Nothing for you to do. - `needs_review`: Autokey is not sure. A person must look at it. It is never sent on its own. Do not retry it and do not send it again; give the seller the `review_url`. - `sending`: on its way into ProShip. - `sent`: created in ProShip. `tracking_no` appears when there is one. - `blocked`: the order could not be sent. The seller has to act. - `cancelled`: cancelled after it was sent. - `discarded`: the seller dropped it. - `unknown`: it is not certain whether ProShip created it. Never resend; the seller will resolve it. ## Idempotency: client_ref Use your own unique id for each order (for example your order number) as `client_ref`, 1 to 100 characters. Never reuse one for a different order, and never copy the id from this page's examples. - Same `client_ref` and the same order again: 409 `duplicate_client_ref`, with the original `reference` and `status`. It is already stored: treat it as success. - Same `client_ref` but a different order: 409 `client_ref_conflict`, with no reference. The id belongs to a different order and nothing was stored. Send again with a new unique id. ## Duplicates An order with the same phone and the same address as another order in the last 24 hours, whether it came from LINE or from the API, goes to review as `possible_duplicate`. ## Rate limit 60 requests a minute per key. Over that you get 429 with a `Retry-After` header (seconds). Wait that long, then retry. Repeated requests with a wrong key get 429. ## Errors - 400 `bad_request`: the JSON is malformed, both or neither of `text` and `order` were sent, a field has the wrong type or is missing, an unknown field was sent, a string has a control character or is not valid text, or `text` is over 5000 characters. Fix the request. Do not retry it unchanged. - 401 `unauthorized`: the key is missing, wrong or revoked. Ask the seller for a key. - 404 `not_found`: no such reference for this shop. - 409 `duplicate_client_ref` and `client_ref_conflict`: see Idempotency. - 422 `not_an_order`: the text does not look like an order (it needs a name, a phone, an address and a payment line). Nothing was stored. Fix the text. - 429 `rate_limited`: too many requests. Wait for `Retry-After` seconds. - 503 `shop_paused`: the seller paused this shop. Bodies are JSON with `error` and, for most, `detail`. 401 and 404 carry only `error`. A request body over 1 MB gets 413 and an unexpected failure gets 500; both come from the server layer with a plain JSON message and no code from this list. For 503 and any 5xx: retry with the same `client_ref` after a wait, at most 3 times with increasing waits, then stop and tell the seller. ## What sends an order to review Review is a normal outcome, not a failure. Do not retry or rewrite the order because of it: the seller fixes it at `review_url`. The `reasons` codes: - `address_too_long`: the address is too long to trust. - `cod_amount_missing`: COD was named without an amount. - `cod_amount_unclear`: the COD amount is unclear or outside 0 to 99999. - `correction_message`: the text looks like a correction of an earlier order. - `geo_ambiguous`: the address matches several places. - `geo_marker_unmatched`: a tambon, amphoe or province in the address matches no known place. - `header_noisy`: the first line carries payment or date text. - `incomplete`: the order is incomplete in a way no other code names. - `multiple_orders_in_message`: the text holds more than one order. - `multiple_payment_lines`: more than one payment line was found. - `multiple_phones`: more than one phone number was found. - `multiple_zipcodes`: more than one zipcode was found. - `name_unclear`: the name looks like something else (no letters, a phone number or a payment word). - `not_new_order_maybe`: the text may not be a new order (cancel, claim, tracking). - `payment_conflict`: the payment lines contradict each other. - `payment_unclear`: the payment line is unclear. - `phone_field_has_text`: the phone field holds text besides phone numbers. - `phone_line_has_name`: a phone line also carries a name or role. - `possible_duplicate`: same phone and same address as another order in the last 24 hours. - `second_address_block`: a second address follows the first. - `sender_block`: the text has a sender block as well as a recipient. - `tag_name_unsplit`: the customer name could not be told apart from the header. - `text_after_payment`: there is extra text after the payment line. - `zip_mismatch`: the zipcode does not match the tambon, amphoe and province. - `zipcode_unknown`: the zipcode is not a known one. - `missing:name`, `missing:phone`, `missing:address`, `missing:sub_district`, `missing:district`, `missing:province`, `missing:zipcode`, `missing:payment`, `missing:weight`: that field could not be read (`missing:weight`: the shop has no default weight). For every code: do not retry; the seller fixes it. ## Thai addresses Write the address with tambon (ตำบล, or แขวง in Bangkok), amphoe (อำเภอ, or เขต in Bangkok), province (จังหวัด) and a 5-digit zipcode. The names are what Autokey trusts: if the zipcode does not match the tambon, amphoe and province you wrote, the names win and the order goes to review. ## For a seller Treat the key like a password: give it only to the system that will send your orders. Paste this line to your AI assistant: Read https://autokey.proship.co.th/llms.txt and send my orders to ProShip Autokey with this key: