OmniTicketz API Documentation

POST/api/v1/api-qrcode-checkin

Consulta dados do QR Code e realiza check-in automaticamente. Retorna formato compatível com API Cross.

Check-in Automático

Ao enviar o QR Code, o check-in é realizado automaticamente. A resposta já retorna os dados do visitante com a leitura registrada.

Formato Compatível com API Cross

Este endpoint retorna dados no formato padrão da API Cross, facilitando integração com catracas e sistemas que já usam esse formato.

QR Codes de Combo

Combos com modo unico possuem um QR code de grupo (formato YYYYMMDD-NNNN — apenas o numero do pedido) e QR codes individuais por pessoa. Ao enviar o QR code de combo, a API realiza o check-in de todos os participantes de uma vez e retorna um objeto estruturado com status, message, dados do pedido, lista de participantes (com qr_code individual de cada um) e adicionais vendidos. Se todos ja fizeram check-in, retorna erro ticket_already_used (409).

Autenticação

Permissão necessária: vouchers:checkin ou checkin ou all

Parâmetros

Request Body (JSON)

Parâmetro	Tipo	Padrão	Descrição
`qr_code`obrigatório	string	—	Código QR do ingresso (ex: EPR9638OS07B75)
`terminal`	string	—	Identificador do dispositivo/catraca (ex: Catraca 01)
`operador`	string	—	Nome do operador que realizou o check-in

Exemplos de Uso

Check-in básico

curl -X POST "https://sua-plataforma.com.br/api/v1/api-qrcode-checkin" \
  -H "X-API-Key: sk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_code": "EPR9638OS07B75",
    "terminal": "Catraca 01",
    "operador": "João Silva"
  }'

Check-in sem terminal/operador

curl -X POST "https://sua-plataforma.com.br/api/v1/api-qrcode-checkin" \
  -H "X-API-Key: sk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{ "qr_code": "EPR9638OS07B75" }'

Resposta

Estrutura (formato API Cross)

Retorna um array com um objeto contendo os dados do visitante, pedido, ingresso, lote e leitura:

200Check-in realizado com sucesso

[
  {
    "receita": "76806be1-00e3-48a8-9595-2c755e2b2dac",
    "sequenciaItem": 1,
    "cancelado": false,
    "dataVisita": "2026-01-30",
    "horarioStr": "08:00-18:00",
    "pedido": {
      "numeroPedido": "20260130-0001",
      "dataVenda": "2026-01-30T10:15:00.000Z",
      "emailCliente": "maria@email.com",
      "nomeCliente": "Maria Silva",
      "valorTotal": 280.00,
      "cupom": {
        "codigo": "VERAO2026",
        "nome": "Desconto de Verão 10%"
      }
    },
    "ingresso": {
      "codigo": "d5b759f4-...",
      "nome": "Pacote Day Use"
    },
    "lote": {
      "codigo": "0933b4b2-...",
      "nome": "Adulto COM Almoço",
      "valorLote": 140.00
    },
    "categoria": {
      "codigo": "01",
      "nome": "Adulto"
    },
    "visitante": {
      "documento": "644.930.261-54",
      "nome": "Betina Lara Pietra Barros"
    },
    "leituras": [
      {
        "data": "2026-01-30T14:27:33.221Z",
        "terminal": "Catraca 01",
        "operador": "João Silva"
      }
    ]
  }
]

Campos da Resposta

Raiz (cada item do array)

Parâmetro	Tipo	Padrão	Descrição
`receita`	uuid	—	ID único do ingresso/voucher (identificador da pessoa_ingresso)
`sequenciaItem`	number	—	Sequência do item dentro do pedido
`cancelado`	boolean	—	true se o pedido foi cancelado
`dataVisita`	string	—	Data de uso do ingresso (YYYY-MM-DD)
`horarioStr`	string	—	Faixa de horário permitida (HH:mm-HH:mm)
`pedido`	object	—	Dados do pedido de origem
`ingresso`	object	—	Tipo de ingresso (produto)
`lote`	object	—	Variação/lote do ingresso
`categoria`	object	—	Categoria do visitante (código numérico)
`visitante`	object	—	Dados de quem usa o ingresso
`leituras`	array	—	Registro da leitura/check-in realizado

