Vouchers

GET

Liste pedidos com vouchers agrupados por cliente e lotes. Estrutura achatada por pessoa (qr_code + campos do formulário) e marcação automática de sincronização.

GET/api/v1/api-vouchers

Lista pedidos com vouchers agrupados por cliente e lotes.

Sincronização Automática

Por padrão, os vouchers retornados são automaticamente marcados como sincronizados para sua API Key. Use ?marcar_sincronizado=false para apenas consultar sem marcar.

Estrutura achatada por pessoa (v2)

Cada item de lote.dados[] traz qr_code + os campos do formulário do ingresso usando o label definido pelo admin (ex: "Nome Completo", "CPF", "RG", "Matricula"). Chaves só aparecem se o valor estiver preenchido. Tenants sem form_config recebem labels padrão (Nome, CPF, Data de Nascimento, Email, Telefone) — também só com valores presentes.

IDs Fixos para Integração Externa

Cada lote inclui identificadores que representam o produto cadastrado, não a venda individual:

ingresso_id — ID do tipo de ingresso (ex: "Ingresso - DayUse").
lote_mestre_id — ID da variação/lote (ex: "Adulto (11 anos ou mais)").
categoria — Tipo público: adulto, infantil ou outros.
valor_unitario — Preço por ingresso desse lote.

Esses IDs são sempre os mesmos para o mesmo produto, independente do pedido, do cliente ou da data de uso.

Objeto pagamento — breakdown monetário (v2.4)

Todo pedido traz pagamento.valores com a composição do preço. Os 3 totais no topo fecham a conta:

total_bruto         209.70    (soma de cada ingresso pelo preço cheio)
total_desconto       76.89    (soma de TODOS os descontos − acréscimos)
total_pago          132.81    (= total_bruto − total_desconto)

Em seguida vem o detalhamento de cada desconto/acréscimo:

total_bruto                       209.70
- desconto_promocao.valor          69.90    (promo de item: brindes, %, fixa)
= subtotal                        139.80
- desconto_pagamento.valor          6.99    (promo de forma: ex: 5% no PIX)
+ acrescimo_pagamento.valor         (0)     (ex: acréscimo de cartão parcelado)
= total_pago                      132.81
+ valor_estornado                   (0)     (em estornos parciais)

desconto_pagamento e acrescimo_pagamento são mutuamente exclusivos: um dos dois é sempre null. Ambos null = forma de pagamento sem ajuste (ex: cartão à vista sem desconto/acréscimo).

Cancelamentos e reembolsos reaparecem na sincronização

Pedidos com status cancelado ou reembolsado entram na resposta da API junto com os pagos. Quando um pedido é cancelado/reembolsado no painel, seus vouchers são automaticamente dessincronizados para todas as API Keys — ou seja, eles voltam a aparecer na próxima chamada com ?sincronizado=false, agora carregando status: "cancelado" (ou "reembolsado").

Use o campo status para reagir no seu sistema: estornar acesso, invalidar QR codes, atualizar contagens, notificar cozinha/operação, etc. Os QR codes continuam vindo no payload — não os invalide cegamente, apenas com base no status do pedido.

Autenticação

Permissão necessária: vouchers:read

Parâmetros

Filtros

Parâmetro	Tipo	Padrão	Descrição
`numero_pedido`	string	—	Busca exata por número do pedido (ex: 20260105-0001)
`sincronizado`	boolean	—	true/false — Filtrar por status de sincronização
`data_uso`	string	—	YYYY-MM-DD — Filtrar por data de uso do ingresso
`checkin_realizado`	boolean	—	true/false — Filtrar por status de check-in
`marcar_sincronizado`	boolean	`true`	Marcar vouchers retornados como sincronizados
`limit`	number	`100`	Itens por página (máx: 1000)
`offset`	number	`0`	Pular N registros

Ordenação

