OmniTicketz API Documentation

GET/api/v1/api-vouchers

Lista pedidos com vouchers agrupados por cliente e lotes. Marca como sincronizado automaticamente.

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.

IDs Fixos para Integração Externa

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

ingresso_id - ID do tipo de ingresso (ex: "Pacote Day Use"). Todos os lotes do mesmo ingresso compartilham este ID.
lote_mestre_id - ID da variação/lote (ex: "Adulto COM Almoço"). Identifica a variação específica dentro do ingresso.
categoria - Tipo público: adulto, infantil ou outros
nome_lote - Nome da variação do ingresso
valor_unitario - Preço por ingresso do lote
subtotal - Valor total do lote (valor_unitario × quantidade)

Esses IDs são sempre os mesmos para o mesmo produto, independente do pedido, do cliente ou da data de uso. Por exemplo, se dois clientes diferentes comprarem "Adulto COM Almoço" para datas diferentes, ambos terão o mesmo ingresso_id e o mesmo lote_mestre_id. Use esses IDs para mapear os produtos no seu sistema externo.

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), created_at
`order`	string	`desc`	Direção: desc ou asc

Exemplos de Uso

Buscar novos vouchers para sincronizar

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

Buscar por número do pedido

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

Vouchers sem check-in

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

Resposta

Estrutura hierárquica

Os dados são organizados por pedido > lotes > pessoas:

200OK

{
  "success": true,
  "pedidos": [
    {
      "numero_pedido": "20260127-0003",
      "pago_em": "2026-01-27T14:30:00Z",
      "origem": "online",
      "total": 399.80,
      "desconto": 40.00,
      "cupom": {
        "codigo": "VERAO2026",
        "nome": "Desconto de Verão 10%"
      },
      "cliente": {
        "nome": "Maria Silva",
        "email": "maria@email.com"
      },
      "lotes": [
        {
          "ingresso_id": "d5b759f4-...",
          "lote_mestre_id": "abc123-mestre-fixo",
          "categoria": "adulto",
          "nome_ingresso": "Pacote Day Use",
          "nome_lote": "Adulto COM Almoço",
          "tipo_ingresso": "dayuse",
          "data_uso": "2026-02-10",
          "quantidade": 2,
          "valor_unitario": 154.90,
          "subtotal": 309.80,
          "pessoas": [
            {
              "id": "uuid-1",
              "qr_code": "US-uuid-1",
              "nome": "Maria Silva",
              "cpf": "12345678900",
              "data_nascimento": "1985-03-20",
              "checkin_realizado": false,
              "checkin_em": null,
              "sincronizado": true,
              "sincronizado_em": "2026-01-27T14:30:00Z"
            }
          ]
        },
        {
          "ingresso_id": "d5b759f4-...",
          "lote_mestre_id": "def456-mestre-fixo",
          "categoria": "infantil",
          "nome_ingresso": "Pacote Day Use",
          "nome_lote": "Criança COM Almoço",
          "tipo_ingresso": "dayuse",
          "data_uso": "2026-02-10",
          "quantidade": 1,
          "valor_unitario": 90.00,
          "subtotal": 90.00,
          "pessoas": [
            {
              "id": "uuid-2",
              "qr_code": "US-uuid-2",
              "nome": "João Silva",
              "cpf": null,
              "data_nascimento": "2018-06-15",
              "checkin_realizado": false,
              "checkin_em": null,
              "sincronizado": true,
              "sincronizado_em": "2026-01-27T14:30:00Z"
            }
          ]
        }
      ],
      "adicionais": [
        {
          "id": "uuid-add-1",
          "adicional_id": "uuid-cat-1",
          "nome": "Almoço Buffet Livre",
          "quantidade": 2,
          "preco_unitario": 45.00,
          "subtotal": 90.00,
          "pessoa_ingresso_id": null
        }
      ],
      "total_pessoas": 3,
      "total_lotes": 2,
      "total_adicionais": 1,
      "sincronizado": false
    }
  ],
  "pagination": {
    "total_pedidos": 1,
    "total_pessoas": 3,
    "limit": 100,
    "offset": 0
  }
}

Campos da Resposta

Pedido

Parâmetro	Tipo	Padrão	Descrição
`numero_pedido`	string	—	Identificador do pedido (ex: 20260218-0004)
`pago_em`	string	—	Data/hora do pagamento (ISO 8601). null se origem balcao
`origem`	string	—	Canal da venda: online, balcao ou central
`total`	number	—	Valor total do pedido em reais (já com desconto aplicado)
`desconto`	number	—	Valor do desconto aplicado em reais. 0 se nenhum desconto
`cupom`	object \| null	—	Dados do cupom usado. null se nenhum cupom foi aplicado
`cliente`	object	—	Dados do comprador: nome e email
`lotes`	array	—	Lista de lotes/variantes comprados neste pedido
`total_pessoas`	number	—	Total de pessoas/ingressos no pedido
`total_lotes`	number	—	Quantidade de lotes diferentes no pedido
`sincronizado`	boolean	—	true se todos os vouchers do pedido foram sincronizados para sua API Key

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: Pacote Day Use). Mesmo ID em todos os pedidos
`lote_mestre_id`	uuid	—	ID fixo da variacao do lote (ex: Adulto COM Almoco). Mesmo ID em todos os pedidos
`categoria`	string	—	Tipo publico: adulto, infantil ou outros
`nome_ingresso`	string	—	Nome do tipo de ingresso
`nome_lote`	string	—	Nome da variacao (ex: Adulto 11 anos ou mais)
`tipo_ingresso`	string	—	Tipo tecnico: dayuse, evento ou dayuse_sem_data
`data_uso`	string	—	Data de uso do ingresso (YYYY-MM-DD)
`quantidade`	number	—	Quantidade de pessoas neste lote
`valor_unitario`	number	—	Preco por ingresso deste lote em reais
`subtotal`	number	—	Valor total do lote: valor_unitario x quantidade
`pessoas`	array	—	Lista de pessoas/vouchers deste lote

Pessoa/Voucher (dentro de lote.pessoas[])

Parâmetro	Tipo	Padrão	Descrição
`id`	uuid	—	ID unico do voucher (use para marcar sincronizado via POST)
`qr_code`	string	—	Codigo QR do ingresso (use para check-in)
`nome`	string	—	Nome da pessoa que usara o ingresso
`cpf`	string	—	CPF da pessoa (null para criancas sem CPF obrigatorio)
`data_nascimento`	string	—	Data de nascimento (YYYY-MM-DD)
`checkin_realizado`	boolean	—	true se o check-in ja foi feito
`checkin_em`	string	—	Data/hora do check-in (ISO 8601). null se nao feito
`sincronizado`	boolean	—	true se este voucher ja foi sincronizado para sua API Key
`sincronizado_em`	string	—	Data/hora da primeira sincronizacao. null se nao sincronizado

Paginacao (pagination)

Parâmetro	Tipo	Padrão	Descrição
`total_pedidos`	number	—	Total de pedidos encontrados com os filtros aplicados
`total_pessoas`	number	—	Total de pessoas/vouchers em todos os pedidos
`limit`	number	—	Limite de itens por pagina usado na requisicao
`offset`	number	—	Offset usado na requisicao
`has_more`	boolean	—	true se existem mais pedidos alem desta pagina

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

Clientes

Combos