Venda de ingressos para eventos

• Superfície autenticada (/event/seller/{account_id}/...) — usada pelo vendedor para gerenciar eventos, ingressos, cupons, checkouts e métricas. Requer um Bearer JWT ou uma chave de API.
• Superfície pública (/event/event/{event_id}/...) — usada pela vitrine. Sem autenticação. Serve para renderizar a página do evento e conduzir o comprador pelo checkout.

​

Tipos e nomenclaturas de evento

​

Fluxo de compra do cliente em resumo

​

Etapa 1 — Criar o evento

• name, description, image_url (banner — faça upload primeiro pela ação upload_logo, máximo 2 MB).
• type (IN_PERSON ou ONLINE), subject, category, nomenclature.
• starts_at, ends_at (ISO 8601, com fuso horário).
• address se IN_PERSON, caso contrário digital_address.

• public — padrão true. Defina como false durante a edição; a vitrine resolve o evento via endpoint de contexto público independentemente, mas você normalmente controla o compartilhamento pela sua própria interface.
• max_installments — teto rígido de parcelas para pagamentos com cartão. Padrão "12".
• max_installments_no_tax — parcelas em que o vendedor absorve juros. "0" significa que o juro recai sempre sobre o comprador e o PIX também recebe o acréscimo. Padrão "0".

curl -X POST "https://api.dlpay.cloud/event/seller/$ACCOUNT_ID/events/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Festival Sunset 2026",
    "description": "Edição de aniversário.",
    "type": "IN_PERSON",
    "image_url": "https://cdn.dlpay.cloud/events/sunset.jpg",
    "subject": "27",
    "category": "39",
    "nomenclature": "TICKETING",
    "max_installments": "12",
    "max_installments_no_tax": "3",
    "starts_at": "2026-08-12T22:00:00Z",
    "ends_at": "2026-08-13T06:00:00Z",
    "address": {
      "name": "Arena Sunset",
      "display_map_widget": true,
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01001-000",
      "country_code": "BR",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": ""
    }
  }'

​

Etapa 2 — Criar ingressos

• name (até 45 caracteres), description, amount em centavos de BRL. Ingressos gratuitos são simplesmente amount: 0 — o checkout é automaticamente promovido para a situação FREE e o e-mail de confirmação é disparado sem passar pelo processador.
• quantity — estoque total para esse tipo de ingresso. Padrão 1000. O ingresso expõe a propriedade quantity_available, que subtrai checkouts ativos em PENDING, PAID e FREE e expira automaticamente os PENDING com mais de 16 minutos a cada leitura.
• sales_period_type — ALWAYS (padrão) ou PERIOD. Quando PERIOD, defina sales_starts_at e sales_ends_at.
• questions — lista de objetos { id, prompt, type, values?, validation_regex? }. O type da pergunta é um de LIST, RADIO, STRING, INTEGER, DATE, EMAIL, PHONE, CPF. LIST / RADIO exigem values. STRING pode carregar um validation_regex. Os ids das perguntas são normalizados em slug e deduplicados no servidor; um id vazio recebe como padrão o slug do prompt.

​

Etapa 3 — Cupons de desconto opcionais

• name — rótulo de exibição.
• code — o que o comprador digita. É colocado em maiúsculas e tem espaços removidos no servidor. Deve ser único dentro do evento e não pode conter espaços.
• type — FIXED (valor em centavos de BRL) ou PERCENTAGE (valor de 1 a 100).
• value — deve ser > 0. Para PERCENTAGE, limitado a 100.

​

Etapa 4 — Publicar

• O contexto público omite o vendedor, a conta e a url do evento digital. A url da reunião só é revelada após o checkout chegar em PAID / FREE.
• O quantity_available retornado pelo contexto público é calculado ao vivo e dispara como efeito colateral a expiração automática de 16 minutos para checkouts pendentes.

​

Etapa 5 — Fluxo do cliente

​

Etapa 6 — Monitorar e validar

​

Métricas em tempo real

• GET .../events/metrics/eventsalesbydate/ — receita bruta por dia.
• GET .../events/metrics/ticketsalesbydate/ — ingressos vendidos por dia.
• GET .../events/metrics/ticketsalesbydateevent/ — abertura por evento.
• GET .../events/metrics/ticketsalesbyhour/ — totais agrupados por hora do dia dentro do intervalo filtrado.

