> ## Documentation Index
> Fetch the complete documentation index at: https://developer.clopos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get up and running with the Clopos Open API in minutes

# Quick Start Guide

Get started with the Clopos Open API in just a few simple steps. This guide will walk you through authentication and making your first API request.

## Prerequisites

Before you begin, make sure you have:

<CardGroup cols={2}>
  <Card title="API Credentials" icon="key">
    Client ID and Client Secret from Clopos
  </Card>

  <Card title="Brand" icon="building">
    Your brand identifier
  </Card>

  <Card title="Integrator ID" icon="id-card">
    Required for v2 authentication. Request one from Clopos via [this form](https://forms.gle/Y9P1Wnv4QFAruxny8).
  </Card>

  <Card title="Support" icon="envelope">
    Missing any of the above? Request access via [this form](https://forms.gle/Y9P1Wnv4QFAruxny8).
  </Card>
</CardGroup>

## Step 1: Authenticate

Exchange your credentials for a JWT by calling the v2 auth endpoint. Note that v2 requires an `integrator_id` and no longer accepts `venue_id` in the request body.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://integrations.clopos.com/open-api/v2/auth \
    -H "Content-Type: application/json" \
    -d '{
      "client_id": "{{client_id}}",
      "client_secret": "{{client_secret}}",
      "brand": "{{brand}}",
      "integrator_id": "{{integrator_id}}"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://integrations.clopos.com/open-api/v2/auth', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      client_id: '{{client_id}}',
      client_secret: '{{client_secret}}',
      brand: '{{brand}}',
      integrator_id: '{{integrator_id}}'
    })
  });

  const data = await response.json();
  const accessToken = data.token;

  // The only header needed for subsequent v2 requests
  const apiHeaders = {
    'x-token': accessToken
  };
  ```

  ```python Python theme={null}
  import requests

  url = "https://integrations.clopos.com/open-api/v2/auth"
  payload = {
      "client_id": "{{client_id}}",
      "client_secret": "{{client_secret}}",
      "brand": "{{brand}}",
      "integrator_id": "{{integrator_id}}"
  }

  response = requests.post(url, json=payload)
  data = response.json()
  access_token = data["token"]

  # The only header needed for subsequent v2 requests
  api_headers = {
      "x-token": access_token
  }
  ```
</CodeGroup>

You'll receive a response like this:

```json theme={null}
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": 1767852332,
  "message": "Authentication successful"
}
```

<Warning>
  Save the `token` value — you'll need it in the `x-token` header on every subsequent request. The token is a JWT that encodes your `brand`, `venue_id`, and `integrator_id`, so you no longer need to send `x-brand` or `x-venue`. Tokens expire after `expires_in` seconds (typically 1 hour).
</Warning>

<Note>
  Don't have an `integrator_id` yet? Request one from Clopos by filling out [this form](https://forms.gle/Y9P1Wnv4QFAruxny8). See the [Authenticate reference](/api-reference/v2/authentication/auth) for details.
</Note>

## Step 2: Make Your First Request

Now let's fetch the list of products using your access token:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://integrations.clopos.com/open-api/v2/products?limit=5" \
    -H "x-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://integrations.clopos.com/open-api/v2/products?limit=5', {
    headers: apiHeaders  // Using the headers from Step 1
  });

  const products = await response.json();
  console.log('Products:', products.data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://integrations.clopos.com/open-api/v2/products"
  params = {"limit": 5}

  response = requests.get(url, headers=api_headers, params=params)  # Using headers from Step 1
  products = response.json()
  print("Products:", products["data"])
  ```
</CodeGroup>

You'll receive a response with your products:

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Coffee",
      "price": "4.50",
      "status": 1,
      "category_id": 3
    },
    {
      "id": 2,
      "name": "Sandwich",
      "price": "8.99",
      "status": 1,
      "category_id": 5
    }
  ],
  "total": 150,
  "time": 45
}
```

## Step 3: Explore More Endpoints

Now that you're authenticated, you can explore other endpoints:

<CardGroup cols={2}>
  <Card title="Get Categories" icon="tags" href="/api-reference/v2/categories/get-categories">
    Fetch product categories
  </Card>

  <Card title="Create Order" icon="shopping-cart" href="/api-reference/v2/orders/create-order">
    Place a new order
  </Card>

  <Card title="Get Customers" icon="users" href="/api-reference/v2/customers/get-all-customers">
    Retrieve customer data
  </Card>

  <Card title="List Receipts" icon="receipt" href="/api-reference/v2/receipts/get-receipts">
    Browse open and closed receipts
  </Card>
</CardGroup>

## Next Steps

* **[Authentication Guide](/authentication)** - Learn more about token management
* **[API Reference](/api-reference/v2/authentication/auth)** - Explore all available endpoints
* **[Contact Support](mailto:dev@clopos.com)** - Get help with integration

You're now ready to build amazing applications with the Clopos Open API! 🚀