Pedido (pedido)

Parâmetro	Tipo	Padrão	Descrição
`numeroPedido`	string	—	Identificador do pedido (ex: 20260130-0001)
`dataVenda`	string	—	Data/hora da venda (ISO 8601)
`emailCliente`	string	—	Email do comprador
`nomeCliente`	string	—	Nome do comprador
`valorTotal`	number	—	Valor total do pedido em reais
`cupom`	object \| null	—	Dados do cupom usado no pedido. null se nenhum cupom foi aplicado

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%)

Ingresso (ingresso)

Parâmetro	Tipo	Padrão	Descrição
`codigo`	uuid	—	ID fixo do tipo de ingresso (mesmo que ingresso_id nos vouchers)
`nome`	string	—	Nome do tipo de ingresso (ex: Pacote Day Use)

Lote (lote)

Parâmetro	Tipo	Padrão	Descrição
`codigo`	uuid	—	ID fixo do lote/variação (mesmo que lote_mestre_id nos vouchers)
`nome`	string	—	Nome da variação (ex: Adulto COM Almoço)
`valorLote`	number	—	Preço unitário do lote em reais

Categoria (categoria)

Parâmetro	Tipo	Padrão	Descrição
`codigo`	string	—	Código numérico: 01 = Adulto, 02 = Infantil, 03 = Outros
`nome`	string	—	Nome da categoria (Adulto, Infantil ou Outros)

Visitante (visitante)

Parâmetro	Tipo	Padrão	Descrição
`documento`	string	—	CPF formatado (xxx.xxx.xxx-xx). null se criança sem CPF
`nome`	string	—	Nome da pessoa que usa o ingresso

Leituras (leituras[])

Parâmetro	Tipo	Padrão	Descrição
`data`	string	—	Data/hora da leitura (ISO 8601)
`terminal`	string	—	Identificador do terminal/catraca que fez a leitura
`operador`	string	—	Nome do operador. null se não informado

Códigos de Erro

Erros possíveis

Parâmetro	Tipo	Padrão	Descrição
`ticket_already_used (combo)`	409	—	Todos os participantes do combo ja realizaram check-in
`ticket_already_used`	409	—	Ingresso já foi utilizado (check-in já realizado)
`ticket_not_found`	404	—	QR Code não encontrado ou não pertence ao tenant
`ticket_expired`	410	—	Ingresso era válido para data passada
`ticket_not_valid_yet`	422	—	Ingresso válido para data futura
`ticket_cancelled`	403	—	Ingresso cancelado ou bloqueado

200Check-in de Combo (todos os participantes de uma vez)

