Tickets

Última atualização: 04 de Maio de 2021

Introdução

A API de integração do ClearSale permite que os integradores enviem pedidos para análise de acordo com o tipo de produto contratado. Através da API é possível enviar pedidos e consultar informações relevantes da análise da ClearSale.

Etapas da Homologação

Algumas integrações necessitam ser homologadas. Os dados dos pedidos enviados no ambiente de homologação devem ser fictícios, evitando dados reais dos clientes, mas que atendam as orientações desta documentação.


Clique aqui para fazer o download das etapas de homologação.

Operações API


Autenticação do Token

Todas as requisições submetidas à nossa API devem ser realizadas através de um token de 2048 caracteres.

O token é gerado através de um usuário e senha que deve ser fornecido pela ClearSale.

Entre em contato com o seu consultor de vendas para maiores informações.

Na autenticação, além do token retornamos sua data de expiração. É necessário que contemple no seu desenvolvimento o gerenciamento da vida útil do token com base nessa data de expiração.

Para o recebimento desse dado é necessário que reserve um espaço de 2048 caracteres. Só gere um novo token após a expiração do seu token atual.

Requisição
POST https://api.clearsale.com.br/v1/authenticate HTTP/1.1
Content-Type: application/json

{
    "name": "{Your User}",
    "password": "{Your Password}"
}
POST https://homologacao.clearsale.com.br/api/v1/authenticate HTTP/1.1
Content-Type: application/json

{
    "name": "{Your User}",
    "password": "{Your Password}"
}
Resposta
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Token": "{Token value}",
  "ExpirationDate": "{Token expiration date}"
}     

Inclusão de Pedidos

