Introdução

Esta é a documentação dos serviços de comunicação para smartphones 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.

Comunicação

A comunicação suportada é SOAP 1.1 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

  • Cliente: é o clube ou parque que contratou o serviço do aplicativo para seus usuários.
  • Usuário: é a pessoa que usa o aplicativo, compra convites e adquire produtos e serviços nos pontos de venda do cliente.
  • Conta de consumo: é o cartão ou pulseira onde são apontados os serviços e produtos adquiridos pelo usuário.
  • Conta de consumo pré-paga: são contas de consumo onde valor é pago antecipadamente ao consumo nos pontos de venda através de recargas de crédito.
  • Conta de consumo pós-paga: são contas de consumo onde valor é pago após o consumo nos pontos de venda. Neste cenário o usuário possui um limite de crédito que define até qual valor o saldo da sua conta poderá ficar negativo. Ao atingir o valor limite, um pagamento é necessário para realizas novos consumos.
  • Conta de acesso: é um cadastro que o usuário deve fazer para uso do aplicativo.
  • Pontos de venda: são pontos de prestação de serviços ou venda de produtos onde o meio de pagamento aceito é um cartão ou pulseira de consumo. Tais pontos são normalmente bares, restaurantes e quiosques.
  • Movimento de consumo: são movimentos financeiro que afetam o saldo do cartão de consumo. Dentre eles: venda, estorno, recarga, pagamento, etc.
  • Crédito: valor positivo do saldo da conta de consumo. Os créditos são utilizados para consumo nos pontos de venda do cliente.
  • Pagamento: pagamento para quitar ou reduzir um saldo devedor. Esta operação é realizada em conta de consumo pós-pagas.
  • Recarga: pagamento antecipado para inclusão de créditos na conta de consumo. Normalmente, esta operação é realizada em conta de consumo pré-paga, mas também pode ser realizada em contas de consumo pós-pagas.
  • Valor faturado: é o valor a pagar de consumos que foi enviado para o cliente, normalmente via cobrança bancária.
  • Cartão verificado: é quando o cartão de crédito teve ao menos uma transação de pagamento aprovada.
  • Cartão autorizado para uso futuro: é quando o usuário autoriza que o cartão fique disponível para uso futuro afim de não precisar digitar os dados novamente.
  • Turma: é o espaço em que o sócio será matriculado para realizar a modalidade que deseja.
  • Modalidade: é a atividade que será realizada na turma em que o sócio for matriculado.
  • Matrícula: é o registro efetivo de um sócio em uma turma.
  • Capacidade: é a quantidade máxima de alunos que uma turma suporta.
  • Taxa de matrícula: é o valor a ser pago por um sócio ao se matricular em uma turma.
  • Manutenção: é o valor mensal que um sócio deve pagar ao estar matrículado em uma turma.
  • Manutenção proporcional: é o valor cobrado referênte à mensalidade da turma em proporção ao número de dias do mês que serão contabilizados desde que matrícula foi efetuada.
  • Fila de espera: fila para realizar a matrícula em uma turma. Caso o sócio deseje fazer matrícula em uma turma cuja capacidade máxima fora alcançada, o mesmo deverá ser inserido na fila de espera.

Funcionamento

A API foi idealizada para que o aplicativo seja usado parcialmente sem conectividade com o servidor. Este comportamento tem como principais objetivos:

  • Aumentar a responsividade do aplicativo.
  • Reduzir o uso de dados do usuário.
  • Permitir o uso do aplicativo sem conexão à internet.

Com esse funcionamento as funcionalidades básicas que devem ser oferecidas no aplicativo são:

Operações com conectividade:

  • Autenticação de usuário.
  • Recepção de atualizações das contas de consumo. É esperado que a atualização dos dados possa ser realizada manualmente pelo usuário e em segundo plano pelo aplicação quando o usuário acionar as funções de consultas ou entrar no aplicativo.
  • Pagamento de conta de consumo pós-paga.
  • Pagamento de estacionamento.
  • Recarga de conta de consumo pré-paga.
  • Consulta de extrato de consumo.
  • Compra de convites.
  • Consulta disponibilidade de convites.
  • Consulta convites comprados.
  • Cancelamento de compras de convites.
  • Consulta de turmas disponíveis para matrícula.
  • Matrícula de sócios em turmas.
  • Cancelamento de matrícula de sócios.
  • Inclusão de sócios na fila de espera de uma turma.
  • Remoção de sócios da fila de espera de uma turma.

