Cartão Fidelidade - Versão 3.0.0.0

A api deverá ser atualizada a cada 4 meses. No primeiro dia dos seguintes mêses janeiro, maio e setembro.

O que é o Programa Fidelidade?

É um programa de fidelização do cliente iniciado pela ObjectPro em parceiria com Rede Soma Drogarias.

Como funciona?

No Modelo por Pontos/Prêmios. A cada compra o cliente acumula pontos, que poderão ser trocados por prêmios.

No Modelo por Desconto. Na hora da compra é feita uma consulta na tabela de Descontos praticada pela Rede e o cliente recebe este desconto. Em contrapartida a Rede buscará sempre fazer a melhor negociação para oferecer os melhores descontos.

URL

Rede Associativa Cidade/UF URL Imagem do Cartão CNPJ de Teste
Rede Soma Drogarias Raul Soares/MG http://soma.clienteshow.com.br /img/progfid.png 18.092.664/0001-93
Rede Omega Ponte Nova/MG http://omega.clienteshow.com.br /img/progfid.png 26.418.471/0001-08
Grupo Multifarma Manhuaçu/MG http://multifarma.clienteshow.com.br /img/progfid.png 03.672.470/0001-90
Rede SmallFarma Drogaris Poços de Caldas/MG http://smallfarma.clienteshow.com.br /img/progfid.png 71.175.178/0001-11
Rede Usifarma Caçador / SC http://usifarma.clienteshow.com.br /img/progfid.png 21.367.142/0001-61

CPF TESTE

Nome CPF
Paulo Barros 044.847.026-81
Rede Soma
Rede Omega
SmallFarma
Multifarma
Usifarma

HEAD Será usado em todos os URI

Nome Valor [Exemplo] Descriçao
Authorization Bearer [Solicitar Token] Envia o token de acesso.
Content-Type application/json Envie o tipo de retorno.
User-Agente Software Envia o nome do software.
Versao 1.0.4.191 Enviar o número da versão do software.

Status Code Tabela geral usada em todos os URI

Código Descriçao Schema
200 Sucesso GET – Irá exibir conteúdo
201 Criado/Atualizado
202 Aceito/Autorizado
203 Não autorizado
204 Não existe conteúdo GET – Item não existe. Ex.: Produto não encontrado
301 Movido {"uri": "string"}
400 Parâmetros Inválidos {"key": ["string"]}
401 Acesso não autorizado
402 Pagamento necessário
403 Proibido
404 Não encontrado, verifique a URL
405 Método não permitido
406 Não executado
408 Tempo esgotado [Timeout]
409 Conflito de regras
410 Url Obsoleta
412 Falha na pré-condição
500 Erro interno do servidor
501 Recurso não implementado
502 Gateway Inválido
503 Serviço indisponível
408,500,503 Observação estes status devem ser tratados para não interromper a aplicação.
No inicio da operação se houve alguma indisponibilidade no servidor,
solicitar o balconista para voltar mais tarde,
O timeout de todos os métodos é 15 segundos.

GET /v2/cliente

Consulta

Parâmetros Sempre enviar em caixa baixa (minúsculas).

Nome Requerido Descrição Schema
cnpj Sim CNPJ da drogaria. String
cpf ou cartao Sim CPF do cliente ou Número do Cartão String

Retorno

Código Descrição Schema
200 Sucesso { "id": "integer", "cpf": "string", "rg": "string", "nome": "string", "nascimento": "date: yyyy-mm-dd", "tlog": "string", "logradouro": "string", "num": "string", "compl": "string", "bairro": "string", "cidade": "string", "uf": "string", "email": "string", "sexo": "integer: 0-Feminino,1-Masculino", "fone1": "string: (XX) XXXX-XXXX", "fone2": "string: (XX) XXXXX-XXXX", "cartao": "string: XXXX.XXXX.XXXX" }
204 Não existe conteúdo
408,500,503 Observação estes status devem ser tratados para não interromper a venda.
No inicio da operação se houve alguma indisponibilidade no servidor,
solicitar o balconista para voltar mais tarde,
informando que ele deve fazer a venda fora do Cartão Fidelidade.
Se durante a operação antes do fechamento da venda houver alguma indisponibilidade,
não é necessário enviar a confirmação no Modelo Desconto para não interromper a venda.
Deve permiter concluir a venda normalmente. Sem exibição de alertas.
O timeout de todos os métodos é 15 segundos.

