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

# Criar insell

> Cria uma promoção de insell (simple, custom ou iframe) em uma ação

Cria um insell na ação — uma promoção exibida na **tela do PIX**, no momento em que a chave aparece para copiar (pedido fechado, pagamento pendente). Máximo de **10 insells por ação**.

<Note>
  **Insell não suporta o tipo `redirect`.** Redirecionar o comprador na hora de pagar abortaria o pagamento. Tipos válidos: `simple`, `custom` e `iframe` — com o mesmo contrato dos [upsells](/api-reference/upsells/criar-upsell) e [presells](/api-reference/presells/criar-presell).
</Note>

## Path params

<ParamField path="id" type="string" required>
  ID da ação (UUID).
</ParamField>

## Body — campos comuns

<ParamField body="type" type="string" default="simple">
  `simple`, `custom` ou `iframe`. Omitido = `simple`.
</ParamField>

<ParamField body="title" type="string" required>
  Título (1–255 caracteres).
</ParamField>

<ParamField body="description" type="string | null">
  Descrição (máx. 1000).
</ParamField>

<ParamField body="display_order" type="number" default="0">
  Ordem de exibição (menor = primeiro).
</ParamField>

<ParamField body="is_active" type="boolean" default="true">
  Se o insell é exibido.
</ParamField>

## Body — por tipo

### `simple`

<ParamField body="simple" type="object" required>
  <Expandable title="simple">
    <ParamField body="button_text" type="string" required>Texto do botão (1–100).</ParamField>
    <ParamField body="button_url" type="string" required>URL http(s) de destino do botão (máx. 500).</ParamField>
  </Expandable>
</ParamField>

### `custom`

<ParamField body="custom" type="object" required>
  <Expandable title="custom">
    <ParamField body="type" type="string" required>`card` (dentro da tela do PIX) ou `fullscreen` (tela inteira).</ParamField>

    <ParamField body="content" type="string" required>
      HTML (1–50.000 caracteres). **Sanitizado no servidor** com as mesmas regras dos upsells/presells.
    </ParamField>

    <ParamField body="url.placeholder" type="string" required>
      Marcador no formato `{{NOME}}`, ex.: `{{INSELL_URL}}`. Precisa aparecer no `content`.
    </ParamField>

    <ParamField body="url.value" type="string" required>
      URL http(s) que substituirá o placeholder na renderização.
    </ParamField>
  </Expandable>
</ParamField>

### `iframe`

<ParamField body="iframe" type="object" required>
  <Expandable title="iframe">
    <ParamField body="type" type="string" required>`card` ou `fullscreen`.</ParamField>
    <ParamField body="url" type="string" required>URL http(s) carregada no iframe.</ParamField>
  </Expandable>
</ParamField>

## Erros

| HTTP  | Código                          | Quando ocorre                                                              |
| ----- | ------------------------------- | -------------------------------------------------------------------------- |
| `404` | `RAFFLE_NOT_FOUND`              | Ação inexistente ou de outra conta                                         |
| `400` | `INSELL_LIMIT_REACHED`          | Já existem 10 insells na ação                                              |
| `400` | `INSELL_SIMPLE_FIELDS_REQUIRED` | tipo `simple` sem o objeto `simple` completo                               |
| `400` | `INSELL_CUSTOM_CONFIG_REQUIRED` | `custom` sem o objeto `custom`                                             |
| `400` | `INSELL_IFRAME_CONFIG_REQUIRED` | `iframe` sem o objeto `iframe`                                             |
| `400` | `INSELL_CONFIG_TYPE_MISMATCH`   | Objeto de configuração não corresponde ao `type`                           |
| `400` | `INSELL_CUSTOM_CONTENT_EMPTY`   | HTML vazio após sanitização                                                |
| `400` | `INSELL_PLACEHOLDER_NOT_FOUND`  | Placeholder não aparece no `content`                                       |
| `422` | `VALIDATION`                    | Formato inválido — inclusive `type: "redirect"`, que não existe em insells |

<RequestExample>
  ```bash custom theme={null}
  curl -u "pb_xxx:sk_xxx" -X POST \
    -H "Content-Type: application/json" \
    -d '{
      "type": "custom",
      "title": "Enquanto o PIX não cai",
      "custom": {
        "type": "card",
        "content": "<h1>Oferta exclusiva!</h1><a href=\"{{INSELL_URL}}\">Aproveitar</a>",
        "url": { "placeholder": "{{INSELL_URL}}", "value": "https://insell.cliente.digital/" }
      }
    }' \
    "https://api.sortify.com.br/v1/raffles/{id}/insells"
  ```

  ```bash iframe theme={null}
  curl -u "pb_xxx:sk_xxx" -X POST \
    -H "Content-Type: application/json" \
    -d '{
      "type": "iframe",
      "title": "Oferta parceira",
      "iframe": { "type": "card", "url": "https://insell.cliente.digital/" }
    }' \
    "https://api.sortify.com.br/v1/raffles/{id}/insells"
  ```

  ```bash simple theme={null}
  curl -u "pb_xxx:sk_xxx" -X POST \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Garanta mais números",
      "simple": {
        "button_text": "Quero mais",
        "button_url": "https://loja.cliente.digital/oferta"
      }
    }' \
    "https://api.sortify.com.br/v1/raffles/{id}/insells"
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "message": "Insell criado com sucesso",
    "data": {
      "id": "4b3a2c1d-0e9f-8a7b-6c5d-e4f3a2b1c0d9",
      "type": "iframe",
      "title": "Oferta parceira",
      "description": null,
      "display_order": 0,
      "iframe": { "type": "card", "url": "https://insell.cliente.digital/" },
      "is_active": true,
      "created_at": "2026-07-06T12:00:00.000Z",
      "updated_at": "2026-07-06T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>