Integração com APIs Vetor Soluções (WebConvênio)

Este documento descreve as APIs disponibilizadas pela Vetor, com as quais se pode realizar consultas de parâmetros de convênios, incluindo informações sobre os convênios e seus conveniados e definições de produtos como produtos bloqueados para venda, produtos com subsídios e listas de preços.

É importante destacar que essa integração exige a contratação da funcionalidade junto à Zetti Tech e à plataforma parceira, além da devida configuração do recurso para que possam operar corretamente no ambiente do cliente.

Informações Básicas

URL Base

A URL base para todas as requisições é: https://api.zetti.dev

Autenticação

A autenticação das APIs se dará por meio de um token fixo e disponibilizado pela Vetor. O token é gerado por rede e ele deve ser informado em todas as requisições no cabeçalho: ApiKey: {sua-chave}

Modelos de Resposta

Todas as requisições irão retornar um objeto padrão conforme o modelo:

{
  "status": 0,
  "data": ...,
  "msg": "string",
  "total": 0
}

CODE

O campo "status" pode conter um dos seguintes valores:

Indica sucesso na requisição.
Indica alguma inconsistência nos dados enviados ou algum critério não atendido em uma
validação.
Indica uma falha interna no servidor.

O campo "data" trará o conteúdo esperado a depender de cada API. O campo "msg" irá descrever o motivo da falha nos casos em que o "status" seja igual a 2 ou 3. Nestes casos a API irá também retornará o statuscode 500. O campo "total" trará a quantidade total de registros que atendam ao critério de busca no caso de consultas paginadas.

Parâmetros Adicionais e Filtros Dinâmicos

As APIs utilizam ainda o padrão do protocolo Odata disponibilizando parâmetros adicionais com os quais é possível realizar filtros dinâmicos e customizações nos dados retornados. Entre os principais estão:

Parâmetro $filter

Realiza filtros dinâmicos com base no modelo de resposta da API.

Deve ser utilizado seguindo o padrão:

?$filter={função | propriedade operador valor}

Exemplo de filtros utilizando funções:

//Filtra convênios que contém a palavra "hospital" no nome
.../webapi/WebConvenio/convenios?$filter=contains(descricao, 'hospital')

//Filtra convênios que o nome começa com "distribuidora"
.../webapi/WebConvenio/convenios?$filter=startsWith(descricao, 'distribuidora')

//Filtra convênios de código 1, 2 e 3
.../webapi/WebConvenio/convenios?$filter=codigo in(1,2,3)

CODE

Exemplo de filtros utilizando operadores:

//Filtra conveniados com o valor de limite maior que zero
/WebConvenio/conveniados?$filter=vlrLimite gt 0

//Filtra conveniados bloqueados e com débitos
/WebConvenio/conveniados?$filter=bloqueado eq true and vlrDebitos gt 0

CODE

A seguir estão alguns operadores disponíveis para utilização:

eq: igual a
ne: diferente de
gt: maior que
ge: maior ou igual a
lt: menor que
le: menor ou igual a
and: "e" lógico
or: "ou" lógico

Parâmetro $select

Por meio deste parâmetro, pode-se especificar as propriedades quem devem ser retornadas de acordo modelo devolvido pela API afim de reduzir o tráfego de dados.

Deve ser utilizado seguindo o padrão:

?$select={propriedades separadas por vírgula}

Exemplo de utilização:

//Forçando o retorno somente das propriedades com o código e descrição dos convênios
.../webapi/WebConvenio/convenios?$select=codigo,descricao

CODE

Parâmetro $orderby

Utilizado para ordenar os resultados da consulta.

Deve ser utilizado seguindo o padrão:

?$select={propriedades separadas por vírgula}

Exemplo de utilização:

//Ordenando os resultados da consulta de convênios com base no código
.../webapi/WebConvenio/convenios?$orderby=codigo

CODE

Parâmetros $skip, $top e $count