Parâmetro	Tipo	Padrão	Descrição
`order_by`	string	`pago_em`	Campo: pago_em (data do pagamento) ou created_at
`order`	string	`desc`	Direção: desc ou asc

Outros Exemplos

Buscar por número do pedido

curl -X GET "https://api.omniticketz.com/v1/api-vouchers?numero_pedido=20260105-0001" \
  -H "X-API-Key: sk_live_SUA_CHAVE_AQUI"

Vouchers sem check-in

curl -X GET "https://api.omniticketz.com/v1/api-vouchers?checkin_realizado=false&marcar_sincronizado=false" \
  -H "X-API-Key: sk_live_SUA_CHAVE_AQUI"

Campos da Resposta

Pedido (chaves no topo)

Parâmetro	Tipo	Padrão	Descrição
`numero_pedido`	string	—	Identificador do pedido (ex: 20260218-0004)
`status`	string	—	Status do pedido: pago, cancelado ou reembolsado. Veja Callout abaixo sobre cancelamentos
`pago_em`	string	—	Data/hora do pagamento (ISO 8601). null se origem balcão sem pagamento ou se o pedido foi cancelado antes de pagar
`origem`	string	—	Canal da venda: online, balcao, central ou afiliado_pdv
`pagamento`	object	—	Tudo financeiro num lugar só: breakdown monetário em 5 etapas (pagamento.valores). Ver tabela Pagamento
`cupom`	object \| null	—	Dados do cupom usado: { codigo, nome }. null se sem cupom
`cliente`	object	—	Dados do comprador (ver tabela Cliente)
`lotes`	array	—	Lista de combinações lote × data (ver tabela Lote)
`total_pessoas`	number	—	Total de pessoas/ingressos no pedido
`total_lotes`	number	—	Quantidade de combinações lote × data no pedido
`sincronizado`	boolean	—	true se TODOS os vouchers do pedido foram sincronizados via esta API Key
`adicionais`	array	—	Lista de adicionais comprados. Aparece SOMENTE quando o pedido tem adicionais

Pagamento (pedido.pagamento)

Parâmetro	Tipo	Padrão	Descrição
`valores`	object	—	Breakdown monetário completo do pedido (ver tabela Valores)

Valores (pedido.pagamento.valores) — composição do preço

Parâmetro	Tipo	Padrão	Descrição
`total_bruto`	number	—	Resumo (1/3): soma de TODOS os ingressos pelo preço cheio + adicionais. É o que o cliente pagaria sem nenhuma promoção
`total_desconto`	number	—	Resumo (2/3): soma de TODOS os descontos do pedido menos acréscimos (= desconto_promocao + desconto_pagamento − acrescimo_pagamento). 0 quando não há nenhum ajuste
`total_pago`	number	—	Resumo (3/3): total que o cliente efetivamente pagou (= total_bruto − total_desconto). Considera estornos parciais
`desconto_promocao`	object \| null	—	Detalhe: desconto aplicado por promoção de item (compre N ganhe M, percentual em ingressos, etc). null quando não há promo de item. Ver tabela DescontoPromocao
`subtotal`	number	—	Detalhe: = total_bruto − desconto_promocao.valor. Valor antes do ajuste por forma de pagamento
`desconto_pagamento`	object \| null	—	Detalhe: desconto vindo da forma de pagamento (ex: 5% no PIX). null se não houve desconto OU se houve acréscimo. Mutuamente exclusivo com acrescimo_pagamento. Ver tabela DescontoPagamento
`acrescimo_pagamento`	object \| null	—	Detalhe: acréscimo vindo da forma de pagamento (ex: cartão parcelado com juros). null se não houve acréscimo OU se houve desconto. Mutuamente exclusivo com desconto_pagamento. Mesma estrutura de desconto_pagamento
`valor_estornado`	number	—	Valor estornado ao cliente. 0 quando não houve estorno. Para descobrir o total original em pedidos com estorno: total_pago + valor_estornado

