Você está vendo a versão antiga da página. Ver a versão atual.

Comparar com o atual Ver Histórico da Página

« Anterior Versão 4 Atual »

Sumário


1 Conceito

Disponibilizada no AutoSystem a funcionalidade que aplica no PDV os descontos em vendas que utilizam vouchers de descontos emitidos por plataforma própria da rede de postos, desde que a comunicação siga o padrão abaixo especificado. Com isso, o estabelecimento que possui alguma plataforma própria para emissão de vouchers de desconto pode integrar esta plataforma ao PDV AutoSystem.


2 Requisitos

Para utilizar esta integração, são necessários alguns requisitos:

  • A versão exigida é a 3.2.6.106 ou 3.3.1.36 (AutoSystem) ou superior;

  • Ter o módulo App do Consumidor liberado na Intranet;

  • Ter um ambiente que atenda a documentação abaixo.

3 Configurando a Integração

No módulo Gerencial, acessar o menu Configurações > Módulos > Integração APP do Consumidor e habilitar a opção Ativar integração App do Consumidor.



No campo URL de comunicação informar o endereço do servidor webservice do cliente. No campo Token App do Posto informar o token de acesso para a autenticação do sistema ao ambiente webservice.

Na guia para Configurar Produtos devem ser informados os produtos que estão cadastrados na plataforma de descontos do estabelecimento e que permitem o uso de voucher:



A imagem da logo que aparece no PDV do AutoSystem poderá ser customizada na solicitação do voucher. Para utilizar uma imagem própria a mesma deve estar salva na pasta C:\autosystem\share\images\icones\logo_app_posto.png, com esta mesma nomenclatura.


4 Fluxo de Integração

O fluxo de integração deve ser realizado da seguinte forma:

  1. O frentista/operador inicia a venda inserindo os itens da venda. O voucher poderá ser solicitado antes de inserir os itens ou depois, conforme configuração;
  2. O operador solicita o código do voucher gerado no app ao cliente que possui o aplicativo;
  3. O cliente informa o código ao frentista/operador e insere esse código no sistema AutoSystem;
  4. Após inserir esse código o sistema envia a requisição Validar Código;
  5. Nesta requisição o código será validado e retornado os valores de desconto concedidos, podendo o desconto ser zerado e mesmo assim considerado como uma venda;
  6. O frentista/operador visualiza o novo valor a ser cobrado do cliente no PDV AutoSystem;
  7. O cliente realiza o pagamento e a venda é finalizada com sucesso;
  8. Após a venda finalizada o sistema envia através do método Pós Venda a confirmação de que o voucher foi utilizado na venda.


5 API's da Integração


5.1 Lista de Validação de Código

O método de validação verifica se o código informado é válido e também recebe array de objeto com os dados do produto para conceder o desconto (caso o código seja válido). O desconto também poderá ser zero e, assim sendo, deverá ser considerado como uma venda pelo sistema do aplicativo. Abaixo, um exemplo de requisição para validação de código:


Requisição: POST /api/v1/integracao/validarcodigo/lista
[ 
   { 
      "codigoColaborador"   :0 ,
       "emailColaborador":"[email protected]",
      "nomeColaborador":"Nome Sobrenome",
      "senhaColaborador":"123456",
      "codigoValidacao":"AAAA",
      "valorVenda":10.00,
      "quantidade":2.55,
      "codigoEmpresa" :"12345678900010",
      "tokenIntegracao":"698dc19d489c4e4db73e28a713eab07b",
      "identificadorExternoProduto" : "123456",
      "dataVenda":"31/12/2020",
      "horaVenda" :"12:35:59",
      "identificadorExternoFormaPagamento":"1",
      "descricaoFormaPagamento":"Crédito",
      "parametroOpcional": "1",
      "contigencia":false,
      "valorPorUnidadeDesconto": 0.10,
      "valorDescontoTotal": 0.15,
      "regraInterna": false,
   },
   { 
      "codigoColaborador"   :0,
              "emailColaborador":"[email protected]",
      "nomeColaborador":"Nome Sobrenome",
      "senhaColaborador":"123456",
      "codigoValidacao": "AAAA",
      "valorVenda"     :15.00,
      "quantidade":5,
      "codigoEmpresa" :"12345678900010",
      "tokenIntegracao":"698dc19d489c4e4db73e28a713eab07b",
      "identificadorExternoProduto"           : "123456790",
      "dataVenda":"31/12/2020",
      "horaVenda":"12:35:59",
      "identificadorExternoFormaPagamento": "1",
      "descricaoFormaPagamento":"Crédito",
      "parametroOpcional": "1",
      "contigencia":false,
      "valorPorUnidadeDesconto": 0.05,
      "valorDescontoTotal": 0.15,
      "regraInterna": false
   }
]


