Το API του to.co
Αφήστε το δικό σας λογισμικό, όπως έναν ιστότοπο, ένα σύστημα ταμείου ή ένα script, να διαβάζει την εταιρεία σας στο to.co και να την κρατά ενημερωμένη. Τα κλειδιά διατίθενται στα προγράμματα Pro και Grow.
Αποκτήστε κλειδί API Διαδρομές
- Βασικό 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, από το ίδιο μηνιαίο όριο με τις κλήσεις του δικού σας βοηθού AI προς τον διακομιστή MCP της επιχείρησής σας: 5,000 τον μήνα ανά εταιρεία στο Pro και 50,000 στο Grow. Ένα αίτημα που αποτυγχάνει επιστρέφει τη μονάδα του. Οι μονάδες ξεκινούν ξανά την 1η κάθε μήνα (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.