Four Keep

      Nesta documentação existem alguns termos que podem não ser familiares para todos, sendo assim seguem alguns deles com suas respectivas explicações:

• Sistema de retaguarda: Refere-se ao sistema que irá realizar a integração dos dados com o Four Keep, geralmente um sistema de gestão.

• Base de integração: Refere-se à base de dados mantida pelo Four Keep, nela são salvos todos os dados transitados nesta API.

• Flex: A rotina de Flex consiste em tornar acréscimos concedidos pelos vendedores, em um "crédito" que poderá ser utilizado como desconto nas próximas vendas. Este "crédito" é chamado de saldo Flex. Quando a rotina de Flex é habilitada no Four Keep (através do campo "habilita_flex" no recurso de "Configuracao"), os vendedores só poderão conceder um valor de desconto caso possuam este valor (ou um valor maior) em seu saldo Flex.

        Imagine que o Four Keep esteja configurado para trabalhar com a rotina de Flex, e um novo vendedor seja contratado. Este vendedor não poderá conceder descontos a nenhum cliente, pois seu saldo Flex ainda estará zerado. Durante seu primeiro dia de trabalho, ele realizou uma venda, e nela conseguiu aplicar acréscimos aos valores dos itens, imagine que o total dos valores de acréscimo desta venda tenha sido R$ 10,00. A partir deste momento, este vendedor, conquistou o direito de conceder um desconto de até R$ 10,00 em suas próximas vendas (respeitando o valor máximo de desconto de cada produto).

  *nota: O saldo Flex de cada usuário deve ser atualizado pelo sistema de retaguarda através do campo "saldo_flex" contido no recurso "Usuario".

      A API Four Keep tem o intuito de tornar o processo de integração entre seu sistema de retaguarda e o aplicativo Four Keep o mais natural possível, sendo assim, possui uma lógica bem simples.

      O envio dos dados do seu sistema de retaguarda à base de integração é feito através de requisições REST feitas à API do Four Keep.

      A URL base para as requisições será: meudominio.fourkeep.com*

*nota: troca-se "meudominio" pelo domínio real do cliente. Este domínio será fornecido pela Alterdata.

      O sistema de retaguarda envia as informações pertinentes (ex.: clientes, produtos, etc.) à nossa API, estes dados são salvos em nossa base de integração e ficam disponíveis para consulta e alteração.

      O aplicativo Four Keep recebe estes dados e os disponibiliza para os usuários(vendedores) para que realizem vendas. Os dados cadastrados no aplicativo Four Keep(ex.: Clientes, Pedidos, etc.) são trazidos de volta à base de integração e ficam disponível para que seu sistema de retaguarda os colete e realize os procedimentos necessários dentro de sua regra de negócio.

      Nossa API não permite duplicação de dados. Sendo assim, recomendamos que mantenha uma base de dados que armazene o vínculo entre os registros de seu sistema de retaguarda e os registros de nossa base de integração, mantendo como propriedade de vínculo o campo "id" gerado pela nossa API. Desta forma, será possível identificar quando um registro deverá ser enviado em uma requisição de cadastro ou de atualização.

• Consultando registros:

        Para consultar registros, deve-se realizar uma requisição utilizando o método HTTP GET. A requisição poderá ser direcionada para a URL raiz de um recurso ou ser direcionada para a URL de um recurso específico.

  Ex.:

  meudominio.fourkeep.com/clientes/ - Retornará todos os clientes disponibilizados ao Four Keep.
  meudominio.fourkeep.com/clientes/100 - Retornará apenas o cliente que possui o id igual a 100.

• Cadastrando registros:

        Para cadastrar registros, deve-se realizar uma requisição utilizando o método HTTP POST, direcionada à URL raiz do recurso.

        Esta requisição deve possuir um cabeçalho específico informando que seu corpo está no formato exigido, JSON:

  Content-Type = application/json

        Caso o cadastro seja realizada com sucesso será retornado o StatusCode 201 (CREATED), e no corpo da requisição será retornado o registro cadastrado, contendo todos os seus atributos, incluindo o "id" gerado pelo Four Keep.

• Atualizando registros:

        Para atualizar registros, deve-se realizar uma requisição utilizando o método HTTP PATCH, direcionada à URL raiz do recurso.

        Esta requisição deve possuir um cabeçalho específico informando que seu corpo está no formato exigido, JSON:

  Content-Type = application/json

        Também é necessário que no corpo da requisição esteja presente o campo "id", determinando o registro que será afetado.

        Caso a atualização seja realizada com sucesso será retornado o StatusCode 200 (OK).