Sendo:

Nome Campo

Tipo

Descrição

Obrigatório?

codigoColaborador

number

Código ou Identificador do colaborador.

Sim

emailColaborador

string

E-mail do colaborador que realizou a venda.

Não

nomeColaborador

string

Nome do Colaborador que realizou a venda.

Sim

senhaColaborador

string

Senha do Colaborador que realizou a venda.

Não

codigoValidacao

string

Código de validação informado pelo cliente ou Código do Cartão do Cliente

Sim

valorVenda

number

Valor Total da Venda.

Sim

quantidade

number

Quantidade do produto vendido.

Sim

codigoEmpresa

string

CNPJ ou Identificador da empresa/posto que está realizando a venda. Enviar sem formatação, somente números.

Sim

tokenIntegracao

string

Token identificador da aplicação. Este token é gerado pelo cliente e deve ser informado no sistema.

Sim 


identificadorExterno

Produto

string

Identificador externo do produto. Pode ser uma chave ou um identificador da tabela de produtos.

Sim

dataVenda

string

Data da Venda no formato
(dd/mm/aaaa)

Sim

horaVenda

string

Hora da Venda no formato
(hh:mm:ss)

Sim

identificadorExterno

FormaPagamento

string

Identificador externo (ou ID) da forma de pagamento. Pode ser uma chave ou um identificador da tabela de forma de pagamento.

Não

descricaoFormaPagamento

string

Descrição da forma de pagamento.

Não

parametroOpcional

string

Parâmetro opcional para realizar algum controle pelo sistema integrador. Deve ser enviado o mesmo conteúdo recebido na requisição.

Sim

contingencia

boolean

Campo para envio de informações em caso de o software integrador estiver operando off-line.

Sim

valorPorUnidadeDesconto

number

Utilizado somente na Contingência ou quando há Regra Interna. Valor com desconto por uma unidade do produto. Este é o mesmo valor do produto menos o desconto. Ou seja, seria o valor líquido por unidade do produto.

Não (Obrigatório para Regra Interna ou Contingência)

valorDescontoTotal

number

Utilizado somente na Contingência ou quando há Regra Interna. Valor total do desconto. O valor de desconto total poderá ser zero. Este é o valor de desconto total. Ou seja, se tiver dando um desconto de 10 centavos e passou duas quantidades, será 20 centavos neste campo.

Não (Obrigatório para Regra Interna ou Contingência)

regraInterna

boolean

Utilizado para dizer para o sistema que está sendo utilizado uma regra de desconto interna.

Não


Ao solicitar a requisição e de todas as validações aceitas, o sistema retornará o valor de desconto da venda e o valor de desconto do produto. Conforme o exemplo abaixo. 
O campo chaveAutenticacao é o mesmo para todos da lista, pois se trata da mesma venda. 


