[خادم MCP](https://to.co/ar-sa/docs/mcp?format=md) · **API**

# 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 إلا المفاتيح، لا جلسة متصفح أبدًا.

مثال على الاستدعاء:

```shell
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».

## الخطوات التالية

- [خادم MCP في to.co، لمساعدي الذكاء الاصطناعي](https://to.co/ar-sa/docs/mcp?format=md)
- [فتح my.to.co](https://my.to.co)
