omnifood/thefork API reference

Omnifood\TheFork

Api class

final class Api Api.php:22

TheFork's B2B API (api.thefork.io/manager), thin: JSON calls with a Bearer token from TheFork's Auth0 (client credentials, audience https://api.thefork.io), held until it dies - TheFork asks not to request a new one before - and its two error shapes as Omnifood's: {"data": {"code"}, "error", "statusCode"} from the API, {"message"} from the gateway; 401 and 403 as UnauthorizedException.

const PLATFORM = 'thefork'

const BASE_URI = 'https://api.thefork.io/manager'

const TOKEN_URL = 'https://auth.thefork.io/oauth/token'

const AUDIENCE = 'https://api.thefork.io'

Api::__construct()

public function __construct(readonly ?string $clientId = null, readonly ?string $clientSecret = null, ?Token $token = null, readonly string $baseUri = self::BASE_URI, readonly string $tokenUrl = self::TOKEN_URL, ?HttpClientInterface $http = null)

Api::request()

public function request(string $method, string $path, array $query = [], array|object|null $json = null): array

Returns

the answer, [] when it has none

Api::token()

public function token(): Token

The token held, a fresh one when there is none or it is about to die.

Api::heldToken()

public function heldToken(): ?Token

Api::refresh()

public function refresh(): Token

TheForkPlatform class

final class TheForkPlatform implements ReservationsInterface, NotifiableInterface, RefreshableInterface TheForkPlatform.php:45

A restaurant's reservations at TheFork, through the B2B API (https://docs.thefork.io/B2B-API/introduction, reference https://api.thefork.io/manager/openapi.json).

• reservations() lists the ids booked from one day to another (by meal date) and reads each, and its customer when with_customers is on: the list itself carries ids only.
• createReservation() books a table (normal stock, or the offer in raw['offerUuid']); updateReservation() changes the date, the party size and the staff note - nothing else is writable; cancelReservation() cancels it, as the restaurant (TheFork takes no reason).
• The service's statuses (arrived, seated, left, no-show) are read (status, mealStatus) but TheFork publishes no call to set them: setStatus() only cancels.
• pushAvailability() opens or closes time slots for online booking (TheFork's override: a range, open or closed - not a number of covers).
• Its webhooks carry an entity and an event, not the reservation: notify() says which, reservation() reads it.

Tables, deposits and card imprints on a reservation are not in the public API.

const PAGE = 100

reservations()' page size; TheFork takes up to 10000

TheForkPlatform::__construct()

public function __construct(readonly Api $api, readonly ?string $restaurantId = null, readonly ?string $webhookToken = null, readonly string $locale = 'fr_FR', readonly string $civility = 'mx', readonly bool $withCustomers = true)

TheForkPlatform::getName()

public function getName(): string

TheForkPlatform::getChannel()

public function getChannel(): Channel

TheForkPlatform::capabilities()

public function capabilities(): Capabilities

TheForkPlatform::reservations()

public function reservations(\DateTimeImmutable $from, \DateTimeImmutable $to): array

TheForkPlatform::reservation()

public function reservation(string $ref): Reservation

TheForkPlatform::createReservation()

public function createReservation(Reservation $reservation): Reservation

Booked on normal stock, or on the offer in $reservation->raw['offerUuid'].

TheFork requires the guest's e-mail, first and last names, a locale and a civility (raw['civility'], else the configured one); the phone in E.164. raw['restaurantNote'] is the staff's note.

TheForkPlatform::updateReservation()

public function updateReservation(Reservation $reservation): Reservation

The date and the party size; the staff's note when raw['restaurantNote'] is there (null clears it).

TheForkPlatform::cancelReservation()

public function cancelReservation(string $ref, ?string $reason = null): void

Cancelled as the restaurant; TheFork records no reason given ($reason is not sent).

TheForkPlatform::setStatus()

public function setStatus(string $ref, ReservationStatus $status): void

TheForkPlatform::pushAvailability()

public function pushAvailability(array $slots): void

Each slot opened (covers > 0) or closed (0) to online booking, from its start to its end (the slot starting at the end included; no end: its start alone), in the restaurant's local time.

TheForkPlatform::notify()

public function notify(string $body, array $headers): Notification

A webhook from TheFork: {"entityType", "eventType", "uuid", "groupUuid", "restaurantUuid"}. TheFork authenticates it by the token the site put in the URL it gave (…?token=…) and nothing else: the controller passes that query parameter among $headers as "token" ($request->headers->all() + ['token' => $request->query->get('token')]).

The notification carries no event id (Notification::$id is null) and no data: a reservationCreated or reservationUpdated is read again with reservation($notification->reference). The endpoint answers 200 {"data": }} within a few seconds.

TheForkPlatform::token()

public function token(): ?Token

TheForkPlatform::refresh()

public function refresh(): Token

A new token (about 2 h 23), for the site to keep and give back as access_token / token_expires_at.

TheForkPlatform::toReservation()

public function toReservation(array $r, ?array $c = null): Reservation

A reservation as TheFork answers it, its customer read or nested.

TheForkPlatform::status()

public static function status(string $status, ?string $mealStatus = null): ReservationStatus

status and, once confirmed, mealStatus: the service as it goes.

TheForkPlatformFactory class

final class TheForkPlatformFactory extends PlatformFactory TheForkPlatformFactory.php:27

TheFork (LaFourchette), through its B2B API - TheFork Manager's:

options: client_id: '%env(default::THEFORK_CLIENT_ID)%' # sent by TheFork (integrations@thefork.com) client_secret: '%env(default::THEFORK_CLIENT_SECRET)%' restaurant_id: '%env(default::THEFORK_RESTAURANT_ID)%' # the restaurant's UUID at TheFork webhook_token: '%env(default::THEFORK_WEBHOOK_TOKEN)%' # the token put in the webhook URL given to TheFork (?token=...) access_token: ~ # a token kept by the site (refresh(), token()), and when it dies: token_expires_at: ~ # ATOM; TheFork asks not to ask for a new one before locale: fr_FR # a guest's, when the reservation does not say civility: mx # a guest's, required by TheFork, when the reservation's raw has none with_customers: true # read each reservation's customer (name, phone, allergies): one call more each base_uri: https://api.thefork.io/manager token_url: https://auth.thefork.io/oauth/token

Options