Exemplo de resposta
[
  {
    "codigoValidacao": "AAAA",
    "valorPorUnidade": 3.921569,
    "valorPorUnidadeDesconto"    : 3.80,
    "valorDescontoTotal": 9.69,
    "valorVendaTotal": 10.00,
    "quantidade": 2.55,
    "nomeCliente"     : "Cliente Nome",
    "chaveAutenticacao":
"a4a9b741d5f0fe61e49d473bd6e7b641d47d2d8411eb051ce677e7d75781fd1c6789 c820f975f9248c2506542957fa371a441dcb4236c42c9ba39326fcee42e8",
    "placa": "AB1CDE2",
    "cpf": "12345678901",
    "isAceitaCPF": false,
    "isEmiteDocumentoFiscal": true,
    "parametroOpcional": "2",
    "identificadorExternoProduto": "123456789",
    "tipoCodigo": "DESCONTO",
    "formaPagamento": "CREDITO_PARCELADO",
    "quantidadeParcela": 2,
  },
  {
    "codigoValidacao": "AAAA",
    "valorPorUnidade": 3.000,
    "valorPorUnidadeDesconto": 2.900,
    "valorDescontoTotal": 14.50,
    "valorVendaTotal": 15.00,
    "quantidade": 5,
    "nomeCliente": "Cliente Nome",
    "chaveAutenticacao":
"a4a9b741d5f0fe61e49d473bd6e7b641d47d2d8411eb051ce677e7d75781fd1c6789 c820f975f9248c2506542957fa371a441dcb4236c42c9ba39326fcee42e8",
    "placa": "AB1CDE2",
    "cpf": "12345678901",
    "isAceitaCPF": false,
    "isEmiteDocumentoFiscal": true,
    "parametroOpcional": "2",
    "identificadorExternoProduto": "123456789",
    "tipoCodigo": "DESCONTO",
    "formaPagamento": "CREDITO_PARCELADO",
    "quantidadeParcela": 2,
  }
]


Sendo:

Nome Campo

Tipo

Descrição

codigoValidacao

string

Código de validação enviado.

valorPorUnidade

number

Valor normal por uma unidade do produto.

valorPorUnidadeDesconto

number

Valor com desconto por uma unidade do produto.

valorDescontoTotal

number

Valor total do desconto. O valor de desconto total poderá ser zero.

valorVendaTotal

number

Valor total da venda sem desconto.

quantidade

number

Quantidade do produto vendido.

nomeCliente

string

Nome do Cliente da Venda.

chaveAutenticacao

string

Chave de autenticação utilizada no posvenda para identificar a venda. Essa chave é utilizada para identificar a venda realizada. Como se fosse um token da venda.

placa

string

Placa no formato 7 letras.

cpf

string

CPF do Usuário.

isAceitaCPF

boolean

Se “true” significa que o usuário aceita o CPF na nota, se “false” usuário não aceita CPF na nota.


isEmiteDocumentoFiscal

boolean

Se “true” significa que o usuário deseja que a nota fiscal, se “false” o usuário não deseja a nota.

parametroOpcional

string

Parâmetro opcional para realizar algum controle pelo sistema integrador.

identificadorExternoProduto

string

Identificador externo do produto. Pode ser uma chave ou um identificador da tabela de produtos.

tipoCodigo

string

Tipo de Código validado podendo ser “DESCONTO” para códigos de desconto, “PONTUACAO” para códigos de pontuação,

“DESCONTO_PONTUACAO” para códigos que dão descontos e pontos ao mesmo tempo, “CASHBACK” para códigos de cashback e “RESGATE” para código de resgate de produtos.

formaPagamento

string

Informa o tipo de pagamento que o usuário irá selecionar. CREDITO_VISTA, CREDITO_PARCELADO, DEBITO, DINHEIRO.

quantidadeParcela

number

Quantidade parcela, caso o formaPagamento for CREDITO_PARCELADO este campo virá com a quantidade parcela.


Se ocorrer algum problema de validação, o retorno do webservice será sempre código 400. Caso ocorra o erro 500, se trata de um erro no servidor que não foi tratado no sistema.

Segue abaixo a lista de mensagens possíveis para o método de validar código:


