> ## 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.

# Shorten a URL

> Shorten a URL

## Shorten a URL

Generates shortened links per affiliate channel. Requires scope `shortener:write`.

### HTTP Request

```http theme={null}
POST https://api-beta.lomadee.com.br/affiliate/shortener/url
```

### Request Body

| Field            | Type   | Required         | Description                                           |
| ---------------- | ------ | ---------------- | ----------------------------------------------------- |
| `organizationId` | string | Yes              | Brand organization UUID                               |
| `type`           | string | Yes              | `Coupon`, `Offer`, `BrandPage`, `Custom`, or `Home`   |
| `featureId`      | string | For Coupon/Offer | Campaign operation ID from `GET /affiliate/campaigns` |
| `url`            | string | For Custom only  | HTTPS URL to shorten                                  |
| `mdasc`          | string | No               | Appended as `?mdasc=` on generated links              |

`url` is only allowed when `type` is `Custom`. For `Coupon` and `Offer`, `featureId` is required.

### Example — Brand page

```bash theme={null}
curl -X POST "https://api-beta.lomadee.com.br/affiliate/shortener/url" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "e36f5bbb-3e5f-42e2-be4c-6c32dac101c2",
    "type": "BrandPage"
  }'
```

### Response

Array of channel objects, each with `id`, `name`, `availableChannel`, `shortUrls`, and optional `message` when link generation is blocked.

```json theme={null}
[
  {
    "id": "channel-uuid",
    "name": "My Blog",
    "availableChannel": { "id": "...", "name": "Blog" },
    "shortUrls": ["https://staging.lmdee.link/abc123"]
  }
]
```

### Errors

| Status | Cause                                                                                                                               |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Missing `featureId` for Coupon/Offer, `url` missing for Custom, invalid domain, campos desconhecidos no body, ou UUID/tipo inválido |
| `401`  | Invalid API key                                                                                                                     |
| `403`  | Missing `shortener:write` scope                                                                                                     |
| `429`  | Rate limit exceeded (60 req/60s)                                                                                                    |


## OpenAPI

````yaml POST /affiliate/shortener/url
openapi: 3.1.0
info:
  title: Lomadee Public API
  description: >-
    REST API for affiliate brands, channels, campaigns, orders, products, and
    link shortener. Authenticate with x-api-key. Rate limit: 60 req/60s per key
    and IP.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.lomadee.com.br/
    description: Production — target URL for all integrations
  - url: https://api-beta.lomadee.com.br/
    description: Beta (legacy) — available during transition; will be retired soon
security:
  - x-api-key: []
paths:
  /affiliate/shortener/url:
    post:
      description: Shorten a URL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - organizationId
                - type
              properties:
                organizationId:
                  type: string
                  description: ID of the organization to generate the URL for
                type:
                  type: string
                  enum:
                    - Coupon
                    - BrandPage
                    - Offer
                    - Custom
                    - Home
                  description: >-
                    Link type. `Coupon` and `Offer` require `featureId`.
                    `Custom` requires `url` (HTTPS).
                featureId:
                  type: string
                  description: >-
                    Campaign operation ID. Required when type is Coupon or
                    Offer.
                url:
                  type: string
                  description: HTTPS URL. Required only when type is Custom.
                mdasc:
                  type: string
                  description: >-
                    Optional tracking identifier appended as ?mdasc= on
                    generated links.
      responses:
        '200':
          description: Shorten URL response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShortenUrlChannelResult'
          headers:
            X-RateLimit-Limit:
              description: Max requests per window
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Remaining requests in window
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp when window resets
              schema:
                type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    ShortenUrlChannelResult:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        availableChannel:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        shortUrls:
          type: array
          items:
            type: string
        message:
          type: string
  responses:
    Unauthorized:
      description: API key missing or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
              code:
                type: string
    Forbidden:
      description: Valid key without required scope
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
              code:
                type: string
    TooManyRequests:
      description: Rate limit exceeded (60 req/60s per key + IP)
      headers:
        X-RateLimit-Limit:
          description: Max requests per window
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Remaining requests in window
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix timestamp when window resets
          schema:
            type: integer
        Retry-After:
          description: Seconds until retry
          schema:
            type: integer
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
              code:
                type: string
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key

````