Versão: 2.0

Finalidade

A solução de CBM Mercafácil entrega um sistema para o gerenciamento de comportamento dos consumidores ao varejista e, para tanto, necessita do PDV as seguintes funcionalidades:

1. Na implantação do cliente (Mercadista):

   1. carga completa de produtos;

   2. carga completa de operadores do pdv;

   3. carga histórica de vendas;

2. Durante a compra e disponibilização de ofertas, o PDV deverá:

   1. Antes da venda identificar o cliente para verificar se faz parte do clube de vantagens;

   2. Durante a venda aplicar as ofertas disponibilizadas pelo sistema da Mercafácil ao cliente identificado e não identificado;

   3. Na finalização da venda quais ofertas foram utilizadas na venda para a Mercafácil;

   4. Enviar os dados da venda;

3. Ter rotinas agendada para enviar:

   1. Vendas canceladas;

   2. Atualizações dos produtos e operadores;

   3. Envios pendentes (vendas, vendas canceladas e ofertas utilizadas).

4. Além disso o sistema deverá permitir ao cliente ou suporte da empresa:

   1. Alterar campos de configurações da Integração

   2. Ativar a execução de uma rotina agendada

   3. Salvar logs das requisições e respostas

Funcionalidades e Métodos

As funcionalidades mencionadas são entregues ao varejista por meio da integração entre o PDV e sistema da Mercafácil via API REST.

A seguir são detalhados os métodos em acordo com a lista de funcionalidade mostrada anteriormente.

==Documentação API: ==https://discounts-beta.mercafacil.com/api/docs/

usuário: mercafacil

senha: bp45yTHvhRHujm52E

1.Autenticação

A autenticação da API de integração é feita através de um token que é enviado no cabeçalho da requisição. Conforme exemplo abaixo:

Authorization: Bearer <token>

O token identifica qual cliente e loja estão autorizados a utilizar a API. O token não tem um tamanho específico e pode variar de cliente para cliente. Portanto ao salvá-lo em um banco de dados, utilizar um tipo sem restrição de tamanho ou reservar no mínimo 500 caracteres. Cada cliente receberá um token por loja.

1.1 Versão do PDV

Enviar a versão do sistema integrador (PDV) no header em todas as requisições:

pdv-version: <versão>

2.Cargas (Implantação)

É necessário desenvolver uma rotina no PDV, onde diariamente seja enviado os seguintes dados:

Rotas das APIS:

• 2.a POST - /v2/products

  • A carga deve possuir modificações e novos produtos . O envio é feito em lote e o tamanho da requisição não pode exceder 25Mb.

• 2.b POST - /v2/operators

  • Os únicos campos obrigatórios são ID e NOME, os demais podem ser enviados vazio (““).

• 2.c POST /v2/coupons-list

  • O envio é feito em lote e o tamanho da requisição não pode exceder 25Mb.

3.Ofertas

3.a Identificação de Clientes

• A identificação do cliente será realizada para que o sistema integrado possa verificar se o cliente possui cadastro no clube de vantagens

  • Identificação podendo ser CPF ou CNPJ

• Rota: POST - v2/transaction/start

• A rota retorna se o cliente faz parte ou não do clube.

• O campo booleano “loyalty” é true quando o cliente faz parte do clube.

• O nome é retornado no campo name e poderá ser mostrado na tela do PDV.

• Caso seja retornado algum objeto no campo message, iniciar o fluxo de mensagem apresentado no Anexo 1.

3.b Consultar descontos aplicáveis

• Rota: POST v2/transaction/apply

• Todos os items registrados no pdv devem ser enviados

• Os valores com desconto devem ser enviados caso existam outras ofertas

• Enviar o valor com 3 casas decimais para produtos pesáveis

• packing_quantity: Quantidade do produto na embalagem (por exemplo pack de 12 unidades);

Ps.: Esse endpoint deverá ser consultado também por clientes que não fazem parte do clube, nesse caso enviar o campo client_id = “0”

3.c Confirmação das ofertas aplicadas

• O método de confirmação de ofertas aplicadas na venda deverá ser utilizado para que o PDV envie a confirmação de qual promoção foi aplicada na venda.

• Rota: POST - v2/transaction/confirm

3.d Cancelamento da Operação (transaction)

• O método de cancelamento da operação, deve ser chamado caso a pessoa desista da compra, não termine ela no PDV, ou cancele algum produto dentro da compra.

• Rota: POST - v2/transaction/cancel

3.e Envio da Venda

• Todos os cupons sejam identificados ou não, deverão ser transmitidos para a API. Os cupons podem ser enviados um por vez:

• Rota: POST - /v2/coupons/

• Os id dos cupons precisam ser únicos. Exemplo:

  • Concatenar as informações de LOJA+DATA+HORA+OPERADOR+PDV+ID_CUPOM;

  • Utilizar UUID (Identificador único universal).

  • packing_quantity : Quantidade do produto na embalagem (por exemplo pack de 12 unidades);

4. Rotinas Agendadas

