MultiClubes Tickets API v2

Esta é a documentação dos serviços de comunicação da solução MultiClubes. Este manual tem como objetivo ajudar no entendimento e na implementação de uso dos serviços que compõem a API. Este manual se destina aos integradores na implementação do projeto venda de ingressos integrada com a solução MultiClubes.

Comunicação

A comunicação suportada é SOAP sobre HTTPS com o uso do protocolo TLS 1.0 e SSL 3.0. O certificado fornecido pelo servidor deve ser inspecionado a cada nova conexão, para confirmar que se trata de um certificado confiável. A URL do servidor contida no certificado deve corresponder ao endereço correto do MultiClubes (multiclubes.com.br). Os dados devem estar codificados no formato UTF8.

Autenticação

O acesso à API é restrito aos parceiros cadastrados, sendo necessário informar, em cada conexão, a chave de autenticação fornecida pela nossa equipe de suporte técnico ao parceiro. A duração da chave é indeterminada, somente perdendo a validade caso a conta de acesso seja desativada. A chave de autenticação deve ser informada pelo cabeçalho da chamada pelo header com nome _AuthenticationKey com namespace ns.

Glossário

  • Adquirentes: são empresas que fazem a comunicação da transação entre a loja e a bandeira e entregam os valores recebidos. Exemplos: Cielo, Rede, Amex, GetNet, etc.
  • Bandeira do cartão: é a marca do cartão de crédito ou débito. São elas que determinam as regras de uso e validação de estabelecimentos para receber o pagamento.
  • TEF: é um sistema que permite a transferência de transações financeiras de forma eletrônica.
  • NSU: é a sigla para Número Sequencial Único. É um número único gerado para identificar uma transação ou uma nota fiscal.
  • DOC: é a abreviação de Documento de Ordem de Crédito. É uma transação usada para transferir no máximo R$ 4.999,99 para uma conta de um banco diferente.
  • Estorno: é a devolução de uma quantia cobrada.
  • Catraca: é um meio físico com uma barreira que impede ou permite a passagem de uma pessoa por vez.
  • Link de pagamento: URL única e temporária gerada para que um cliente realize o pagamento de um serviço ou produto de forma online.
  • Webhook: Mecanismo de notificação automática que envia dados em tempo real para uma URL específica quando determinados eventos ocorrem no sistema.

Processamento de Eventos do Webhook

Fila Principal (executa a cada 1 minuto)

  • Processa eventos novos com menos de 3 falhas.
  • Tenta envio até 3 vezes antes de passar para a fila secundária.
  • Finaliza quando o webhook é entregue com sucesso.
  • Frequência do intervalo pode ser personalizada diretamente no ambiente.

Fila Secundária (executa a cada 3 horas)

  • Reprocessa eventos que falharam 3 ou mais vezes.
  • Continua tentando realizando envios até 3 dias após criação do link de pagamento.
  • Após 3 dias, o evento expira automaticamente e nenhuma tentativa de notificação ao Webhook será efetuada.
  • Frequência do intervalo pode ser personalizada diretamente no ambiente.

Critério de Sucesso: Um webhook é considerado bem-sucedido quando retorna código HTTP entre 200-299.

Formato do Payload JSON Uma requisição POST será enviada ao endereço do webhook no formato JSON, conforme abaixo:

Campo Tipo Tamanho Máximo Descrição
eventType string 100 caracteres Tipo do evento que originou a notificação
data.saleId integer - ID único da venda no sistema
data.dueDate string 10 caracteres Data de vencimento do link de pagamento (formato: dd/MM/yyyy)
data.voucherCode string 50 caracteres Código único do voucher gerado
data.orderNumber string 50 caracteres Número do pedido associado ao link de pagamento
data.url string 2000 caracteres URL do link de pagamento para o cliente
data.value decimal 18,2 Valor total da(s) venda(s) ativa(s) associada(s) ao link de pagamento

Funcionamento

  • Consulta disponibilidade de ingressos.
  • Venda de ingressos.
  • Consulta vendas de ingressos.
  • Cancelamento de vendas.

Como começar

  1. Obtenha o endereço do serviço de homologação.
  2. Abra o endereço do serviço no navegador e obtenha a documentação WSDL.
  3. Realize chamadas em homologação para testes de reconhecimento.
  4. Integre as chamadas com seu software em homologação.
  5. Obtenha o endereço do serviço de produção.
  6. Realize chamadas em produção para testes de finalização.

Notas de versão

2.0.0

14/12/2018

  1. Criada esta documentação para auxiliar no entendimento e implementação.

2.0.1

04/01/2019

  1. Foi alterado o método GetTickets para retornar os planos de venda dos ingressos.
  2. Incluído o código de erro InvalidAccessCode.
  3. Incluído o código de erro PaymentValueGreaterThanSale.

2.0.2

10/07/2019

  1. Foi alterado o método Sell para retornar o identificador único da unidade dos ingressos vendidos.
  2. Foi alterado o método Sell para suportar as formas de pagamento Document (documento) e ThirdParties (terceiros).
  3. Foi alterado o método Sell para vendas por promotores.
  4. Incluído o código de erro InvalidPromoterThirdParties.
  5. Incluído o código de erro PromoterNotFound.
  6. Incluído o código de erro InvalidPromoterPaymentType.
  7. Incluído o código de erro InvalidThirdPartiesDunInstitution.
  8. Incluído o código de erro OnlyOnePromoterThirdPartiesPaymetType.
  9. Incluído o método CreatePromoter para realizar o cadastro de promotores.
  10. Incluído o código de erro InvalidPromoterManager.
  11. Incluído o código de erro InvalidPromoterCpf.
  12. Incluído o código de erro InvalidPromoterCnpj.
  13. Incluído o código de erro InvalidPromoterEmail.
  14. Incluído o código de erro InvalidPromoterPromoterTitleSalePlan.
  15. Incluído novo método Edit para editar vendas existentes.
  16. Incluído o código de erro CurrentPromoterWithBalance.