POST /v1/cliente

Envio

Parâmetros Sempre enviar em caixa baixa (minúsculas).

Nome Requerido Descrição Schema
cnpj Sim CNPJ da drogaria. String
cpf Sim CPF do cliente String
cartao Não Número do Cartão String
nome Sim Nome do Cliente String
sexo Sim 0-Feminino,1-Masculino integer
nascimento Sim Data de Nascimento Date – formato yyyy-mm-dd
email Não Email String
fone1 Não Telefone String
fone2 Não Telefone String
fone3 Não Telefone String
tlog Não Tipo de Logradouro ex: Rua String
logradouro Não Endereço String
num Não Número String
compl Não Complemento String
bairro Não Bairro String
cidade Não Cidade String
uf Não UF, sigla do estado String

Retorno

Código Descrição Schema
201 Criado/Atualizado

Modelo por Prêmios

Exemplo de como pode ser o fluxo:

A tabela de transmissão [venda_id,b1,b2] pode ser usada em segundo plano por outro executável no servidor para fazer a transmissão dos dados evitando de travar o caixa.

Chamaremos de Transmissão cada sessão.

As transmissões ocorrerão de 15 em 15 minutos. Se houve alguma indisponibilidade no servidor, será feita nova tentativa daqui a 15 minutos.

CPF: 044.847.026-81
Programa RESTFul sugerido: Postman

GET /v1/reset

Quanto houver divergência, o WebService pode solicitar uma nova varredura no sistema da softhouse. Sempre antes de enviar uma nova tentativa de transmissão, verificar este método, ser for retornado vazio prosseguir, se caso for retornado uri e data no formato yyyy-mm-dd. Retransmitir os dados a partir daquela data. Seguindo a regra, como se os dados não estivem sido transmitidos.

Parâmetros Sempre enviar em caixa baixa (minúsculas).

Nome Requerido Descrição Schema
cnpj Sim CNPJ da drogaria. String

Retorno

Código Descrição Schema
200 Sucesso [ { "uri": "lancador", "data": "2017-12-06" } ]

Post /v1/reset

Confirmação do Reset

Parâmetros Sempre enviar em caixa baixa (minúsculas).

Nome Requerido Descrição Schema
cnpj Sim CNPJ da drogaria. String
uri Sim Uri String

Retorno

Código Descrição Schema
202 Sucesso

POST /v1/lancador

Método para lançar venda, pagamento, devolução gerando os pontos.

Parâmetros Sempre enviar em caixa baixa (minúsculas).

Nome Requerido Descrição Schema
api_token Sim Token de autenticação. String
cpf Sim CPF do cliente. String
legado Sim Código que identifique a venda/cupon, pagamento ou devolução no sistema do terceiro. Integer
ponto Sim Valor da venda, pagamento, devolução. Double – usar separado decimal [.] ponto final, ex: 1.00, 1.50
dtocorrencia Sim Data da ocorrência da venda, pagamento ou devolução. DateTime – formato yyyy-mm-dd hh:nn:ss
tipo Sim Tipo de transação, 0.Venda, 1.Pagamento, 2.Devolução Integer
cnpj Sim CNPJ da drogaria. String
versao Não Nome Abreviado do Software com versão.
Pode ser o nome do exe seguido da versão.
Ex: RS1.0.01, DigiFarma1.0.1, Automatiza1.0.01
String

Retorno

Código Descrição Schema
200 Sucesso

GET /v2/saldo

Envio

Parâmetros Sempre enviar em caixa baixa (minúsculas).

cnpj cpf/cartao Descrição Schema
cnpj Sim CNPJ da drogaria. String
cpf/cartao Sim CPF do cliente ou Número do Cartão String

Retorno

Código Descrição Schema
200 Sucesso { "cpf":"string", "nome":"string", "email":"string", "saldo":integer }

OBS

Observação
Quando o campo 'cartao' for enviado o campo 'cpf' não precisa ser enviado.

POST /v2/resgate

Envio

Parâmetros Sempre enviar em caixa baixa (minúsculas).

