# Corksy API

API for retrieving orders, customers, inventory, wine-club data, and products.

## Authentication

This API uses a two-step authentication process:

### Step 1: Generate API Key
First, generate your API key from the Admin Settings API page:
- Go to: https://admin.corksy.io/settings/apiaccess
- Create a new API key for your application

### Step 2: Obtain Bearer Token
Use your API key to obtain a bearer token by making a POST request to the authentication endpoint:

**Production:**
```bash
curl --location 'https://connect-api.corksy.io/v1/auth/public/login' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key-here"
}'
```

**Staging:**
```bash
curl --location 'https://staging.corksy.io/connect-api/v1/v1/auth/public/login' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key-here"
}'
```

**Response:**
```json
{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 1800000
}
```

### Step 3: Use Bearer Token
Use the `accessToken` from the response as a Bearer token in the Authorization header for all subsequent API requests:

**Example Requests:**

**Get Orders:**
```bash
curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
```

**Get Customers:**
```bash
curl --location 'https://connect-api.corksy.io/v1/customers' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
```

**Get Inventory:**
```bash
curl --location 'https://connect-api.corksy.io/v1/inventory' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
```

**Get Wine Clubs:**
```bash
curl --location 'https://connect-api.corksy.io/v1/wine-clubs' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
```

**Get Wine Club Members:**
```bash
curl --location 'https://connect-api.corksy.io/v1/wine-club-members' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
```

**Get Products:**
```bash
curl --location 'https://connect-api.corksy.io/v1/products?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
```

**Note:** The bearer token expires after 30 minutes (1,800,000 microseconds). You'll need to obtain a new token when it expires.

## Pagination

All list endpoints support pagination to handle large datasets efficiently. The API uses offset-based pagination with the following parameters:

### Pagination Parameters

- **`offset`** (optional): Number of records to skip. Default: `0`
- **`pageSize`** (optional): Number of records to return per page. Default: `1000`, Maximum: `1000`

### Pagination Response

Each paginated response includes a `pagination` object with the following information:

```json
{
  "data": [...],
  "pagination": {
    "current_offset": 0,
    "page_size": 50,
    "total_records": 1250,
    "total_pages": 25,
    "current_page": 1,
    "pages_remaining": 24,
    "has_next_page": true,
    "has_previous_page": false
  }
}
```

### Pagination Examples

**First Page (Default):**
```bash
curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31' \
--header 'Authorization: Bearer YOUR_TOKEN'
```

**Second Page (50 records per page):**
```bash
curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31&offset=50&pageSize=50' \
--header 'Authorization: Bearer YOUR_TOKEN'
```

**Custom Page Size:**
```bash
curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31&pageSize=100' \
--header 'Authorization: Bearer YOUR_TOKEN'
```

### Best Practices

1. **Start with the first page** (no parameters or `offset=0`)
2. **Use `has_next_page`** to determine if more pages exist
3. **Increment `offset` by `page_size`** to get the next page
4. **Choose appropriate `page_size`** based on your needs. 
5. **Handle rate limits** - each page request counts toward your rate limit


Version: 1.2.0

## Servers

Staging Environment
```
https://staging.corksy.io/connect-api/v1
```

Production Environment
```
https://connect-api.corksy.io
```

## Security

### BearerAuth

Bearer token obtained from the authentication endpoint.

**Token Format:** JWT (JSON Web Token)
**Expiration:** 30 minutes (1,800,000 microseconds)
**Header Format:** `Authorization: Bearer <token>`

**Example:**
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
```


Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[Corksy API](https://developers.corksy.io/_bundle/openapi.yaml)

## Authentication

Endpoints related to authentication and authorization

### Authenticate with API key to obtain bearer token

 - [POST /v1/auth/public/login](https://developers.corksy.io/openapi/authentication/authenticate.md): Authenticate using your API key to obtain a JWT bearer token for accessing protected endpoints.

Rate Limit: 10 requests / minute

Note: The returned token expires after 30 minutes. You'll need to call this endpoint again to get a new token.

## Orders

Endpoints related to orders

### Retrieve a list of orders within a date range

 - [GET /orders](https://developers.corksy.io/openapi/orders/getorders.md): 🚦 Rate Limit: 100 requests / minute

## Customers

Endpoints related to customers

### Retrieve a list of customers

 - [GET /customers](https://developers.corksy.io/openapi/customers/getcustomers.md): 🚦 Rate Limit: 100 requests / minute

## Inventory

Endpoints related to inventory

### Retrieve a list of inventory items

 - [GET /inventory](https://developers.corksy.io/openapi/inventory/getinventory.md): 🚦 Rate Limit: 100 requests / minute

## Wine Clubs

Endpoints related to wine clubs

### Retrieve a list of wine clubs

 - [GET /wine-clubs](https://developers.corksy.io/openapi/wine-clubs/getwineclubs.md): 🚦 Rate Limit: 100 requests / minute

## Wine Club Members

Endpoints related to wine-club members

### Retrieve a list of wine-club members

 - [GET /wine-club-members](https://developers.corksy.io/openapi/wine-club-members/getwineclubmembers.md): 🚦 Rate Limit: 100 requests / minute

## Products

Endpoints related to products

### Retrieve a list of products

 - [GET /products](https://developers.corksy.io/openapi/products/getproducts.md): 🚦 Rate Limit: 100 requests / minute