Mensagem

Descrição

Token inválido


Quando código de autorização da aplicação é inválido. Esse token é utilizado para identificar a aplicação que está integrando com o app do posto.

Valor da venda não pode ser nulo ou zero

Quando o valor da venda com valor zero ou não é enviado.

Empresa inválida

Quando a empresa enviada não é encontrada cadastrada no webservice.

Código não enviado

Quando o código de desconto não é enviado.

Código não encontrado

Quando o código de desconto enviado não é encontrado pelo app do posto.

A data de geração do código está defasada

Quando a data do código enviado (código gerado pelo app) está defasada.

O código da empresa não confere

Quando o código de desconto informado não é da empresa onde requer o desconto. Ou seja, o usuário gerou o código para empresa/posto errada.

Código bloqueado

Quando o código ou usuário está bloqueado.

O tempo para utilização do código expirou

Quando o tempo de utilização do código de desconto já expirou. O dono da rede pode definir quanto tempo aquele código de desconto é válido. Ou seja, caso informe que todo código tem duração de 10 minutos. O usuário ao gerar um código tem até 10 minutos para utilizado. Caso extrapole este tempo, é necessário novamente gerar um novo código.

Limite de código utilizados foi excedido

Quando o usuário já utilizou a quantidade máxima de códigos. O sistema define a quantidade de código que cada usuário pode utilizar por dia. Quando extrapole essa quantidade é lançada uma exceção.

 Os campos, bem como as mensagens, são as mesmas utilizadas no Validar Código. 


6 Pós Vendas

O método pós-venda é utilizado ao finalizar uma venda. Ele é necessário para inserir a venda no sistema do webservice do posto. Sendo assim ele será chamado após o cliente realizar o pagamento e a venda ter sido realizado com sucesso. Requisição de exemplo:

Requisição: POST /api/v1/integracao/posvenda
{
  "tokenIntegracao" : "698dc19d489c4e4db73e28a713eab07b",
  "chaveAutenticacao"        : "1548036428557",
  "linkDocumentoFiscal"     : "http://nfe.gov.br/12332123123",
}


Nome Campo

Tipo

Descrição

Obrigatório?

tokenIntegracao

string

Token identificador da aplicação. Este token é fornecido pelo cliente.

Sim

chaveAutenticacao

string

Chave de autenticação da venda, necessário para identificar qual venda foi finalizada.

Sim

linkDocumentoFiscal

string

Link da nota fiscal emitida.

Não


Resposta exemplo
[
  {
    "codigoValidacao"          : "AAAA",
    "valorPorUnidade"         : 3.922,
    "valorPorUnidadeDesconto"    : 3.80,
    "valorDescontoTotal"     : 0.311,
    "valorVendaTotal"          : 9.69,
    "quantidade"        : 2.550,
    "nomeCliente"     : "Ricardo Henrique de Souza",
    "chaveAutenticacao"     : "1548996244105",
    "identificadorExternoProduto"  : "123456789"
  },
  {
    "codigoValidacao"          : "AAAA",
    "valorPorUnidade"         : 3.80,
    "valorPorUnidadeDesconto"    : 3.70,
    "valorDescontoTotal"     : 0.311,
    "valorVendaTotal"          : 9.435,
    "quantidade"        : 2.550,
    "nomeCliente"     : "Ricardo Henrique de Souza",
    "chaveAutenticacao"     : "1548996244105",
    "identificadorExternoProduto"  : "123456789"
  }
]


Se ocorrer problema de validação, o retorno do webservice será sempre código 400. Caso ocorra o erro 500, se trata de um erro no servidor que não foi tratado no sistema.

Segue abaixo a lista de mensagens possíveis para o método de pós-venda:

Mensagem

Descrição

Token Inválido

Quando código de autorização da aplicação é inválido.

Chave de Autenticação Inválida

Quando a chave de autenticação enviada não existe na base de dados do webservice.


