Ticketing

Visão geral

Essa API é criada especificamente para suportar clientes do setor de ticketeiras. Caso tenha dúvida se deveria ou não estar usando essa API por favor entre em contato com o time de Solutions da Legiti.
Você pode enviar informações relacionadas a pedidos para a Legiti por meio do endpoint /order, que suporta requisições POST (create). Nesse endpoint você pode especificar, por meio da flag evaluate, se deseja ou não receber uma avaliação da Legiti para o pedido. Caso deseje receber a avaliação da Legiti é importante que você trate a resposta da API de modo diferente.
É importante ressaltar que essa é uma variação da API de delivery da Legiti então dados relacionados ao "evento" e "dono do ingresso" serão coletados por meio das entidades de custom_data dento da entidade de produto. Além disso, alguns nomes de campos não são exatamente adaptados a realidade de eventos.

Quando rastrear

Você pode ver mais informações sobre onde adicionar estes endpoints no seu fluxo de pagamento aqui

Entidades

Pedido

{
"id": "12345",
"evaluate": true,
"total_paid_value": 110.0,
"total_gross_value": 100.0,
"discount_value": 10.0,
"coupon_names": ["LOTR"],
"currency": "BRL",
"status": "pending",
"creation_datetime": "2020-02-10T20:18:40Z",
"tax_invoice_document_type": "cpf",
"tax_invoice_document": "12345678911",
"user": {
"id": "98745",
"name":"john fulano",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code":"55",
"password_hash": "effebbbeeabc123",
"gender": "male",
"social_login": "facebook",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Apto 11",
"label": "Casa"
}
},
"items": [
{
"quantity":2,
"unit_price":30,
"unit_discount":0,
"total_value":60,
"product": {
"sku": "15975368",
"title": "Event A",
"product_id": "123",
"description": "Cool Event A",
"categories": ["8"],
"custom_data": {
"event": {
"start_datetime": "2019-12-17T00:48:03Z",
"end_datetime": "2019-12-17T00:48:03Z",
"seating_option": "premium",
"venue": {
"address": {
"street_name": "Rua Bruxelas",
"street_number": "188",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"latitude": 12.569692,
"longitude": 58.3813781
},
"is_virtual": false,
"capacity": 30000
}
},
"guest": {
"name":"james fulano",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code":"55"
}
}
}
},
{
"quantity":1,
"unit_price":50.0,
"unit_discount":10.0,
"total_value":40.0,
"product": {
"sku": "75363418",
"title": "Event B",
"product_id": "456",
"description": "Cool Event B",
"categories": ["8", "9"],
"custom_data": {
"event": {
"start_datetime": "2019-12-17T00:48:03Z",
"end_datetime": "2019-12-17T00:48:03Z",
"seating_option": "premium",
"venue": {
"address": {
"street_name": "Rua Bruxelas",
"street_number": "188",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"latitude": 12.569692,
"longitude": 58.3813781
},
"is_virtual": false,
"capacity": 30000
}
},
"guest": {
"name":"john fulano",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code":"55"
}
}
}
}
],
"payments": [
{
"id": "974613",
"method": "credit_card",
"payment_value": 110.0,
"installments": 1,
"interest": 0.1,
"document_type": "cpf",
"document": "12345678911",
"credit_card": {
"first_six_digits": "123456",
"last_four_digits": "1234",
"expiration_date": "23/05",
"holder_name": "Random da Silva"
},
"billing_address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR"
}
}
]
}
Propriedade
Tipo
Descrição
id
String
O identificador exclusivo do pedido na sua plataforma. Este é o id que será usado nos dashboards fornecidos pela Legiti
evaluate
Boolean
Indica se a Legiti deve retornar ou não uma avaliação sobre o pedido
user
Usuário
Informações sobre o comprador
total_paid_value
Float
O valor exato que o usuário pagou pelo pedido (total_paid_value = total_gross_value + - discount_value)
total_gross_value
Float
A soma dos valores de todos os itens do pedido, sem adicionar discount_value
discount_value
Float
O valor do desconto aplicado ao pedido
coupon_names
Array de Strings
Os nomes dos cupons que foram aplicados. Nota: se coupon_names é fornecido, discount_value também é obrigatório
currency
String
A moeda do total_paid_value, como um código de moeda ISO-4217
status
String
Status do pedido. Valores permitidos: approved, declined, pending, cancelled, manual_analysis, unauthorized. Você pode ver mais sobre isso aqui
status_reason
String
O motivo para a mudança de status.
tax_invoice_document_type
String
O tipo de documento associado com a nota fiscal. Valores aceitos são cpf, cnpj e other
tax_invoice_document
String
O número do documento associado com a nota fiscal
items
Array de Item
Os itens comprados (por exemplo, produtos)
payments
Array de Pagamento
Os pagamentos usados nesta compra
creation_datetime
String
A data e hora em que o pedido foi criado. Este deve ser o mesmo horário em que o pedido foi enviado para o endpoint de avaliação.O valor deve estar em UTC seguindo o formato ISO 8601 (YYYY-MM-DDTHH:mm:ssZ)
custom_data
JSON para captura de dados customizados para cada cliente

