to.co API
Anna oman ohjelmiston, kuten verkkosivuston, kassajärjestelmän tai skriptin, lukea yrityksen tietoja to.co:ssa ja pitää ne ajan tasalla. Avaimet sisältyvät Pro- ja Grow-paketteihin.
- Perus-URL
https://api.to.co/v1/orgs/{host}- Todennus
Authorization: Bearer toco_ak_…
Hanki API-avain
Avaa yritys my.to.co:ssa ja valitse API-avaimet ja sitten Luo avain. Nimeä avain, valitse sen käyttöoikeudet ja voimassaolon päättyminen (enintään vuosi) ja kopioi se: avain näytetään vain kerran, ja siitä säilytetään vain tiiviste.
Lähetä avain Authorization-otsakkeessa jokaisessa pyynnössä. Avain toimii vain omalle yritykselleen: mikä tahansa muu osoite vastaa, ettei sitä löydy. API hyväksyy vain avaimia, ei koskaan selainistuntoa.
Esimerkkikutsu
curl https://api.to.co/v1/orgs/mybusiness.uk.to.co \
-H "Authorization: Bearer toco_ak_…"
Käyttöoikeudet ja paketit
Avain voi tehdä vain sen, minkä sen käyttöoikeudet sallivat, ja vain sen, mitä yrityksen paketti sisältää kunkin pyynnön hetkellä. Lukeminen sisältyy Pro- ja Grow-paketteihin; muutokset Grow-pakettiin.
| Käyttöoikeus | Mitä se tekee | Paketista alkaen |
|---|---|---|
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 |
Reitit
Kaikki reitit ovat perus-URL:n alla, ja yrityksen to.co-osoite tulee kohtaan {host}, esimerkiksi mybusiness.uk.to.co. Pyynnöt ja vastaukset ovat JSON-muotoisia. Muutokset käyvät läpi samat tarkistukset, historian ja uudelleenjulkaisun kuin my.to.co:ssa tehdyt muutokset, ja ne kirjataan avaimen tekemiksi.
| Reitti | Mitä se tekee | Käyttöoikeus |
|---|---|---|
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 |
Krediitit ja rajoitukset
- Jokainen pyyntö käyttää yhden API-krediitin samasta kuukausikiintiöstä kuin oman tekoälyavustajan kutsut yrityksen MCP-palvelimeen: 5,000 kuukaudessa yritystä kohden Pro-paketissa ja 50,000 Grow-paketissa. Epäonnistunut pyyntö palauttaa krediittinsä. Krediitit alkavat alusta kunkin kuun 1. päivänä (UTC), eikä ylityksistä veloiteta. Vastauksissa on otsakkeet X-Credits-Limit, X-Credits-Remaining ja X-Credits-Reset.
- Enintään 120 pyyntöä minuutissa avainta kohden.
- Enintään 60 muutosta minuutissa yritystä kohden, mukaan lukien my.to.co:ssa ja MCP:n kautta tehdyt muutokset.
Virheet
Virhe palauttaa HTTP-tilan ja JSONin: error (viesti), code (jokin alla olevista) ja request_id. Tilaan 429 sisältyy 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.
Webhookit
Grow-paketissa to.co voi myös lähettää allekirjoitettuja tapahtumia omalle palvelimelle, kun jokin muuttuu, esimerkiksi saapuu uusi viesti tai yrityksen tiedot muuttuvat. Määritä ne my.to.co:ssa kohdassa Webhookit.