...
Painel | ||||||
---|---|---|---|---|---|---|
| ||||||
|
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.
...
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
[ { "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 | Sim |
horaVenda | string | Hora da Venda no formato | 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.
...
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
[ { "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.
...
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "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 |
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
[ { "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" } ] |
...
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:
...
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
[ { "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:
...
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.
...
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "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 |