Usuário

Formato padronizado da Legiti para representar usuários.
{
"id": "12345",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code": "55",
"password_hash": "effebbbeeabc123",
"name": "john fulano",
"gender": "male",
"user_type": "consumidor",
"social_login": "facebook",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Apto 11",
"label": "Casa"
}
}
Propriedade
Tipo
Descrição
id
String
O identificador exclusivo do usuário na sua plataforma
email
String
O e-mail principal associado ao usuário
document
String
O número do documento associado ao usuário
document_type
String
O tipo do documento utilizado. Valores aceitos são cpf, cnpj, passport, rg, rne e other
phone_number
String
O número de telefone principal associado ao usuário (apenas números; código do país não incluído). Nota: se o phone_number é fornecido, phone_country_code também é obrigatório
phone_country_code
String
Código do país associado ao número de telefone (apenas números). Nota: se o phone_country_code é fornecido, phone_number também é obrigatório
password_hash
String
A senha protegida (salted e hashed) associada com o usuário
name
String
Nome completo do usuário
gender
String
O gênero do usuário. Os valores aceitos são: male, female, other, e undisclosed
social_login
String
Se o usuário se cadastrou usando um serviço de terceiros. Valores aceitos são: facebook, apple, google, twitter
creation_datetime
String (formato YYYY-MM-DDTHH:mm:ssZ em UTC)
A data e hora de quando a conta do usuário foi criada
address
Address
O endereço associado ao usuário
custom_data
JSON para captura de dados customizados para cada cliente

Item

Formato padronizado da Legiti para representar itens comprados.
{
"quantity":2,
"unit_price":30,
"unit_discount":0,
"total_value":60,
"product": {
"sku": "15975368",
"title": "Event A",
"product_id": "123",
"description": "Cool Event A",
"categories": ["8"],
"custom_data": {
"event": {
"start_datetime": "2019-12-17T00:48:03Z",
"end_datetime": "2019-12-17T00:48:03Z",
"seating_option": "premium",
"venue": {
"address": {
"street_name": "Rua Bruxelas",
"street_number": "188",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"latitude": 12.569692,
"longitude": 58.3813781
},
"is_virtual": false,
"capacity": 30000
}
},
"guest": {
"name":"john fulano",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code":"55"
}
}
}
}
Propriedade
Tipo
Descrição
quantity
Integer
A quantidade comprada deste produto
unit_price
Float
Preço unitário do produto comprado
unit_discount
Float
O valor do desconto aplicado a cada unidade deste produto
total_value
Float
O valor total pago por este produto
product
Produto
Dados do produto comprado
custom_data
JSON para captura de dados customizados para cada cliente

Produto