Operações sem conectividade:

  • Entrada no aplicativo de usuário previamente autenticado.
  • Consulta de saldo de consumo.

Para permitir as operações sem conectividade, o aplicativo deve armazenar localmente os dados previamente recebidos e atualizá-los a medida que novos dados de atualizações forem recebidos. Veja aqui uma estrutura de banco de dados em SQL Lite para servir como ponto de partida.

Como começar

  1. Obtenha o endereço do serviço e chave de autenticaçã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 e chave de autenticação de produção.
  6. Realize chamadas em produção para testes de finalização.

Notas de versão

Versão atual: 1.0.32

1.0.0

25/04/2018

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

1.0.1

16/05/2018

  1. Alterada a versão SOAP utilizada.
  2. Alterada a versão do TLS e SSL utilizadas.
  3. Chave de segurança AuthenticationKey renomeada para _AuthenticationKey e inserida necessidade de ser enviada no namespace ns.
  4. Removido o código de erro InvalidIntegrationUser dos códigos de erros do serviço Consumption.

1.0.2

24/07/2018

Banco de dados

  1. Alterada a tabela ConsumptionAccounts para conter os campos Type e OpenInvoiceValue.

Serviço Account

  1. Alterado o campo Email de LoginData para Credential.
  2. Alterado o código de erro InvalidEmailOrPassword para InvalidCredentialOrPassword.
  3. Incluído o código de erro TitleNotActive.
  4. Incluído o código de erro TitleHasNotAccount.

Serviço Consumption

  1. Alterado o método Refresh para retornar as contas de consumo de sócio.
  2. Incluído o campo Type no retorno AccountResult para identificar o tipo da conta de consumo.
  3. Incluído o campo OpenInvoiceValue no retorno AccountResult para identificar o valor faturado.
  4. Incluído o método LoadLimit.
  5. Incluído o método EditLimit.
  6. Alterado o código de erro InvalidAccount para InvalidConsumptionAccount.
  7. Alterado o código de erro AccountNotFound para ConsumptionAccountNotFound.
  8. Incluído o código de erro MaxCreditLimitExceeded.
  9. Incluído o código de erro UnauthorizedCreditLimit.
  10. Incluído o código de erro InvalidCloudAccount.
  11. Incluído o código de erro UnauthorizedCloudAccount.

1.0.3

08/08/2018

  1. O elemento AppFault disparado em exceções teve as seguintes alterações:
    • Renomeado para SecuredFault.
    • Namespace alterado para http://multiclubes.com.br.

1.0.4

25/09/2018

Foram realizadas modificações que tiveram o objetivo de alterar a consulta do extrato de movimentos de consumo para exigir conectividade. Desta forma, foram simplificados os mecanismos de atualização de dados necessários para operações sem conectividade com o servidor. Os dados para operações sem conectividade ficaram restritos a autenticação e a visão geral das contas de consumo.

Banco de dados

  1. Removida tabela ConsumptionMovements.
  2. Removida tabela ConsumptionMovementDetails.
  3. Removido o campo CloudAccounts.LastRefreshDate.
  4. Removido o campo ConsumptionAccounts.LastRefreshDate.
  5. Removido a chave estrangeira IX_ConsumptionMovements_AccountNumber.

Serviço Consumption

  1. Incluído o método LoadMovements.
  2. Alteração do retorno do método AddAccount com a remoção do campo AddAccountResult.Movements.
  3. Alteração do parâmetro do método LoadPayment com a remoção do campo LoadPaymentData.LastRefreshDate e renomeação do campo LoadPaymentResult.Changes para LoadPaymentResult.Refresh.
  4. Alteração do parâmetro do método PerformPayment com a remoção do campo PerformPaymentData.LastRefreshDate.
  5. Alteração do parâmetro do método PerformPayment e PerformRecharge com a renomeação do campo PaymentResult.Changes para PaymentResult.Refresh.
  6. Alteração do parâmetro do método PerformRecharge com a remoção do campo PerformRechargeData.LastRefreshDate.
  7. Alteração do parâmetro do método Refresh com a remoção do campo RefreshData.LastRefreshDate.
  8. Alterações do retorno dos métodos Refresh, EditLimit, LoadPayment, PerformPayment e PerformRecharge:
    • Removido campo RefreshResult.Status.
    • Removido campo RefreshResult.Movements.
    • Removido campo RefreshResult.Date.
    • Removido campo RefreshResult.RemovedAccountNumbers.