Requisição
POST https://api.clearsale.com.br/v1/orders/
Content-Type: application/json
Authorization: Bearer {TOKEN}
[{
	"code": "ORDER_EXAMPLE_0_0_0_1",
	"sessionID": "SessionIDValue",
	"date": "2017-03-22T13:38:59",
	"email": "email@email.com.br",
	"itemValue": 10.00,
	"totalValue": 15.00,
	"ip": "192.168.0.1",
	"giftMessage": "Message Example",
	"observation": "Observation example",
	"status": 0,
	"origin": "Origin example",
	"country": "Brasil",
	"purchaseInformation": {
		"lastDateInsertedMail": "2015-03-01T02:40:00",
		"lastDateChangePassword": "2015-04-02T05:15:00",
		"lastDateChangePhone": "2015-05-03T10:45:00",
		"lastDateChangeMobilePhone": "2015-06-04T12:05:00",
		"lastDateInsertedAddress": "2015-07-05T15:25:00",
		"purchaseLogged": false,
		"email": "email@email.com.br",
		"login": "SocialNetworkLogin"
	},
	"billing": {
		"clientID": "Client123",
		"type": 1,
		"primaryDocument": "12345678910",
		"secondaryDocument": "12345678",
		"name": "Complete Client Name",
		"birthDate": "1990-01-10T00:00:00",
		"email": "email@email.com.br",
		"gender": "M",
		"motherName": "Mother Name Example",
		"address": {
			"street": "Street name example",
			"number": "0",
			"additionalInformation": "Additional information example",
			"county": "County Example",
			"city": "City Example",
			"state": "SP",
			"zipcode": "12345678",
			"country": "Brasil",
			"reference": "Address reference example"
		},
		"phones": [{
			"type": 1,
			"ddi": 55,
			"ddd": 11,
			"number": 33333333,
			"extension": "1111"
		}]
	},
	"shipping": {
		"clientID": "Client123",
		"type": 1,
		"primaryDocument": "12345678910",
		"secondaryDocument": "12345678",
		"name": "Complete Client Name",
		"birthDate": "1990-01-10T00:00:00",
		"email": "email@email.com.br",
		"gender": "M",
		"address": {
			"street": "Street name example",
			"number": "0",
			"additionalInformation": "Additional information example",
			"county": "County Example",
			"city": "City Example",
			"state": "SP",
			"zipcode": "12345678",
			"country": "Brasil",
			"reference": "Address reference example"
		},
		"phones": [{
			"type": 1,
			"ddi": 55,
			"ddd": 11,
			"number": 33333333,
			"extension": "1111"
		}],
		"deliveryType": "1",
		"price": 5.00
	},
	"payments": [{
		"sequential": 1,
		"date": "2017-03-21T22:36:53",
		"value": 80.00,
		"type": 1,
		"installments": 1,
		"interestRate": 0.00,
		"interestValue": 0.00,
		"card": {
			"number": "123456xxxxxx1234",
			"hash": "12345678945612301234569874563210",
			"bin": "123456",
			"end": "1234",
			"type": 1,
			"validityDate": "02/2021",
			"ownerName": "Owner Card Name",
			"document": "12345678910",
			"nsu": "12345"
		}
	}],
	"tickets": [{
		"convenienceFeeValue": 0.00,
		"quantityFull": 500,
		"quantityHalf": 250,
		"batch": 12345,
		"virtual": true,
		"event": {
			"id": "123456",
			"name": "Event name exeample",
			"local": "Event's place example",
			"date": "2017-03-21T22:36:53",
			"type": 1,
			"genre": "Music concert",
			"quantityTicketSale": 800,
			"quantityEventHouse": 2,
			"address": {
				"street": "Street name example",
				"number": "10",
				"county": "County Example",
				"city": "City Example",
				"state": "SP",
				"country": "Brasil",
				"zipcode": "12345678"
			}
		},
		"peoples": [{
			"name": "Name example",
			"legalDocument": "12345678910"
		}],
		"categories": [{
			"name": "Category name example",
			"quantity": 100,
			"value": 100.00
		}],
		"additionalInformations": [{
			"name": "Product name example",
			"quantity": 5,
			"value": 10.00
		}]
	}]
}]
POST https://homologacao.clearsale.com.br/api/v1/orders/
Content-Type: application/json
Authorization: Bearer {TOKEN}
[{
	"code": "ORDER_EXAMPLE_0_0_0_1",
	"sessionID": "SessionIDValue",
	"date": "2017-03-22T13:38:59",
	"email": "email@email.com.br",
	"itemValue": 10.00,
	"totalValue": 15.00,
	"ip": "192.168.0.1",
	"giftMessage": "Message Example",
	"observation": "Observation example",
	"status": 0,
	"origin": "Origin example",
	"country": "Brasil",
	"purchaseInformation": {
		"lastDateInsertedMail": "2015-03-01T02:40:00",
		"lastDateChangePassword": "2015-04-02T05:15:00",
		"lastDateChangePhone": "2015-05-03T10:45:00",
		"lastDateChangeMobilePhone": "2015-06-04T12:05:00",
		"lastDateInsertedAddress": "2015-07-05T15:25:00",
		"purchaseLogged": false,
		"email": "email@email.com.br",
		"login": "SocialNetworkLogin"
	},
	"billing": {
		"clientID": "Client123",
		"type": 1,
		"primaryDocument": "12345678910",
		"secondaryDocument": "12345678",
		"name": "Complete Client Name",
		"birthDate": "1990-01-10T00:00:00",
		"email": "email@email.com.br",
		"gender": "M",
		"motherName": "Mother Name Example",
		"address": {
			"street": "Street name example",
			"number": "0",
			"additionalInformation": "Additional information example",
			"county": "County Example",
			"city": "City Example",
			"state": "SP",
			"zipcode": "12345678",
			"country": "Brasil",
			"reference": "Address reference example"
		},
		"phones": [{
			"type": 1,
			"ddi": 55,
			"ddd": 11,
			"number": 33333333,
			"extension": "1111"
		}]
	},
	"shipping": {
		"clientID": "Client123",
		"type": 1,
		"primaryDocument": "12345678910",
		"secondaryDocument": "12345678",
		"name": "Complete Client Name",
		"birthDate": "1990-01-10T00:00:00",
		"email": "email@email.com.br",
		"gender": "M",
		"address": {
			"street": "Street name example",
			"number": "0",
			"additionalInformation": "Additional information example",
			"county": "County Example",
			"city": "City Example",
			"state": "SP",
			"zipcode": "12345678",
			"country": "Brasil",
			"reference": "Address reference example"
		},
		"phones": [{
			"type": 1,
			"ddi": 55,
			"ddd": 11,
			"number": 33333333,
			"extension": "1111"
		}],
		"deliveryType": "1",
		"price": 5.00
	},
	"payments": [{
		"sequential": 1,
		"date": "2017-03-21T22:36:53",
		"value": 80.00,
		"type": 1,
		"installments": 1,
		"interestRate": 0.00,
		"interestValue": 0.00,
		"card": {
			"number": "123456xxxxxx1234",
			"hash": "12345678945612301234569874563210",
			"bin": "123456",
			"end": "1234",
			"type": 1,
			"validityDate": "02/2021",
			"ownerName": "Owner Card Name",
			"document": "12345678910",
			"nsu": "12345"
		}
	}],
	"tickets": [{
		"convenienceFeeValue": 0.00,
		"quantityFull": 500,
		"quantityHalf": 250,
		"batch": 12345,
		"virtual": true,
		"event": {
			"id": "123456",
			"name": "Event name exeample",
			"local": "Event's place example",
			"date": "2017-03-21T22:36:53",
			"type": 1,
			"genre": "Music concert",
			"quantityTicketSale": 800,
			"quantityEventHouse": 2,
			"address": {
				"street": "Street name example",
				"number": "10",
				"county": "County Example",
				"city": "City Example",
				"state": "SP",
				"country": "Brasil",
				"zipcode": "12345678"
			}
		},
		"peoples": [{
			"name": "Name example",
			"legalDocument": "12345678910"
		}],
		"categories": [{
			"name": "Category name example",
			"quantity": 100,
			"value": 100.00
		}],
		"additionalInformations": [{
			"name": "Product name example",
			"quantity": 5,
			"value": 10.00
		}]
	}]
}]
Resposta
Content-Type: application/json
Request-ID: 12J6-11B3-11A7-93C0
{
  "packageID": "4825dc1d-5246-45d3-ba32-d2de9bbff478",
  "orders": [
    {
      "code": "{CODIGO_DO_MEU_PEDIDO}",
      "status": "NVO",
      "score": null
    }
  ]
}

