API Use Ingresso

API REST para organizadores integrarem CRMs, ERPs, planilhas e automações externas com os dados da sua organização.

Base URLhttps://useingresso.com/api/v1

Autenticação

Gere a credencial em Integrações → API Use Ingresso (apenas o proprietário do evento pode gerar).

Envie a chave no header Authorization em todas as requisições:

Header

Authorization: Bearer ui_live_a1b2c3d4e5f6789012345678abcdef01
Accept: application/json

Para validar a credencial e obter os dados da organização autenticada, use GET /api/v1/me.

Paginação

Endpoints de listagem aceitam page e limit. O padrão é página 1 com 20 itens; o máximo por página é 100.

Parâmetro	Tipo	Descrição
`page`	integer	Número da página (mín. 1, máx. 1.000).
`limit`	integer	Itens por página (mín. 1, máx. 100). Padrão: 20.

A resposta inclui o objeto pagination:

Objeto pagination

{
  "page": 1,
  "limit": 20,
  "total": 856,
  "total_pages": 43,
  "has_next": true,
  "has_prev": false
}

Metadados da API

GET/api/v1

Retorna nome, versão, link da documentação e lista de endpoints disponíveis.

Requisição

curl -s -X GET "https://useingresso.com/api/v1" \
  -H "Authorization: Bearer ui_live_SUA_CHAVE" \
  -H "Accept: application/json"

200Sucesso

Resposta

{
  "name": "Use Ingresso Organizer API",
  "version": "v1",
  "documentation": "/developers/api",
  "endpoints": [
    { "method": "GET", "path": "/api/v1/me" },
    { "method": "GET", "path": "/api/v1/events" },
    { "method": "GET", "path": "/api/v1/events/:eventId" },
    { "method": "GET", "path": "/api/v1/events/:eventId/orders" },
    { "method": "GET", "path": "/api/v1/events/:eventId/participants" }
  ]
}

Minha organização

GET/api/v1/me

Retorna o perfil público da organização vinculada à credencial: nome, avatar, e-mail, telefone, endereço e demais dados de contato.

Requisição

curl -s -X GET "https://useingresso.com/api/v1/me" \
  -H "Authorization: Bearer ui_live_SUA_CHAVE" \
  -H "Accept: application/json"

200Sucesso

Resposta

{
  "data": {
    "id": "64a1b2c3d4e5f678901234ab",
    "name": "Exemplo Eventos",
    "slug": "exemplo-eventos",
    "avatar_url": "https://cdn.useingresso.com/organizations/avatar-exemplo.png",
    "email": "contato@exemplo.com.br",
    "phone": "12121214444",
    "event_instagram": "exemploeventos",
    "short_description": "Produtora de eventos de exemplo.",
    "business_type": "company",
    "address": {
      "street": "Avenida José de Souza Campos",
      "number": "S/N",
      "complement": null,
      "neighborhood": "Cambuí",
      "city": "Campinas",
      "state": "SP",
      "zipcode": "13025900"
    },
    "status": "approved",
    "created_at": "2024-03-10T14:22:00.000Z",
    "updated_at": "2026-06-01T09:15:33.000Z"
  }
}

Listar eventos

GET/api/v1/events

Lista todos os eventos da organização autenticada, ordenados por data decrescente.

Query parameters

Parâmetro	Tipo	Descrição
`page`	integer	Página (ver Paginação).
`limit`	integer	Itens por página (ver Paginação).
`status`	string	Filtra por status do evento (ex.: active, draft). Use all para todos.
`enabled`	boolean	true ou false. Filtra eventos habilitados ou desabilitados.

Requisição

curl -s -X GET "https://useingresso.com/api/v1/events?page=1&limit=20&status=active" \
  -H "Authorization: Bearer ui_live_SUA_CHAVE" \
  -H "Accept: application/json"

200Sucesso

Resposta

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "title": "Festival de Verão 2026",
      "slug": "festival-de-verao-2026",
      "organizer_slug": "exemplo-eventos",
      "date": "2026-06-18T03:00:00.000Z",
      "time": "14:00",
      "end_date": "2026-06-18T03:00:00.000Z",
      "end_time": "16:00",
      "venue": "Arena Exemplo",
      "location": "Campinas - SP",
      "address": {
        "city": "Campinas",
        "state": "SP",
        "neighborhood": "Cambuí"
      },
      "category": "festa",
      "status": "active",
      "enabled": true,
      "visibility": "unlisted",
      "total_sales": 21,
      "max_capacity": 1000000,
      "ticket_types_count": 5,
      "created_at": "2025-09-22T19:02:38.256Z",
      "updated_at": "2026-06-10T23:10:03.873Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Detalhe do evento

GET/api/v1/events/:eventId