Formato padronizado da Legiti para representar produtos.
{
"sku": "15975368",
"title": "Event A",
"product_id": "123",
"description": "Cool Event A",
"categories": ["8"],
"custom_data": {
"event": {
"start_datetime": "2019-12-17T00:48:03Z",
"end_datetime": "2019-12-17T00:48:03Z",
"seating_option": "premium",
"venue": {
"address": {
"street_name": "Rua Bruxelas",
"street_number": "188",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"latitude": 12.569692,
"longitude": 58.3813781
},
"is_virtual": false,
"capacity": 30000
}
},
"guest": {
"name":"john fulano",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code":"55"
}
}
}
Propriedade
Tipo
Descrição
sku
String
O identificador do evento exclusivo na sua plataforma
title
String
O nome do evento
product_id
String
ID secundário do evento (pode ser o ID do evento principal caso esta seja apenas uma variação)
description
String
A descrição do evento
categories
Array de String
As categorias desse evento na sua plataforma. (Categorias arbitrárias são aceitas, mas devem ser consistentes.)
custom_data
JSON para captura de dados customizados para cada cliente
Evento
Formato padronizado da Legiti para representar eventos.
Essa entidade fica dentro do campo (ou chave) custom_data da entidade de produto.
{
"custom_data": {
"event": {
"start_datetime": "2019-12-17T00:48:03Z",
"end_datetime": "2019-12-17T00:48:03Z",
"seating_option": "premium",
"venue": {
"address": {
"street_name": "Rua Bruxelas",
"street_number": "188",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"latitude": 12.569692,
"longitude": 58.3813781
},
"is_virtual": false,
"capacity": 30000
}
},
}
}
Propriedade
Tipo
Descrição
start_datetime
String (formato YYYY-MM-DDTHH:mm:ssZ em UTC)
Data em que o evento começa
end_datetime
String (formato YYYY-MM-DDTHH:mm:ssZ em UTC)
Data em que o evento termina. Campo necessário para eventos com mais de um dia (e.g. festivais)
seating_option
String
Tipo de ticket (e.g. camarote)
venue
Venue
Dados sobre o local do evento. Esse field também é necessário para eventos virtuais
Venue
Formato padronizado da Legiti para representar dados sobre o local do evento.
Essa entidade fica dentro do campo (ou chave) custom_data da entidade de produto.
{
"venue": {
"is_virtual": false,
"capacity": 30000,
"address": {
"street_name": "Rua Bruxelas",
"street_number": "188",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"latitude": 12.569692,
"longitude": 58.3813781
}
}
}
Propriedade
Tipo
Descrição
is_virtual
Boolean
Se o evento é virtual ou físico/presencial
capacity
Integer
Capacidade de venda de ingressos para o evento. Esse campo funciona tanto para eventos virtuais como físicos/presenciais
address
Address
Local onde o evento será realizado. Necessário apenas para eventos físicos/presenciais
Guest
Formato padronizado da Legiti para representar dados sobre o dono do ingresso.
Essa entidade fica dentro do campo (ou chave) custom_data da entidade de produto.
{
"custom_data": {
"guest": {
"name":"john fulano",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code":"55"
}
}
}
Propriedade
Tipo
Descrição
email
String
O e-mail principal associado ao dono do ingresso
name
String
Nome completo do dono do ingresso
document
String
O número do documento associado ao dono do ingresso
document_type
String
O tipo do documento utilizado. Valores aceitos são cpf, cnpj, passport, rg, rne e other
phone_number
String
O número de telefone principal associado ao dono do ingresso (apenas números; código do país não incluído). Nota: se o phone_number é fornecido, phone_country_code também é obrigatório
phone_country_code
String
Código do país associado ao número de telefone (apenas números). Nota: se o phone_country_code é fornecido, phone_number também é obrigatório
custom_data
JSON para captura de dados customizados para cada cliente

Pagamento

Formato padronizado da Legiti para representar pagamentos de um pedido.
{
"id": "974613",
"acquired_id": "123654789",
"method": "credit_card",
"payment_value": 110.0,
"installments": 1,
"interest": 0.1,
"document_type": "cpf",
"document": "12345678911",
"credit_card": {
"first_six_digits": "123456",
"last_four_digits": "1234",
"expiration_date": "23/05",
"holder_name": "Random da Silva"
},
"billing_address":{
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR"
}
}
Propriedade
Tipo
Descrição
id
String
O identificador único do pagamento na sua plataforma. Se não tiver um, pode nos enviar o identificador do pedido. Este é o identificador a ser usado no futuro se você precisar atualizar as informações de pagamento
acquirer_id
String
O identificador único para cada transação retornada pela adquirente/gateway. Este identificador é usado para vincular chargebacks
method
String
Método de pagamento. Valores aceitos: credit_card, boleto, wallet, cash, vr (vale refeição), pix, transfer, apple_pay, goole_pay e other
payment_value
Float
O montante pago
installments
Integer
O número de parcelas a serem pagas.
interest
Float
A taxa de juros aplicada - onde 0 significa que não foram aplicados juros e 1 significa 100% de juros mensais
document_type
String
Tipo de documento associado ao pagamento. Valores aceitos são cpf, cnpj, passport, rg, rne e other
document
String
Número do documento associado ao pagamento
credit_card
Cartão de crédito associado ao pagamento. Observação: credit_card é necessário somente se o método de pagamento é credit_card
billing_address
Address
Endereço de cobrança associado ao pagamento. Observação: billing_address é necessário somente se o método de pagamento for credit_card ou boleto
custom_data
JSON para captura de dados customizados para cada cliente

