Introdução

Seja bem-vindo à API para credenciamento de eventos da plataforma Evemplus :)

API para credenciamento do evento

Esta API é destinada as empresas de credenciamento para executar ações específicas de controle de acesso e credenciamento do evento, ela permite efetuar check-in dos participantes, consultar status, listar participantes, buscar (por nome, Código do Qr Code e e-mail) e cadastrar novo participante (cadastro manual) e consultar disponibilidade de ingresso.

A API fornece endpoints com resultados representados em formato JSON, e em conformidade com o princípio REST de maneira segura, eficiente e de fácil integração. Para garantir a segurança de acesso somente a dados relacionados aos seus eventos, a API exige também a autenticação prévia.

Neste documento você encontrará a referência técnica de como acessar todos os serviços disponíveis da API.

Token para autenticação do evento

Para executar requisições válidas a Evemplus API é necessário uma chave de acesso (token) associada ao seu evento na plataforma. Este token deverá assinar todas as requisições enviadas à API.

Para criar um novo token, acesse dentro do gerenciador do seu evento, no menu lateral (versão desktop) a opção "pacotes" e procure pelo pacote "Evemplus API para credenciamento", (na versão de celular clique no menu do topo e clique em pacotes), clique em "gerenciar pacote" ou "Instalar pacote" (caso o pacote não esteja instalado), pronto, você terá acesso a página de criação ou modificação de token.

Nesta página, basta clicar em "Criar novo token". a qualquer momento você poderá gerar um novo token, a geração de novo token irá invalidar o token gerado anteriormente para o evento.

Ambiente sandbox para testes na plataforma

POST /credential/v1/sandbox/

Efetue testes na plataforma antes da implementação do seu sistema. os dados retornados no modo sandbox são fictícios e não pertencem a nenhum evento.

VARIAVEIS DO AMBIENTE SANDBOX

TOKEN	sandbox-2e15932a-de2fe4bf-b4a8b15b-f9615da6
TICKET_CODE	TK12MTB
TICKET_NAME	João de Souza Andrade No modo sandbox você deverá utilizar o nome completo para a busca, no modo produção você poderá efetuar a busca por parte do nome.

// Request samples CURL (SANDBOX)
curl --request POST \
--url 'https://api.evemplus.com.br/credential/v1/sandbox/{solicitação}' \
--header 'token: <CODIGO_TOKEN>'

Ambiente de produção da plataforma Evemplus

POST /credential/v1/

Execute ações de credenciamento e controle de acesso com esta API.

// Request samples CURL
curl --request POST \
--url 'https://api.evemplus.com.br/credential/v1/{solicitação}' \
--header 'token: <CODIGO_TOKEN>'

Apresentando a API

Abaixo você poderá acompanhar como integrar o seu evento com a plataforma para credenciamento da Evemplus, todos os exemplos deste documento são apresentados em modo produção, para alterar para o modo sandbox basta adicionar "sandbox/" nas solicitações.

Retornando participantes do evento

POST /credential/v1/participants

Retorna informações detalhadas sobre os participantes do evento, é possível utilizar parâmetros para filtrar os resultados.

HEADER PARAMETERS

TOKEN

required

(string)

Token de autenticação do evento.

POST PARAMETERS

status	string (Filtra os participantes pelo status da transação) Enum: CONFIRMADO EM ANALISE PENDENTE CANCELADO REEMBOLSADO Para informações detalhadas sobre o status de uma transação consulte o ítem status das transações
name	string (filtra participantes pelo seu nome) este campo deverá ter no mínimo 4 caracteres para efetuar a busca
email	string (filtra participantes pelo e-mail relacionado ao ingresso)
ticket_code	string (filtra participantes pelo Qr Code do ingresso)
checkin	boolean (filtra participantes por check-in) Este filtro só está disponível no modo produção Enum: TRUE FALSE
field_sort	string (Permite que os resultados sejam ordenados) deve ser utilizado para retornar apenas os atributos indicados do objeto. Os atributos indicados devem ser separados por (virgula)
sort	string (Ordenação dos resultados) Default: ASC Enum: ASC DESC

// Request samples CURL
curl --request POST \
--url 'https://api.evemplus.com.br/credential/v1/participants' \
--header 'token: <CODIGO_TOKEN>'

Responses application/json

int32 (Identificador único do participante)

name

string (Nome do participante)

string (E-mail do participante)

