OmniTicketz API Documentation

GET/api/integration/combos

Lista combos ativos com itens, precos, economia e disponibilidade. Suporta dois modos de QR code.

Modos de QR Code

Cada combo define como QR codes sao 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 numero do pedido (formato: YYYYMMDD-NNNN), mais QR codes individuais por pessoa. O QR do combo agrupa todos os participantes para check-in simultaneo.

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

Autenticacao

Permissao necessaria: integration:combos:read

Envie sua API Key no header X-Integration-Key.

Listar Combos

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 pagina (max: 100)
`offset`	number	`0`	Pular N registros

Listar todos os combos ativos

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

Filtrar combos em destaque

curl -X GET "https://sua-plataforma.com.br/api/v1/integration/combos?destaque=true" \
  -H "X-Integration-Key: sk_live_SUA_CHAVE_AQUI"

Resposta - Listar Combos

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",
      "percentual_desconto": null,
      "modo_qrcode": "por_pessoa",
      "requer_data": true,
      "destaque": true,
      "max_por_pedido": 5,
      "data_inicio": "2026-01-01",
      "data_fim": "2026-12-31",
      "itens": [
        {
          "tipo_ingresso_id": "d5b759f4-...",
          "tipo_ingresso_nome": "Day Use",
          "lote_nome": "Adulto COM Almoco",
          "categoria_lote_id": "abc123-...",
          "lote_id": null,
          "quantidade": 2,
          "preco_unitario": 150.00
        },
        {
          "tipo_ingresso_id": "d5b759f4-...",
          "tipo_ingresso_nome": "Day Use",
          "lote_nome": "Crianca COM Almoco",
          "categoria_lote_id": "def456-...",
          "lote_id": null,
          "quantidade": 2,
          "preco_unitario": 75.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"
}

Campos do Combo

Raiz

Parâmetro	Tipo	Padrão	Descrição
`id`	uuid	—	Identificador unico do combo
`nome`	string	—	Nome do combo
`slug`	string	—	Slug URL-friendly para links diretos
`descricao`	string	—	Descricao do combo (pode conter HTML)
`preco_combo`	number	—	Preco final do combo (com desconto aplicado)
`preco_original`	number	—	Soma dos precos 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 esta em destaque
`max_por_pedido`	number	—	Quantidade maxima por pedido (null = ilimitado)
`total_ingressos`	number	—	Total de ingressos inclusos no combo
`itens_resumo`	string	—	Resumo legivel dos itens (ex: 2x Adulto + 2x Crianca)

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 estavel)
`quantidade`	number	—	Quantidade de ingressos deste item no combo
`preco_unitario`	number	—	Preco unitario congelado na criacao do combo

GET/api/integration/combos/:id

Retorna detalhe de um combo especifico. Aceita UUID ou slug como identificador.

Buscar por ID

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

404Combo nao encontrado

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

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

Retorna datas disponiveis para um combo. A disponibilidade e a intersecao de todos os itens do combo.

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 periodo
`date_to`	string	`hoje+90d`	YYYY-MM-DD - Data final do periodo

Consultar disponibilidade

curl -X GET "https://sua-plataforma.com.br/api/v1/integration/combos/0c9469c9-3da3-.../availability?date_from=2026-04-01&date_to=2026-04-30" \
  -H "X-Integration-Key: sk_live_SUA_CHAVE_AQUI"

Resposta - Disponibilidade

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
          },
          {
            "tipo_ingresso_nome": "Day Use",
            "lote_nome": "Crianca COM Almoco",
            "quantidade_necessaria": 2,
            "estoque_disponivel": 23
          }
        ]
      },
      {
        "date": "2026-04-02",
        "available": true,
        "min_stock": 50,
        "items_availability": [
          {
            "tipo_ingresso_nome": "Day Use",
            "lote_nome": "Adulto COM Almoco",
            "quantidade_necessaria": 2,
            "estoque_disponivel": 50
          },
          {
            "tipo_ingresso_nome": "Day Use",
            "lote_nome": "Crianca COM Almoco",
            "quantidade_necessaria": 2,
            "estoque_disponivel": 50
          }
        ]
      }
    ]
  },
  "timestamp": "2026-03-27T15:00:00.000Z"
}

Campos da Disponibilidade

Parâmetro	Tipo	Padrão	Descrição
`combo_id`	uuid	—	ID do combo consultado
`combo_nome`	string	—	Nome do combo
`modo_qrcode`	string	—	Modo de geracao de QR code
`total_ingressos`	number	—	Total de ingressos no combo
`requer_data`	boolean	—	Se o combo requer selecao de data
`dates[].date`	string	—	Data no formato YYYY-MM-DD
`dates[].available`	boolean	—	Se todos os itens tem estoque nesta data
`dates[].min_stock`	number	—	Quantos combos podem ser vendidos (baseado no item com menor estoque)
`dates[].items_availability[]`	array	—	Estoque detalhado por item do combo

Modos de QR Code

`por_pessoa` - QR Code Individual

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

Exemplo: Combo com 4 ingressos (2 adultos + 2 criancas) = 4 QR codes, 4 formularios de dados pessoais.

`unico` - QR Code Unico por Pedido

Gera um QR code de grupo baseado no numero do pedido (formato: YYYYMMDD-NNNN), que agrupa todos os participantes para check-in simultaneo. Alem disso, cada participante recebe seu proprio QR code individual.

Exemplo: Combo com 4 ingressos = 1 QR code de combo (combo_qr_code) + 4 QR codes individuais (qr_code).

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

Erros Possiveis

Codigos de Erro

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

Vouchers

QR Code Check-in

Autenticacao

Listar Combos

Filtros

Listar todos os combos ativos

Filtrar combos em destaque

Resposta - Listar Combos

Campos do Combo

Raiz

itens[]

Buscar por ID

Filtros

Consultar disponibilidade

Resposta - Disponibilidade

Campos da Disponibilidade

Modos de QR Code

por_pessoa - QR Code Individual

unico - QR Code Unico por Pedido

Erros Possiveis

Codigos de Erro

`por_pessoa` - QR Code Individual

`unico` - QR Code Unico por Pedido