MultiClubes Retail VendingMachine API

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 compoem a API.

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

  • Operação de consumo: é o registro de itens consumidos em uma conta de consumo.
  • Conta de consumo: é onde os consumos são registrados e deduzidos dos créditos disponíveis. Existem as modalidades de crédito "pós-pago" ou "pré-pago".
  • Crédito disponível: é o valor total que uma conta de consumo dispõe para consumir no momento.
  • Cartão de consumo ou pulseira: é o meio físico (um cartão ou pulseira) que representa a conta de consumo. Pode ter seu código armazenado em uma tag NFC, tarja magnética, código de barras, etc.
  • Ponto de venda: é o equipamento onde consumo é registrado.

Funcionamento

  • Registra a operação de consumo deduzindo dos créditos disponíveis na conta de consumo.
  • Estorna a operação de consumo previamente registrada.

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

1.0.0

11/12/2018

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

1.0.1

21/01/2019

  1. Redefinição da API de forma mais simplificada para operações com VendingMachines.

1.0.2

14/08/2020

  1. Inclusão do campo PrintOrderTicketNumber para retorno do número do pedido impresso.

1.0.3

28/03/2023

  1. Adicionado o campo ConsumptionAccount ao BalanceResult para retorno do número da conta de consumo.
  2. Adicionado o campo Document ao BalanceResult para retorno do documento do cliente da conta de consumo.
  3. Adicionado o campo Email ao BalanceResult para retorno do e-mail do cliente da conta de consumo.
  4. Adicionado o campo Phone ao BalanceResult para retorno do telefone do cliente da conta de consumo.

1.0.4

30/04/2024

  1. Adicionado o campo Comments ao ConsumptionItemData para cadastrar um comentário no item.

1.0.5

03/05/2024

  1. Criado o novo método PerformSale para realizar vendas pela API utilizando TEF.

1.0.6

17/01/2025

  1. Criado o novo tipo Pix no PaymentType para realizar vendas pela API com a forma de pagamento Pix.

1.0.7

19/08/2025

  1. Criado o novo método SearchAccounts para realizar busca de contas de consumo ativas pela API.

22/09/2025

1.0.8

  1. Adicionado o campo DeliveryLocation ao ConsumptionData para cadastrar um endereço de entrega ao pedido.