ticket_code

string (Código Qr code do ingresso)

ticket_name

string (Nome do ingresso)

date

string (Data do cadastro)
Data no formato YYYY-MM-DD HH:mm:ss (2019-11-23 13:10:00)

checkin

boolean (Se o check-in foi realizado)

checkin_date

string (Data do check-in)
Data no formato YYYY-MM-DD HH:mm:ss (2019-11-23 13:10:00)

checkin_ref

string (Campo opcional utilizado no check-in do participante)

custom_form

custom_form responses

id	int32 (Identificador único do campo personalizado)
type	string (Tipo de campo personalizado) Enum: address cpf cpnj rg date text textarea option radio checkbox termo
name	string (Nome do campo personalizado)
value	string (Valor do campo personalizado)

event_id

int32 (Identificador único do evento)

transaction

string (Identificador único da transação)

ticket_price

float (Preço do ingresso)

ticket_tax

float (Taxa de venda do ingresso)

ticket_amount

float (Preço de venda do ingresso)
O preço de venda final pode ser diferente devido a parcelamento com juros, o valor final será relacionado na transação do pedido.

ticket_status

string (Status da transação)
Enum: CONFIRMADO EM ANALISE PENDENTE CANCELADO REEMBOLSADO
Para informações detalhadas sobre o status de uma transação consulte o ítem status das transações

+ Error responses (400)

Efetuar o check-in de um participante

POST /credential/v1/checkin

Efetua check-in de um participante utilizando o Qr Code do ingresso. Somente será possível efetuar check-in de participantes com status confirmado.

HEADER PARAMETERS

TOKEN

required

(string)

Token de autenticação do evento.

POST PARAMETERS

TICKET_CODE required	string (Código Qr Code do ingresso)
CHECKIN_DATE optional	string (Data e hora do check-in) Data no formato YYYY-MM-DD HH:mm:ss (2020-01-08 13:46:42) Defaut: CURRENT TIMESTAMP [BRT]
CHECKIN_REF optional	string(20) (Campo opcional para referência do check-in) Você pode usar este campo para identificar por exemplo, a máquina que efetuou o check-in (Número de IP)

// Request samples CURL
curl --request POST \
--url 'https://api.evemplus.com.br/credential/v1/checkin' \
--header 'token: <CODIGO_TOKEN>'

Responses application/json

status	boolean (Se o check-in foi realizado)
date	string (Data do check-in) Data no formato YYYY-MM-DD HH:mm:ss (2019-11-23 13:10:22)
message	string (Mensagem de retorno)

Mensagens de retorno do check-in

status	TRUE
message	Check-in realizado.
status	FALSE
message	Ingresso não encontrado.
message	O check-in deste ingresso já foi realizado.

+ Error responses (400)

Efetuando nova inscrição

Antes de efetuar a inscrição de um participante pela API Evemplus, você deverá retornar a lista de ingressos disponíveis para venda, e ao iniciar o processo de preenchimento dos dados você deverá reservar o ingresso para a compra, cada reserva de ingresso ficará disponível por 15 minutos, após este prazo não havendo a finalização da inscrição, a reserva será cancelada e o ingresso ficará disponivel para compra novamente.

Obtendo ingressos disponíveis para a venda

POST /credential/v1/tickets

Retorna a lista de ingressos disponíveis para venda, os ingressos retornados serão aqueles que estão dentro do prazo de venda, não estão esgotados, não estão ocultos e a sua quantidade mínima de venda ser iqual a 1

HEADER PARAMETERS

TOKEN

required

(string)

Token de autenticação do evento.

// Request samples CURL
curl --request POST \
--url 'https://api.evemplus.com.br/credential/v1/tickets' \
--header 'token: <CODIGO_TOKEN>'

Responses application/json

ticket_id	int32 (Identificador único do ingresso)
name	string (Nome do ingresso)
ticket_price	float (preço do ingresso)
ticket_tax	float (taxa do ingresso)
ticket_amount	float (Preço de venda do ingresso) Utilize este valor para efetuar a venda do ingresso
number_tickets	int32 (Quantidade de ingressos disponíveis para venda)
end_date	string (Data máxima de venda do ingresso) Data no formato YYYY-MM-DD HH:mm:ss (2020-11-23 16:10:22)

+ Error responses (400)

Reservando ingressos para venda

POST /credential/v1/reserve

Efetua a reserva de ingressos para a venda