Notificação de alteração de status (Webhook)

Sempre que ocorrer alterações no status de um pedido, o Webhook da Clearsale irá enviar uma notificação da alteração (sem o status) para uma URL que deverá ser desenvolvida no lado do integrador.

A URL deverá ser capaz de interpretar a requisição abaixo:

Requisição
POST {URL_DO_INTEGRADOR}
Content-Type: application/json
{
	"code": "{CODIGO_DO_MEU_PEDIDO}",
	"date": "2016-01-01T10:30:00.9931909-02:00",
	"type": "status"
}

Importante: Assim que a URL for desenvolvida, é necessário que seja enviada a equipe de integração da ClearSale através do e-mail integracao@clear.sale, para que ela seja configurada em nossa base de dados.

O status não será informado na notificação do Webhook e deverá ser consultado via API, vide Consulta de Status.

Se a URL do integrador retornar qualquer status http diferente de 200, o Webhook irá tentar notificar novamente para o pedido.

Consulta de Status

Requisição
GET https://api.clearsale.com.br/v1/orders/{CODIGO_DO_MEU_PEDIDO}/status
Accept: application/json
Authorization: Bearer {TOKEN}
GET https://homologacao.clearsale.com.br/api/v1/orders/{CODIGO_DO_MEU_PEDIDO}/status
Accept: application/json
Authorization: Bearer {TOKEN}
Resposta
Content-Type: application/json
Request-ID: 12J6-11B3-11A7-93C0
{
  "code": "{CODIGO_DO_MEU_PEDIDO}",
  "status": "AMA",
  "score": 99.99
}

Atualização de Status

Requisição
PUT https://api.clearsale.com.br/v1/orders/{CODIGO_DO_MEU_PEDIDO}/status
Content-Type: application/json
Authorization: Bearer {TOKEN}
{
	"status ": "Sigla do status"
}
PUT https://homologacao.clearsale.com.br/api/v1/orders/{CODIGO_DO_MEU_PEDIDO}/status
Content-Type: application/json
Authorization: Bearer {TOKEN}
{
	"status ": "Sigla do status"
}

Exemplo de status de pagamento

Resposta
Content-Type: application/json
Request-ID: 12J6-11B3-11A7-93C0
{
 	 "status": "OK",
 	 "message": "Status was changed with success"
}

