# 24SO Integration API - Comments and doubts

## Sync call (2021-11-17) - Summary

1. pushing orders to an API will be separated from pushing doctor settlements, by means of different endpoints and different time of the pushing
1.1 Orders will be pushed on the daily basis observing a delay period.
1.2 Doctor's settlement items will be pushed:
- once a month; (and this is by default) in which case all the compensation items (individual lines), will be pushed, thus generating a new invoice-for-doctor (by means of reverse-invoicing). In that sense, compensation items will "pile up" on HJ's side.
- on-demand; in which case all no-previously-pushed compensation items for a certain doctor are sent, also generatinv a new invoice
1.3 As for pushing orders 7-day delay period will be observed prior HJ pushes it to API.
1.4 Grace period also applies for Doctor settlements (@Øyvind please confirm)
1.5 Duration of the delay period may be changed on HJ side, separately, for Orders and Compensation items
2. Doctor's compensation items
2.1 Compensation items are going to be pushed to API only for doctors with provision-based compensation model. Flat-rate doctors are of no concern for this integration.
2.2 Most comp. items will be related to an order. In that case Id of related order will be put in the description.
2.3 Comp. items unrelated to an order will be used in cases such as
- bonuses
- corrections e.g. number of patients for an order has changed over order's lifetime.

# Original proposal:

That's what the Google translate told me about two choices we were given

### Option #1

We can "build" a medical settlement in 24SO. Each doctor has an open order in 24SO, every customer order that is transferred and invoiced from 24SO is also placed on the associated doctor's order. At the end of each month, the doctors' order is closed, the credit note is sent to the doctor, and the settlement is paid. This settlement should then be checked against a final settlement from Hjemmelegene's system before it is sent out from 24SO.

### Option #2
We keep the doctor settlement separate, regular customer orders are transferred daily to 24SO. The doctors' settlement is transferred every month. The home doctors then post information about what is to be transferred to 24SO on the various doctors' settlements. The information we need about doctors is relatively similar to the information we need about customers, which is mentioned in the API documentation of Kjell Morten.

## Comments & Questions (2021-11-15):

1) As to Option #2, I suppose we then need at least two endpoints, right? One for orders (`POST /invoices`) and the other for doctors compensations, right? Or is it that you intend to use the same only with different payload?

2) I can't see any information about authentication, nor the headers.

3) https://virtserver.swaggerhub.com/kjellmorten/hjemmelegene-24so/1.0.0 <- is this Production or staging? If staging, what is production's url? Which url can be safely used for testing?

4) What about doctors being paid for something totally unrelated to an order?
business cases:
- doctors on the payroll (monthly salary but without connection to any particular order)
- doctors who were supposed to be paid extra for whatever business reasons
- doctors that must be compensated for wrongly calculated compensations from before etc.

5) We need to know more about the payload:

{
  "id": "31001", // is this supposed to be 24SO ID or ID from our system's db?
  "status": "invoiced", // are there any other options possible?
  "title": "Invoice #31001",
  "description": "Consultations done on location",
  "orderedAt": "2021-08-29T09:12:33.001Z",
  "invoicedAt": "2021-08-29T09:12:33.001Z",
  "deliveredAt": "2021-08-29T09:12:33.001Z",
  "paidAt": "2021-08-29T09:12:33.001Z",
  "updatedAt": "2021-08-29T09:12:33.001Z",
  "amount": 3375,
  "vatAmount": 675,
  "doctorAmount": 1800, // see comment #4
  "currencySymbol": "NOK",
  "paymentDays": 14,
  "paymentMethod": "invoice", // are there any other options possible
  "distributeInvoice": true,            // please explain
  "ourReference": "",                   // please explain
  "yourReference": "Rolf Midttun",      // please explain
  "customer": {
    "id": "1001", // this is 24SO ID or our ID? 
    "type": "business", // what are the possible values?
    "name": "Company AS"
  },
  "doctor": {
    "id": "2001", // this is 24SO ID or our ID? 
    "name": "Dr. Hansen" // If the doctor does not yet exist will he be auto-created if incoming payload shall be like : { id: null, name: "Per Vaglum" }  ?
  },
  "rows": [
    {
      "id": "1",
      "productId": "CONS001",
      "text": "Consultation",
      "price": 900,    // what does it mean exactly? 9 NOK or 900 NOK?
      "quantity": 3,
      "taxPercent": 25 // i understand that for the most part this is equal to 0
    }
  ],
  "doctorRows": [ // these are doctor settlements right?
    {
      "id": "1",
      "productId": "CONS001",
      "text": "Consultation",
      "price": 900,
      "quantity": 3,
      "taxPercent": 25 // i understand that for the most part this is equal to 0
    }
  ]
}

Updated API spec, version 1.1.0: https://app.swaggerhub.com/apis/kjellmorten/hjemmelegene-24so/1.1.0