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

# Overview

> Quick guide to the Cariqa Connect API

<Card title="OpenAPI Specification" icon="download" horizontal href="/openapi.yaml">
  Download the full OpenAPI 3.0 spec
</Card>

This guide walks you through the essential endpoints and workflows for integrating with the Cariqa Connect API.

## Prerequisites

Before starting, ensure you have:

* **API Token** - Contact Cariqa for your access token
* **Stripe Integration** - Frontend Stripe SDK setup is mandatory for payments
* **HTTPS Environment** - All API calls must use HTTPS

## Core Workflows

### 1. User Management

All endpoints starting with `/users` require users to be created in the system first.

<CodeGroup>
  ```bash cURL theme={null}
  # Create User
  curl -X POST "https://connect.cariqa.com/api/v1/users/" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "user@example.com",
      "locale": "de"
    }'

  # Get User  
  curl -X GET "https://connect.cariqa.com/api/v1/users/123/" \
    -H "Authorization: Bearer YOUR_TOKEN"

  # Update User
  curl -X PATCH "https://connect.cariqa.com/api/v1/users/123/" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"locale": "en"}'
  ```

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

  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }

  # Create User
  user_data = {
      "first_name": "John",
      "last_name": "Doe", 
      "email": "john@example.com"
  }
  response = requests.post(
      "https://connect.cariqa.com/api/v1/users/",
      headers=headers,
      json=user_data
  )

  # Get User
  response = requests.get(
      "https://connect.cariqa.com/api/v1/users/123/",
      headers=headers
  )

  # Update User
  update_data = {"first_name": "Jane"}
  response = requests.patch(
      "https://connect.cariqa.com/api/v1/users/123/",
      headers=headers,
      json=update_data
  )
  ```

  ```javascript JavaScript theme={null}
  const headers = {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  };

  // Create User
  const createUser = await fetch('https://connect.cariqa.com/api/v1/users/', {
    method: 'POST',
    headers,
    body: JSON.stringify({
      first_name: 'John',
      last_name: 'Doe',
      email: 'john@example.com'
    })
  });

  // Get User
  const getUser = await fetch('https://connect.cariqa.com/api/v1/users/123/', {
    headers
  });

  // Update User  
  const updateUser = await fetch('https://connect.cariqa.com/api/v1/users/123/', {
    method: 'PATCH',
    headers,
    body: JSON.stringify({
      first_name: 'Jane'
    })
  });
  ```
</CodeGroup>

**Supported operations:**

* `POST /users/` - Create user
* `GET /users/` - List all users
* `GET /users/<id>/` - Get user by ID
* `PATCH /users/<id>/` - Update user
* `DELETE /users/<id>/` - Soft delete user

### 2. Billing Details

User accounts are divided into **Personal** (default) and **Business** types.

<CodeGroup>
  ```bash Update Billing Details theme={null}
  curl -X PUT "https://connect.cariqa.com/api/v1/users/123/billing-details/" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "account_type": "business",
      "company_name": "Example Corp",
      "vat_number": "DE123456789"
    }'
  ```

  ```bash Get Billing Details theme={null}
  curl -X GET "https://connect.cariqa.com/api/v1/users/123/billing-details/" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

* **Business accounts** include company name and VAT number on invoices
* **Personal accounts** use first and last names on invoices

### 3. Payment Methods

<Warning>
  Payment method data is handled by Stripe. Use [Stripe's SDK](https://docs.stripe.com/payments/mobile/set-up-future-payments?platform=ios\&mobile-ui=payment-element#collect-payment-details) to collect payment details securely.
</Warning>

<CodeGroup>
  ```bash List Payment Methods theme={null}
  curl -X GET "https://connect.cariqa.com/api/v1/users/123/payment-methods/" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```bash Setup Intent for Card theme={null}
  curl -X GET "https://connect.cariqa.com/api/v1/users/123/setup-intents/?pm_type=card" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```bash Set Default Payment Method theme={null}
  curl -X POST "https://connect.cariqa.com/api/v1/users/123/payment-methods/pm_abc123/default/" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

**Supported operations:**

* `GET /users/<id>/payment-methods/` - List payment methods
* `DELETE /users/<id>/payment-methods/<pm_id>/` - Remove payment method
* `POST /users/<id>/payment-methods/<pm_id>/default/` - Set as default
* `GET /users/<id>/setup-intents/?pm_type=card` - Connect payment method (supports `card` and `paypal`)

### 4. Station Discovery

Station endpoints are **not tied to specific users** - they're general lookup endpoints.

<CodeGroup>
  ```bash Stations Around Location theme={null}
  curl -X GET "https://connect.cariqa.com/api/v1/stations/around/" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "latitude": 52.520008,
      "longitude": 13.404954,
      "distance": 5000
    }'
  ```

  ```bash Station Details theme={null}
  curl -X GET "https://connect.cariqa.com/api/v1/stations/details/?type=station_id&id=station_1234" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```bash Station Tile Data theme={null}
  curl -X GET "https://connect.cariqa.com/api/v1/stations/tile/?z=12&x=1234&y=5678" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

**Available endpoints:**

* `GET /stations/around/` - Find stations near a location
* `GET /stations/details/` - Get detailed station information
* `GET /stations/tile/` - Get map tile data for visualization

### 5. Charging Sessions

<CodeGroup>
  ```bash Start Charging theme={null}
  curl -X POST "https://connect.cariqa.com/api/v1/users/123/charging/start/" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_method_id": "pm_abc123",
      "evse_id": "DEBLA0034232"
    }'
  ```

  ```bash Stop Charging theme={null}
  curl -X POST "https://connect.cariqa.com/api/v1/users/123/charging/stop/456/" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```bash List Sessions theme={null}
  curl -X GET "https://connect.cariqa.com/api/v1/users/123/charging-sessions/" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

**Session management:**

* `POST /users/<id>/charging/start/` - Start charging session
* `POST /users/<id>/charging/stop/<session_id>/` - Stop charging session
* `GET /users/<id>/charging-sessions/` - List charging sessions
* `GET /users/<id>/charging-sessions/<session_id>/` - Get session details

## Typical Integration Flow

1. **Create user** in the Cariqa system
2. **Set up Stripe** payment methods using Stripe SDK
3. **Connect payment method** via setup intents
4. **Search stations** around user's location
5. **Start charging session** with payment method and EVSE ID
6. **Monitor session** status and handle completion
7. **Process invoicing** through automated CDR generation

## Next Steps

* Explore [Authentication](/authentication) for token setup
* Review [API Reference](/api-reference) for complete endpoint documentation
* Check integration examples for your platform
* Set up error handling and monitoring

<Note>
  Remember that Stripe SDK integration on your frontend is mandatory for PSD2/SCA compliance - payments cannot be processed backend-only.
</Note>