Importante: Os status de atualização devem ser combinados com a equipe de integração.

Marcação de Chargeback

Requisição
POST https://api.clearsale.com.br/v1/chargeback
Content-Type: application/json
Authorization: Bearer {TOKEN}
{
    "message" : "Message example",
	"orders" : ["{ORDER_CODE}"]
}
POST https://homologacao.clearsale.com.br/api/v1/chargeback
Content-Type: application/json
Authorization: Bearer {TOKEN}
{
    "message" : "Message example",
	"orders" : ["{ORDER_CODE}"]
}
Resposta
Content-Type: application/json
Request-ID: 12J6-11B3-11A7-93C0
{   
    "code": "{CODIGO_DO_MEU_PEDIDO}",
    "status": "Chargeback done"
}

Resolução de problemas


Em todas as requisições realizadas será retornado uma chave no header chamada Request-ID, o valor desta chave conterá 19 caracteres, através de tal valor nosso suporte será capaz de capturar a sua transação e auxiliá-lo na resolução de algum problema.

Tabelas código e descrição


Tipo de telefone (billing/shipping.phone.type)


Código Descrição
0 Não definido
1 Residencial
2 Comercial
3 Recados
4 Cobrança
5 Temporário
6 Celular

Tipo pessoa (billing/shipping.type)


Código Descrição
1 Pessoa Física
2 Pessoa Jurídica

Tipo de sexo (billing/shipping.gender)


Código Descrição
M Masculino
F Feminino

Tipo de pagamento (payment.type)


Código Descrição
1 Cartão de Crédito
2 Boleto Bancário
3 Débito Bancário
4 Débito Bancário - Dinheiro
5 Débito Bancário - Cheque
6 Transferência Bancária
7 Sedex a cobrar
8 Cheque
9 Dinheiro
10 Financiamento
11 Fatura
12 Cupom
13 Multicheque
14 Outros
16 Vale
27 PIX
1041 Cartão Presente Virual
4011 Cartão de Débito / Transferência Eletrônica (CD)

Bandeira Cartão de Crédito (card.type)


Código Descrição
1 Diners
2 MasterCard
3 Visa
4 Outros
5 American Express
6 HiperCard
7 Aura
10 Cartão Elo
50 LeaderCard
100 Fortbrasil
101 Sorocred
102 A Vista
103 Cartão Mais
105 Cartão C&A

Lista de Status (de retorno)


Status Descrição
APA (Aprovação Automática) – Pedido foi aprovado automaticamente segundo parâmetros definidos na regra de aprovação automática
APM (Aprovação Manual) – Pedido aprovado manualmente por tomada de decisão de um analista
RPM (Reprovado Sem Suspeita) – Pedido Reprovado sem Suspeita por falta de contato com o cliente dentro do período acordado e/ou políticas restritivas de CPF (Irregular, SUS ou Cancelados)
AMA (Análise manual) – Pedido está em fila para análise
NVO (Novo) – Pedido importado e não classificado Score pela analisadora (processo que roda o Score de cada pedido)
SUS (Suspensão Manual) – Pedido Suspenso por suspeita de fraude baseado no contato com o “cliente” ou ainda na base ClearSale
CAN (Cancelado pelo Cliente) – Cancelado por solicitação do cliente ou duplicidade do pedido
FRD (Fraude Confirmada) – Pedido imputado como Fraude Confirmada por contato com a administradora de cartão e/ou contato com titular do cartão ou CPF do cadastro que desconhecem a compra
RPA (Reprovação Automática) – Pedido Reprovado Automaticamente por algum tipo de Regra de Negócio que necessite aplicá-la
RPP (Reprovação Por Política) – Pedido reprovado automaticamente por política estabelecida pelo cliente ou Clearsale
APP (Aprovação Por Política) – Pedido aprovado automaticamente por política estabelecida pelo cliente ou Clearsale

Lista de Status (de entrada)

Atenção: Ao enviar o status no pedido é importante ressaltar que este pedido será incluso como histórico e não será analisado pela ClearSale.

Somente os pedidos que forem enviados com o status 0 – NVO ou que não tiverem o status definido que serão analisados pelo ClearSale.