• Deletando registros:

        Para garantir a integridade das informações a API do Four Keep trabalha com o conceito de deleção lógica, ou seja, uma informação nunca será removida de nossa base de dados.

        Todos os nossos registros possuem uma propriedade denominada ativo, caso seja necessário indisponibilizar um registro ao Four Keep, basta realizar uma atualização do registro informando o campo ativo como false.

Autenticação

      Para garantir a segurança dos seus dados, a API do Four Keep utiliza uma chave de segurança para autenticar suas requisições. Chamaremos essa chave de MINHA_API_KEY. A MINHA_API_KEY é única para cada cliente e é gerada automaticamente quando um cliente adquire o Four Keep.

      Para realizar qualquer requisição em nossa API, é necessário que a mesma possua um cabeçalho de autorização, da seguinte maneira:
      Authorization: Key MINHA_API_KEY

      A aplicação cliente deverá possuir um campo onde a MINHA_API_KEY possa ser informada e, desta forma, autorizar as requisições. Essa chave ficará de posse do cliente e é de sua responsabilidade mantê-la em segurança, impedindo assim que terceiros possam acessar ou modificar seus dados.

Paginação

      Todas as consultas citadas nesta API podem ser realizadas de maneira paginada, visando maximizar a performance das integrações.

      Imagine que já tenham sido exportados para a API do Four Keep milhares de clientes. Caso uma requisição do tipo GET seja realizada no end point de /clientes, irá gerar uma resposta muito grande, causando possíveis lentidões no download dos dados. Em um cenário assim, recomendamos fortemente o uso da paginação.

      Para tornar qualquer consulta em uma consulta paginada é bem simples, basta adicionar dois parâmetros ao endereço de sua requisição, são eles:

      limit: Determina quantos registros estarão presentes em cada página da requisição.

      offset: Determina a partir de qual posição os registros serão recuperados (exclusivamente).

      Ou seja, caso queira realizar uma consulta no end point de /clientes de maneira paginada, recuperando 1000 clientes por página, realize uma requisição do tipo GET da seguinte forma:

      meudominio.fourkeep.com/clientes/?limit=1000&offset=0

      A resposta desta requisição trará os primeiros 1000 clientes existentes, caso queira solicitar os próximos 1000 clientes, realize a seguinte requisição:

      meudominio.fourkeep.com/clientes/?limit=1000&offset=1000

      A resposta irá conter os próximos 1000 clientes, e assim por diante. Repare que para buscar a próxima página basta incrementar o parâmetro offset.

      É importante se atentar que a estrutura do JSON de resposta de uma consulta paginada é diferente de uma consulta comum. Na consulta comum a lista dos objetos de resposta já está contida na raiz do JSON:

[
  {
    "id": 1,
    "id_retaguarda": "00A0000001",
    "codigo": "000001",
    "nome": "FOUR KEEP",
    "cnpj": "123456789123",
    "ativo": true
  }
]

      Já no JSON de resposta da consulta paginada, a raiz apresenta campos úteis para o controle da paginação:

{
  "count": 2,
  "next": "http://172.16.52.74/empresas/?limit=1&offset=1",
  "previous": null,
  "results": [
    {
      "id": 1,
      "id_retaguarda": "00A0000001",
      "codigo": "000001",
      "nome": "ALTERDATA MOBILE",
      "cnpj": "123456789123",
      "ativo": true
    }
  ]
}

      Estes campos podem ser utilizados para facilitar o controle da paginação de registros, fornecendo informações úteis como:

      count: Informa o número total de registros contidos em cada recurso (não em cada página).

      next: Informa o endereço de consulta para a próxima página, quando a consulta já estiver na última página este campo será preenchido com o valor null.

      previous: Informa o endereço de consulta para a página anterior, quando a consulta estiver na primeira página este campo será preenchido com o valor null.

      results: Neste campo é disponibilizada a lista de objetos retornados na consulta (No mesmo padrão da resposta de uma consulta comum).

*dica: Não é necessário que o sistema de retaguarda monte o endereço de requisição a cada integração incrementando o campo offset, para econimizar esforços, basta utilizar o campo next contido em cada resposta para obter o endereço da próxima página da consulta.