ServeCounter booking

Find businesses on ServeCounter that take bookings from assistants: by name (`query`, at least 3 letters, such as "studio noord"), by trade (`trade`, such as "barber" or "nail-salon"; the trade's key or its English or Dutch name), by place (`city`, or `latitude` and `longitude` with `radiusKm`, 10 by default and at most 50) and, with `freeOn` (YYYY-MM-DD), only those with a free time that day. Give at least one of name, trade, city or coordinates. Needs no sign-in. Answers up to 20 businesses a page with their address, which the other tools take as `business`; ask again with the answer's `nextCursor` for the next page. How results are ordered, always the same way: nearest first when coordinates are given, then the earliest free time on `freeOn` when it is given, then name A to Z. A `city` alone only limits the results to that city: ServeCounter does not measure from a city's centre, so give coordinates for distance. A city alone is ordered by first free time, then name (the free time needs `freeOn`; without it, by name). There is no paid placement: no business can pay to be listed higher, and the answer says how it was ordered in `orderedBy`. Only businesses whose booking page is live and that allow assistants are listed.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Part of the business's name or booking address, at least 3 letters.",
      "type": "string"
    },
    "trade": {
      "description": "The trade: its key (\"barber\", \"hairdresser\", \"nail-salon\") or its English or Dutch name (\"Kapsalon\").",
      "type": "string"
    },
    "city": {
      "description": "The city, as it is written in the business's address, such as \"Amsterdam\". Limits the results to it; it does not rank by distance.",
      "type": "string"
    },
    "latitude": {
      "description": "Where you are looking from, WGS 84 degrees; needs `longitude`. Results are then the nearest first.",
      "minimum": -90,
      "maximum": 90,
      "type": "number"
    },
    "longitude": {
      "description": "WGS 84 degrees; needs `latitude`.",
      "minimum": -180,
      "maximum": 180,
      "type": "number"
    },
    "radiusKm": {
      "description": "How far from the coordinates, in kilometres: 10 by default, at most 50.",
      "minimum": 0.1,
      "maximum": 50,
      "type": "number"
    },
    "freeOn": {
      "description": "A day, YYYY-MM-DD: only businesses with a free time then, the earliest first after distance. At most 40 businesses are checked, in order of distance, then name, and the answer says when a request's limit on work left some unchecked.",
      "type": "string"
    },
    "limit": {
      "description": "How many businesses a page: 20 by default and at most 20.",
      "minimum": 1,
      "maximum": 20,
      "type": "integer"
    },
    "cursor": {
      "description": "The `nextCursor` of the previous page of this same search.",
      "type": "string"
    }
  }
}

A business's locations, services, prices, add-ons and what it asks to be paid up front, the same as its booking page shows and nothing else. Needs no sign-in. With more than one open location, answer again with its `locationId` to see its services.

{
  "type": "object",
  "properties": {
    "business": {
      "description": "The business's address from find_business, such as \"studio-noord\", or its booking page link.",
      "type": "string"
    },
    "locationId": {
      "description": "A location's id, when the business has more than one open location.",
      "type": "integer"
    }
  },
  "required": [
    "business"
  ]
}

The free times for one service at one location, day by day, as the booking page offers them: at most 14 days a request. Needs no sign-in. Times are in the location's own time zone.

{
  "type": "object",
  "properties": {
    "business": {
      "description": "The business's address, such as \"studio-noord\".",
      "type": "string"
    },
    "locationId": {
      "description": "The location's id from get_business.",
      "type": "integer"
    },
    "serviceId": {
      "description": "The service's id from get_business.",
      "type": "integer"
    },
    "variantId": {
      "description": "A variant of the service, when it has them.",
      "type": "integer"
    },
    "addOnIds": {
      "description": "Add-ons chosen with the service.",
      "items": {
        "type": "integer"
      },
      "type": "array"
    },
    "personId": {
      "description": "Who it is with, from get_business people; leave out for no preference.",
      "type": "integer"
    },
    "from": {
      "description": "The first day, YYYY-MM-DD.",
      "type": "string"
    },
    "until": {
      "description": "The last day, YYYY-MM-DD, at most 14 days from `from`.",
      "type": "string"
    }
  },
  "required": [
    "business",
    "locationId",
    "serviceId",
    "from",
    "until"
  ]
}

Prepares a booking for the person who allowed you, for a free time. Nothing is booked yet: it returns a link (`orderUrl`) to give to the person. They read who the seller is and the terms, tick two boxes and press the button, and only then is it booked. Needs the person's own ServeCounter sign-in (OAuth). The booking is always for that person, whatever name or email you send; their phone number and full name are needed only when their account has none. Send an `idempotencyKey` (a new random value for each booking you mean to make) so that asking again after a lost answer is safe: the same key with the same arguments, within 24 hours, gives the first answer again and makes no second order; the same key with other arguments is refused with `idempotency-key-reused`.

{
  "type": "object",
  "properties": {
    "business": {
      "description": "The business's address, such as \"studio-noord\".",
      "type": "string"
    },
    "locationId": {
      "description": "The location's id from get_business.",
      "type": "integer"
    },
    "serviceId": {
      "description": "The service's id from get_business.",
      "type": "integer"
    },
    "variantId": {
      "description": "A variant of the service, when it has them.",
      "type": "integer"
    },
    "addOnIds": {
      "description": "Add-ons chosen with the service.",
      "items": {
        "type": "integer"
      },
      "type": "array"
    },
    "personId": {
      "description": "Who it is with; leave out for no preference.",
      "type": "integer"
    },
    "date": {
      "description": "The day, YYYY-MM-DD, from get_free_times.",
      "type": "string"
    },
    "start": {
      "description": "The start time, HH:MM, from get_free_times.",
      "type": "string"
    },
    "payment": {
      "description": "Only where the business lets the customer choose: pay the full amount now, or pay at the business with a deposit now. Defaults to the deposit.",
      "enum": [
        "now",
        "at-shop"
      ],
      "type": "string"
    },
    "name": {
      "description": "The person's full name, if their account has none.",
      "type": "string"
    },
    "phone": {
      "description": "The person's phone number, if their account has none.",
      "type": "string"
    },
    "idempotencyKey": {
      "description": "A value you make up once per booking, at most 255 characters, such as a UUID. Send the same one again only to repeat this same call.",
      "type": "string"
    }
  },
  "required": [
    "business",
    "locationId",
    "serviceId",
    "date",
    "start"
  ]
}

Where an order you prepared stands: `open` (the person has not ordered yet), `booked` (with a link to manage it) or `ended` (expired). Only for orders of the person who allowed you. Needs their sign-in.

{
  "type": "object",
  "properties": {
    "business": {
      "description": "The business's address.",
      "type": "string"
    },
    "order": {
      "description": "The order's code, the last part of the orderUrl, or the whole link.",
      "type": "string"
    }
  },
  "required": [
    "business",
    "order"
  ]
}