Skip to main content
Version: 1.0

Formation Catering. Partners API

This is the REST API docs for the Formation Catering Partners.

Base URL​

/v1

Authentication and Authorization​

Authorization: Bearer {accessToken}

Please ensure that the Authorization header is included in every request.

Access token will be provided to you separately. It will have an unlimited lifetime.

Example:

GET /orders?page=1&perPage=100
Authorization: Bearer {accessToken}
POST /orders
Authorization: Bearer {accessToken}
Content-Type: application/json

{ ... }

Rate limits​

120 request/minute (2 request/second) per method.

It may be changed in the future.

Timeouts​

Request timeout = 30s.

If for some reason we are unable to process the request (generate a response) in the specified time, we terminate the connection.

Common​

To reset or set the value by default of a property, pass null as value. Not all properties can be reset, some of them are required! Always check the specific request.

Dates and times​

All input datetime values must be in ISO 8016 format, UTC time zone. Allowed formats: 2024-12-31T23:59:59.000Z or 2024-12-31T23:59:59Z. But after saving, milliseconds will be ignored since we store dates in seconds. So, 2024-12-31T23:59:59.999Z will be saved as 2024-12-31T23:59:00Z.

Phone Numbers Validation​

Under the hood we use libphonenumber-js library. It supports the following formats:

  • +12054567890
  • +1 205 4567890
  • +1 (205) 456 7890
  • +1-205-456-7890
  • +1.234.567.890
  • +1234567890x1234
  • +12054567890 ext.123
  • and more.

Webhooks​

If you want to be notified of changes, you must provide to us a URL to which Formation will send notifications of changes.

POST {partnerWebhookUrl}
User-Agent: Formation/1.0.0
Content-Type: application/json

{
  "eventType": "", // enum(orderChanged, invoiceChanged, invoiceCreated, menuChanged)
  "data": {
    "id": 1 // Order.id or Invoice.orderId
  },
  "timestamp": "2024-12-31T23:59:59.000Z"
}

Retries​

Expected response status code: ≥ 200, ≤ 299.

If the response status code does not meet the conditions above (≥ 200, ≤ 299), we will try to send the next request after 5 seconds. Total number of additional retry attempts = 2.

No more than three requests in total.

Event types​

  • orderChanged
  • orderOnHold
  • orderDeleted
  • quoteConvertedToOrder
  • invoiceCreated
  • invoiceChanged
  • invoiceDeleted
  • menuChanged

Changes​

We send notifications about the following changes:

Order/Quotes (orderChanged):

  • change tailNo (not aircraft entity editing)
  • status
  • trip numbers
  • items
  • change airport of order (not airport entity editing)
  • fbo
  • delivery date and time, wheels up/down date and time

Order status became "On Hold" (orderOnHold) - error with your payment details, provide new payment details.

Order Deleted (orderDeleted):

This event is triggered when an order is deleted from the system.

Quotes:

  • quote converted to order (quoteConvertedToOrder)

Invoice Created (invoiceCreated):

This event is triggered when an invoice is generated for a quote or an order.

  • If a previous invoice was removed, this event will also trigger when a new invoice is generated.

Invoice Changed (invoiceChanged):

This event occurs when there are modifications to the invoice. Changes can be of two types:

  1. Non-Pricing Changes (do not affect the total amount but need to be reflected on the invoice):

    • Updates to trip details (e.g., Trip, Tail #, Delivery Date & Time).
    • Modifications to item details (e.g., Item Names, Item Descriptions).

  2. Pricing Changes (affect the total amount on the invoice):

    • New items added or removed.
    • Changes to Airport, FBO.
    • Quantities changed.

Invoice Deleted (invoiceDeleted):

This event is triggered when:

  • Price-impacting changes occur (e.g., new items added/removed, airport/FBO/quantity changed), requiring a new invoice.
  • The order is canceled less than 12 hours before delivery (such cancellations are free of charge).
  • A quote is converted into an order, but changes affecting the price are made.
  • A quote is canceled before an order is created.

Menu Changed (menuChanged):

  • item added
  • item removed
  • item updated (price, name, description, category, unit)

Testing notifications​

To emulate notifications you can use the following endpoint:

POST /v1/webhook-trigger
Api-Key: {apiKey}
Content-Type: application/json

{
  "eventType": "orderChanged",
  "data": {
    "id": 1 // orderId or menuItemId
  }
}

P.S. Api-Key will be provided to you separately.
P.P.S. This endpoint is only for testing purposes and will not be available for you on the production environment.

Request Examples​

POST {partnerWebhookUrl}
User-Agent: Formation/1.0.0
Content-Type: application/json

{
  "eventType": "orderChanged",
  "data": {
    "id": 1
  }
}
POST {partnerWebhookUrl}
User-Agent: Formation/1.0.0
Content-Type: application/json

{
  "eventType": "menuChanged",
  "data": {
    "id": 1
  }
}
POST {partnerWebhookUrl}
User-Agent: Formation/1.0.0
Content-Type: application/json

{
  "eventType": "quoteConvertedToOrder",
  "data": {
    "id": 1
  }
}

Authentication​

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

opaque