HEADER PARAMETERS

TOKEN

required

(string)

Token de autenticação do evento.

POST PARAMETERS

TICKET_ID required	int32 (Identificador único do ingresso que foi recebido no passo anterior)
NUMBER_TICKETS required	int32 (Quantidade de tickets para reserva) No momento a API evemplus só permite a reserva de um ingresso por vez, portante este valor sempre deverá ser 1

// Request samples CURL
curl --request POST \
--url 'https://api.evemplus.com.br/credential/v1/reserve' \
--header 'token: <CODIGO_TOKEN>'

Responses application/json

status	boolean (Se reserva foi efetuada)
reserve_id	string (Identificador único da reserva) este valor será solicitado posteriormente para o cadastro do participante
time	string (Tempo em milissegundos até a reserva expirar)

+ Error responses (400)

Finalizando a inscrição

POST /credential/v1/register

Efetua uma nova inscrição no evento, todas as inscrições realizadas na API se comportam como uma inscrição realizada dentro do gestor do evento. (Inscrição manual)

HEADER PARAMETERS

TOKEN

required

(string)

Token de autenticação do evento.

POST PARAMETERS

RESERVE_ID required	string (Código da reserva obtido no passo anterior)
NAME required	string(200) (Nome para geração do ingresso)
EMAIL optional	string(200) (E-mail da conta Evemplus) Apesar de não ser obrigatório este e-mail será utilizado para efetuar um pre-cadastro na Evemplus (quando não existir esta conta), ou incluirá esse ingresso na conta associada a este e-mail do usuário, permitindo emissão do certificado de participação ou pesquisa de satisfação quando disponibilizado pelo organizador.
CHECKIN optional	boolean (Se já efetuar o check-in do participante no ato do cadastro) Defaut: FALSE Enum: TRUE FALSE
INFORMAÇÕES DE COBRANÇA
BUYER_NAME optional	string (Nome do comprador) Defaut: adicionado manualmente
BUYER_DOC_NUM optional	string (Número do documento) Número do CPF ou CNPJ
BUYER_PHONE optional	string (Telefone do comprador)
BUYER_ADDRESS optional	string (Endereço do comprador)
ADDRESS_NUM optional	string (Número)
ADDRESS_ALT optional	string (Complemento)
NEIGHBORHOOD optional	string (Bairro)
CITY optional	string (Cidade)
STATE optional	string (Estado)
ZIP_CODE optional	string (CEP)

// Request samples CURL
curl --request POST \
--url 'https://api.evemplus.com.br/credential/v1/register' \
--header 'token: <CODIGO_TOKEN>'

Responses application/json

status	boolean (Se o cadastro foi realizado)
id	string (identificador único do participante)
ticket_code	string (Código Qr Code do ingresso)

+ Error responses (400)

Cancelando uma reserva

POST /credential/v1/reserve_cancel

Cancela uma reserva e libera o ingresso para a venda novamente.

HEADER PARAMETERS

TOKEN

required

(string)

Token de autenticação do evento.

POST PARAMETERS

RESERVE_ID

required

string (Código da reserva)

// Request samples CURL
curl --request POST \
--url 'https://api.evemplus.com.br/credential/v1/reserve_cancel \
--header 'token: <CODIGO_TOKEN>'

Responses application/json

status	boolean (Se reserva foi cancelada)
message	string (Mensagem de retorno do cancelamento)

+ Error responses (400)

Referência status de uma transação

CONFIRMADO	Significa que a transação está confirmada, para pagamento gratuito o status retornado também é confirmado.
EM ANALISE	Significa que a transação está pendente de aprovação (cartão de crédito)
PENDENTE	Significa que a transação está pendente de pagamento (boleto bancário e débito bancário)
CANCELADO	Significa que o pedido não foi aprovado ou que o pagamento não foi concluído e, portanto, não foi pago
REEMBOLSADO	Significa que foi solicitado o reembolso da transação.

Consultar status de funcionamento da API para credenciamento

Você poderá consultar se a API para credenciamento Evemplus está funcionando corretamente, enviando uma solicitação para:

POST https://api.evemplus.com.br/credential/v1/

RESPONSE SCHEMA: application/json

error	FALSE
code	1
message	Evemplus credential API is working correctly

error	boolean (Parâmetro informando que existe um erro)
code	int32 (Código de erro)
message	string (Descrição do erro)