Em casos que a nota fiscal seja emitida em contingência poderá enviar uma requisição para o mesmo método porém agora com o tipo de requisição PUT, conforme abaixo: 

Requisição: PUT /api/v1/integracao/posvenda
{
  "tokenIntegracao" : "698dc19d489c4e4db73e28a713eab07b",
  "chaveAutenticacao"        : "1548036428557",
  "linkDocumentoFiscal" : "http://nfe.gov.br/12332123123",
 }


A resposta será a mesma da requisição, confirmando que a transação ocorreu com sucesso. 


Exemplo de Resposta
{
  "tokenIntegracao"  : "698dc19d489c4e4db73e28a713eab07b",
  "chaveAutenticacao"        : "1548036428557",
  "linkDocumentoFiscal" : "http://nfe.gov.br/12332123123",
}


7 Produtos

Este método é utilizado para realizar a sincronização dos produtos. Os produtos são vinculados com a empresa, podendo ter um mesmo produto para várias empresas, como por exemplo, um etanol para 5 postos diferentes.

O sistema identifica se este será um novo produto caso o código de identificadorExternoProduto não esteja cadastrado na base. Caso o identificadorExternoProduto seja o mesmo, entretanto o codigoEmpresa é diferente do cadastrado na base, o sistema irá adicionar um vínculo do produto para a empresa enviada. Para atualização, caso já exista o identificadorExternoProduto é realizado a atualização da descrição ou do status do produto.

Neste caso, não será possível excluir um produto. Para retirar basta enviar INATIVO para o identificadorExternoProduto acompanhado do codigoEmpresa. Neste caso o sistema irá desabilitar o produto enviado.

POST: /api/v1/integracao/produto/lista
[
  {
    "identificadorExternoProduto"  : "aabb1",
    "descricaoProduto"        : "Diesel S500",
    "modalidadeProduto"     : "DIESEL",
    "codigoEmpresa" : "27008904000110",
    "tokenIntegracao"           : "698dc19d489c4e4db73e28a713eab07b",
    "valor"       : 10.00,
    "status"     : "ATIVO",
    "codigoBarras"    : "112233",
    "ncm"        : "7766",
    "anp": "30303030",
  },
  {
    "identificadorExternoProduto": "432",
    "descricaoProduto": "Etanol",
    "modalidadeProduto": "ETANOL",
    "codigoEmpresa": "27008904000110",
    "tokenIntegracao": "698dc19d489c4e4db73e28a713eab07b",
    "valor": 10.00,
    "status": "INATIVO",
           "codigoBarras": "112233",
    "ncm": "7766",
    "anp": "30303031",
  }
]


O retorno da requisição será uma lista contendo a mesma requisição mais um campo chamado acao. Este campo irá retornar com a ação realizada pelo sistema. No caso podendo ser CREATE, UPDATE ou DISABLE. 


Exemplo de Resposta
[
  {
    "identificadorExternoProduto": "aabb1",
    "descricaoProduto": "Diesel S500",
    "ncm": "7766",
    "anp": "30303030",
    "codigoBarras": null
    "valor": 10.00,
    "status": "ATIVO",
    "acao": "CREATE",
  },
  {
    "identificadorExternoProduto": "432",
    "descricaoProduto": "Etanol",
    "ncm"        : null,
    "anp": "30303031",
    "codigoBarras": "223344",
    "valor": 10.00,
    "status": "ATIVO",
    "acao": "CREATE"
  }
]


Campo

Tipo

Descrição

Obrigatório?

identificadorExternoProduto

string

Identificador externo do produto. Pode ser uma chave ou um identificador da tabela de produtos. 

Sim

modalidadeProduto

string

Modalidade ou Tipo do Produto podendo ser os valores: ETANOL, ETANOL_ADITIVADO, GASOLINA, GASOLINA_ADITIVADA, DIESEL, DIESEL_S500_ADITIVADO, DIESEL_ADITIVADO, DIESEL_S10_ADITIVADO, GASOLINA_PODIUM, GASOLINA_PREMIUM, GNV, ARLA32, QUEROSENE, GASOLINA_TROCA_OLEO, OUTRO.