​

Listagem administrativa de eventos

​

Exemplo ponta a ponta

import requests

BASE = "https://api.dlpay.cloud"
TOKEN = "<jwt-do-vendedor-ou-chave-de-api>"
ACCOUNT_ID = "<uuid-da-conta-unificada>"

auth = {"Authorization": f"Bearer {TOKEN}"}

event = requests.post(
    f"{BASE}/event/seller/{ACCOUNT_ID}/events/",
    headers=auth,
    json={
        "name": "Workshop de Lançamento",
        "description": "Tarde prática.",
        "type": "ONLINE",
        "image_url": "https://cdn.dlpay.cloud/events/workshop.jpg",
        "subject": "24",
        "category": "35",
        "nomenclature": "REGISTRATION",
        "max_installments": "6",
        "max_installments_no_tax": "3",
        "starts_at": "2026-06-10T19:00:00-03:00",
        "ends_at": "2026-06-10T22:00:00-03:00",
        "digital_address": {"platform": "ZOOM", "url": "https://zoom.us/j/123"},
    },
).json()

ticket = requests.post(
    f"{BASE}/event/seller/{ACCOUNT_ID}/events/{event['id']}/tickets/",
    headers=auth,
    json={
        "name": "Inscrição Geral",
        "amount": 5000,
        "quantity": 50,
        "description": "Acesso ao workshop ao vivo.",
        "questions": [
            {"prompt": "Empresa", "type": "STRING"},
        ],
    },
).json()

print("Link da vitrine:", event["link"])

context = requests.get(f"{BASE}/event/event/{event['id']}/").json()
sellable = context["tickets"][0]

checkout = requests.post(
    f"{BASE}/event/event/{event['id']}/checkout/",
    json={
        "customer": {
            "name": "Maria Silva",
            "email": "maria@example.com",
            "phone_number": "11987654321",
            "country_code": "+55",
        },
        "tickets": [
            {
                "ticket": sellable["id"],
                "question_answers": [
                    {"question_id": "empresa", "answer": "Acme"},
                ],
            }
        ],
    },
).json()

pix = requests.post(
    f"{BASE}/event/event/{event['id']}/checkout/{checkout['id']}/pay/",
    json={"type": "pix"},
).json()

print("Mostre este PIX ao comprador:", pix)

​

Armadilhas

• As situações do checkout são específicas do domínio. Use EXPIRED, FREE, PENDING, PAID, CANCELED. Estados genéricos de transação como CONFIRMED / REFUNDED não se aplicam ao checkout de evento — filtrar ou comparar com eles sempre retorna zero linhas.
• É quantity, não max_quantity. O campo de estoque do ingresso é quantity. Não existe max_quantity e campos desconhecidos são descartados silenciosamente — seus ingressos ficarão com o padrão de 1000 vagas.
• Reservas de estoque expiram em 16 minutos. O quantity_available expira automaticamente checkouts em PENDING com mais de 16 minutos a cada leitura, mas os próprios checkouts permanecem pagáveis por 20 minutos via is_payable. As duas janelas são intencionais — o comprador ainda consegue concluir o pagamento por alguns minutos depois que a vaga já foi tecnicamente liberada.
• Ingressos gratuitos pulam o processador. Quando total < 1 (por exemplo, ingressos todos gratuitos ou um cupom de 100%), a criação muda a situação para FREE. Não chame pay/ nesses casos — retornará 400.
• Os ids de pergunta são em slug. prompt: "Tamanho da camiseta" vira id: "tamanho-da-camiseta". Esse mesmo slug é o que você envia de volta em question_answers[].question_id.
• A url digital é sensível. Ela nunca é retornada pelo contexto público do evento. Exponha apenas a donos autenticados ou a compradores depois que o checkout chegar em PAID / FREE.
• Códigos de cupom são insensíveis a maiúsculas, mas armazenados em caixa alta. Um cupom code: "sunset10" é armazenado como SUNSET10; tanto a validação quanto a criação do checkout aplicam strip().upper() antes da busca.
• As métricas são deltas com sinal, não snapshots. Mover manualmente um checkout pago de volta para PENDING fora do fluxo normal decrementará contadores e geralmente é um erro — deixe o pipeline do processador conduzir as transições.