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 é 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/Retail/Rest/VendingMachine/v1.svc.
  • Rota para serviço de autenticação: /getBalance.
  • Endereço completo para a requisição: http://127.0.0.1/MultiClubes/Services/Extensions/Retail/Rest/VendingMachine/v1.svc/getBalance.

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/VendingMachine.
  • Rota para serviço de autenticação: /getBalance.
  • Endereço completo para a requisição: http://exemplo.multiclubes.com/VendingMachine/getBalance.

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

  • 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.
  • Consulta o saldo de uma conta de consumo.
  • Realiza uma venda.
  • Cancela e estorna a venda previamente realizada

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

10/10/2024

  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

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.3

30/04/2024

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

1.0.4

03/05/2024

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

1.0.5

17/01/2025

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

1.0.6

19/08/2025

1.0.7

19/08/2025

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

1.0.8

22/09/2025

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