4.a Cancelamento de venda

• Todos os cupons cancelados após a transmissão para API deverão ser cancelados utilizando-se a rota da API: POST - /v2/coupons-cancellation/

4.b Atualizações Produtos e Operadores

• Atualizar os produtos e operadores de maneira incremental, uma ou mais vezes ao dia, utilizando as mesmas rotas apresentadas nos itens 2.a e 2.b, isto é, após a implantação é necessário somente os envios dos novos produtos/operadores ou atualizações cadastrais de produtos/operadores.

4.c Envios Pendentes

• Os envios pendentes de vendas, cancelamentos e informações de vendas devem ser enviados assim que a conexão for restabelecida e/ou serem guardados para reenvio ao final do dia.

Processo de Desenvolvimento

Homologação

O processo de homologação da integração é dividido em quatro etapas, sendo elas:

1. IMPLANTAÇÃO / ENVIOS DE ROTINA

   1. Envio manual de implantação:

      1. Envio de produtos

      2. Envio de operadores de caixa

      3. Envio do histórico de vendas (6 meses)

      4. Envio de vendas com forma de pagamento.

   2. Rotinas Agendadas

      1. Reenvio de produtos ao atualizar/adicionar

      2. Reenvio de operadores ao atualizar/adicionar

   3. Configurações

      1. URL base da api customizável: Exemplo: https://discounts-beta.mercafacil.com/api/ (homologação)

      2. Verificar tamanho do token (minimo 500 char)

      3. Validar se a base é unificada em multiloja

2. OFERTAS / contingência

   1. Validar disponibilização de descontos gerais do clube

   2. Validar disponibilização de descontos personalizados

   3. Validar disponibilização de desconto absoluto

   4. Confirmação de Vendas

   5. Validar envio de cupons

      1. Verificar client_id para clientes dentro e fora do clube

      2. Campo cupom é único?

      3. Validar o total_value_with_discounts com produtos fora e dentro do clube

      4. Testar com produtos pesáveis

      5. Produtos sem desconto

   6. Validar valores de desconto enviados nos cupons

3. Roteiro de teste para novos tipos de ofertas (percentage, takepay e combo)

• Cadastrar uma oferta do tipo ‘percentage’, com o mínimo 2 e o máximo 4 e testar:

  • Um apply com 2 produtos(tanto com os 2 juntos como com eles separados) para confirmar que o desconto foi aplicado;

  • Um apply com a quantidade menor que o mínimo;

  • Um apply com a quantidade maior que o máximo;

  • Cadastrar uma segunda oferta para o mesmo produto e verificar se a com maior desconto será aplicada;

  • Finalizar uma sale com o produto para testar o confirmSales;

  • Realizar um novo apply para testar se o limite máximo vai levar em conta o que já foi utilizado;

• Cadastrar uma oferta do tipo = ‘takepay’, take = 3, pay = 2, maximum_per_client = 2 e testar

• Cadastrar uma oferta do tipo = ‘takepay’, take = 4, pay = 2, maximum_per_client = 2 e testar

  • Um apply com 3 produtos(com os 3 juntos e também com os 3 separados) para confirmar que o desconto foi aplicado;

  • Um apply com a quantidade menor que o mínimo por grupo (2);

  • Um apply com a quantidade maior que o máximo de grupos (9);

  • Cadastrar uma segunda oferta para o mesmo produto e verificar se a com maior desconto será aplicada;

  • Finalizar uma sale com o produto para testar o confirmSales;

  • Realizar um novo apply para testar se o limite máximo de grupos vai levar em conta o que já foi utilizado;

• Cadastrar uma oferta do tipo ‘combo’ com dois trigger_products com o quantity = 3 cada um, um target_product com percentage_discount = 10, na sale o maximum_per_client = 2:

  • Um apply com 3 produtos de um dos triggers e 1 do target para validar o desconto aplicado;

  • Um apply sem a quantidade nencessária em nenhum dos triggers para validar a quantidade minima por grupo;

  • Um apply com 9 itens de um dos triggers para testar o maximo de grupos por cliente;

  • Um apply com 2 itens de um trigger e 1 de outro, para validar que os descontos não serão aplicados dessa forma;

  • Um apply 6 itens em algum dos triggers porém apenas 1 produto do target;

  • Realizar um novo apply para testar se o limite máximo vai levar em conta o que já foi utilizado;

  • Finalizar uma sale com o produto para testar o confirmSales;

  • Realizar um novo apply para testar se o limite máximo de grupos vai levar em conta o que já foi utilizado;

4. Cliente piloto

   Esta etapa tem como objetivo validar a integração em produção, em um cliente antes de disponibilizar para os demais visando qualidade no serviço. É importante que o cliente seja treinado para operar no PDV e o time de integrações precisa estar ciente de todas as exceções e limitações do sistema.

   1. Validações:

      1. Aplicação de desconto para clientes clube nos produtos cadastrados na plataforma Mercafacil.

      2. Faturamento (cupons enviados) estão de acordo com relatórios que o cliente acompanha no sistema ERP.

