Combos

GET

Liste combos ativos com itens, preços, economia e disponibilidade. Suporta dois modos de QR code.

GET/api/integration/combos

Lista combos ativos com itens, preços e economia.

Modos de QR Code

Cada combo define como QR codes são gerados no checkout:

por_pessoa - Um QR code por pessoa. Todas as pessoas do combo precisam preencher nome, CPF, etc.
unico - Um QR code de grupo baseado no número do pedido (formato: YYYYMMDD-NNNN), mais QR codes individuais por pessoa. O QR do combo agrupa todos os participantes para check-in simultâneo.

O campo modo_qrcode está presente em todas as respostas para que seu sistema saiba qual fluxo de checkout apresentar.

Autenticação

Permissão necessária: integration:combos:read. Envie sua API Key no header X-Integration-Key.

Filtros

Parâmetro	Tipo	Padrão	Descrição
`destaque`	boolean	—	Filtrar apenas combos em destaque
`slug`	string	—	Buscar combo por slug exato (ex: combo-familia)
`limit`	number	`50`	Itens por página (max: 100)
`offset`	number	`0`	Pular N registros

Campos do Combo

Raiz

Parâmetro	Tipo	Padrão	Descrição
`id`	uuid	—	Identificador único do combo
`nome`	string	—	Nome do combo
`slug`	string	—	Slug URL-friendly para links diretos
`descricao`	string	—	Descrição do combo (pode conter HTML)
`preco_combo`	number	—	Preço final do combo (com desconto aplicado)
`preco_original`	number	—	Soma dos preços individuais dos itens (sem desconto)
`economia.valor`	number	—	Valor economizado em reais
`economia.percentual`	number	—	Percentual de desconto (0-100)
`tipo_desconto`	string	—	preco_fixo (valor manual) ou percentual (desconto %)
`modo_qrcode`	string	—	por_pessoa (1 QR por pessoa) ou unico (1 QR por pedido)
`requer_data`	boolean	—	Se true, cliente deve selecionar data de uso
`destaque`	boolean	—	Se o combo está em destaque
`max_por_pedido`	number	—	Quantidade máxima por pedido (null = ilimitado)
`total_ingressos`	number	—	Total de ingressos inclusos no combo
`itens_resumo`	string	—	Resumo legível dos itens

itens[]

Parâmetro	Tipo	Padrão	Descrição
`tipo_ingresso_id`	uuid	—	ID do tipo de ingresso
`tipo_ingresso_nome`	string	—	Nome do tipo de ingresso
`lote_nome`	string	—	Nome do lote/categoria
`categoria_lote_id`	uuid	—	ID da categoria de lote (identificador estável)
`quantidade`	number	—	Quantidade de ingressos deste item no combo
`preco_unitario`	number	—	Preço unitário congelado na criação do combo

Request

curl -X GET "https://api.omniticketz.com/v1/integration/combos" \
  -H "X-Integration-Key: sk_live_SUA_CHAVE_AQUI"

Response

200OK

{
  "success": true,
  "data": [
    {
      "id": "0c9469c9-3da3-4422-b01d-b7275e911ed7",
      "nome": "Combo Familia",
      "slug": "combo-familia",
      "descricao": "2 adultos + 2 criancas com almoco",
      "imagem_url": "https://...",
      "preco_combo": 299.90,
      "preco_original": 450.00,
      "economia": { "valor": 150.10, "percentual": 33 },
      "tipo_desconto": "preco_fixo",
      "modo_qrcode": "por_pessoa",
      "requer_data": true,
      "destaque": true,
      "max_por_pedido": 5,
      "itens": [
        {
          "tipo_ingresso_id": "d5b759f4-...",
          "tipo_ingresso_nome": "Day Use",
          "lote_nome": "Adulto COM Almoco",
          "quantidade": 2,
          "preco_unitario": 150.00
        }
      ],
      "total_ingressos": 4,
      "itens_resumo": "2x Adulto COM Almoco + 2x Crianca COM Almoco"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 3,
    "total_pages": 1
  },
  "timestamp": "2026-03-27T15:00:00.000Z"
}

GET/api/integration/combos/:id

Retorna detalhe de um combo específico. Aceita UUID ou slug como identificador.

Buscar por ID ou slug

curl -X GET "https://api.omniticketz.com/v1/integration/combos/0c9469c9-3da3-4422-b01d-b7275e911ed7" \
  -H "X-Integration-Key: sk_live_SUA_CHAVE_AQUI"

# Ou por slug
curl -X GET "https://api.omniticketz.com/v1/integration/combos/combo-familia" \
  -H "X-Integration-Key: sk_live_SUA_CHAVE_AQUI"

404Combo não encontrado

{
  "success": false,
  "error": {
    "code": "COMBO_NOT_FOUND",
    "message": "Combo nao encontrado: combo-inexistente"
  }
}

GET/api/integration/combos/:id/availability

Retorna datas disponíveis para um combo (interseção de todos os itens).

Estoque Compartilhado

A disponibilidade de um combo depende de todos os seus itens terem estoque na mesma data. O campo min_stock indica quantos combos podem ser vendidos naquela data (limitado pelo item com menor estoque).

Filtros

Parâmetro	Tipo	Padrão	Descrição
`date_from`	string	`hoje`	YYYY-MM-DD - Data inicial do período
`date_to`	string	`hoje+90d`	YYYY-MM-DD - Data final do período

Consultar disponibilidade

curl -X GET "https://api.omniticketz.com/v1/integration/combos/COMBO_ID/availability?date_from=2026-04-01&date_to=2026-04-30" \
  -H "X-Integration-Key: sk_live_SUA_CHAVE_AQUI"

200OK

{
  "success": true,
  "data": {
    "combo_id": "0c9469c9-3da3-4422-b01d-b7275e911ed7",
    "combo_nome": "Combo Familia",
    "modo_qrcode": "por_pessoa",
    "total_ingressos": 4,
    "requer_data": true,
    "dates": [
      {
        "date": "2026-04-01",
        "available": true,
        "min_stock": 23,
        "items_availability": [
          {
            "tipo_ingresso_nome": "Day Use",
            "lote_nome": "Adulto COM Almoco",
            "quantidade_necessaria": 2,
            "estoque_disponivel": 45
          }
        ]
      }
    ]
  },
  "timestamp": "2026-03-27T15:00:00.000Z"
}

Modos de QR Code

`por_pessoa`

Gera um QR code único para cada pessoa do combo. Todas as pessoas precisam preencher seus dados (nome, CPF, etc.) no checkout.

Exemplo: Combo com 4 ingressos = 4 QR codes, 4 formulários de dados.

`unico`

Gera um QR code de grupo baseado no número do pedido (formato: YYYYMMDD-NNNN), que agrupa todos os participantes para check-in simultâneo. Cada participante também recebe seu próprio QR individual.

No endpoint /orders/:id/qrcodes, os campos combo_qr_code e is_titular indicam o QR do grupo e quem é o responsável.

Erros Possíveis

Códigos de Erro

Parâmetro	Tipo	Padrão	Descrição
`COMBO_NOT_FOUND`	404	—	Combo não encontrado pelo ID ou slug informado
`QUERY_ERROR`	500	—	Erro interno ao consultar dados
`AUTH_ERROR`	401	—	API Key inválida ou sem permissão integration:combos:read
`RATE_LIMITED`	429	—	Limite de requisições excedido (100 req/min para GET)

Vouchers

QR Code Check-in