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

# Introduction

> Lomadee API Documentation

## Welcome to Lomadee API

The Lomadee API enables seamless integration and programmatic management of your affiliate campaigns, brands, and orders. Our RESTful API provides comprehensive endpoints to handle all aspects of your affiliate network operations.

## Base URL

| Environment   | URL                               | Status                                                |
| ------------- | --------------------------------- | ----------------------------------------------------- |
| Production    | `https://api.lomadee.com.br`      | **Target URL** — use for new integrations             |
| Beta (legacy) | `https://api-beta.lomadee.com.br` | Available during transition; **will be retired soon** |

The API is moving to **`api.lomadee.com.br`**. The `api-beta` host still works today, but plan to update your base URL before it is shut down. Paths, headers, and response formats are unchanged.

See the [Changelog](/api-reference/changelog) for migration details.

## Available Resources

### Brands

* List and retrieve all available brands
* Get detailed information about specific brands
* Monitor approval status and access restrictions
* Track brand performance metrics

### Channels

* List all affiliate-owned channels (used for link generation)
* Get a specific channel by ID
* Channels belong to the authenticated affiliate (`user_id`), not to an organization

### Campaigns

* List and filter active campaigns
* Campaign types:
  * PersonalCoupon: Unique coupon codes for specific users
  * GenericCoupon: Public coupon codes for general use
  * Offer: Special promotional offers and deals
* Manage campaign lifecycle:
  * Set validity periods
  * Control campaign highlights
  * Update status
  * Organize by categories and tags

### Orders

* Query and track completed orders
* Monitor commission status and earnings
* View detailed item information
* Track transaction values and commission rates
* Export order reports

### Products

* List and search available products across all brands
* Filter products by price range, brand, and availability
* Access detailed product information including images and specifications
* View pricing, stock levels, and product variants
* Build product catalogs and recommendation systems

## Authentication

All API requests require authentication using an API key in the request header:

```json theme={null}
{
  "headers": {
    "x-api-key": "your-api-key"
  }
}
```

API keys are provisioned via GraphQL on the open-api service (dashboard JWT in `x-api-token`). See [API Keys](/api-reference/api-keys) for scopes and key formats.

Each affiliate key carries granular scopes. Missing scope returns `403 Forbidden`.

## Pagination

Pagination shape varies by resource. Query parameters `page` and `limit` are supported where noted.

**`limit` ceiling:** maximum **20** on list endpoints that generate affiliate links (`GET /affiliate/brands`, `GET /affiliate/campaigns`). Values above 20 are **clamped silently**. Maximum **100** on orders, shortener, and partner list endpoints (clamp silently above 100). `GET /affiliate/channels` returns at most **20** channels. `GET /affiliate/products` returns **400** if `limit` is less than 1 or greater than 100.

| Resource       | Response pagination field                             | Default `limit` | Max `limit` |
| -------------- | ----------------------------------------------------- | --------------- | ----------- |
| Brands         | `pagination` (`page`, `limit`, `total`, `totalPages`) | 20              | 20          |
| Campaigns      | `meta`                                                | 10              | 20          |
| Orders         | `meta`                                                | 10              | 100         |
| Shortener URLs | `meta`                                                | 10              | 100         |
| Products       | `count` (total only; no `page` in body)               | 5               | 100         |
| Channels       | `count` (max 20 channels)                             | —               | 20          |

Example with `meta` (campaigns, orders, shortener):

```json theme={null}
{
  "data": [],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 10,
    "totalPages": 10
  }
}
```

Example with `pagination` (brands):

```json theme={null}
{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}
```

Example with `count` (products, channels):

```json theme={null}
{
  "data": [],
  "count": 107
}
```

## Status Codes

* `200`: Success - Request completed successfully
* `400`: Bad Request - Invalid parameters or malformed request
* `401`: Unauthorized - API key missing, invalid, or wrong type
* `403`: Forbidden - Valid key without required scope
* `404`: Not Found - Resource doesn't exist
* `429`: Too Many Requests - Rate limit exceeded
* `500`: Internal Server Error - Server-side error

All error responses follow:

```json theme={null}
{
  "success": false,
  "message": "Human-readable description",
  "code": "ERROR_CODE"
}
```

## Rate limiting

Global limit: **60 requests per 60 seconds** per API key and client IP.

Every response may include:

| Header                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the window   |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets    |

When exceeded, the API returns `429` with `Retry-After` (seconds until retry) and `X-RateLimit-Limit`, `X-RateLimit-Remaining` (0), and `X-RateLimit-Reset`.

## API Limits and Quotas

* Rate limiting: 60 requests per 60 seconds (per key + IP)
* Maximum payload size: 1MB per request
* Request timeout: 60 seconds

## Best Practices

1. Implement proper error handling
2. Use pagination for large datasets
3. Cache responses when appropriate
4. Monitor rate limits
5. Validate request parameters

## Support and Resources

For technical assistance and API-related questions:

1. Comprehensive [API Documentation](https://docs.lomadee.com)
2. Technical [Support Portal](https://suporte.lomadee.com)
3. [Developer Portal](https://developers.lomadee.com) with:
   * API Reference
   * Code Examples
   * SDK Downloads
   * Integration Guides