Retorna detalhes completos de um evento: endereço, tipos de ingresso, lineup, datas de venda e configurações.

Path parameters

Parâmetro	Tipo	Descrição
`eventId`obrigatório	string	ID do evento.

Requisição

curl -s -X GET "https://useingresso.com/api/v1/events/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer ui_live_SUA_CHAVE" \
  -H "Accept: application/json"

200Sucesso

Resposta

{
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "title": "Festival de Verão 2026",
    "slug": "festival-de-verao-2026",
    "organizer_slug": "exemplo-eventos",
    "date": "2026-06-18T03:00:00.000Z",
    "time": "14:00",
    "end_date": "2026-06-18T03:00:00.000Z",
    "end_time": "16:00",
    "venue": "Arena Exemplo",
    "location": "Campinas - SP",
    "address": {
      "street": "Avenida José de Souza Campos",
      "number": "S/N",
      "complement": "",
      "neighborhood": "Cambuí",
      "city": "Campinas",
      "state": "SP",
      "zipcode": "13025900"
    },
    "category": "festa",
    "status": "active",
    "enabled": true,
    "visibility": "unlisted",
    "total_sales": 21,
    "max_capacity": 1000000,
    "ticket_types_count": 5,
    "created_at": "2025-09-22T19:02:38.256Z",
    "updated_at": "2026-06-10T23:10:03.873Z",
    "description": "Descrição de exemplo do evento.",
    "image_url": "https://cdn.useingresso.com/events/exemplo-banner.png",
    "banner_url": null,
    "age_restriction": "18_anos",
    "allow_ticket_transfer": true,
    "auto_close_sales": false,
    "sales_start_date": "2026-05-17T03:00:00.000Z",
    "sales_start_time": "18:30",
    "tickets": [
      {
        "id": 1001,
        "name": "Ingresso Pista",
        "description": "Acesso à área pista do evento.",
        "price": 80,
        "quantity": 500,
        "sold_quantity": 120,
        "max_per_person": 4,
        "is_active": true,
        "group_name": null
      },
      {
        "id": 1002,
        "name": "Ingresso VIP",
        "description": "Acesso à área VIP.",
        "price": 150,
        "quantity": 100,
        "sold_quantity": 45,
        "max_per_person": 2,
        "is_active": true,
        "group_name": null
      }
    ],
    "lineup": [
      {
        "name": "Artista A",
        "image_url": "https://cdn.useingresso.com/events/exemplo-artista-a.jpg"
      },
      {
        "name": "Artista B",
        "image_url": "https://cdn.useingresso.com/events/exemplo-artista-b.jpg"
      }
    ]
  }
}

404EVENT_NOT_FOUND. Evento não encontrado.

Erro

{
  "error": "Evento não encontrado",
  "code": "EVENT_NOT_FOUND"
}

Pedidos do evento

GET/api/v1/events/:eventId/orders

Lista pedidos do evento com status, itens, cupom e dados do comprador.

Query parameters

Parâmetro	Tipo	Descrição
`page`	integer	Página (ver Paginação).
`limit`	integer	Itens por página (ver Paginação).
`status`	string	Filtro por status. Valores: pending, approved, refunded, cancelled, rejected. Aliases: pago, reembolsado, cancelado. Múltiplos separados por vírgula: approved,pending.
`payment_method`	string	pix, credit_card ou free.

Status de pagamento

pending

Aguardando pagamento

approved

Pago

refunded

Reembolsado

cancelled

Cancelado

rejected

Recusado

Requisição

curl -s -X GET "https://useingresso.com/api/v1/events/507f1f77bcf86cd799439011/orders?status=approved&payment_method=pix&page=1" \
  -H "Authorization: Bearer ui_live_SUA_CHAVE" \
  -H "Accept: application/json"

200Sucesso

Resposta

