API في to.co
اسمح لبرامجك الخاصة، مثل موقع إلكتروني أو نظام نقاط بيع أو نص برمجي، بقراءة شركتك على to.co وإبقائها محدَّثة. المفاتيح متاحة في Pro وGrow.
- عنوان URL الأساسي
https://api.to.co/v1/orgs/{host}- المصادقة
Authorization: Bearer toco_ak_…
احصل على مفتاح API
افتح شركتك في my.to.co واختر «مفاتيح API»، ثم «إنشاء مفتاح». سمِّه، واختر نطاقاته وتاريخ انتهائه (سنة كحد أقصى)، وانسخه: يُعرض مرة واحدة ولا يُحتفظ إلا بقيمة مُجزَّأة (hash) له.
أرسل المفتاح في ترويسة Authorization مع كل طلب. يعمل المفتاح لشركته فقط: أي عنوان آخر يرد بأنه غير موجود. لا تقبل API إلا المفاتيح، لا جلسة متصفح أبدًا.
مثال على الاستدعاء
curl https://api.to.co/v1/orgs/mybusiness.uk.to.co \
-H "Authorization: Bearer toco_ak_…"
النطاقات والخطط
لا يستطيع المفتاح إلا ما تسمح به نطاقاته، وما تتضمنه خطة الشركة لحظة كل طلب. القراءة متاحة في Pro وGrow؛ والتغييرات في Grow.
| النطاق | ما يفعله | ابتداءً من خطة |
|---|---|---|
company:read | Your company details, services and locations. | Pro |
messages:read | Messages from your contact form (not those held as spam). | Pro |
company:write | Replace your services, and change phone numbers and opening hours. | Grow |
posts:read | The posts you write on to.co, drafts included. | Pro |
posts:write | Write, save, publish, unpublish and delete posts. | Grow |
المسارات
كل مسار يقع تحت عنوان URL الأساسي، مع عنوان شركتك على to.co مكان {host}، مثل mybusiness.uk.to.co. الطلبات والإجابات بصيغة JSON. تمر التغييرات عبر الفحوص والسجل وإعادة النشر نفسها التي تمر بها التغييرات المُجراة في my.to.co، وتُسجَّل على أنها أُجريت بالمفتاح.
| المسار | ما يفعله | النطاق |
|---|---|---|
GET /v1/orgs/{host} | The company record, with its services and locations. | company:read |
GET /v1/orgs/{host}/services | The services, in order. | company:read |
GET /v1/orgs/{host}/locations | The locations, with phones and opening hours. | company:read |
GET /v1/orgs/{host}/messages | Contact form messages. Filter with ?status=new|read|replied|archived. | messages:read |
GET /v1/orgs/{host}/messages/{id} | One message. | messages:read |
PATCH /v1/orgs/{host} | Change the company phone numbers: JSON { "phones": … }. | company:write |
PUT /v1/orgs/{host}/services | Replace the whole list of services, in order: JSON { "services": [ … ] }. | company:write |
PATCH /v1/orgs/{host}/locations/{location} | Change a location: JSON with any of phones, normal_hours and special_hours. Every value is checked, and the answer carries the checks. The registered office comes from the register and cannot be changed. | company:write |
GET /v1/orgs/{host}/posts | Posts written on to.co, newest change first, a page at a time: ?limit, ?state and ?cursor (next_cursor from the page before). | posts:read |
GET /v1/orgs/{host}/posts/{id} | One post, its body as blocks, with its version as the ETag. | posts:read |
POST /v1/orgs/{host}/posts | A new draft: JSON { "title", "standfirst", "body" }, or the body as text/markdown. | posts:write |
PATCH /v1/orgs/{host}/posts/{id} | Save a post. Send the version you are changing as If-Match; JSON, or the body as text/markdown. | posts:write |
DELETE /v1/orgs/{host}/posts/{id} | Move a post to the bin. The owner can restore it in my.to.co for 30 days. | posts:write |
POST /v1/orgs/{host}/posts/{id}/publish | Publish the If-Match version. It is checked first, as when the owner publishes. | posts:write |
POST /v1/orgs/{host}/posts/{id}/unpublish | Take a post off the page and back to a draft. | posts:write |
الأرصدة والحدود
- يستهلك كل طلب رصيد API واحدًا، من الحصة الشهرية نفسها التي تستهلكها طلبات مساعد الذكاء الاصطناعي الخاص بك إلى خادم MCP لنشاطك التجاري: 5,000 شهريًا لكل شركة في Pro و50,000 في Grow. الطلب الفاشل يعيد رصيده. تتجدد الأرصدة في اليوم الأول من كل شهر (UTC)، ولا توجد رسوم تجاوز. تحمل الإجابات X-Credits-Limit وX-Credits-Remaining وX-Credits-Reset.
- حتى 120 طلب في الدقيقة لكل مفتاح.
- حتى 60 تغيير في الدقيقة لكل شركة، تُحتسب مع التغييرات المُجراة في my.to.co وعبر MCP.
الأخطاء
يرد الخطأ بحالة HTTP وJSON: error (رسالة)، وcode (أحد الرموز أدناه)، وrequest_id. ويحمل الرد 429 ترويسة Retry-After.
invalid_request(400) — The body or a query value is not valid; the message says which field.cookie_not_accepted(400) — The request carried a browser session. This API takes an API key only.if_match_required(400) — A post change without If-Match.not_ready(400) — The post cannot be published yet; problems lists why.image_unknown(400) — A post body shows an image the post does not have. A key cannot upload images.invalid_key(401) — No key, or one that is unknown, revoked or expired.insufficient_scope(403) — The key does not have the scope this route needs.plan_required(403) — The company plan does not include this scope now; plan_needed names the plan that does.insufficient_role(403) — The person who made the key no longer has the role for this; an owner makes a new key.not_found(404) — Not found. A host other than the key's own company is always not found.registered_office(409) — The registered office comes from the company register and cannot be changed with a key.post_changed(409) — The post changed since the If-Match version. Read it again.post_deleted(409) — The post is in the bin.not_draft(409) — Only a draft can be scheduled.slug_taken(409) — Another post already uses that address.rate_limited(429) — Too many requests. Wait for Retry-After.credits_exhausted(429) — This month's API credits are used. They start again on the first of next month; there are no overage charges.credits_unavailable(503) — The API cannot count credits right now. Try again later.
Webhooks
في Grow، يمكن لـ to.co أيضًا إرسال أحداث موقَّعة إلى خادمك الخاص عند تغيّر شيء ما، مثل رسالة جديدة أو تغيير في بيانات شركتك. أعدّها في my.to.co ضمن «Webhooks».