DescontoPromocao (pedido.pagamento.valores.desconto_promocao)

Parâmetro	Tipo	Padrão	Descrição
`nome`	string	—	Nome da promoção (ex: 'MÊS DA MÃES', 'FERIADÕES DE ABRIL')
`tipo`	string	—	Tipo da promoção: BUY_N_GET_M (compre N ganhe M), TIERED_QUANTITY (desconto por quantidade), PERCENTAGE (percentual), FIXED (valor fixo)
`detalhes`	string	—	Descrição textual (ex: '1 brindes', '2 itens = 5% de desconto')
`valor`	number	—	Valor monetário do desconto em reais. Para BUY_N_GET_M é calculado: qtd_brindes × preço real do ingresso

DescontoPagamento / AcrescimoPagamento (mesma estrutura)

Parâmetro	Tipo	Padrão	Descrição
`nome`	string \| null	—	Nome da promoção de pagamento (ex: '5% no PIX'). Para acréscimo, vem como 'Acréscimo de cartão'
`forma`	string	—	Forma de pagamento que disparou: pix, cartao_credito_1x, cartao_credito_2x, ... cartao_debito
`percentual`	number	—	Percentual aplicado (ex: 5.00 para 5%)
`valor`	number	—	Valor monetário em reais. Sempre POSITIVO em ambos os objetos (a semântica desconto/acréscimo vem do qual campo está populado)

Cliente (pedido.cliente)

Parâmetro	Tipo	Padrão	Descrição
`nome`	string	—	Primeiro nome
`sobrenome`	string	—	Sobrenome
`email`	string	—	E-mail do comprador
`cpf`	string	—	CPF (somente dígitos)
`data_nascimento`	string	—	YYYY-MM-DD
`telefone`	string	—	Somente dígitos
`whatsapp`	string	—	Somente dígitos
`endereco`	object	—	{ cep, rua, numero, complemento, bairro, cidade, estado }

Cupom (pedido.cupom) — null se não usado

Parâmetro	Tipo	Padrão	Descrição
`codigo`	string	—	Código do cupom utilizado (ex: VERAO2026)
`nome`	string	—	Nome/descrição do cupom (ex: Desconto de Verão 10%)

Lote (dentro de pedido.lotes[])

Parâmetro	Tipo	Padrão	Descrição
`ingresso_id`	uuid	—	ID fixo do tipo de ingresso (ex: Ingresso - DayUse)
`lote_mestre_id`	uuid	—	ID fixo da variação do lote (ex: Adulto - 11 anos ou mais)
`categoria`	string	—	Tipo público: adulto, infantil ou outros
`nome_ingresso`	string	—	Nome do tipo de ingresso
`nome_lote`	string	—	Nome da variação
`tipo_ingresso`	string	—	Tipo técnico: dayuse, evento, dayuse_sem_data ou dia_unico
`data_uso`	string	—	Data de uso (YYYY-MM-DD)
`valor_unitario`	number	—	Preço por ingresso deste lote em reais
`sincronizado`	boolean	—	true se TODOS os vouchers desse lote foram sincronizados (bool_and)
`sincronizado_em`	string	—	Data/hora mais recente de sincronização entre as pessoas (MAX)
`checkin_realizado`	boolean	—	true se TODAS as pessoas fizeram check-in (bool_and)
`checkin_em`	string	—	Data/hora mais recente de check-in entre as pessoas (MAX). null se nenhum
`dados`	array	—	Lista de pessoas (qr_code + campos do formulário)

Pessoa (dentro de lote.dados[])

Parâmetro	Tipo	Padrão	Descrição
`qr_code`	string	—	Código QR do ingresso (use para check-in). Sempre presente
`<label do form_config>`	string	—	Cada chave restante usa o label definido no formulário do ingresso (ex: "Nome Completo", "CPF", "RG", "Matricula"). Só aparece se o valor estiver preenchido

