npm package: @molin.ai/api
Description: Public Molin API
Author: Molin AI
Latest version: 0.1.3

# Molin API integration specs

- [Molin API integration specs](#molin-api-integration-specs)
  - [Example](#example)
  - [Versioning](#versioning)
  - [Schemas](#schemas)
  - [Security](#security)
    - [Sensitive information in responses](#sensitive-information-in-responses)
    - [HMAC signature verification](#hmac-signature-verification)
    - [Encryption](#encryption)
  - [Webhooks API](#webhooks-api)
    - [Order Query](#order-query)
      - [Request](#request)
      - [Response](#response)
    - [Order Cancellation](#order-cancellation)
      - [Request](#request-1)
      - [Response](#response-1)
  - [Product Sync API](#product-sync-api)
    - [Intro](#intro)
    - [Endpoints](#endpoints)
      - [Retrieving all products](#retrieving-all-products)
        - [Spec](#spec)
        - [Example](#example-1)
        - [Mandatory fields](#mandatory-fields)
        - [Optional but recommended fields](#optional-but-recommended-fields)
      - [Retrieving 1 product](#retrieving-1-product)
    - [Authentication](#authentication)
      - [Example](#example-2)
  - [Custom Actions API](#custom-actions-api)

## Example

```sh
npm install --save valibot # peer dependency
```

```js
import { OrderCancellationResponseSchema } from '@molin.ai/api/v20240910.js';
import * as v from 'valibot';

v.parse(OrderCancellationResponseSchema, {
  cancelled: false,
  reason: 'Invalid order ID',
});
```

## Versioning

Please note that the API is versioned. Whenever you configure a webhook via our dashboard, you will need to select a version. The version you select will determine the format of the request that Molin will send to you and the format of the response you must respond with.

## Schemas

We use `valibot` schemas to validate the request and response payloads. We also publish these schemas via `npm`, so you can use them to validate the response payloads in your code. Using the `npm` package is optional as long as your implementation is compliant and follows the schemas documented below.

Unless a field is marked as optional using `v.optional()`, it is required and cannot be `null/undefined`. Generally, all top-level fields are required, nested fields may be optional, and you may provide additional data in the `extra` field.

## Security

### Sensitive information in responses

Do not include sensitive information in any response. You should assume that the response will be visible to the user in its entirety. If you need to include sensitive information, you should provide a link to a secure page where the user can view the information.

### HMAC signature verification

We are working on implementing HMAC signatures on all requests so you can verify that the request is coming from Molin. This feature is not yet available, but we will update this document when it is.

### Encryption

Our API does not support `http` connections. You must use `https` to ensure that the data is encrypted in transit.

## Webhooks API

This API is similar to the webhooks system in other platforms such as Stripe. You must configure these endpoints in the [molin.ai](https://molin.ai/app) dashboard.

### Order Query

Molin will send Order Query requests when a user requests information about an order. You should respond with the order details.

Example URL: https://store.com/webhook/molin/v20240910/order-query

#### Request

Method: POST

Schema:

```js
const OrderQueryRequestSchema = v.object({
  widgetId: v.string(),
  conversationId: v.string(),
  orderId: v.string(),
  orderEmail: v.string(),
});
```

Example:

```json
{
  "widgetId": "v0iyxl53",
  "conversationId": "2d326641-a872-4d7c-8306-9a42e6bd05ca",
  "orderId": "ex123",
  "orderEmail": "john@example.com"
}
```

#### Response

If the order is not found, you should respond with a 404 status code.

If found, you should respond with a 200 status code and the following body.

Schema:

```js
const OrderQueryResponseSchema = v.object({
  status: v.string(),
  payment: v.object({
    method: v.optional(v.string()),
  }),
  shipping: v.object({
    method: v.optional(v.string()),
    trackingURL: v.optional(v.string()),
  }),
  customer: v.object({
    name: v.optional(v.string()),
    email: v.optional(v.string()),
  }),
  extra: v.any(),
});
```

Example:

```json
{
  "status": "shipped",
  "payment": {
    "method": "credit card"
  },
  "shipping": {
    "method": "courier - DHL Express",
    "trackingURL": "https://dhl.com/track/123456"
  },
  "customer": {},
  "extra": {
    "expectedDeliveryDate": "2026-12-25"
  }
}
```

In general, strings should be human readable, but short and succinct.

### Order Cancellation

Molin will send Order Cancellation requests when a user requests to cancel an order. You should respond with the status of the cancellation.

Example URL: https://store.com/webhook/molin/v20240910/order-cancellation

#### Request

Method: POST

Schema:

```js
const OrderCancellationRequestSchema = v.object({
  widgetId: v.string(),
  conversationId: v.string(),
  orderId: v.string(),
  orderEmail: v.string(),
});
```

Example:

```json
{
  "widgetId": "v0iyxl53",
  "conversationId": "2d326641-a872-4d7c-8306-9a42e6bd05ca",
  "orderId": "ex123",
  "orderEmail": "john@example.com"
}
```

#### Response

You should always respond with a 200 status code.

Schema:

```js
const OrderCancellationResponseSchema = v.object({
  cancelled: v.boolean(),
  reason: v.optional(v.string()),
});
```

Examples:

```json
{
  "cancelled": true
}
```

```json
{
  "cancelled": false,
  "reason": "order not found / order already shipped"
}
```

## Product Sync API

_This spec describes a JSON API served via HTTP, using header-based authentication and the schema.org format for product data._

### Intro

We borrowed the [JSON-LD spec](https://json-ld.org/) because shops already use it, for example visit any product page hosted by Shopify and you’ll find a **type="application/ld+json"** script tag encoding product information in a [schema.org](https://schema.org) format.

### Endpoints

We require the following endpoints if you are creating a custom API for us.

#### Retrieving all products

We need an endpoint that we can call frequently to download your products.

##### Spec

- Content-Type must be **application/json**
- The body must contain a list of products encoded as a JSON string
- Each product object must be of type [Product (schema.org)](https://schema.org/Product)

##### Example

GET [https://petshop.com/molin/products.json](https://petshop.com/molin/products.json)

```json
[
  {
    "@context": "http://schema.org",
    "@type": "Product",
    "name": "Coffee Lenoa | Espresso",
    "brand": "Coffee Lenoa",
    "image": "//lenoacoffeeandshop.hu/cdn/shop/files/...",
    "url": "https://lenoacoffeeandshop.hu/products/lenoa-espresso",
    "offers": {
      "@type": "AggregateOffer",
      "priceCurrency": "USD",
      "lowPrice": "12.99",
      "highPrice": "19.99",
      "itemCondition": "http://schema.org/New",
      "availability": "http://schema.org/InStock",
      "offerCount": "2",
      "offers": [
        {
          "@type": "Offer",
          "name": "Coffee Lenoa | Espresso — 1000 gramm",
          "availability": "http://schema.org/InStock",
          "priceCurrency": "USD",
          "price": "19.99"
        },
        {
          "@type": "Offer",
          "name": "Coffee Lenoa | Espresso — 250 gramm",
          "availability": "http://schema.org/InStock",
          "priceCurrency": "USD",
          "price": "12.99"
        }
      ]
    }
  }
]
```

The above response contains 1 product along with price and stock information.

Note: You don’t have to use an AggregateOffer, you can just return 1 offer (1 price).

##### Mandatory fields

- **name**
- **offers** (so we can extract a price — must include **price** and **priceCurrency**)
- **url** (so we can uniquely identify the product)

##### Optional but recommended fields

- **Image**

#### Retrieving 1 product

This is an optimization that we have not built yet.

If you have lots of products, it is more efficient to also offer a single product endpoint. For example, if a customer asks Molin about the stock of 1 specific product, we will update only this specific product (quicker than downloading all of them).

### Authentication

You may add header-based authentication that relies on a simple shared secret (token).

#### Example

If you give us the token `M123ABC`, we will include the following header in all requests:

```
Authorization: M123ABC
```

## Custom Actions API

We are working on an API that allows you to define custom actions that can be triggered by the user. For example, you could define an action that sends an email to the user with a discount code, when they request one. Stay tuned!