2.0.3

  1. Foi alterado o método CreatePromoter para permitir informar a inscrição estadual.
  2. Incluído o código de erro InvalidPromoterEdit.

2.0.4

23/12/2019

  1. Foi alterado o método Sell para permitir informar o código do voucher a ser gerado na venda.
  2. Incluído código de erro VoucherCodeAlreadyUsed.

2.0.5

10/01/2020

  1. Foi alterado o método UsageResult para retornar todos os ingressos utilizados do voucher com data e código de acesso.

2.0.6

16/01/2020

  1. Foi criado o método GetTicketPromoter para retornar os ingressos vinculados a parcelas de acerto de comissão que já foram pagas.

2.0.7

21/02/2020

  1. Adicionado o método GetVoucherSales para consulta de vendas realizadas.

2.0.8

Adicionado a validação de limite de bloqueio de vendas do promotor

  1. Incluído o código de erro PromoterOutOfBalance

2.0.9

03/04/2020

  1. Adicionado o opcional AddressData ao SaleItemData para identificar o endereço do visitante.

2.0.10

27/04/2020

  1. Adicionado o campo opcional SaleDate ao PaymentData para identificar a data real do pagamento.

2.0.11

22/06/2020

  1. Adicionado os campos Email e PhoneNumber à SaleItemData para não haver a perda dessas informações na edição.

2.0.12

02/07/2020

  1. Adicionado o campo AccountNumber à SaleItemData para permitir vincular um ingresso vendido à uma conta de consumo existente (cartão ou pulseira).
  2. Novo retorno de erro InvalidAccountNumber para validação do AccountNumber.

2.0.13

07/08/2020

  1. Adicionado os métodos SearchVoucher e RescheduleVoucher para permitir a consulta e reagendamento de voucher devido à pandemia da COVID-19.
  2. Incluído o código de erro InvalidParameter.
  3. Incluído o código de erro VoucherIsNotReadyToAccess.
  4. Incluído o código de erro VoucherAccessedCantBeRescheduled.
  5. Incluído o código de erro FoundMultipleVouchers.

2.0.14

09/12/2020

  1. Adicionado o campo AccessCodes ao SearchVoucherResult para identificar os códigos de acesso do voucher.

2.0.15

28/12/2021

  1. Adicionado os métodos GetReserveAvailabilityIntervals e GetReserveAvailabilityDay para permitir a consulta das disponibilidades do controle de reservas para a regra de horário e a regra de dia.
  2. Incluído o código de erro ReserveExhausted.
  3. Incluído o código de erro InvalidCalendarInterval.
  4. Incluído o código de erro InvalidAttraction.
  5. Incluído o código de erro InvalidAttractionInterval
  6. Incluído o código de erro RescheduleIntervalRequired.
  7. Incluído o código de erro RescheduleInvalidInterval.
  8. Incluído o código de erro InvalidReschedule.
  9. Incluído o código de erro InvalidCalendar.
  10. Adicionado o campo Intervals à RescheduleVoucherData para permitir indicar novo horário para um ingresso.
  11. Adicionado o campo Interval à SaleItemData para permitir indicar o horário do ingresso.
  12. Adicionado o campo Interval à SaleItemResult para informar o horário do ingresso.
  13. Adicionado o campo Intervals à SearchVoucherResult para informar os horários dos ingressos.
  14. Adicionado o campo Reserve à TicketResult para informar a quantidade disponível do ingresso para o dia ou horário no controle de reservas.
  15. Adicionado o campo Interval à UsageResult para informar o horário do ingresso.

2.0.16

18/02/2022

  1. Incluído o código de erro InvalidCalendarExternalConnection.
  2. Incluído o código de erro InvalidAttractionExternalConnection.
  3. Adicionado comportamento aos métodos GetReserveAvailabilityIntervals e GetReserveAvailabilityDay para realizarem a consulta das disponibilidades do controle de reservas apenas em calendários e atração que possuem disponibilidade interna.

2.0.17

30/10/2025

  1. Adicionado o campo PaymentLink à SaleData para permitir a criação de vendas com link de pagamento.
  2. Adicionado o campo WebhookUrl à PaymentLink para informar a URL do webhook que receberá notificações sobre mudanças de status no link de pagamento.
  3. Adicionado o campo DueDays à PaymentLink para informar a quantidade de dias até o vencimento do link de pagamento, contados a partir da data de criação.
  4. Incluído o código de erro InvalidPaymentValueForSellUsingPaymentLink.
  5. Incluído o código de erro InvalidDueValueForSellUsingPaymentLink.
  6. Incluído o código de erro InvalidPaymentForSellUsingPaymentLink.
  7. Incluído o código de erro InvalidWebhoolUrlPaymentLink.
  8. Incluído o código de erro InvalidPaymentLinkDueDaysForVisitDate.
  9. Incluído o código de erro PaymentlinkNotEnabled.
  10. Incluído o código de erro PaymentLinkNotAllowedForVoucherWithoutLink.
  11. Incluído o código de erro PaymentNotAllowedForVoucherWithLink.
  12. Incluído o código de erro PayRequestCreditCardPaymentCancellationFailed.
  13. Incluído o código de erro TefReversalDataNotAllowedForPaymentLink.

2.0.18

03/11/2025

  1. Incluído o código de erro ExistingTicketSaleSourceEid referente a validação de duplicidade no campo SellData.SaleItemData.SourceEid.