Sem form_config (labels default)

Quando o tipo de ingresso não tem form_config personalizado, os campos preenchidos aparecem com labels default:Nome, CPF, Data de Nascimento, Email, Telefone. Em ambos os casos, chaves vazias são omitidas.

Adicional (dentro de pedido.adicionais[])

Parâmetro	Tipo	Padrão	Descrição
`adicional_id`	uuid	—	ID do produto adicional no catálogo (cruze com seu cadastro)
`nome`	string	—	Nome do adicional (snapshot no momento da venda)
`quantidade`	number	—	Quantidade comprada
`preco_unitario`	number	—	Preço unitário em reais
`subtotal`	number	—	Total do adicional (preço × quantidade)
`pessoa_ingresso_id`	uuid \| null	—	Vínculo com pessoa específica (quando adicional é por pessoa)
`combo_id`	uuid \| null	—	ID do combo (combos.id) quando o adicional veio embutido em um combo. null = adicional avulso
`combo_item_id`	uuid \| null	—	ID da linha do combo (combo_itens.id) que originou este adicional — define a config específica de quantidade/preço/is_brinde
`is_brinde`	boolean	—	true se configurado como brinde dentro do combo (subtotal pode ser 0)
`codigo_integracao`	string	—	Código externo do adicional para ERPs/cozinha. Sempre string — vazia ("") quando não cadastrado
`adicional_qr_code`	string \| null	—	QR Code da unidade do adicional (primeira unidade gerada). null quando não há unidade

Fluxo típico de integração

Chame ?sincronizado=false para obter vouchers novos (marca automaticamente)
Processe os dados no seu sistema
Na próxima chamada, apenas vouchers novos aparecerão

Como funciona a sincronização

Ao chamar a API, os vouchers são marcados como sincronizados para sua API Key
O campo sincronizado_em registra a data/hora da primeira chamada
Chamadas subsequentes NÃO alteram o sincronizado_em
Outra API Key ainda verá os mesmos vouchers como não sincronizados

Mudanças mais recentes (2026-05-19) — v2.4 pagamento.valores em 5 etapas

pagamento.valores reescrito pra refletir a composição real do preço em 5 linhas:total_bruto → desconto_promocao → subtotal →desconto_pagamento / acrescimo_pagamento → total.
Novo: total_bruto mostra o valor que o cliente pagaria sem nenhuma promoção (brindes contam pelo preço cheio). Calculado a partir do preço REAL de cada lote no pedido.
desconto_promocao virou objeto: { nome, tipo, detalhes, valor }. O valor agora é correto pra BUY_N_GET_M (= qtd_brindes × preço real, não mais o cálculo divergente da v2.3).
desconto_pagamento também virou objeto: { nome, forma, percentual, valor }. Resolve nome via promoções de pagamento ativas (ex: "5% no PIX").
Novo: acrescimo_pagamento separado pra acréscimos de cartão parcelado (mutuamente exclusivo com desconto_pagamento). Mesma estrutura.
Removidos da v2.3: subtotal_ingressos, subtotal_adicionais,desconto (dentro de valores), valor_brindes, taxa_gateway,preco_cartao, preco_pix. Toda essa info agora está nos 5 campos novos.
Removidos do topo do pedido: desconto, total_ingressos,total_pedido, total_adicionais e promocao_ativa. Eram redundantes — todas essas informações vivem em pagamento.valores com nomenclatura mais clara.

Mudanças anteriores (2026-05-12)

Novo campo status no topo do pedido (pago, cancelado ou reembolsado) — permite distinguir pedidos ativos dos cancelados/reembolsados na mesma resposta.
Quando um pedido é cancelado/reembolsado, seus vouchers são automaticamente dessincronizadose voltam a aparecer na próxima chamada com ?sincronizado=false, agora trazendo o novo status.
Respostas vazias passaram a incluir um campo mensagem explicando o motivo (ex: "Nenhum voucher pendente — todos os pedidos pagos já foram sincronizados para esta API Key").