1.0.5

16/10/2018

Foram realizadas modificações que tiveram o objetivo de exibir os cartões de crédito vinculados a conta e também a possibilidade de removê-los da conta. Desta forma, o processo de pagamento foi simplificado para utilizar cartões já cadastrados anteriormente e possibilitar o gerenciamento dos cartões da conta.

Serviço Consumption

  1. Alteração do parâmetro do método PerformPayment com inclusão do campo PaymentData.NewCard.
  2. Alteração do parâmetro do método PerformPayment com inclusão do campo PaymentData.ExistingCard.
  3. Alteração do parâmetro do método PerformPayment com a remoção do campo PaymentData.CreditCard.
  4. Alteração do retorno do método LoadPayment com a inclusão do campo LoadPaymentResult.Cards.
  5. Incluído o código de erro RequiredCreditCard.

Serviço Account

  1. Criação do método LoadCards.
  2. Criação do método RemoveCard.
  3. Incluído o código de erro UnauthorizedCloudAccount.
  4. Incluído o código de erro HasAwaitingPayments.

1.0.6

04/01/2019

  1. O campo Code no retorno AccountResult passou a ser opcional, para suportar contas de consumo que estão ativas e que não possuem código vinculado. No momento em que uma conta de consumo é criada, ela sempre possui um código vinculado, porém existem operações no sistema, que podem remover o código da conta de consumo e a mesma continuar ativa.

1.0.7

07/02/2019

Foram realizadas modificações que tiveram o objetivo de retornar um código de erro mais claro ao cenário de pagar um cartão de consumo pós-pago com saldo zerado.

Serviço PerformPayment

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

1.0.8

12/30/2019

  1. Inclusão do serviço Title para visualização de sócios e cobranças de um título.

1.0.9

03/13/2020

Serviço Title

  1. Alterações do retorno do método GetMembers:
    • Incluído o campo MemberResult.Email
    • Incluído o campo MemberResult.Card
    • Incluído o campo MemberResult.Registers

1.0.10

06/10/2020

Serviço Consumption

  1. Adicionado o método Transfer para transferências de saldo entre contas de consumo
  2. Adicionado o método ReverseTransfer para reverter transferências de saldo entre contas de consumo

1.0.11

06/12/2020

Serviço Consumption

  1. Adicionado o método LoadVouchers para exibir as informações do voucher.
  2. Incluído novo código de erro InvalidProductVoucher

1.0.12

06/15/2020

Foram realizadas modificações para que a API liste automaticamente os cartões de consumo vinculados com o mesmo Documento (CPF/Outro) da conta do app. Foram incluídas as informações de hotelaria nos retornos da API de consumo.

Serviço Consumption

  1. Incluído o campo HotelReserve em AccountResult para exibir dados da reserva na API.

1.0.13

06/19/2020

Incluído o suporte à convênio e-commerce por Hotel. Método LoadPayment retorna as bandeiras de cartões aceitas no método.

Serviço Consumption

  1. Incluído o código de erro PaymentGatewayRulesConflict
  2. Alteração do retorno do método LoadPayment adicionado o campo LoadPaymentResult.EnabledCardTypes
  3. Alteração do parametro do método LoadPayment o campo AccountNumbers passa a ser obrigatório.
  4. Alteração do retorno do método LoadPayment adicionado o campo LoadPaymentResult.EnabledCardTypes

1.0.14

07/02/2020

Incluído o suporte à operações de convites.

Método GetInvitations retorna os convites disponíveis para a data selecionada. Método GetSales retorna os convites comprados, com seus detalhes e código. Método Sell realiza a venda de convites por cartão de crédito. Método CancelSale cancela uma compra de convites.

Serviço Invitations

1.0.15

03/08/2020

Serviço Consumption

  1. Alterações do retorno do método LoadVouchers:
    • Incluído o campo AccountVoucher.Description que retorna a descrição do produto contido no voucher.

1.0.16

17/09/2020

Serviço Consumption

  1. Alterações do retorno do método Refresh:
    • Incluído o campo CustomerType que retorna id e nome do tipo de cliente.

1.0.17

03/05/2021

Serviço Support

  1. Incluído o serviço Support

1.0.18

06/05/2021

Serviço RewardPoints

  1. Incluído o serviço RewardPoints

1.0.19

16/09/2021

