Convênios - Versão 1.0.0

A api deverá ser atualizada semestralmente nos dias 1º de fevereiro e 1º de julho.

O que é o Convênio?

É a plataforma de administração de convênios da Object Pro Tecnologia, feita em parceiria com Abrafad e Rede Soma Drogarias

Como funciona?

As vendas realizadas pelos convênios são captadas pela plataforma. As empresas conveniadas recebem mensalmente o extrato com os gastos dos funcionários para desconto em Folha de Pagamento. Os funcionários tem um desconto exclusivo, e até 40 dias para pagar.

Diagrama de Fluxo:

Vizualizar

URL

Empresa Cidade / UF URL
Object Pro Tecnologia Raul Soares / MG https://convenios.objectpro.com.br

CNPJ da Empresa: 18.092.664/0001-93

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.
software Software Enviar 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.

Grupos Tabela geral

Código Descriçao
1 Propagados
2 Similares
3 Genéricos
4 Perfumaria
5 Correlatos
6 Outros

Unidade de Medida Tabela geral

Código Descriçao
un Unidade
Kg Kilo Grama
g Grama
m Metro
l Litro
ml Mililitro

GET /v1/saldo

Método para consultar o saldo do cliente

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

Nome Requerido Descrição Schema
cpf Sim CPF do Cliente String

Retorno

Código Descrição Schema
200 Sucesso
{
“saldo” : { "type" : "number", "format" : "0.00" }
}

GET /v1/venda

Método para consultar dados da venda [opcional]

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

Nome Requerido Descrição Schema
cnpj_forn Sim Informe o cnpj do Fornecedor do Convênio. String
cpf_clie Sim CPF do cliente. String
legado Sim Identificação da Venda/Cupom no sitema do empresa para posterior conferência Integer

Retorno - Status Code

Código Descrição Schema
200 Sucesso
{
"id" : { "type" : "number" },
"cnpj_forn" : { "type" : "string" },
"cnpj_clie" : { "type" : "string" },
"cpf" : { "type": "string" },
"legado" : { "type": "string" },
"dtocorrencia" : { "type": "string", "format": "yyyy-mm-dd hh:nn:ss" },
"valor" : { "type" : "number", "format" : "0.00" },
"desco" : { "type" : "number", "format" : "0.00" },
"total" : { "type" : "number", "format" : "0.00" },
"itens" : [ {
"id" : { "type" : "number" },
"ean" : { "type" : "string" },
"produto" : { "type" : "string" },
"quant" : { "type" : "number" },
"valor" : { "type" : "number", "format" : "0.00" },
"desco" : { "type" : "number", "min" : 0, "max" : 0 },
"subtotal" : { "type" : "number", "format" : "0.00" },
} ]
}
[venda.desco = Desconto em Reais],[venda.itens[0].desco = Desconto em percentual]

GET /v1/cliente

Método para consultar o saldo do cliente

1 = Método obrigatório no fluxo da venda deve exibir os dados do funcionário, empresa vinculada e saldo

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

Nome Requerido Descrição Schema
cpf Sim CPF do Cliente String
cnpj Sim CNPJ do Fornecedor de convenio String

Retorno

Código Descrição Schema
200 Sucesso
{
“cnpj” : { "type" : "string" },
“razao_social” : { "type" : "string" },
“nome_fantasia” : { "type" : "string" },
"convenio" : { "type" : "string" },
“cpf” : { "type" : "string" },
“nome” : { "type" : "string"},
“dtnascimento” : { "type" : "string", "format" : "yyyy-mm-dd" },
“saldo” : { "type" : "number", "format" : "0.00" }
}

GET /v1/item

Método para consultar desconto

2 = Método obrigatório no fluxo da venda deve consultar o produto pelo ean para ver se existe desconto

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

Nome Requerido Descrição Schema
cnpj_forn Sim Informe o cnpj do Fornecedor do Convênio. String
cpf_clie Sim CPF do cliente. String
legado Sim Identificação da Venda/Cupom no sitema do empresa para posterior conferência Integer
ean Sim Código Ean do produto. Integer

Retorno

Código Descrição Schema
200 Sucesso
{
"ean" : { "type" : "string" },
"produto" : { "type" : "string" },
"desco" : { "type" : "number", "format" : "0.00" }
}

POST /v1/item

Método para envio dos itens da venda

3 = Método obrigatório no fluxo da venda deve enviar os itens vendidos

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

Nome Requerido Descrição Schema
cnpj_forn Sim Informe o cnpj do Fornecedor do Convênio. String
cpf_clie ou cartao Sim CPF do cliente ou Número do Cartão String
cpf_vend Não CPF do Vendedor. String
legado Sim Identificação da Venda/Cupom no sitema do empresa para posterior conferência Integer
ean Sim Código Ean do produto. Integer
produto Sim Descrição do Produto string[255]
um Sim Unidade de Médida String[3]
quant Sim Informe a quantidade vendida do produto. float [1.00]
valor Sim Preço Unitário do Produto. float [3.00]
dtocorrencia Sim Data da ocorrencia da venda. 'Y-m-d H:i:s'
desco Sim Desconto Unitário em Percentual, [desco<=1] float [0.50]
subtotal Sim Preço Unitário menos Desconto Unitário multiplicado pela quantidade [(valor-(valor*desco/100))*quant] float [2.50]

Retorno - Status Code

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

POST /v1/venda

Método para confirmar venda

4 = Método obrigatório no fluxo da venda deve enviar confirmação da venda para que ela seja aceita.

Venda que não forem confirmadas em 15 minutos serão apagadas

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

Nome Requerido Descrição Schema
cnpj_forn Sim Informe o cnpj do Fornecedor do Convênio. String
cpf_clie Sim CPF do cliente. String
legado Sim Identificação da Venda/Cupom no sitema do empresa para posterior conferência Integer
total Sim Total da final da venda subtraindo os descontos [formato "0.00"] number

Retorno - Status Code

Código Descrição Schema
202 Aceito/Autorizado
203 Não autorizado

DELETE /v1/venda

Método para deletar todos os itens da venda

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

Nome Requerido Descrição Schema
cnpj_forn Sim Informe o cnpj do Fornecedor do Convênio. String
cpf_clie Sim CPF do cliente. String
legado Sim Identificação da Venda/Cupom no sitema do empresa para posterior conferência Integer

Retorno - Status Code

Código Descrição Schema
200 Sucesso

DELETE /v1/item

Método para deletar um dos os itens da venda

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

Nome Requerido Descrição Schema
cnpj_forn Sim Informe o cnpj do Fornecedor do Convênio. String
cpf_clie Sim CPF do cliente. String
legado Sim Identificação da Venda/Cupom no sitema do empresa para posterior conferência Integer
ean Sim Código Ean do produto. Integer

Retorno - Status Code

Código Descrição Schema
200 Sucesso