Por meio destes parâmetros, pode-se realizar uma paginação nas consultas onde o parâmetro $skip especifica a quantidade de registros ignorados na consulta e $top especifica a quantidade máxima de registros a serem retornados. Por meio do parâmetro $count é possível sinalizar a API se deve ou não retornar a quantidade total de registros da consulta.

Exemplo de utilização:

//Consultando convênios de forma paginada ignorando os 10 primeiros registros e retornando os próximos 20
.../webapi/WebConvenio/convenios?$skip=10&$top=20&$count=true

CODE

Relação de APIs

GET /webapi/WebConvenio/convenios

O seu intuito é listar os convênios disponíveis no sistema.

Exemplo de Resposta

{
    "status": 0,
    "data": [
        {
            "codigo": 1, // Código identificador do convênio
            "descricao": "Zetti Tech", // Nome do convênio
            "qtdMaximaParcelas": 3, // Quantidade máxima de parcelas permitida para recebimento parcelado
            "vlrMinimoParcela": 50.0, // Valor mínimo da parcela para recebimento parcelado
            "percRecebimentoMaximo": 50.0, // Percentual máximo permitido para recebimento em convênio em relação ao total da venda
            "percRecebimentoMinimo": 5.0, // Percentual mínimo permitido para recebimento em convênio em relação ao total da venda
            "inativo": true // Situação do convênio
        }
    ],
    "msg": "string",
    "total": 0
}

CODE

GET /webapi/WebConvenio/convenioBloqueioProdutos

Seu objetivo é listar os produtos bloqueados para a venda para um convênio específico.

Parâmetros de Query

cdConvenio: código do convênio (obrigatório)
cpf: CPF do conveniado (opcional se informado a matrícula)
matricula: matrícula do conveniado (opcional se informado o CPF)

Exemplo de Requisição

.../webapi/WebConvenio/convenioBloqueioProdutos?cdConvenio=123&cpf=123456789-00

Exemplo de Resposta

{
     "status": 200,
     "data": [
         {
             "cdProduto": 123, //Código do produto
             "dsProduto": "Produto Bloqueado A", //Descrição do produto
             "cdTabela": 456, //Código da tabela de bloqueio
             "dsTabela": "Tabela de Bloqueio X" //Descrição da tabela de bloqueio
         }
     ],
     "msg": null,
     "total": 1
}

CODE

GET /webapi/WebConvenio/convenioSubsidioProdutos

Seu objetivo é listar os produtos com subsídio para um convênio específico.

Parâmetros de Query

cdConvenio: código do convênio (obrigatório)
cpf: CPF do conveniado (opcional se informado a matrícula)
matricula: matrícula do conveniado (opcional se informado o CPF)

Exemplo de Requisição

.../webapi/WebConvenio/convenioSubsidioProdutos?cdConvenio=123&cpf=123456789-00

Exemplo de Resposta

{
     "status": 200,
     "data": [
          {
              "cdProduto": 789, //Código do produto
              "dsProduto": "Produto com Subsídio B", //Descrição do produto
              "cdTabela": 101, //Código da tabela de subsídio
              "dsTabela": "Tabela de Subsídio Y", //Descrição da tabela de subsídio
              "vlrSubsidio": 15.50, //Valor do subsídio
              "qtdLimite": 2, //Quantidade limite para compra
              "qtdDiasLimite": 30 //Quantidade de dias para validação da quantidade limite para compra
          }
     ],
     "msg": null,
     "total": 1
}

CODE

GET /webapi/WebConvenio/convenioListaPrecosProdutos

Seu objetivo é listar os produtos com preço definido pelo convênio.

Parâmetros de Query

cdConvenio: código do convênio (obrigatório)
cpf: CPF do conveniado (opcional se informado a matrícula)
matricula: matrícula do conveniado (opcional se informado o CPF)

Exemplo de Requisição

.../webapi/WebConvenio/convenioListaPrecosProdutos?cdConvenio=123&cpf=123456789-00

Exemplo de Resposta

