> ## 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 Pedidos
> Lista pedidos da sua conta com suporte a filtros, busca e paginação
#### Escopo
```bash theme={null}
read orders
```
## Filtros Disponíveis
Filtros podem ser combinados para refinar ainda mais os resultados.
Exemplo: `?customer=123&status=paid,waiting_payment` - Filtra pedidos do cliente com Id 123 que estão com status pago ou aguardando pagamento.
* `id` - Id do pedido (múltiplos valores separados por vírgula)
* `refId` - Id de referência do pedido (múltiplos valores separados por vírgula)
**Exemplo:** `?refId=ORDER123` - Filtra pedidos com Id de referência "ORDER123"
* `amount` - Valor total do pedido
* `baseAmount` - Valor base do pedido (sem taxa de parcelamento)
* `discount` - Valor do desconto aplicado (cupom, se houver)
Suporte a operadores de comparação (`__gt`, `__gte`, `__lt`, `__lte`)
**Exemplo:** `?amount__gte=1040` - Filtra pedidos com valor maior ou igual a R\$ 10,40
* `createdAt` - Data de criação do pedido
* `updatedAt` - Data de atualização do pedido
* `paidAt` - Data de confirmação do pagamento
* `refundedAt` - Data do reembolso
* `chargedbackAt` - Data do chargeback
* `canceledAt` - Data do cancelamento (normalmente para assinaturas)
* `due_date` - Data de agendamento do pagamento (normalmente para assinaturas)
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:** `?paidAt__gte=2024-01-01&paidAt__lt=2024-02-01` - Filtra pedidos pagos em janeiro de 2024
* `status` - [Status](/api-reference/orders/retrieve#status-do-pedido) do pedido
Suporte a múltiplos valores separados por vírgula.
**Exemplo:** `?status=paid,refunded` - Filtra pedidos pagos ou reembolsados
* `offer_type` - Tipo da oferta (main, upsell, downsell, orderbump)
* `type` - Tipo do produto (unique, subscription)
Suporte a múltiplos valores separados por vírgula.
**Exemplo:** `?offer_type=main,upsell&type=subscription` - Filtra pedidos de ofertas principais e upsell de produtos recorrentes
* `customer` - **Id**, **nome**, **email** ou **documento** do cliente
* `affiliate` - **Id** ou **email** do afiliado
* `product` - **Id** ou **nome** do produto
* `products` - **Id** dos produtos (múltiplos valores suportados)
* `offer` - **Id** da oferta (múltiplos valores suportados)
* `checkout` - **Id** do checkout (múltiplos valores suportados)
**Exemplo:** `?product=123&affiliate=456` - Filtra pedidos de um produto específico vendidos por um afiliado
* `paymentMethod` - Método de pagamento (múltiplos valores suportados)
* `coproductionType` - Tipo de coprodução (production, coproduction, affiliate)
* `installments` - Número de parcelas (múltiplos valores suportados)
* `couponCode` - Código do cupom utilizado
* `utm_source` - Fonte da campanha
* `utm_medium` - Meio da campanha
* `utm_campaign` - Nome da campanha
* `utm_term` - Termo da campanha
* `utm_content` - Conteúdo da campanha
* `checkoutURL` - URL do checkout (busca parcial case-insensitive)
* `referererURL` - URL de referência (busca parcial case-insensitive)
* `reason` - Motivo de recusa do pagamento (busca parcial case-insensitive)
**Exemplo:** `?paymentMethod=credit_card&installments=12` - Filtra pedidos pagos em 12x no cartão de crédito
## Dados do Cliente e Endereço
**Importante:** Os dados do cliente retornados dependem do nível de acesso do usuário:
O nível de acesso é determinado pelas configurações do produto vendido que pode ou não compartilhar as informações de contato do cliente com afiliados e coprodutores.
* **Com acesso total:** Retorna todos os dados do cliente (nome, email, telefone, documento, etc.)
* **Sem acesso:** Retorna apenas o nome do cliente
O mesmo se aplica aos dados de endereço do pedido, retornando `null` quando o usuário não tem acesso.
## Ordenação
Você pode ordenar os resultados usando o parâmetro `ordering`.
Campos suportados: `paidAt`, `createdAt`, `amount`, `refId`
Use o prefixo `-` para ordenação decrescente.
**Exemplo:** `?ordering=-paidAt` - Ordena por data de pagamento (mais recentes primeiro)
## OpenAPI
````yaml GET /public_api/orders/
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/orders/:
get:
tags:
- orders
description: >-
Public API for managing orders, inherits from OrderRetrieveAPI and
OrderListAPIView,
customizes the schema generation and authentication/permission settings.
operationId: orders_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/PaginatedOrderSchemaList'
examples:
Successo:
value:
count: 123
next: http://api.example.org/accounts/?page=4
previous: http://api.example.org/accounts/?page=2
results:
- id: 10bb51bb-03be-473c-b4c5-3490765c4096
refId: CATDiPp
status: refunded
type: unique
offer_type: main
baseAmount: '33.00'
discount: '0.00'
amount: '34.35'
coupon: null
couponCode: null
reason: null
refund_reason: null
product:
id: 10bb51bb-03be-473c-b4c5-3490765c4096
name: Product Name
image: >-
https://api.cakto.com.br/images/products/product_logo.png
description: Product description
price: 33
type: unique
contentDeliveries:
- cakto_v2
- emailAccess
emailAccessLink: https://example-email-to-send-to-customers.com.br
salesPage: https://api.cakto.com.br/dashboard/products
status: active
paymentMethods:
- boleto
- credit_card
- pix
category:
id: 10bb51bb-03be-473c-b4c5-3490765c4096
name: Cat2
checkout: 52
subscription: null
subscription_period: null
installments: 1
paymentMethod: credit_card
createdAt: '2025-10-03T11:19:35.019507-03:00'
due_date: null
paidAt: '2025-10-03T11:19:37.064939-03:00'
releaseDate: null
refundedAt: '2025-10-29T18:35:40.729119-03:00'
chargedbackAt: null
canceledAt: null
customer:
name: Customer Name Example
email: teste74727@gmail.com
birthDate: null
phone: '16999997777'
docType: cpf
docNumber: '11199933377'
address:
country: BR
state: MG
city: Monte Carmelo
zipcode: '38500000'
street: Rua Teste
neighborhood: Centro
complement: Point of reference
number: '177'
shipping: null
fees: '1.52'
commissionedUsers:
- id: 1
email: teste@teste.com
- id: 2
email: testeando@teste.com
commissions:
- userId: '1'
type: producer
commissionPercentage: 50
commissionValue: 15.41
- userId: '2'
type: coproducer
commissionPercentage: 50
commissionValue: 15.42
utm_source: ''
utm_medium: ''
utm_campaign: ''
utm_term: ''
utm_content: ''
sck: null
checkoutUrl: https://pay.cakto.com.br/EXAMPLE
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:
PaginatedOrderSchemaList:
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/OrderSchema'
UnauthenticatedError:
type: object
properties:
detail:
type: string
OrderSchema:
type: object
properties:
id:
type: string
title: Id do Pedido
description: Identificador único do pedido no sistema
maxLength: 255
refId:
type: string
title: Id de Referência
description: Id curto de referência do pedido
maxLength: 255
status:
allOf:
- $ref: '#/components/schemas/OrderSchemaStatusEnum'
description: |-
Status atual do pedido
* `processing` - Processando
* `authorized` - Autorizado
* `paid` - Pago
* `refund_requested` - Reembolso solicitado
* `in_settlement` - Em efetivação
* `acquirer_error` - Erro na adquirente
* `refunded` - Reembolsado
* `waiting_payment` - Aguardando pagamento
* `refused` - Recusado
* `blocked` - Recusado
* `chargedback` - Chargeback
* `canceled` - Cancelado
* `in_protest` - Em protesto
* `partially_paid` - Parcialmente pago
* `prechargeback` - Prechargeback
* `scheduled` - Scheduled
* `retrying` - Retrying
* `MED` - Med
type:
allOf:
- $ref: '#/components/schemas/ProductType'
title: Tipo de Produto
description: |-
Tipo do produto comprado no pedido
* `unique` - Pagamento único
* `subscription` - Assinatura recorrente
offer_type:
allOf:
- $ref: '#/components/schemas/OfferTypeEnum'
title: Tipo de Oferta
description: |-
Tipo da oferta comprada no pedido
* `main` - Principal
* `upsell` - Upsell
* `downsell` - Downsell
* `orderbump` - Order Bump
baseAmount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
title: Valor Base
description: Valor base do pedido antes de descontos e taxas
discount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
nullable: true
title: Desconto
description: Valor do desconto aplicado no pedido
amount:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
nullable: true
title: Valor Total
description: Valor total do pedido após descontos e taxas
coupon:
allOf:
- $ref: '#/components/schemas/CouponPublic'
readOnly: true
description: Cupom aplicado na compra
couponCode:
type: string
nullable: true
title: Código do Cupom
description: Código do cupom de desconto aplicado no pedido
maxLength: 255
reason:
type: string
nullable: true
title: Motivo de recusa
description: Motivo de recusa do pagamento
maxLength: 255
refund_reason:
type: string
nullable: true
title: Motivo do Reembolso
description: Descrição do motivo do reembolso do pedido
product:
allOf:
- $ref: '#/components/schemas/Product'
readOnly: true
description: Produto adquirido na compra
checkout:
type: integer
nullable: true
description: Checkout onde a compra foi realizada
subscription:
type: string
title: Assinatura
description: Assinatura associada ao pedido
nullable: true
subscription_period:
type: integer
maximum: 2147483647
minimum: -2147483648
nullable: true
title: Período da Assinatura
description: Período da assinatura que este pedido corresponde
installments:
type: integer
maximum: 2147483647
minimum: -2147483648
title: Parcelas
description: Número de parcelas que o valor foi dividido
paymentMethod:
type: string
description: Método de pagamento utilizado na compra
createdAt:
type: string
format: date-time
readOnly: true
title: Data de criação
description: Data e hora de criação
due_date:
type: string
format: date-time
nullable: true
title: Data de agendamento
description: Data e hora em que o pagamento será processado
paidAt:
type: string
format: date-time
nullable: true
title: Data de pagamento
description: Data e hora em que o pedido foi pago
releaseDate:
type: string
format: date-time
nullable: true
title: Data de liberação
description: Data e hora estimada de liberação das comissões
refundedAt:
type: string
format: date-time
nullable: true
title: Data de reembolso
description: Data e hora em que o pedido foi reembolsado
refundRequestedAt:
type: string
format: date-time
nullable: true
title: Data de solicitação de reembolso
description: Data e hora em que a solicitação de reembolso foi feita pelo cliente
refundReversalDeadlineAt:
type: string
format: date-time
nullable: true
title: Prazo final para reversão
description: >-
Momento em que o reembolso será efetivado automaticamente se não
houver cancelamento
chargedbackAt:
type: string
format: date-time
nullable: true
title: Data de chargeback
description: Data e hora que o chargeback foi realizado
canceledAt:
type: string
format: date-time
nullable: true
title: Data de cancelamento
description: Data e hora de cancelamento do pedido
customer:
allOf:
- $ref: '#/components/schemas/OrderCustomer'
readOnly: true
description: Cliente que realizou a compra
address:
allOf:
- $ref: '#/components/schemas/CustomerAddressFull'
readOnly: true
description: Endereço do cliente
fees:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
nullable: true
title: Taxas
description: Valor total das taxas aplicadas ao pedido
additionalInstallmentInterest:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
title: Juros Adicional de Parcelamento
description: >-
Valor adicional de juros de parcelamento cobrado do cliente, aumenta
os ganhos do produtor
interest:
type: string
format: decimal
pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
nullable: true
title: Juros
description: Valor total de juros de parcelamento cobrado
absorbInstallmentInterest:
type: boolean
readOnly: true
description: Indica se o produtor absorveu os juros de parcelamento
commissionedUsers:
type: array
items:
$ref: '#/components/schemas/UserReadOnly'
readOnly: true
description: Usuários comissionados na compra
commissions:
type: array
items:
$ref: '#/components/schemas/CommissionsSchema'
readOnly: true
description: Detalhes das comissões associadas à compra
utm_source:
type: string
nullable: true
description: 'Origem do tráfego (ex: google, instagram, newsletter)'
maxLength: 255
utm_medium:
type: string
nullable: true
description: 'Meio do tráfego (ex: cpc, email, social)'
maxLength: 255
utm_campaign:
type: string
nullable: true
description: 'Nome da campanha (ex: promocao_2023)'
maxLength: 255
utm_term:
type: string
nullable: true
description: 'Termo da campanha (ex: sapato+vermelho)'
maxLength: 255
utm_content:
type: string
nullable: true
description: 'Conteúdo da campanha (ex: banner_superior)'
maxLength: 255
sck:
type: string
nullable: true
description: >-
Parâmetro personalizado, geralmente usado internamente para rastrear
algo específico (ex: ID de clique, sessão, ou código de origem
próprio)
maxLength: 255
checkoutUrl:
type: string
nullable: true
title: URL do Checkout
description: URL do checkout onde o pedido foi realizado
required:
- absorbInstallmentInterest
- address
- baseAmount
- commissionedUsers
- commissions
- coupon
- createdAt
- customer
- paymentMethod
- product
OrderSchemaStatusEnum:
enum:
- processing
- authorized
- paid
- refund_requested
- in_settlement
- acquirer_error
- refunded
- waiting_payment
- refused
- blocked
- chargedback
- canceled
- in_protest
- partially_paid
- prechargeback
- scheduled
- retrying
- MED
type: string
description: |-
* `processing` - Processando
* `authorized` - Autorizado
* `paid` - Pago
* `refund_requested` - Reembolso solicitado
* `in_settlement` - Em efetivação
* `acquirer_error` - Erro na adquirente
* `refunded` - Reembolsado
* `waiting_payment` - Aguardando pagamento
* `refused` - Recusado
* `blocked` - Recusado
* `chargedback` - Chargeback
* `canceled` - Cancelado
* `in_protest` - Em protesto
* `partially_paid` - Parcialmente pago
* `prechargeback` - Prechargeback
* `scheduled` - Scheduled
* `retrying` - Retrying
* `MED` - Med
ProductType:
enum:
- unique
- subscription
type: string
description: |-
* `unique` - Pagamento único
* `subscription` - Assinatura recorrente
OfferTypeEnum:
enum:
- main
- upsell
- downsell
- orderbump
type: string
description: |-
* `main` - Principal
* `upsell` - Upsell
* `downsell` - Downsell
* `orderbump` - Order Bump
CouponPublic:
type: object
properties:
code:
type: string
title: Código do cupom
description: Código usado para obter o desconto
maxLength: 30
discount:
type: number
format: double
description: Desconto aplicado pelo cupom
applyOnBumps:
type: boolean
title: Aplicar em Order Bumps
description: Define se o cupom pode ser aplicado em order bumps
startTime:
type: string
format: date-time
title: Data de início
description: Data e hora em que o cupom começa a ser válido
endTime:
type: string
format: date-time
nullable: true
title: Data de término
description: >-
Data e hora em que o cupom deixa de ser válido. Se nulo, o cupom não
expira.
required:
- code
- discount
- startTime
Product:
type: object
properties:
id:
type: string
description: Identificador único do produto
maxLength: 255
name:
type: string
title: Nome
description: Nome do produto
maxLength: 255
image:
type: string
format: uri
readOnly: true
nullable: true
title: Imagem
description: Imagem do produto
description:
type: string
title: Descrição
description: Descrição do produto
price:
type: number
format: double
description: Preço do produto
currency:
allOf:
- $ref: '#/components/schemas/CurrencyEnum'
title: Moeda
description: |-
Moeda do produto
* `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
type:
allOf:
- $ref: '#/components/schemas/ProductType'
title: Tipo
description: |-
Tipo de venda do produto, ex.: venda única, assinatura...
* `unique` - Pagamento único
* `subscription` - Assinatura recorrente
contentDeliveries:
type: array
items:
type: string
readOnly: true
description: Id dos métodos de entrega de conteúdo disponíveis
emailAccessLink:
type: string
format: uri
nullable: true
title: Link de acesso
description: Link a ser enviado por e-mail para acesso ao conteúdo após a compra
maxLength: 2048
salesPage:
type: string
format: uri
nullable: true
title: Página de vendas
description: Link da página de vendas do produto
maxLength: 2048
status:
allOf:
- $ref: '#/components/schemas/ProductStatus'
description: |-
Status atual do produto
* `active` - Ativo
* `waiting_config` - Aguardando Configuração
* `blocked` - Bloqueado
* `deleted` - Deletado
paymentMethods:
type: array
items:
type: string
readOnly: true
description: Id dos métodos de pagamento disponíveis
category:
allOf:
- $ref: '#/components/schemas/Category'
readOnly: true
description: Categoria do produto
required:
- category
- contentDeliveries
- description
- image
- name
- paymentMethods
- price
OrderCustomer:
oneOf:
- $ref: '#/components/schemas/CustomerOrder'
- $ref: '#/components/schemas/OrderCustomerMinimal'
CustomerAddressFull:
type: object
properties:
id:
type: integer
readOnly: true
customer:
type: integer
readOnly: true
title: Cliente
description: Cliente proprietário do endereço
country:
type: string
title: País
description: 'Código do país no formato ISO 3166-1 Alpha-2 (ex: BR para Brasil)'
maxLength: 2
state:
type: string
title: Estado
description: >-
Código do estado no formato ISO 3166-2 Alpha-2 (ex: SP para São
Paulo)
maxLength: 2
city:
type: string
title: Cidade
description: Nome da cidade
maxLength: 255
zipcode:
type: string
title: CEP
description: Código Postal
maxLength: 30
street:
type: string
title: Rua
description: Nome da rua
maxLength: 255
neighborhood:
type: string
nullable: true
title: Bairro
description: Nome do bairro
maxLength: 255
complement:
type: string
nullable: true
title: Complemento
description: Complemento do endereço
maxLength: 255
number:
type: string
title: Número
description: Número do endereço
maxLength: 255
is_default:
type: boolean
title: Endereço Principal
description: Define se este é o endereço principal do cliente
createdAt:
type: string
format: date-time
readOnly: true
title: Data de criação
description: Data e hora de criação
updatedAt:
type: string
format: date-time
readOnly: true
title: Data de atualização
description: Data e hora da última atualização
required:
- city
- country
- createdAt
- customer
- id
- number
- state
- street
- updatedAt
- zipcode
UserReadOnly:
type: object
properties:
id:
type: integer
readOnly: true
email:
type: string
format: email
title: Endereço de email
description: Email. Obrigatório e único
maxLength: 254
required:
- id
CommissionsSchema:
type: object
properties:
userId:
type: integer
description: ID do usuário comissionado
type:
allOf:
- $ref: '#/components/schemas/CommissionsSchemaTypeEnum'
description: |-
Tipo de comissão
* `affiliate` - Afiliado
* `coproducer` - Coprodutor
* `producer` - Produtor
commissionPercentage:
type: number
format: double
description: Porcentagem de comissão
commissionValue:
type: number
format: double
description: Valor da comissão
required:
- commissionPercentage
- commissionValue
- type
- userId
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
ProductStatus:
enum:
- active
- waiting_config
- blocked
- deleted
type: string
description: |-
* `active` - Ativo
* `waiting_config` - Aguardando Configuração
* `blocked` - Bloqueado
* `deleted` - Deletado
Category:
type: object
properties:
id:
type: string
maxLength: 255
name:
type: string
maxLength: 255
required:
- name
CustomerOrder:
type: object
properties:
id:
type: integer
readOnly: true
name:
type: string
title: Nome
description: Nome completo do cliente
maxLength: 255
email:
type: string
format: email
description: Endereço de email do cliente
maxLength: 254
birthDate:
type: string
format: date
nullable: true
title: Nascimento
description: Data de nascimento do cliente
phone:
type: string
title: Telefone
description: Número de telefone do cliente
maxLength: 255
docType:
nullable: true
title: Tipo de Documento
description: |-
Tipo do documento (ex: cpf, cnpj)
* `cpf` - CPF
* `cnpj` - CNPJ
* `dni` - DNI
* `cuit` - CUIT
oneOf:
- $ref: '#/components/schemas/DocTypeEnum'
- $ref: '#/components/schemas/BlankEnum'
- $ref: '#/components/schemas/NullEnum'
docNumber:
type: string
nullable: true
title: Documento
description: Número do documento do cliente
maxLength: 255
required:
- email
- id
- name
- phone
OrderCustomerMinimal:
type: object
properties:
name:
type: string
required:
- name
CommissionsSchemaTypeEnum:
enum:
- affiliate
- coproducer
- producer
type: string
description: |-
* `affiliate` - Afiliado
* `coproducer` - Coprodutor
* `producer` - Produtor
DocTypeEnum:
enum:
- cpf
- cnpj
- dni
- cuit
type: string
description: |-
* `cpf` - CPF
* `cnpj` - CNPJ
* `dni` - DNI
* `cuit` - CUIT
BlankEnum:
enum:
- ''
NullEnum:
enum:
- null
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).
````