{
  "event_id": "507f1f77bcf86cd799439011",
  "data": [
    {
      "id": "675b2c3d4e5f678901234abc",
      "external_reference": "UI-20260315-8F3A2B",
      "status": "approved",
      "payment_method": "pix",
      "provider": "pagseguro",
      "amount": 2,
      "fee_amount": 0.5,
      "total_amount": 2.5,
      "currency": "BRL",
      "customer": {
        "name": "Maria Silva",
        "email": "maria.silva@email.com",
        "cpf": "123.###.###-09"
      },
      "items": [
        {
          "ticket_type_id": 1001,
          "ticket_type_name": "Ingresso Pista",
          "quantity": 1,
          "unit_price": 2,
          "total_price": 2
        }
      ],
      "product_items": [],
      "coupon": null,
      "metadata": {
        "event_title": "Festival de Verão 2026",
        "promoter_purchase": false,
        "payment_received_in_cash": false
      },
      "created_at": "2026-03-15T18:42:11.000Z",
      "updated_at": "2026-03-15T18:43:05.000Z",
      "processed_at": "2026-03-15T18:43:05.000Z",
      "expires_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 856,
    "total_pages": 43,
    "has_next": true,
    "has_prev": false
  },
  "filters": {
    "status": ["approved"],
    "payment_method": "pix"
  }
}

Participantes do evento

GET/api/v1/events/:eventId/participants

Lista ingressos e produtos vendidos com status, check-in e dados do participante.

Query parameters

Parâmetro	Tipo	Descrição
`page`	integer	Página (ver Paginação).
`limit`	integer	Itens por página (ver Paginação).
`status`	string	valid, used, pending_payment, cancelled, refunded. Múltiplos separados por vírgula.
`checked_in`	boolean	true: apenas com check-in. false: sem check-in.

O campo checked_in indica se o participante fez check-in. O campo type pode ser ticket ou product.

Requisição

curl -s -X GET "https://useingresso.com/api/v1/events/507f1f77bcf86cd799439011/participants?checked_in=true&page=1" \
  -H "Authorization: Bearer ui_live_SUA_CHAVE" \
  -H "Accept: application/json"

200Sucesso

Resposta

{
  "event_id": "507f1f77bcf86cd799439011",
  "data": [
    {
      "id": "676c3d4e5f678901234def01",
      "ticket_code": "UI-8F3A2B-001",
      "type": "ticket",
      "ticket_type_name": "Ingresso Pista",
      "product_name": null,
      "variation_name": null,
      "status": "used",
      "checked_in": true,
      "checked_in_at": "2026-06-18T17:14:33.000Z",
      "purchase_date": "2026-03-15T18:43:05.000Z",
      "price_paid": 2,
      "payment_method": "pix",
      "payment_id": "675b2c3d4e5f678901234abc",
      "participant": {
        "name": "Maria Silva",
        "email": "maria.silva@email.com",
        "cpf": "123.###.###-09"
      }
    },
    {
      "id": "676c3d4e5f678901234def02",
      "ticket_code": "UI-8F3A2B-002",
      "type": "ticket",
      "ticket_type_name": "Ingresso VIP",
      "product_name": null,
      "variation_name": null,
      "status": "valid",
      "checked_in": false,
      "checked_in_at": null,
      "purchase_date": "2026-03-15T18:43:05.000Z",
      "price_paid": 0,
      "payment_method": "free",
      "payment_id": "675b2c3d4e5f678901234def99",
      "participant": {
        "name": "João Santos",
        "email": "joao.santos@email.com",
        "cpf": null
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1250,
    "total_pages": 63,
    "has_next": true,
    "has_prev": false
  },
  "filters": {
    "status": null,
    "checked_in": true
  }
}

Erros e headers

Todas as respostas de erro seguem o formato { "error": "...", "code": "..." }.

HTTP	Código	Descrição
401	`INVALID_API_KEY`	Chave ausente, inválida ou revogada
403	`ORGANIZATION_SUSPENDED`	Organização suspensa
403	`ORGANIZATION_NOT_APPROVED`	Organização ainda não aprovada
404	`ROUTE_NOT_FOUND`	Rota da API inexistente
404	`EVENT_NOT_FOUND`	Evento não encontrado
405	`METHOD_NOT_ALLOWED`	Método HTTP não suportado (apenas GET)
429	`RATE_LIMITED`	Limite de requisições excedido
500	`INTERNAL_ERROR`	Erro interno do servidor

Exemplos de erro

401Credencial inválida

Resposta

{
  "error": "Credencial inválida ou ausente.",
  "code": "INVALID_API_KEY"
}

404Rota inexistente

Resposta

{
  "error": "Rota não encontrada.",
  "code": "ROUTE_NOT_FOUND",
  "path": "/api/v1/events/xyz/invalid",
  "method": "GET",
  "documentation": "/developers/api"
}

429Rate limit

Resposta

{
  "error": "Limite de requisições excedido. Tente novamente em instantes.",
  "code": "RATE_LIMITED"
}

Headers de rate limit

Em respostas autenticadas, a API envia os headers abaixo:

Boas práticas

Recomendações para integrações estáveis e seguras em produção.

Variável de ambiente

Armazene a chave no seu backend, por exemplo em USEINGRESSO_API_KEY.

Rotação de credencial

Rotacione a chave imediatamente se houver suspeita de vazamento.

Paginação

Não assuma que todos os registros cabem em uma única página.

Retry com backoff

Implemente nova tentativa com backoff exponencial em respostas 429.

Cache inteligente

Cacheie listagens de eventos por alguns minutos se não precisar de dados em tempo real.