{
     "status": 200,
     "data": [
           {
               "cdProduto": 112, //Código do produto
               "dsProduto": "Produto com Preço Especial", //Descrição do produto
               "cdTabela": 131, //Código da tabela com a lista de preços
               "dsTabela": "Tabela de Preços Z", //Descrição da tabela com a lista de preços
               "vlrVenda": 89.90 //Valor de venda do produto
           }
      ],
      "msg": null,
      "total": 1
}

CODE

GET /webapi/WebConvenio/conveniados/{cdConvenio}

Seu objetivo é pesquisar conveniados de um convênio específico.

Parâmetros de Query

cdConvenio: código do convênio (obrigatório)

Exemplo de Requisição

.../webapi/WebConvenio/conveniados/123

Exemplo de Resposta

{
     "status": 200,
     "data": {
          "codigo": 1001, //Código identificador do conveniado
          "nome": "João da Silva", //Nome do conveniado
          "cpf": "123.456.789-00", //CPF do conveniado
          "vlrLimite": 1000.00, //Valor de limite de compras
          "vlrDebitos": 150.50, //Valor dos débitos em aberto
          "bloqueado": false, //Situação do conveniado
          "numeroCartao": "1234567890", //Número do cartão de identificação
          "matricula": "MAT001", //Número de matrícula
          "cdConvenio": 1, //Código do convênio
          "dsConvenio": "Convênio Exemplo", //Descrição do convênio
          "cdUsuario": 50, //Código do usuário responsável pelo cadastro/alteração
          "cdUsuarioWebConvenio": 60, //Código do usuário do webconvênio responsável pelo cadastro/alteração
          "nmUsuarioResponsavel": "Admin Sistema", //Nome do usuário responsável pelo cadastro/alteração
          "dtUltimaAlteracao": "2023-10-15T14:30:00Z", //Data da última alteração do registro
          "dependentes": [
             {
               "cdDependente": 2001, //Código de identificação do dependente
               "nome": "Maria da Silva", //Nome do dependente
               "inativo": false //Situação do dependente
             }
          ], //Relação de dependentes do conveniado
          "cdPlanoVenda": 5,
          "dsPlanoVenda": "Plano Premium"
      },
	  "msg": null,
	  "total": 1
}

CODE

GET /webapi/WebConvenio/conveniados

Seu objetivo é pesquisar conveniados com base em critérios de filtros.

Parâmetros de Query

cpf: CPF do conveniado (opcional se informado a matrícula)
matricula: matrícula do conveniado (opcional se informado o CPF

Exemplo de Requisição

.../webapi/WebConvenio/conveniados?cpf=123456789-00

Exemplo de Resposta

{
      "status": 200,
      "data": {
           "codigo": 1001, //Código identificador do conveniado
           "nome": "João da Silva", //Nome do conveniado
           "cpf": "123.456.789-00", //CPF do conveniado
           "vlrLimite": 1000.00, //Valor de limite de compras
           "vlrDebitos": 150.50, //Valor dos débitos em aberto
           "bloqueado": false, //Situação do conveniado
           "numeroCartao": "1234567890", //Número do cartão de identificação
           "matricula": "MAT001", //Número de matrícula
           "cdConvenio": 1, //Código do convênio
           "dsConvenio": "Convênio Exemplo", //Descrição do convênio
           "cdUsuario": 50, //Código do usuário responsável pelo cadastro/alteração
           "cdUsuarioWebConvenio": 60, //Código do usuário do webconvênio responsável pelo cadastro/alteração
           "nmUsuarioResponsavel": "Admin Sistema", //Nome do usuário responsável pelo cadastro/alteração
           "dtUltimaAlteracao": "2023-10-15T14:30:00Z", //Data da última alteração do registro
           "dependentes": [
              {
                "cdDependente": 2001, //Código de identificação do dependente
                "nome": "Maria da Silva", //Nome do dependente
                "inativo": false //Situação do dependente
              }
            ], //Relação de dependentes do conveniado
            "cdPlanoVenda": 5,
            "dsPlanoVenda": "Plano Premium"
        },
        "msg": null,
 	    "total": 1
}

CODE

Explore outros conteúdos e descubra o passo a passo da operação.