Fluxo de homologação

Fluxo Validação PDV V2

Anexo 1. Fluxo de Mensagem

Objetivo

Criar um canal de comunicação com o cliente por meio do PDV.

Motivadores:

• Pré-cadastro

• Avisar sobre benefícios disponíveis (e.g Cartões pré-aprovados, divulgar app)

• Dar tratamento especial ao cliente (e.g. Parabéns no dia do aniversário)

Fluxo

1. No início da transação com o pdv (transaction/start) é enviado todo o roteiro de mensagens que será realizado após a identificação do cliente

2. Após o fluxo de mensagens terminar as respostas devem ser enviadas via rota (transaction/message)

Exemplos

Pré-cadastro

Fluxo de mensagens para quando o cliente não faz parte do clube.

O Esboço das tela abaixo representa a primeira interação que será apresentada após verificação do cadastro. Caso seja escolhido sim, é apresentada a segunda tela abaixo. Caso seja escolhido não, nada é apresentado e o fluxo de compra segue normalmente.

O retorno da rota transaction/start para esse caso:

{
  "loyalty": false,
  "user": {"document_no": "12345678901"},
  "transaction_id": "79a8bc0a-e8b8-41b2-ba86-91b9763f5d75",
  "message": {
    "text": "Cadastro não encontado. Realizar pré-cadastro?.",
    "responses": [
      {
        "button": "Sim",
        "tag": "aceitou-pre-cadastro",
        "text_next_window": "Digite celular com DDD",
        "input_next_window": true,
      },
      {
        "button": "Nao"
        "tag": "nao-aceitou-pre-cadastro",
        "text_next_window": "",     // sem próxima janela
        "input_next_window": false, // sem entrada de texto
      }
    ]
  },
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "datetime": "2021-02-24 12:36:37"
}

Modelo de resposta que deve ser enviado para a rota (transaction/message) no caso do cliente escolher efetuar o pré-cadastro:

{
  "transaction_id": "79a8bc0a-e8b8-41b2-ba86-91b9763f5d75",
  "document_no": "12345678901",
  "message_tag": "aceitou-pre-cadastro",
  "input_value": "41987762038",
}

Modelo de resposta que deve ser enviado para a rota (transaction/message) no caso do cliente escolher não efetuar o pré-cadastro:

{
  "transaction_id": "79a8bc0a-e8b8-41b2-ba86-91b9763f5d75",
  "document_no": "12345678901",
  "message_tag": "nao-aceitou-pre-cadastro",
}

Exemplo de mensagens genéricas

Cartão pré aprovado.

Fluxo de mensagens para quando o cliente faz parte do clube e tem um cartão de crédito pré-aprovado.

O Esboço das tela abaixo mostra a primeira tela que deverá ser apresentada após verificação do cadastro. Caso seja escolhido sim, é apresentada a tela abaixo. Caso seja escolhido não, nada é apresentado e o fluxo de compra segue normalmente.

{
  "loyalty": true,
  "user": {"name": "Larissa", "document_no": "12345678910", "birth_date": "2011-10-01"},
  "transaction_id": "79a8bc0a-e8b8-41b2-ba86-91b9763f5d75",
  "message": {
    "text": "Tem crédito pré-aprovado! Quer pedir seu cartão agora?",
    "responses": [
      {
        "button": "Sim",
        "tag": "aceitou",
        "text_next_window": "Leia o QRcode e peça seu cartão já!",
        "qr_code_next_window": {
          "url": "http://qrcodes.com/qrcode2.png"
        },
        "button": "Nao"
        "tag": "nao-aceitou",
      }
    ]
  },
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "datetime": "2021-02-24 12:36:37"
}

Modelo de resposta que deve ser enviado para a rota (transaction/message) no caso do cliente escolher pedir o cartão.

{
  "transaction_id": "79a8bc0a-e8b8-41b2-ba86-91b9763f5d75",
  "document_no": "12345678901",
  "message_tag": "aceitou",
}

Modelo de resposta que deve ser enviado para a rota (transaction/message) no caso do cliente escolher não pedir o cartão.

{
  "transaction_id": "79a8bc0a-e8b8-41b2-ba86-91b9763f5d75",
  "document_no": "12345678901",
  "message_tag": "nao-aceitou",
}

APP

Fluxo de mensagens para quando é enviada uma notificação ao cliente.

Exemplo de retorno da rota (transaction/start) para o caso acima.

{
  "loyalty": true,
  "user": {"name": "Larissa", "document_no": "12345678910", "birth_date": "2011-10-01"},
  "transaction_id": "79a8bc0a-e8b8-41b2-ba86-91b9763f5d75",
  "message": {
    "text": "Aproveite ofertas exclusivas! Leia o QRcode e baixe nosso APP!",
    "qr_code_next_window": {
          "url": "http://qrcodes.com/qrcode2.png"
        },
    "responses": []
  },
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "datetime": "2021-02-24 12:36:37"
}

Nesse caso não é necessário enviar nada na rota (transaction/message).