// Enviar o combo QR code (formato YYYYMMDD-NNNN) realiza check-in de todos os participantes pendentes.
// Headers adicionais: X-Combo-Checkin: true, X-Combo-Total: 3, X-Combo-Checkins: 3
{
  "status": "OK",
  "message": "Check-in realizado com sucesso para 3 pessoa(s) do combo.",
  "combo_qr_code": "20260415-3904",
  "total_checkins": 3,
  "total_pessoas": 3,
  "pedido": {
    "numeroPedido": "20260415-3904",
    "nomeCliente": "Matheus Nattan",
    "emailCliente": "matheus@email.com",
    "dataVenda": "2026-04-15T11:26:18Z",
    "valorTotal": 235.78,
    "cupom": null
  },
  "ingresso": { "nome": "Ingresso - DayUse", "codigo": "d5b759f4-21e5-47fa-a263-bf7acd386db8" },
  "categoria": { "nome": "Outros", "codigo": "03" },
  "dataVisita": "2026-04-15",
  "horarioStr": "",
  "data": [
    {
      "qr_code": "US-SO4H9C4WDZ",
      "receita": "7de49e67-51d6-4849-8ac0-a38f109c098e",
      "sequenciaItem": 1,
      "valorLote": 71.96,
      "lote": { "nome": null, "codigo": null },
      "visitante": { "nome": "Matheus Nattan", "documento": null },
      "leituras": [{ "data": "2026-04-15T11:34:23Z", "operador": "Lorrany Silva", "terminal": "Catraca 012" }]
    },
    {
      "qr_code": "US-BORYJ42XIP",
      "receita": "1ab13d87-ba33-4dec-85eb-d80aef2b270a",
      "sequenciaItem": 1,
      "valorLote": 71.96,
      "lote": { "nome": null, "codigo": null },
      "visitante": { "nome": "Convidado", "documento": null },
      "leituras": [{ "data": "2026-04-15T11:34:23Z", "operador": "Lorrany Silva", "terminal": "Catraca 012" }]
    },
    {
      "qr_code": "US-4E4ETRGM1K",
      "receita": "23301b1e-8226-4cc5-98ae-27ff1dc0753d",
      "sequenciaItem": 1,
      "valorLote": 11.96,
      "lote": { "nome": null, "codigo": null },
      "visitante": { "nome": "Convidado", "documento": null },
      "leituras": [{ "data": "2026-04-15T11:34:23Z", "operador": "Lorrany Silva", "terminal": "Catraca 012" }]
    }
  ],
  "adicionais": [
    {
      "id": "uuid",
      "adicional_id": "uuid",
      "nome": "Almoco Buffet Livre",
      "quantidade": 2,
      "preco_unitario": 45.00,
      "subtotal": 90.00,
      "pessoa_ingresso_id": null
    }
  ]
}

409Combo - todos ja fizeram check-in

{
  "error": "ticket_already_used",
  "message": "Todos os 3 participantes do combo já realizaram check-in.",
  "combo_qr_code": "20260415-3904",
  "total_pessoas": 3
}

409Ingresso já utilizado

{
  "error": "ticket_already_used",
  "message": "Ingresso já utilizado em 30/01/2026 às 10:30.",
  "qr_code": "EPR9638OS07B75",
  "checkin_em": "2026-01-30T13:30:00.000Z",
  "nome": "João Silva",
  "cpf": "123.456.789-00"
}

404Ingresso não encontrado

{
  "error": "ticket_not_found",
  "message": "Ingresso não encontrado.",
  "qr_code": "EPR0000INVALIDO"
}

410Ingresso expirado

{
  "error": "ticket_expired",
  "message": "Ingresso expirado. Era válido para 20/01/2026.",
  "dataIngresso": "2026-01-20",
  "dataAtual": "2026-01-22",
  "diasDiferenca": -2,
  "qr_code": "EPR9638OS07B75"
}

422Ingresso ainda não é válido

{
  "error": "ticket_not_valid_yet",
  "message": "Ingresso válido apenas para 25/01/2026. Hoje é 24/01/2026.",
  "dataIngresso": "2026-01-25",
  "dataAtual": "2026-01-24",
  "diasDiferenca": 1,
  "qr_code": "EPR9638OS07B75"
}

403Ingresso cancelado

{
  "error": "ticket_cancelled",
  "message": "Ingresso cancelado.",
  "qr_code": "EPR9638OS07B75",
  "status_pedido": "cancelado"
}

Dados salvos no banco (primeiro check-in)

checkin_realizado = true
checkin_em = data/hora do check-in
checkin_dispositivo = valor do campo terminal
checkin_operador_externo = valor do campo operador
sistema_externo = true (sempre quando via API)

PATCH/api/v1/api-qrcode-checkin

Estorna uma leitura (check-in) realizada. Só é permitido estorno no mesmo dia.

Estorno apenas no mesmo dia

O estorno só é permitido no mesmo dia em que a leitura foi efetuada. Caso contrário, será retornado erro ESTORNO_NAO_PERMITIDO.

Estorno de Combo