Código Descrição
0 Novo (será analisado pelo ClearSale)
9 Aprovado (irá ao ClearSale já aprovado e não será analisado)
41 Cancelado pelo cliente (irá ao ClearSale já cancelado e não será analisado)
45 Reprovado (irá ao ClearSale já reprovado e não será analisado)

Status de pagamento


Código Descrição
PGA Pedido Aprovado
PGR Pedido Reprovado

Tipo de Entrega (shipping.deliveryType)


Código Descrição
0 Outros
1 Normal
2 Garantida
3 ExpressaBR
4 ExpressaSP
5 Alta
6 Econômica
7 Agendada
8 Extra Rápida
9 Impresso
10 Aplicativo
11 Correio
12 Motoboy
13 Retirada Bilheteria
14 Retirada Loja Parceira
15 Cartão de Crédito Ingresso
16 Retirada Loja
17 Retirada via Lockers (Parceiros)
18 Retirada em Agencia dos Correios
19 Entrega Garantida no mesmo dia da compra
20 Entrega Garantida no dia seguinte da compra
21 Retirada em loja - Expresso

Importante: Em caso de envio de algum tipo de entrega como “Retirada”, é necessário também enviar pedidos de teste em homologação com os dados de endereço do estabelecimento de retirada no objeto de entrega da compra (shipping.address).

Os dados de endereço de cobrança (billing.address) devem continuar sendo os do cliente.

Lista de Eventos (ticket.event.type)


ID Descrição
1 Festas
2 Shows
3 Evento universitário
4 Festivais
5 Exposições
6 Rodeio
7 Circense
8 Esportivo
9 Cinema
10 Teatro
11 Reveillon
12 Carnaval
13 Outro

Descrição de campos


Objeto order


Propriedade Descrição Tipo Tamanho Obrigatório
code Código do pedido String 50 S
sessionID Identificador único da sessão do usuário String 128 S
date Data do pedido Datetime S
email Email do pedido String 150 S
itemValue Valor Total dos Itens Decimal 20,4 N
totalValue Valor Total do Pedido Decimal 20,4 S
ip IP do Pedido String 50 N
giftMessage Mensagem de Presente String 8000 N
observation Observação do Pedido String 8000 N
status Status do Pedido Integer N
origin Origem do Pedido String 150 N
country Nome do País String 50 N
purchaseInformation Dados de Cadastro purchaseInformation N
billing Dados de cobrança billing S
shipping Dados de entrega shipping S
payments Dados de pagamento Array<payment> S
tickets tickets Array<ticket> S

Objeto purchaseInformation


Propriedade Descrição Tipo Tamanho Obrigatório
lastDateInsertedMail Data da última alteração do e-mail Datetime N
lastDateChangePassword Data da última alteração da senha Datetime N
lastDateChangePhone Data da última alteração do telefone Datetime N
lastDateChangeMobilePhone Data da última alteração do telefone móvel Datetime N
lastDateInsertedAddress Data da última alteração do endereço Datetime N
purchaseLogged Compra logado boolean N
email E-mail de Cadastro String 200 N
login Login de Acesso String 200 N

Objeto billing


Propriedade Descrição Tipo Tamanho Obrigatório
clientID Código do cliente String 50 N
type Pessoa Física ou Jurídica Integer S
primaryDocument CPF ou CNPJ String 100 S
secondaryDocument RG ou Inscrição Estadual String 100 N
name Nome do cliente String 500 S
birthDate Data de Nascimento Datetime N
email Email String 150 N
gender Sexo String 1 N
motherName Nome da mãe do cliente String 500 N
address Endereço address N
phones Telefones Array<phone> S

Objeto shipping


Propriedade Descrição Tipo Tamanho Obrigatório
clientID Código do cliente String 50 N
type Pessoa Física ou Jurídica Integer S
primaryDocument CPF ou CNPJ String 100 S
secondaryDocument RG ou Inscrição Estadual String 100 N
name Nome do cliente String 500 S
birthDate Data de Nascimento Datetime N
email Email String 150 N
gender Sexo String 1 N
address Endereço address N
phones Telefones Array<phone> S
deliveryType ID do Tipo de entrega String 50 N
price Valor do Frete Decimal 20,4 N

Objeto payments


