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.

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

Versão atual: 2.0.13

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.