> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cakto.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar Ofertas
> Lista ofertas dos seus produtos com suporte a filtros, busca e paginação
#### Escopo
```bash theme={null}
read offers
```
## Filtros Disponíveis
Filtros podem ser combinados para refinar ainda mais os resultados.
Exemplo: `?product=123&status=active,disabled` - Filtra ofertas ativas ou desabilitadas de um produto específico.
* `id` - Id da oferta (múltiplos valores separados por vírgula)
* `name` - Nome da oferta (busca parcial, case-insensitive)
**Exemplo:** `?id=OFF123,OFF456&name=meu-produto` - Filtra ofertas com Id OFF123 ou OFF456 e nome contendo "meu-produto"
* `price` - Valor da oferta
Suporte a operadores de comparação (`__gt`, `__gte`, `__lt`, `__lte`)
**Exemplo:** `?price__gte=5000` - Filtra ofertas com valor maior ou igual a R\$ 50,00
* `createdAt` - Data de criação
* `updatedAt` - Data de última atualização
Suporte a operadores de comparação (`__gt`, `__gte`, `__lt`, `__lte`)
Formato de data: `YYYY-MM-DD` ou [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) `YYYY-MM-DDTHH:MM:SS±hh:mm`
**Exemplo:** `?createdAt__gte=2024-01-01&createdAt__lt=2024-02-01T23:59:59Z` - Filtra produtos criados em janeiro de 2024
* `status` - Status da oferta (active, disabled)
Suporte a múltiplos valores separados por vírgula.
**Exemplo:** `?status=active&type=subscription` - Filtra ofertas ativas de assinatura
* `type` - Tipo da oferta (unique, subscription)
Suporte a múltiplos valores separados por vírgula.
**Exemplo:** `?type=subscription` - Filtra ofertas de assinatura
Esses filtros são aplicáveis apenas para ofertas do tipo `unique`.
* `intervalType` - Tipo de intervalo da oferta (day, week, month, year) (múltiplos valores suportados)
* `interval` - Quantidade de intervalos (número inteiro)
**Exemplo:** `?intervalType=month&interval=6` - Filtra ofertas com intervalo de 6 meses
Esses filtros são aplicáveis apenas para ofertas do tipo `subscription`.
* `recurrence_period` - Período de recorrência em dias (número inteiro)
* `quantity_recurrences` - Quantidade de recorrências (número inteiro)
* `trial_days` - Quantidade de dias de período de teste (número inteiro)
* `max_retries` - Quantidade máxima de tentativas de cobrança (número inteiro)
* `retry_interval` - Quantidade de dias entre tentativas de cobrança (número inteiro)
**Exemplo:** `?recurrence_period=30&quantity_recurrences=12` - Filtra ofertas com renovação mensal e duração de 1 ano
* `product` - **Id** do produto ao qual a oferta pertence
Suporte a múltiplos valores separados por vírgula.
**Exemplo:** `?product=AB123,BC456` - Filtra ofertas dos produtos com Id AB123 e BC456
* `default` - Se é a oferta padrão do produto (true/false)
**Exemplo:** `?default=true` - Filtra apenas ofertas padrão dos produtos
## Busca
O endpoint suporta busca textual pelo parâmetro `search` nos seguintes campos:
* `name` - Nome da oferta
* `id` - Id da oferta
* `product.name` - Nome do produto associado à oferta
* `product.short_id` - Id curto do produto associado à oferta
* `product.id` - Id completo do produto associado à oferta
**Exemplo:** `?search=meu-produto` - Busca pelo texto "meu-produto" nos campos de busca.
Qualquer oferta onde um dos campos contenha o texto será retornada, ("meu-produto 2.0" e "Oferta B meu-produto" seriam retornadas).
## Ordenação
Você pode ordenar os resultados usando o parâmetro `ordering`:
Campos suportados: `id`, `name`, `price`, `product`, `status`, `default`, `createdAt`, `updatedAt`
Use o prefixo `-` para ordenação decrescente.
**Exemplo:** `?ordering=-createdAt` - Ordena por data de criação (mais recentes primeiro)
## OpenAPI
````yaml GET /public_api/offers/
openapi: 3.0.3
info:
title: Cakto API
version: 1.0.0
description: Documentação da API pública do Cakto.
servers:
- url: https://api.cakto.com.br
description: Cakto API
security: []
paths:
/public_api/offers/:
get:
tags:
- offers
description: |-
Public API for managing offers, inherits from OfferAPIView,
customizes the schema generation and authentication/permission settings.
operationId: offers_list
parameters:
- name: limit
required: false
in: query
description: Número de resultados a serem retornados por página.
schema:
type: integer
- name: page
required: false
in: query
description: Número da página a ser retornada.
schema:
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedOfferList'
examples:
Successo:
value:
count: 123
next: http://api.example.org/accounts/?page=4
previous: http://api.example.org/accounts/?page=2
results:
- id: 5Hrb526
name: Nome da Oferta
image: https://example.com/image.png
price: 5
units: 1
default: true
product: fb3fda61-e88f-43b5-982a-32d50f112414
status: active
type: unique
intervalType: week
interval: 1
recurrence_period: 30
quantity_recurrences: -1
trial_days: 0
max_retries: 3
retry_interval: 1
description: Corpo da resposta status 200
'401':
description: Request não autenticado devido à ausência ou invalidez do token.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedError'
examples:
Token ausente ou inválido:
$ref: '#/components/examples/UnauthenticatedErrorExample'
security:
- OAuth Token: []
components:
schemas:
PaginatedOfferList:
type: object
properties:
count:
type: integer
example: 123
next:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?page=4
previous:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?page=2
results:
type: array
items:
$ref: '#/components/schemas/Offer'
UnauthenticatedError:
type: object
properties:
detail:
type: string
Offer:
type: object
description: >-
Secure file replacement (context)
-------------------------------
When an update replaces an existing uploaded file (e.g. a profile
picture), the
old file usually remains in storage unless you explicitly delete it.
Over time,
this leaves orphaned files and increases storage costs.
What this class does
--------------------
This is an opt-in base serializer that deletes old files from storage
*after* a
successful update that replaces (or clears) a Django
``models.FileField`` /
``models.ImageField``.
It is configured via ``Meta.delete_replaced_files_fields``:
- As a list/tuple/set of field names, or
- As a dict mapping field name → options.
Supported options (per field)
-----------------------------
- ``delete_on_clear`` (bool, default True): when the update sets the
field to
``None``/empty, delete the previous stored file.
Example usage (simple)
----------------------
```python
class UserUpdateSerializer(DeleteOldFilesMixin,
serializers.ModelSerializer): # DeleteOldFilesMixin should be first
that the actual serializer
class Meta:
model = User
fields = ["id", "picture", "first_name", "last_name"]
delete_replaced_files_fields = ["picture"]
```
Example usage (per-field options)
--------------------------------
```python
class DocumentUpdateSerializer(DeleteOldFilesMixin,
serializers.ModelSerializer): # DeleteOldFilesMixin should be first
that the actual serializer
class Meta:
model = Document
fields = ["id", "picture", "document_image"]
delete_replaced_files_fields = {
"picture": {"delete_on_clear": True},
"document_image": {"delete_on_clear": False},
}
```
properties:
id:
type: string
readOnly: true
title: Identificador
description: Identificador único da oferta
name:
type: string
title: Nome
description: Nome da oferta, exibido no checkout e em outros locais
maxLength: 255
image:
type: string
format: uri
nullable: true
price:
type: number
format: double
description: Preço da oferta
currency:
allOf:
- $ref: '#/components/schemas/CurrencyEnum'
title: Moeda
description: |-
Moeda da oferta
* `BRL` - Real
* `EUR` - Euro
* `MXN` - Peso Mexicano
* `PEN` - Sol Peruano
* `USD` - Dólar
* `CLP` - Peso Chileno
* `COP` - Peso Colombiano
* `ARS` - Peso Argentino
* `BOB` - Boliviano
* `UYU` - Peso Uruguayo
units:
type: integer
maximum: 2147483647
minimum: 1
title: Unidades
description: >-
Número de unidades que o cliente irá adquirir ao comprar esta
oferta.
default:
type: boolean
readOnly: true
description: Indica se esta é a oferta padrão do produto
product:
type: string
description: Produto ao qual esta oferta pertence
title: Produto
status:
allOf:
- $ref: '#/components/schemas/OfferStatus'
description: |-
Status atual da oferta
* `active` - Ativo
* `disabled` - Desabilitado
* `deleted` - Deletado
type:
allOf:
- $ref: '#/components/schemas/ProductType'
title: Tipo de pagamento
description: |-
Tipo de pagamento da oferta (ex: unique, subscription)
* `unique` - Pagamento único
* `subscription` - Assinatura recorrente
intervalType:
allOf:
- $ref: '#/components/schemas/IntervalTypeEnum'
title: Tipo de intervalo
description: >-
Tipo de intervalo do acesso concedido pela oferta (ex: month, week,
lifetime)
* `week` - Semana
* `month` - Mês
* `year` - Ano
* `lifetime` - Vitalício
interval:
type: integer
maximum: 2147483647
minimum: -2147483648
title: Quantidade de intervalos
description: >-
Número de intervalos que serão concedidos ao comprar esta oferta.
Ex: `interval=2` e `intervalType=month` concede 2 meses de acesso.
recurrence_period:
type: integer
maximum: 2147483647
minimum: -2147483648
title: Período de recorrência
description: Número de dias entre cada cobrança da assinatura
quantity_recurrences:
type: integer
maximum: 2147483647
minimum: -2147483648
title: Quantidade de recorrências
description: >-
Número de cobranças que serão feitas na assinatura. Use -1 para
cobranças ilimitadas.
trial_days:
type: integer
maximum: 2147483647
minimum: -2147483648
title: Dias de teste
description: Número de dias de teste grátis antes da primeira cobrança
max_retries:
type: integer
maximum: 2147483647
minimum: -2147483648
title: Quantidade de retentativas de cobrança
description: >-
Número máximo de retentativas de cobrança em caso de falha no
pagamento
retry_interval:
type: integer
maximum: 2147483647
minimum: -2147483648
title: Intervalo entre retentativas
description: Número de dias entre cada retentativa de cobrança
required:
- default
- id
- name
- price
- product
CurrencyEnum:
enum:
- BRL
- EUR
- MXN
- PEN
- USD
- CLP
- COP
- ARS
- BOB
- UYU
type: string
description: |-
* `BRL` - Real
* `EUR` - Euro
* `MXN` - Peso Mexicano
* `PEN` - Sol Peruano
* `USD` - Dólar
* `CLP` - Peso Chileno
* `COP` - Peso Colombiano
* `ARS` - Peso Argentino
* `BOB` - Boliviano
* `UYU` - Peso Uruguayo
OfferStatus:
enum:
- active
- disabled
- deleted
type: string
description: |-
* `active` - Ativo
* `disabled` - Desabilitado
* `deleted` - Deletado
ProductType:
enum:
- unique
- subscription
type: string
description: |-
* `unique` - Pagamento único
* `subscription` - Assinatura recorrente
IntervalTypeEnum:
enum:
- week
- month
- year
- lifetime
type: string
description: |-
* `week` - Semana
* `month` - Mês
* `year` - Ano
* `lifetime` - Vitalício
examples:
UnauthenticatedErrorExample:
summary: Token ausente ou inválido
description: Token ausente ou inválido
value:
detail: As credenciais de autenticação não foram fornecidas.
securitySchemes:
OAuth Token:
type: http
scheme: bearer
in: header
name: Authorization
description: >-
Token de autenticação do tipo `Bearer {access_token}`, onde
`{access_token}` é o token obtido no fluxo de
[autenticação](/authentication).
````