Ao enviar um QR code de combo (formato YYYYMMDD-NNNN — apenas o numero do pedido), o estorno é realizado para todos os participantes que possuem check-in. Retorna a lista de estornados.

Autenticação

Permissão necessária: vouchers:checkin ou checkin ou all

Parâmetros

Request Body (JSON)

Parâmetro	Tipo	Padrão	Descrição
`qr_code`obrigatório	string	—	QR code individual do ingresso ou QR code de combo (YYYYMMDD-NNNN) para estorno em grupo
`terminal`	string	—	Identificador do terminal que realizou o estorno
`operador`	string	—	Nome do operador que realizou o estorno

Exemplos de Uso

curl -X PATCH "https://sua-plataforma.com.br/api/v1/api-qrcode-checkin" \
  -H "X-API-Key: sk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_code": "EPR9638OS07B75",
    "terminal": "Catraca 01",
    "operador": "João Silva"
  }'

Resposta

200Estorno realizado com sucesso

{
  "status": "OK",
  "message": "Estorno realizado com sucesso.",
  "data": {
    "qr_code": "EPR9638OS07B75",
    "nome": "Maria Silva",
    "estornado_em": "2026-01-29T15:30:00.000Z",
    "terminal": "Catraca 01",
    "operador": "João Silva"
  }
}

200Estorno de combo (todos os participantes)

{
  "status": "OK",
  "message": "Estorno realizado com sucesso para 3 pessoa(s) do combo.",
  "combo_qr_code": "20260415-3904",
  "total_estornados": 3,
  "data": [
    {
      "qr_code": "US-SO4H9C4WDZ",
      "nome": "Matheus Nattan",
      "estornado_em": "2026-04-15T11:28:34.320Z",
      "terminal": "Catraca 012",
      "operador": "Lorrany Silva"
    },
    {
      "qr_code": "US-BORYJ42XIP",
      "nome": "Convidado",
      "estornado_em": "2026-04-15T11:28:34.320Z",
      "terminal": "Catraca 012",
      "operador": "Lorrany Silva"
    },
    {
      "qr_code": "US-4E4ETRGM1K",
      "nome": "Convidado",
      "estornado_em": "2026-04-15T11:28:34.320Z",
      "terminal": "Catraca 012",
      "operador": "Lorrany Silva"
    }
  ]
}

Campos da Resposta

Raiz

Parâmetro	Tipo	Padrão	Descrição
`status`	string	—	OK quando o estorno foi realizado com sucesso
`message`	string	—	Mensagem descritiva do resultado
`data`	object	—	Dados do estorno realizado

Dados do Estorno (data)

Parâmetro	Tipo	Padrão	Descrição
`qr_code`	string	—	Código QR do ingresso estornado
`nome`	string	—	Nome da pessoa do ingresso
`estornado_em`	string	—	Data/hora do estorno (ISO 8601)
`terminal`	string	—	Terminal que realizou o estorno
`operador`	string	—	Operador que realizou o estorno

Códigos de Erro

Erros possíveis

Parâmetro	Tipo	Padrão	Descrição
`ESTORNO_NAO_PERMITIDO`	422	—	Estorno só é permitido no mesmo dia do check-in
`SEM_CHECKIN`	422	—	Ingresso não possui check-in para estornar
`ticket_not_found`	404	—	QR Code não encontrado
`TENANT_MISMATCH`	403	—	Ingresso não pertence a este tenant

422Estorno não permitido (outro dia)

{
  "error": "ESTORNO_NAO_PERMITIDO",
  "message": "Estorno permitido apenas no mesmo dia do check-in. Check-in foi em 28/01/2026, hoje é 29/01/2026.",
  "dataCheckin": "2026-01-28",
  "dataAtual": "2026-01-29",
  "qr_code": "EPR9638OS07B75"
}

422Sem check-in para estornar

{
  "error": "SEM_CHECKIN",
  "message": "Este ingresso não possui check-in para estornar.",
  "qr_code": "EPR9638OS07B75"
}

Combos

Webhooks