# Beelong - Calculateur - API: Post clientUpdateServedFormulas
###### tags: `Beelong` `API` `Calculateur` `Technical Documentation`

[TOC]

## 1. Introduction

This API specification aims to provide the client with an external and automatable way to set the number of served formulas in his calendar.

This API suits particularly clients who use payment services, like TCPOS. As a prerequisite, clients should be able to extract sales data from their payment service and send them to Beelong through a GraphQL API.

With this API, the client can add and update all his sales data for a specific formula, date, and type of price. He can send them one by one, or by batch of 20 items maximum.

In return, you will get two lists of items, the first for the succeeded ones and the other for the failed ones.

> Note: The list of price types has to be retrieved from Beelong

## 2. Prerequisites

### Beelong
Beelong will provide access tokens that allow updating establishments and kitchens separately. Those tokens will be provided for each for each environment (dev/prod).

### Client
Be sure to have your payment reference (e.g. your TCPOS ID) ready. You'll need to provide it for each formula:

<img src="https://hackmd.io/_uploads/r1bYnxPRh.png)" alt="drawing" height="400"/>

This dialog can be found on the UI interface on the formulas of the establishment or kitchen. The payment reference is also accessible through the `publicClientCalendar` API (see point 6.2 below).

Once you have the data to update along with the formula payment reference(s), you'll be able to send the list of formula sales of the establishment or kitchen.

## 3. Schema

type Query {
     priceTypes: [PriceType!]!
}

type PriceType {
  id: Int!
  code(locale: Locale! = "FR"): String!
  name(locale: Locale! = "FR"): String!
}

type Mutation {
    clientUpdateServedFormulas(
        input: ExternalFormulasSalesInput!
    ): FormulasSalesPayload!
}

input ExternalFormulasSalesInput {
  formulasSales: [FormulaHasSaleFromExternalServiceInput!]!
}

input FormulaHasSaleFromExternalServiceInput {
  paymentReference: String!
  priceTypeId: Int!

  # Date format like 2023-08-31
  date: DateTime!
  quantity: Int!
  unitPrice: Int!
  totalPrice: Int!
}


type FormulasSalesPayload {
  succeededItems: [FormulaHasSale!]!
  failedItems: [AddOrEditSaleToFormulaPayload!]!
}

type FormulaHasSale {
  formulaId: Int!
  priceTypeId: Int!
  date: DateTime!
  nbServed: Int!
  unitPrice: Int!
  totalPrice: Int!
}

type AddOrEditSaleToFormulaPayload {
  formulaId: String!
  priceTypeId: Int!
  date: DateTime!
  nbServed: Int!
  unitPrice: Int!
  totalPrice: Int!
  error: String!
}

## 4. Technologies

The API language is GraphQL. JSON will be used for the request payload.

## 5. Example

An establishement will be setup with fictitious calendar for the client, on **staging** environment, to provide the best and complete experience for the testers of this API.

All data of this example can be used as is to access this etablishment, except for the token which will be provided by Beelong, and the filters which should be adjusted.

The client can visualize the public calendar on the url provided as well.

### 5.1 The request

#### 5.1.1 GraphQL header (example)

A token is required in the HTTP request.
Example:

x-api-key client@1N4fnskfk8djsN8j

:warning: The above token is only shown for demonstration purposes.

#### 5.1.2 Queries

URL of the API (staging): https://api.secure.staging.beelong.ch/graphql
URL of the API (prod): https://api.secure.beelong.ch/graphql

query {
  priceTypes {
    id
    code
    name
  }
}

mutation ($input: ExternalFormulasSalesInput!) {
  clientUpdateServedFormulas(input: $input) {
    # Sales created/updated
    succeededItems {
        formulaId
        priceTypeId
        date
        nbServed
        unitPrice
        totalPrice
    }
    # Sales that couldn't be processed
    failedItems {
        formulaId
        priceTypeId
        date
        nbServed
        unitPrice
        totalPrice
        error
    }
  }
}

#### 5.1.3 GraphQL variables

{ 
    "input": {
        "formulasSales": [ # maximum 20 items
            {
                "paymentReference": "FORMULA_REF_1",
                "priceTypeId": 3, # --> provided by the priceTypes query above
                "date": "2023-09-06", # with format yyyy-mm-dd
                "quantity": 9,
                "unitPrice": 10,
                "totalPrice": 90
            },
            {
                "paymentReference": "FORMULA_REF_1",
                "priceTypeId": 2, # --> provided by the priceTypes query above
                          
                "date": "2023-09-06",
                "quantity": 5,
                "unitPrice": 10,
                "totalPrice": 50
            }
        ]
    }
}

### 5.2 The response

{
    "data": {
        "clientUpdateServedFormulas": {
            "succeededItems": [
                {
                    "formulaId": 105,
                    "priceTypeId": 3,
                    "date": "2023-09-06",
                    "nbServed": 9,
                    "unitPrice": 10,
                    "totalPrice": 90
                },
                {
                    "formulaId": 105,
                    "priceTypeId": 2,
                    "date": "2023-09-06",
                    "nbServed": 5,
                    "unitPrice": 10,
                    "totalPrice": 50
                }
            ],
            "failedItems": []
        }
    }
}

### 5.3 The result in the Calculator interface

<img src="https://hackmd.io/_uploads/H1rUIGD0n.png)" alt="drawing" height="300"/>

<img src="https://hackmd.io/_uploads/BkS8LMP03.png)" alt="drawing" height="200"/>

## 6 How to retrieve the payment reference from the publicClientCalendar API

If you are already using the publicClientCalendar API from Beelong, you can easily retrieve the payment reference of your formulas, by requesting the **paymentReference** field of the FormulaCalendar type.

### 6.1 Complete your schema

type FormulaCalendar implements Node {
  # The id of the formula
  id: String!

  # The date of the menu in the formula in format ISO 8601 YYYY-MM-DD
  date: String!

  # The list of menus in the formula
  menus: [MenuCalendar!]!

  # The name of the formula
  name: String!

  # The description of the formula
  description: String

  # The payment reference of the formula (ex: tcpos id)
  paymentReference: String # <-- HERE
    
  # The list of prices
  prices: [FormulaHasPrice!]!
}

### 6.2 Complete your query

query ($filters: CalendarFilters!, $locale: String!) {
  publicClientCalendar(filters: $filters) {
    id
    ### Company/establishment ###
    entity {
      ...
    }

    ### Public calendar ##

    # Formulas and menus existing in the range of time selected
    formulas {
      ...
      paymentReference # <-- HERE
    }