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 é REST sobre HTTPS com formatação JSON e 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 UTF-8.

Todos os serviços podem ser acessados ao incluir a rota logo após o endereço base do serviço. Por exemplo:

  • Endereço base para o serviço de autenticação: http://127.0.0.1/MultiClubes/Services/Extensions/App/Rest/Account/v1.svc.
  • Rota para serviço de autenticação: /login.
  • Endereço completo para a requisição: http://127.0.0.1/MultiClubes/Services/Extensions/App/Rest/Account/v1.svc/login.

O mesmo se aplica caso uma rota alternativa esteja configurada para o serviço. Por exemplo:

  • Endereço base para o serviço de autenticação: http://exemplo.multiclubes.com/Account.
  • Rota para serviço de autenticação: /login.
  • Endereço completo para a requisição: http://exemplo.multiclubes.com/Account/login.

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 adicionando um cabeçalho de nome _AuthenticationKey à requisição.

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.

Mensagens de erro

Falhas e erros nas requisições serão sempre reportadas por meio de uma resposta com o código de status HTTP 500 Internal Server Error e com o corpo preenchido da seguinte forma:

{
    "Code": "AM7XOODN", //Código de referência do erro no serviço
    "Message": "Não é possível localizar a conta de consumo." //Mensagem de erro
}

Como começar

  1. Obtenha o endereço do serviço de homologação.
  2. Verifique a documentação dos endpoints na descrição dos serviços
  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

1.0.0

21/01/2025

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

1.0.1

11/02/2025

Modificação nos modelos de contrato para que todos os campos que informam a bandeira do cartão usem o novo tipo TefCardType.

A alteração foi realizada para que a documentação seja devidamente apresentada. Apesar da alteração, os valores usados se mantiveram.

Serviço Account

  1. Alteração do retorno do método LoadCards, alterando o tipo do campo LoadCardResult.CardType nos elementos.

Serviço Consumption

  1. Alteração do retorno do método LoadPayment, alterando o tipo do campo LoadPaymentResult.EnabledCardTypes.
  2. Alteração do retorno do método LoadPayment, alterando o tipo da propriedade CardType nos elementos do campo LoadPaymentResult.Cards.
  3. Alteração do parâmetro do método LoadAcquirerAuthentication, alterando o tipo da propriedade CardType no campo LoadAcquirerAuthenticationData.NewCard.
  4. Alteração do parâmetro do método PerformPayment, alterando o tipo da propriedade CardType no campo PerformPaymentData.NewCard.
  5. Alteração do parâmetro do método PerformRecharge, alterando o tipo da propriedade CardType no campo PerformRechargeData.NewCard.
  6. Incluído o código de erro InvalidCardTypeConversion.

Serviço Disciplines

  1. Alteração do parâmetro do método Register, alterando o tipo da propriedade CardType no campo RegisterData.Payment.NewCard.

Serviço Invitations

  1. Alteração do parâmetro do método Sell, alterando o tipo da propriedade CardType no campo SellData.Payment.NewCard.

Serviço Title

  1. Alteração do parâmetro do método PayDuns, alterando o tipo da propriedade CardType no campo PerformPaymentData.NewCard.

1.0.2

21/02/2025

Serviço Consumption

  1. Incluída a propriedade CanStoreCard no objeto LoadPaymentResult do método LoadPayment o qual informa se os dados do cartão podem ser salvos para transações posteriores.

1.0.3

21/02/2025

Serviço Consumption

  1. Incluída a propriedade AcquirerAuthenticationProvider no objeto LoadPaymentResult do método LoadPayment, o qual informa o provedor de autenticação do adquirente.

1.0.4

27/02/2025

Serviço Consumption

  1. Alterado o retorno do método LoadPayment para que ele não retorne a lista de cartões quando a operação possuir autenticação 3DS.

1.0.5

05/03/2025

Serviço Account

  1. Adicionado novo método LoginToken que permite a autenticação do usuário através do token gerado pelo método GenerateToken.

1.0.6

10/03/2025

Criação de nova seção para documentar o fluxo de pagamento PIX na API de consumo.

Serviço Consumption

  1. Adicionado o método CreatePixPayment para criação de código de pagamento PIX do cartão de consumo.
  2. Adicionado o método CreatePixRecharge para criação de código de recarga PIX do cartão de consumo.
  3. Adicionado o método AbortPix para cancelar transação PIX criada para pagamento ou recarga do cartão de consumo.
  4. Adicionado o método ConfirmPixPayment para confirmação de pagamento PIX do cartão de consumo.
  5. Adicionado o método ConfirmPixRecharge para confirmação de recarga PIX do cartão de consumo.
  6. Adicionado novo método LoginToken que permite a autenticação do usuário através do token gerado pelo método GenerateToken.
  7. Alterado o retorno do método LoadPayment para que ele não retorne a lista de cartões quando a operação possuir autenticação 3DS.

1.0.7

10/03/2025

Serviço Exams

  1. Inclusão do novo serviço de exames.
  2. Criado novo método LoadIntervals que retorna os horários de exames disponíveis para agendamento.

1.0.7

14/03/2025

Serviço Exams

  1. Criado novo método Schedule que efetiva o agendamento do exame.

1.0.8

17/03/2025

Serviço Exams

  1. Criado novo método Load que lista os agendamentos de exames ativos do título, os tipos de exames disponíveis para agendamento, sócios que podem realizar o agendamento e informações sobre as formas de pagamento.

1.0.9

18/03/2025

Serviço Address

  1. Inclusão do novo serviço de endereços.
  2. Criado novo método Search que retorna as informações de um endereço através de seu CEP (Código de Endereçamento Postal).

1.0.10

18/12/2025

Serviço Consumption

  1. Incluída a propriedade MovementUID no objeto MovementResult do método LoadMovements o qual informa o identificador único do movimento.

1.0.11

15/01/2026

Serviço Facilities

  1. Inclusão do novo serviço de espaços.
  2. Criado novo método Load que retorna os espaços existentes, a regras de locação e consulta e as locações do título.
  3. Criado novo método CheckAvailability que retorna os espaços e as datas em que ele estará alugado.
  4. Criado novo método Rent que realiza locações de espaços.
  5. Criado novo método GetFacilityRentContract que retorna o contrato de locação.