Mudanças desde a v1 (2026-04-26)

pessoas dentro do lote foi renomeado para dados e achatado (qr_code + labels do formulário).
O id interno da pessoa e o id interno do adicional foram removidos do payload.
Status (sincronizado, checkin_realizado e timestamps) e preco_unitario subiram para o nível do lote.
Topo do pedido reorganizado: desconto → total_ingressos → total_adicionais → total_pedido.
desconto agora vem arredondado a 2 casas decimais.
total_adicionais antes era contagem (count). Agora é valor (R$).
adicionais e total_adicionais são condicionais: se o pedido não tem adicionais, essas chaves não aparecem.
Bloco pagination foi removido — resposta minimalista.

Request

curl -X GET "https://api.omniticketz.com/v1/api-vouchers?sincronizado=false" \
  -H "X-API-Key: sk_live_SUA_CHAVE_AQUI"

Response

200OK

{
  "success": true,
  "data": {
    "pedidos": [
      {
        "numero_pedido": "20260105-0001",
        "status": "pago",
        "pago_em": "2026-01-05T14:30:00.000Z",
        "origem": "online",
        "pagamento": {
          "valores": {
            "total_bruto": 209.70,
            "total_desconto": 76.89,
            "total_pago": 132.81,
            "desconto_promocao": {
              "nome": "MÊS DA MÃES",
              "tipo": "BUY_N_GET_M",
              "detalhes": "1 brindes",
              "valor": 69.90
            },
            "subtotal": 139.80,
            "desconto_pagamento": {
              "nome": "5% no PIX",
              "forma": "pix",
              "percentual": 5,
              "valor": 6.99
            },
            "acrescimo_pagamento": null,
            "valor_estornado": 0
          }
        },
        "cupom": null,
        "cliente": {
          "nome": "Maria",
          "sobrenome": "Silva",
          "email": "maria.silva@example.com",
          "cpf": "00011122233",
          "data_nascimento": "1990-05-20",
          "telefone": "11999990000",
          "whatsapp": "11999990000",
          "endereco": {
            "cep": "01310000",
            "rua": "Av. Paulista",
            "numero": "1000",
            "complemento": "Apto 101",
            "bairro": "Bela Vista",
            "cidade": "São Paulo",
            "estado": "SP"
          }
        },
        "lotes": [
          {
            "ingresso_id": "00000000-0000-0000-0000-000000000001",
            "lote_mestre_id": "00000000-0000-0000-0000-000000000aaa",
            "categoria": "adulto",
            "nome_ingresso": "Ingresso - DayUse",
            "nome_lote": "Adulto (11 anos ou mais)",
            "tipo_ingresso": "dayuse",
            "data_uso": "2026-01-10",
            "valor_unitario": 135,
            "sincronizado": true,
            "sincronizado_em": "2026-01-05T14:35:00.000Z",
            "checkin_realizado": false,
            "checkin_em": null,
            "dados": [
              {
                "qr_code": "EXEMPLO-ABC123",
                "Nome Completo": "Maria Silva",
                "RG": "00.000.000-0",
                "Matricula": "000000"
              }
            ]
          }
        ],
        "total_pessoas": 2,
        "total_lotes": 2,
        "sincronizado": true,
        "adicionais": [
          {
            "adicional_id": "00000000-0000-0000-0000-000000000bbb",
            "nome": "Almoço - Infantil (04 a 11 anos)",
            "quantidade": 2,
            "preco_unitario": 29.9,
            "subtotal": 59.8,
            "pessoa_ingresso_id": null,
            "combo_id": null,
            "combo_item_id": null,
            "is_brinde": false,
            "codigo_integracao": "",
            "adicional_qr_code": "USTGJ755FWGGVN"
          }
        ]
      }
    ]
  }
}

Clientes

Combos