Serviço Title

  1. Alterações do retorno do método GetMembers:
    • Incluído o campo MemberResult.ExamResults

1.0.20

16/09/2021

Serviço Title

  1. Alterações do retorno do método GetDuns:
    • Incluído o campo DunResult.DunType
    • Incluído o campo DunResult.TypeTypeableLine

1.0.21

12/08/2022

Serviço Parking

  1. Incluído o serviço Parking

1.0.22

05/10/2023

Serviço Disciplines

Incluído o serviço Disciplines.

Método GetAvailableClasses retorna os sócios e as turmas disponíveis para matrícula para um título. Método GetRegisters retorna os sócios de um título e suas respectivas matrículas. Método Register realiza a matrícula de um sócio em uma modalidade. Método Unregister desfaz a matrícula de um sócio em uma modalidade.

1.0.23

23/11/2023

Serviço Invitations

Incluído o serviço Invitations.

Propriedade VoucherId de SoldResult renomeada para SaleId.

1.0.24

29/11/2023

Serviço Invitations

  1. Alterações do método Sell:
    • Incluído o campo de retorno PlanResult.AvailableDates.
    • Incluído o campo de retorno InvitationResult.MapId.
  2. Alterações do método GetInvitations:
    • Incluído o campo de retorno SellResult.Success.
    • Incluído o campo de retorno SellResult.NotAvailableMapLocations.
    • Alterado o campo de retorno SellResult.SaleId.
  3. Alterações do método GetSales:
    • Alterado parâmetro SoldData para SalesData.
    • Alterado parâmetro SoldResult para SaleResult.
    • Alterado retorno SoldtemResult para SaletemResult.
    • Incluído o campo de retorno SaletemResult.MapLocation. 4 Removido o campo InvitationsData.VisitDate.
  4. Incluído o código de erro MapNotFound.
  5. Incluído o código de erro MapLocationNotFound.
  6. Incluído o código de erro MapLocationInvalidInvitationQuantity.
  7. Incluído o código de erro IntegrationNotEnabled.
  8. Incluído o código de erro TefCancelFailed.
  9. Adicionado o método GetAvailableQuantity para retornar a quantidade disponível do convite para uma determinada data.
  10. Adicionado o método GetMapLocations para retornar os locais disponíveis de um mapa para uma determinada data.

1.0.25

06/12/2023

Serviço Disciplines

Incluída propriedade ProportionalMaintenanceTax no objeto AvailableClassResult.

1.0.26

21/12/2023

Serviço Invitations

Renomeado objeto SaletemResult para SaleItemResult.

1.0.28

11/01/2024

Serviço Disciplines

Adicionado o método GetParcels para retornar as informações de parcelamento do pagamento da matrícula.

1.0.29

29/01/2024

Serviço Invitations

Adicionado método GetInvitationParcels que retorna as possibilidades de parcelamento de convite

  1. Alteração no método Sell
    • Incluído o código de erro SalePlanPaymentNotConfigured,
    • Incluído o código de erro OneMoreSalePlan
    • Incluído o código de erro InvalidParcelQuantity
    • Incluído o código de erro InvalidValueOfParcel

1.0.30

29/01/2024

Serviço Invitations

  1. Alterações do retorno do método GetSales:
    • Incluída propriedade Description no objeto SaleItemResult.

1.0.31

29/01/2024

Serviço Invitations

  1. Alterações do retorno do método GetSales:
    • Incluída propriedade PlanId no objeto SaleItemResult.

1.0.32

30/01/2024

Serviço Disciplines

  1. Adicionado método GetContract, que permite emitir o contrato de matrícula ou de cancelamento de um sócio

  2. Alterações do retorno do método Register:

    • Incluída propriedade RegisterTaxesResult no objeto RegisterResult, que retorna informações de taxas da matrícula efetuada

    • Incluído o código de erro OneMoreSalePlan,

    • Incluído o código de erro InvalidParcelQuantity,
    • Incluído o código de erro InvalidValueOfParcel.

1.0.33

05/02/2024

Serviço Invitations

Adicionado objeto AvailableQuantityResult que retorna a quantidade disponível para a capacidade de venda do título e a capacidade do mapa.

1.0.34

05/02/2024

Serviço Disciplines

Adicionado objeto RegisterProduct que retorna as informações de parcelas geradas e pagas com a operação de matrícula. Objeto RegisterProduct adicionado dentro do ClassRegisterResult para que seja retornado no método GetRegisters().