Propriedade Descrição Tipo Tamanho Obrigatório
sequential Sequência de realização do pagamento Integer N
date Data do pagamento Datetime N
value Valor cobrado neste pagamento Decimal 20,4 N
type Tipo de Pagamento Integer S
installments Quantidade de Parcelas Integer N
interestRate Taxa de Juros Decimal 4,2 N
interestValue Valor dos Juros Decimal 20,4 N
card cartão card S

Objeto address


Propriedade Descrição Tipo Tamanho Obrigatório
street Nome do logradouro String 200 S
number Número do Endereço String 15 S
additionalInformation Complemento do Endereço String 250 N
county Bairro do Endereço String 150 S
city Cidade do Endereço String 150 S
state Sigla do Estado do Endereço - UF String 2 S
country País do Endereço String 150 N
zipcode CEP do Endereço String 10 S
reference Referência do Endereço String 250 N

Importante: O envio do endereço não é obrigatório, porém caso tenha essa informação para envio, deverá respeitar a obrigatoriedade mínima dos campos informados como ‘S’.

Se em sua regra de negócio existir entrega física, os dados de entrega (shipping) deverão ser informados.

Objeto phones


Propriedade Descrição Tipo Tamanho Obrigatório
type Tipo de Telefone Integer S
ddi DDI do Telefone Integer N
ddd DDD do Telefone Integer S
number Número do Telefone Integer S
extension Ramal do Telefone String 10 N

Importante: É obrigatório o envio de pelo menos 1 telefone.

Objeto card


Propriedade Descrição Tipo Tamanho Obrigatório
number Número do Cartão String 200 N
hash Hash do número do cartão String 128 N
bin Número do BIN do Cartão String 6 S
end 4 últimos digitos do número de cartão String 4 S
type Bandeira do Cartão Integer N
validityDate Data da Expiração String 50 N
ownerName Nome de Cobrança String 150 S
document Documento da Pessoa de Cobrança String 100 N
nsu Número identificador único de uma transação de cartão String 50 N

Objeto Ticket


Propriedade Descrição Tipo Tamanho Obrigatório
convenienceFeeValue Taxa de Conveniência Decimal 10,4 N
quantityFull Quantidade de ingressos com valor integral Integer N
quantityHalf Quantidade de ingresso com desconto (meia entrada) Integer N
batch Lote do Ingresso Integer N
virtual Ingresso Virtual (informar "true" ou "false") Boolean N
event Evento event S
peoples Pessoas Array<people> N
categories Categorias Array<category> N
additionalInformations Informações adicionais Array<additionalInformation> N

Objeto event


Propriedade Descrição Tipo Tamanho Obrigatório
id Código do evento String 50 N
name Nome do Evento String 200 S
local Local do Evento String 200 N
date Data do Evento Datetime S
type Lista de Evento Integer N
genre Genero do tipo de evento String 200 N
quantityTicketSale Quantidade de Ingresso à venda Integer N
quantityEventHouse Quantidade de vezes que o evento será realizado na casa Integer N
address Endereço do evento eventAddress N

Objeto eventAddress


Propriedade Descrição Tipo Tamanho Obrigatório
street Nome do logradouro String 200 S
number Número do Endereço String 15 S
county Bairro do Endereço String 150 S
city Cidade do Endereço String 150 S
state Sigla do Estado do Endereço - UF String 2 S
country Pais do Endereço String 150 N
zipcode CEP do Endereço String 10 S

Objeto people


Propriedade Descrição Tipo Tamanho Obrigatório
name Nome da Pessoa que comparecerá ao evento. String 200 S
legalDocument Documento de identificação da pessoa que comparecerá ao evento String 50 N

Objeto category


Propriedade Descrição Tipo Tamanho Obrigatório
name Descrição da categoria do Ingresso comprado String 200 S
quantity Quantidade de ingressos comprado na categoria Integer S
value Valor unitário do ingresso na categoria Decimal 10,4 S

Objeto additionalInformation


Propriedade Descrição Tipo Tamanho Obrigatório
name Nome do produto adicional adquirido String 200 S
quantity Quantidade do produto adicional adquirido Integer S
value Valor do produto adicional adquirido Decimal 10,4 S

Importante: As informações adicionais são os complementos da compra do tickets. EX: Combos de Pipoca com Refrigerante.