Sim

descricaoProduto

string

Descrição ou nome do produto.

Sim

tokenIntegracao

string

Token identificador da aplicação. 

Sim

codigoEmpresa

string

CNPJ ou Identificador da empresa/posto. Enviar sem formatação, somente números.

Sim

status

string

 Status do produto. Podendo ser ATIVO ou INATIVO.

Sim

ncm

string

Nomenclatura Comum do Mercosul do produto.

Não

anp

string

Código da ANP.

Não

codigoBarras

string

Código de Barras do Produto.

Não

valor

number

Valor do produto na empresa especificada.

Sim

acao

string

Ação realizada sistema. Podendo CREATE, UPDATE DISABLE.

Sim


Segue abaixo a lista de mensagens possíveis para o método de pós-venda. Se ocorrer algum problema de validação o retorno do webservice será sempre código 400. Caso ocorra o erro 500, se trata de um erro no servidor que não foi tratado no sistema.


Mensagem

Descrição

Token Inválido

Quando código de autorização da aplicação é inválido.

Empresa inválida

Quando a empresa enviada não é encontrada pelo sistema do webservice.


8 Cancelamento 

O cancelamento da venda realiza exclusão dos registros e da transação da venda. Para realizar o cancelamento da venda basta enviar a seguinte requisição:


Requisição: POST /api/v1/integracao/cancelarvenda
{
  "tokenIntegracao" : "698dc19d489c4e4db73e28a713eab07b",
  "chaveAutenticacao"       : "1548036428557",
}


Segue abaixo a descrição dos campos:

Nome Campo

Tipo

Descrição

Obrigatório?

tokenIntegracao

 string

Token identificador da aplicação. 

Sim

chaveAutenticacao

 string

Chave de autenticação da venda, necessário para identificar qual venda foi finalizada.

Sim


Se ocorrer algum problema de validação o retorno do webservice será sempre código 400. Caso ocorra o erro 500 se trata de um erro no servidor que não foi tratado no sistema. 

Segue abaixo a lista de mensagens possíveis para o método de pós-venda:

Mensagem

Descrição

Chave de Autenticação Inválida

Não foi encontrado nenhuma venda para esta chaveAutenticacao.


9 Especificações QRCode

O aplicativo poderá gerar dois tipos de QRCode a ser interpretado pelo PDV do AutoSystem. Um QRCode poderá gerar somente o PIN, mas codificado em formato QRCode. E também poderá gerar o QRCode mais completo, contendo outras informações. Abaixo as informações que poderão vir no QRCode Completo. Esta implementação de QR Code é opcional a critério do estabelecimento.


Corpo do QRCode
{ 
   "codigoValidacao"           : "A0BC14DGY7",
   "placa"        : "AC1DCED",
   "isAceitaCPF"       : false,
   "isEmiteDocumentoFiscal"        : true,
   "CPF"         : "12453678920",
   "identificadorExternoGrupoDesconto" :23      ,
   "data"          :01/01 /2019,
   "hora"         :15:50 ,
   "limiteUso" :5
}


Nome Campo

Tipo

Descrição

Obrigatório ?

codigoValidacao

string

Código de validação informado pelo cliente ou código do cartão do cliente.

Sim

isAceitaCPF

boolean

Descrição do grupo de desconto (categoria ou classe) de clientes do parceiro integrador.

Não

CPF

string

CPF do usuário gerador de código. 

Não

identificadorExternoGrupoDesconto

number

Identificador de categorias, classes ou grupos de usuários no AutoSystem. 

Sim

limiteUso

number

Limite de uso de voucher.

Sim

data

string

Data que foi gerado o código.

Sim

hora

string 

Hora que foi gerado o código.

Sim



  • Sem rótulos