Cartão de Crédito

Formato padronizado da Legiti para representar as informações de cartão de crédito de um pagamento.
{
"first_six_digits": "123456",
"last_four_digits": "1234",
"expiration_date": "23/05",
"holder_name": "Random da Silva"
}
Propriedade
Tipo
Descrição
Placeholder Values*
first_six_digits
String
Os seis primeiros dígitos do número do cartão de crédito (devem ser apenas dígitos)
999999
last_four_digits
String
Os últimos quatro dígitos do número do cartão de crédito (devem ser apenas dígitos)
9999
expiration_date
String
A data de vencimento do cartão de crédito, com formato mm/yy
XX/XX
holder_name
String
O nome completo do titular do cartão de crédito.
Indisponível
custom_data
JSON para captura de dados customizados para cada cliente
-
*Caso você não possua alguma das informações de cartão de crédito você pode utilizar esses valores como placeholder no lugar da informação faltante

Descrição dos Status

Status de Pedido

Estas são as descrições para o campo status na entidade Pedido:
Status do pedido
Status
Descrição
approved
O pedido foi aprovado e é esperado que seja entregue ao consumidor
declined
O pedido foi rejeitado por suspeita de fraude (tanto da Legiti ou por outro provedor de anti-fraude)
pending
O pedido não foi nem rejeitado, nem aprovado, e seu pagamento ainda não foi processado. Você ainda está decidindo se deve aprovar ou rejeitar o pedido
cancelled
O pedido foi cancelado ou reembolsado e não será mais entregue ou o consumidor está devolvendo
manual_analysis
O pedido foi enviado a um humano para revisão
unauthorized
O pagamento não foi aprovado pela adquirente

Endpoints da API

Criação e Avaliação de pedidos