Nome Requerido Descrição Schema
cnpj Sim CNPJ da drogaria. String
cpf/cartao Sim CPF do cliente ou Número do Cartão String
valor Sim Valor Resgatado integer

Retorno

Código Descrição Schema
202 Accepted
203 Non-Authoritative Information {"warning": "Saldo Insuficiente"}

OBS

Observação
Quando o campo 'cartao' for enviado o campo 'cpf' não precisa ser enviado.

Modelo por Desconto

GET /v1/produto

Consulta

Parâmetros Sempre enviar em caixa baixa (minúsculas).

Nome Requerido Descrição Schema
cnpj Sim CNPJ da drogaria. String
cpf/cartao Sim CPF do cliente/Número do Cartão. String
ean Sim Código de Barras EAN do produto. String

Retorno

Código Descrição Schema
200 Sucesso { "id": 611, "ean": "7896554745544", "produto": "Doralgina", "pmc": 15.50, "desconto": 50, "pago": 7.75, "origem": "Rede" }
204 Não existe conteúdo
408,500,503 Observação estes status devem ser tratados para não interromper a venda.
No inicio da operação se houve alguma indisponibilidade no servidor,
solicitar o balconista para voltar mais tarde,
informando que ele deve fazer a venda fora do Cartão Fidelidade.
O timeout de todos os métodos é 15 segundos.

OBS

Observação
Não deve impedir a venda do medicamento quando o desconto não for acatado. Ex: Enviando mensagen de confirmação ou alert....

Sugestão de Tela para ação do método acima. Deve ser disparado ao clicar no botão "Incluir".


POST /v1/produto

Envio

Parâmetros Sempre enviar em caixa baixa (minúsculas).

Nome Requerido Descrição Schema
cnpj Sim CNPJ da drogaria. String
cpf_clie/cartao Sim CPF do cliente/Número do Cartão String
cpf_vend Sim CPF do Vendedor[Balconista] String
dtocorrencia Sim Data da ocorrência da venda DateTime – formato yyyy-mm-dd hh:nn:ss
legado Sim Código que identifique a venda ou cupon no sistema da softhouse. Integer
ean Sim EAN do produto. String
quant Sim Quantidade ex: [2.00]. Double
desco Sim Desconto ex: [15.00]. Double
valor Sim Valor pago pelo cliente ex: [10.00]. Double
origem Sim 0 - Desconto da Drogaria, 1 - Desconto da Rede string

Retorno

Código Descrição Schema
202 Aceito
408,500,503 Observação estes status devem ser tratados para não interromper a venda.
Se durante a operação de confirmação da venda houver alguma indisponibilidade,
não é necessário enviar a confirmação para não interromper a venda.
Deve permiter concluir a venda normalmente. Sem exibição de alertas.
O timeout de todos os métodos é 15 segundos.

OBS

Observação
Quando o campo 'cartao' for enviado o campo 'cpf_clie' não precisa ser enviado.
O campo 'cpf_vend' Não está como obrigatorio mas é imprescindível para algumas redes para premiação.

Sugestão de Tela para ação do método acima. Deve ser disparado ao clicar no botão "Confirmar".


OBS

Observações Gerais
Em todas as vendas com Cartão Fidelidade deve ser identificado o cliente no Cupom Fiscal

Nota Fiscal de Entrada

POST /v1/nfe

Envio

Parâmetros Sempre enviar em caixa baixa (minúsculas).

Nome Requerido Descrição Schema
cnpj Sim CNPJ da drogaria. String
chave Sim chave de acesso da nota no Sefaz String
dtnfe Sim Data de Emissão da Nota Fiscal Date – formato yyyy-mm-dd
total Sim Valor Total da Nota Number – formato 0.00
xml Sim Arquivo xml da nota file

Retorno

Código Descrição Schema
202 Aceito

FTP

O XML da Nota Fiscal de Entrada também pode ser enviado por ftp

Teremos uma login/senha exclusivo for software

A nomenclatura do arquivo XML segue o padrão: chave_sefaz.xml

url: objectpro.com.br
login: software/123456 => Solicitar
arquivo: "/nfe/21186937000173/0000000000000000000000000000000000000000000.xml"