Para receber a avaliação do pedido a flag evaluate deve ser true
Notifica a Legiti sempre que um novo pedido for criado. Caso a flag evaluate seha true o endpoint irá retornar a avaliação da Legiti para o pedido.
A Legiti deve receber todos os pedidos da plataforma, até mesmo aqueles que não são de cartão de crédito já que esses pedidos podem ser usados para a avaliação de outros pedidos. Importante ressaltar que para pedidos que não são de cartão de crédito a flag evaluate deve ser false
É importante aderir às nossas melhores práticas de tratamento de erros de API
Curl
Python
Node.js
PHP
Ruby
Java
curl -X POST https://legiti-api.lgtcdn.net/v2/order \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"id": "12345",
"evaluate": true,
"total_paid_value": 110.0,
"total_gross_value": 100.0,
"discount_value": 10.0,
"coupon_names": ["LOTR"],
"currency": "BRL",
"status": "pending",
"creation_datetime": "2020-02-10T20:18:40Z",
"tax_invoice_document_type": "cpf",
"tax_invoice_document": "12345678911",
"user": {
"id": "98745",
"name":"john fulano",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code":"55",
"password_hash": "effebbbeeabc123",
"gender": "male",
"social_login": "facebook",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Apto 11",
"label": "Casa"
}
},
"items": [
{
"quantity":2,
"unit_price":30,
"unit_discount":0,
"total_value":60,
"product": {
"sku": "15975368",
"title": "Event A",
"product_id": "123",
"description": "Cool Event A",
"categories": ["8"],
"custom_data": {
"event": {
"start_datetime": "2019-12-17T00:48:03Z",
"end_datetime": "2019-12-17T00:48:03Z",
"seating_option": "premium",
"venue": {
"address": {
"street_name": "Rua Bruxelas",
"street_number": "188",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"latitude": 12.569692,
"longitude": 58.3813781
},
"is_virtual": False,
"capacity": 30000
}
},
"guest": {
"name":"john fulano",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code":"55"
}
}
}
},
{
"quantity":1,
"unit_price":50.0,
"unit_discount":10.0,
"total_value":40.0,
"product": {
"sku": "75363418",
"title": "Event B",
"product_id": "456",
"description": "Cool Event B",
"categories": ["8", "9"],
"custom_data": {
"event": {
"start_datetime": "2019-12-17T00:48:03Z",
"end_datetime": "2019-12-17T00:48:03Z",
"seating_option": "premium",
"venue": {
"address": {
"street_name": "Rua Bruxelas",
"street_number": "188",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"latitude": 12.569692,
"longitude": 58.3813781
},
"is_virtual": False,
"capacity": 30000
}
},
"guest": {
"name":"james fulano",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code":"55"
}
}
}
}
],
"payments": [
{
"id": "974613",
"method": "credit_card",
"payment_value": 110.0,
"installments": 1,
"interest": 0.1,
"document_type": "cpf",
"document": "12345678911",
"credit_card": {
"first_six_digits": "123456",
"last_four_digits": "1234",
"expiration_date": "23/05",
"holder_name": "Random da Silva"
},
"billing_address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR"
}
}
]
}'
import json
import requests
headers = {
'Authorization': 'Bearer $API_KEY',
}
data = {
'id': '12345',
'evaluate': true,
'total_paid_value': 110.0,
'total_gross_value': 100.0,
'discount_value': 10.0,
'coupon_names': ['LOTR'],
'currency': 'BRL',
'status': 'pending',
'creation_datetime': '2020-02-10T20:18:40Z',
'tax_invoice_document_type': 'cpf',
'tax_invoice_document': '12345678911',
'user': {
'id': '98745',
'name':'john fulano',
'email': '[email protected]',
'document': '123.456.789-10',
'document_type': 'cpf',
'phone_number': '11999123456',
'phone_country_code':'55',
'password_hash': 'effebbbeeabc123',
'gender': 'male',
'social_login': 'facebook',
'creation_datetime': '2019-12-17T00:48:03Z',
'address': {
'street_name': 'Rua Fidalga',
'street_number': '252',
'zip_code': '05432-010',
'city': 'São Paulo',
'state': 'SP',
'country': 'BR',
'details': 'Apto 11',
'label': 'Casa'
}
},
'items': [
{
'quantity':2,
'unit_price':30,
'unit_discount':0,
'total_value':60,
'product': {
'sku': '15975368',
'title': 'Event A',
'product_id': '123',
'description': 'Cool Event A',
'categories': ['8'],
'custom_data': {
'event': {
'start_datetime': '2019-12-17T00:48:03Z',
'end_datetime': '2019-12-17T00:48:03Z',
'seating_option': 'premium',
'venue': {
'address': {
'street_name': 'Rua Bruxelas',
'street_number': '188',
'zip_code': '05432-010',
'city': 'São Paulo',
'state': 'SP',
'country': 'BR',
'latitude': 12.569692,
'longitude': 58.3813781
},
'is_virtual': false,
'capacity': 30000
}
},
'guest': {
'name':'john fulano',
'email': '[email protected]',
'document': '123.456.789-10',
'document_type': 'cpf',
'phone_number': '11999123456',
'phone_country_code':'55'
}
}
}
},
{
'quantity':1,
'unit_price':50.0,
'unit_discount':10.0,
'total_value':40.0,
'product': {
'sku': '75363418',
'title': 'Event B',
'product_id': '456',
'description': 'Cool Event B',
'categories': ['8', '9'],
'custom_data': {
'event': {
'start_datetime': '2019-12-17T00:48:03Z',
'end_datetime': '2019-12-17T00:48:03Z',
'seating_option': 'premium',
'venue': {
'address': {
'street_name': 'Rua Bruxelas',
'street_number': '188',
'zip_code': '05432-010',
'city': 'São Paulo',
'state': 'SP',
'country': 'BR',
'latitude': 12.569692,
'longitude': 58.3813781
},
'is_virtual': false,
'capacity': 30000
}
},
'guest': {
'name':'james fulano',
'email': '[email protected]',
'document': '123.456.789-10',
'document_type': 'cpf',
'phone_number': '11999123456',
'phone_country_code':'55'
}
}
}
}
],
'payments': [
{
'id': '974613',
'method': 'credit_card',
'payment_value': 110.0,
'installments': 1,
'interest': 0.1,
'document_type': 'cpf',
'document': '12345678911',
'credit_card': {
'first_six_digits': '123456',
'last_four_digits': '1234',
'expiration_date': '23/05',
'holder_name': 'Random da Silva'
},
'billing_address': {