Ir para o conteúdo

Exemplos

Introdução

A Fieldy CONNECT é uma API REST capaz de fornecer acesso à Base de Dados da aplicação MOBIUSOne.

Este documento apresenta o formato de acesso de requisições genéricas e os padrões de resposta de sucesso ou erro.

A API recebe e retorna informações no formato JSON.

Para mais informações sobre as rotas suportadas, acesse a Referência.

Formato

Todos os endpoints da Fieldy CONNECT são construídos de acordo com o seguinte formato: 

https://api.fieldy.com.br/api/v1/<Holding>/<Tabela>/<Objeto>

onde:

  • v1 é a versão da API
  • <Holding> é o CPF/CNPJ da empresa detentora da Base de Dados
  • <Tabela> é a fonte de dados desejada
  • <Objeto> é o identificador único do objeto.

Caso deseje mais informações sobre as tabelas disponíveis, clique aqui.

São implementados os métodos GET, POST, PUT, PATCH e DELETE, onde cada um deles oferece uma funcionalidade:

  • GET: retorna os dados de um recurso.
  • POST: adiciona um novo registro à base de dados.
  • PUT: sobresecreve completamente um registo.
  • PATCH: corrige um ou mais campos de um registro.
  • DELETE: realiza a deleção lógica de um registro da base de dados.

Abaixo, são fornecidos alguns exemplos de requisições suportadas pela Fieldy CONNECT.

Regras de Criação dos Endpoints

Os endpoints da API da MOBIUSOne são criados dinâmicamente de acordo com as tabelas do Banco de Dados do cliente.

O endereço de um objeto na API é criado de acordo com o seu Id, i.e., sua chave primária.

As tabelas da MOBIUSOne, em sua maioria, possuem como chave primária os campos idHolding e idUnidadeNegocio. No entanto, como cada endpoint e cada usuário da API é direcionado a uma Holding, não é necessário indicar tais campos explícitamente na pesquisa.

Em geral, a chave primária é simples, no entanto existem exceções. Abaixo, estão alguns exemplos.

Tabela com Chave Primária Simples

A maior parte das tabelas da MOBIUSOne são estruturadas com Chave Primária Simples. Deste modo, para se identificar um objeto, somente é necessário indicar o seu Id.

Por exemplo:

  • Deseja-se requisitar as informações do seguinte Cliente:
{
  "idHolding": "15347602000197",
  "idCliente": "000003",
  "idUnidadeNegocio": "15347602000197",
  "idUnidadeLocal": null,
  "idColaborador": null,
  "idCondicaoPagamento": null,
  "idFormaPagamento": null,
  "idSegmento": null,
  "idSetor": null,
  "idTerritorio": null,
  "idRegiao": null,
  "idClienteLocal": null,
  "codigoRetaguarda": "C000003",
  [...]
}

Ao se observar a estrutura da tabela Cliente, identifica-se que as chaves primárias desta tabela são idHolding e idCliente.

Como idHolding já foi informado através do usuário e do endpoint, é necessário somente fornecer o identificador idCliente do objeto desejado.

No objeto acima, idCliente = "000003". Logo, o endpoint que se refere à este objeto é: 

GET https://api.fieldy.com.br/api/v1/15347602000197/Cliente/000003

Tabela com Chave Primária Composta

Algumas das tabelas da MOBIUSOne são estruturadas com Chave Primária Composta.

Sendo assim, um endpoint com apenas uma chave, como por exemplo /v1/<Holding>/Cliente/000003 não é capaz de identificar um elemento único.

Para identificar objetos com chaves primárias compostas, foi definido o uso de Objetos JSON para identificação, como por exemplo:

  • Deseja-se solicitar o objeto da tabela ClienteEndereco que possui a seguinte estrutura:
{
  "idHolding": "15347602000197",
  "idCliente": "000003",
  "idClienteEndereco": 0,
  "idUnidadeNegocio": null,
  "idFornecedor": null,
  "idEndereco": null,
  [...]
}

Ao se observar a estrutura da tabela ClienteEndereco, identifica-se que as chaves primárias desta tabela são idHolding, idCliente e idClienteEndereco.

Como idHolding já foi informado através do usuário e do endpoint, é necessário fornecer dois identificadores, idCliente e idClienteEndereco do objeto desejado.

Para o objeto acima, com idCliente = "000003" e idClienteEndereco = 0, o endpoint é construído da seguinte da seguinte forma:

GET https://api.fieldy.com.br/api/v1/15347602000197/ClienteEndereco/{ "idCliente":"000003", "idClienteEndereco": 0 }

Pontos de Atenção:

  • Chaves de Abertura ({) e Fechamento (}) são obrigatórias
  • Aspas são obrigatórias em nomes dos campos e chaves do tipo CHAR / NVARCHAR / STRING
  • A ordem dos IDs não é levada em consideração
  • Faz-se distinção entre maiúsculas e minúsculas

GET

Listar todos os clientes

Este exemplo equivale à uma query SQL 

SELECT * 
FROM [Cliente]

Endpoint: 

GET https://api.fieldy.com.br/api/v1/15347602000197/Cliente

Header: 

Authorization: Basic <Credencial>

Exemplo de Resposta Bem-Sucedida:

Será retornada uma lista de todos os Clientes da holding.

{
  "total": 8726,
  "limit": 100,
  "skip": 0
  "data": [
      {
        "idHolding": "15347602000197",
        "idCliente": "000001",
        "idUnidadeNegocio": "15347602000197",
        [...],
        "entrada": "2019-01-10T17:25:42.957Z",
        "transmissao": null,
        "backofficeMSG": null,
        "idGerador": null
      },
      {
        "idHolding": "15347602000197",
        "idCliente": "000002",
        [...]
      },
      {
        "idHolding": "15347602000197",
        "idCliente": "000003",
        [...]
      }, 
      [...]
  ]
}


Exemplo de Resposta com Erro:

Erro no CNPJ/CPF (rota inválida):

Status: 404 NOT FOUND

Cannot GET /v1/15347602000198/Cliente/

Requisitar cliente por ID

Este exemplo equivale à uma query SQL 

SELECT * 
FROM   [Cliente] 
WHERE  [idCliente] = '000001'

Endpoint: 

GET https://api.fieldy.com.br/api/v1/15347602000197/Cliente/000001

Header: 

Authorization: Basic <Credencial>

Exemplo de Resposta Bem-Sucedida:

Será retornado somente o cliente com identificador "idCliente": "000001"

{
  "idHolding": "15347602000197",
  "idCliente": "000001",
  "idUnidadeNegocio": "15347602000197",
  [...],
  "entrada": "2019-01-10T17:25:42.957Z",
  "transmissao": null,
  "backofficeMSG": null,
  "idGerador": null
}


Exemplo de Resposta com Erro:

Recurso não encontrado:

Status: 500 INTERNAL SERVER ERROR

NotFound: No record found for id '000001'

Listar produtos com estoque inferior a 100

Este exemplo equivale à uma query SQL 

SELECT * 
FROM   ProdutoEstoque 
WHERE  estoque <= 100

Endpoint:

GET https://api.fieldy.com.br/api/v1/15347602000197/ProdutoEstoque

Header: 

Authorization: Basic <Credencial>

Parâmetros: 

estoque[$lte]=100

Uma lista com todos os parâmetros suportados está disponível na Referência.


Exemplo de Resposta Bem-Sucedida:

Será retornada uma lista de todos os Produtos cujo estoque é menor ou igual a 100 unidades

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
      {
          "idHolding": "15347602000197",
          "idUnidadeNegocio": "15347602000197",
          "idUnidadeLocal": "15347602000197",
          "idProduto": "0004",
          "estoque": 53,
          "precoBase": 494.97,
          "precoValeCompras": null,
          "precoValeTicket": null,
          "descPercMax": 30,
          "estoqueVenda": "S",
          "icms": null,
          "condicaoVenda": "1",
          "entradaPrevista": null,
          "quantidadePrevista": null,
          "comissaoVenda": null,
          "margemLucro": null,
          "estoqueReserva": null,
          "dataVisualizacao": null,
          "statusRegistro": 1,
          "situacao": null,
          "operacao": 0,
          "ticket": null,
          "erro": null,
          "entrada": "2018-10-14T12:36:27.000Z",
          "transmissao": "2018-10-24T06:10:41.000Z",
          "backofficeMSG": null,
          "idGerador": null
      }
  ]
}


Exemplo de Resposta com Erro:

Recurso não encontrado:

Status: 500 INTERNAL SERVER ERROR

NotFound: No record found for id '1'

Formato de dados inválido:

Status: 500 INTERNAL SERVER ERROR

GeneralError: Error converting data type nvarchar to numeric.

Observações:

  • É possível passar quantos argumentos forem necessários
  • Todos os argumentos são agregados com o conectivo AND

POST

Inserir uma nova Condição de Pagamento

Este exemplo equivale a uma query SQL 

INSERT INTO [CondicaoPagamento] 
            ([idHolding], 
             [idUnidadeNegocio], 
             [idCondicaoPagamento], 
             [idFormaPagamento], 
             [condicaoPagamento], 
             [parcelaNumero], 
             [statusRegistro],
             [operacao]) 
VALUES      ("15347602000197", 
             "15347602000197", 
             "01", 
             "01", 
             "À Vista", 
             1, 
             2, 
             0)

Endpoint:

POST https://api.fieldy.com.br/api/v1/15347602000197/CondicaoPagamento

Header: 

Authorization: Basic <Credencial>

Parâmetros: 

{
  "idHolding": "15347602000197",
  "idUnidadeNegocio": "15347602000197",
  "idCondicaoPagamento": "01",
  "idFormaPagamento": "01",
  "condicaoPagamento": "À Vista",
  "parcelaNumero": 1,
  "statusRegistro": 2,
  "operacao": 0
}


Exemplo de Resposta Bem-Sucedida:

Será retornado o objeto inserido

{
    "idHolding": "15347602000197",
    "idUnidadeNegocio": "15347602000197",
    "idCondicaoPagamento": "01",
    "idFormaPagamento": "01",
    "condicaoPagamento": "À Vista",
    "parcelaNumero": 1,
    "prazoMedio": null,
    "indice": null,
    "parcelaMinima": null,
    "notas": null,
    "dataVisualizacao": null,
    "statusRegistro": 2,
    "situacao": null,
    "operacao": 0,
    "ticket": null,
    "erro": null,
    "entrada": "2019-01-23T14:23:38.773Z",
    "transmissao": null,
    "backofficeMSG": null
}


Exemplo de Resposta com Erro:

Objeto Duplicado:

Status: 500 INTERNAL SERVER ERROR

Cannot insert duplicate key in object 'dbo.CondicaoPagamento'.

Chave Estrangeira Inválida

Status: 500 INTERNAL SERVER ERROR

The INSERT statement conflicted with the FOREIGN KEY constraint "FK__CondicaoPagament__44CA3770".

Campos obrigatórios não preenchidos

Status: 500 INTERNAL SERVER ERROR

Cannot insert the value NULL into column 'idUnidadeNegocio'

PUT

O método PUT substitui informações de todos os campos de um objeto.

Não deve ser utilizado para atualização, e sim para substitução.

Alterar um Endereço de Cliente

Este exemplo equivale a uma query SQL 

UPDATE [ClienteEndereco] 
SET    [idHolding] = '15347602000197', 
       [idUnidadeNegocio] = '15347602000197',
       [idCliente] = '000004',
       [idClienteEndereco] = 1, 
       [idFornecedor] = NULL,
       [idEndereco] = NULL,
       [nomeLocal] = NULL,
       [inscricaoRural] = NULL,
       [cep] = '01014001', 
       [logradouro] = 'Rua Boa Vista', 
       [numero] = '185', 
       [complemento] = '', 
       [bairro] = 'Centro', 
       [cidade] = 'São Paulo', 
       [uf] = 'SP', 
       [referenciaEndereco] = NULL,
       [telefone] = NULL,
       [ramal] = NULL,
       [GPSLatitude] = '-23.545885', 
       [GPSLongitude] = '-46.633751', 
       [GPSData] = '2018-01-07T11:05:53.000Z', 
       [ordemVisita] =  NULL,
       [dataVisita] = '2018-01-07T00:00:00.000Z',
       [dataCompra] = NULL,
       [dataVisualizacao] = NULL,
       [statusRegistro] = 2,
       [situacao] = NULL,
       [operacao] = 1,
       [ticket] = NULL,
       [erro] = NULL,
       [entrada] = '2019-01-11T11:36:43.000Z',
       [transmissao] = '2019-01-11T11:42:08.000Z',
       [backofficeMSG] = NULL
WHERE  [idCliente] = '000004' 
       AND [idClienteEndereco] = 1;

Endpoint:

PUT https://api.fieldy.com.br/api/v1/15347602000197/ClienteEndereco/{"idCliente":"000004", "idClienteEndereco":1}

Header: 

Authorization: Basic <Credencial>

Parâmetros: 

{
    "idHolding": "15347602000197",
    "idCliente": "000004",
    "idClienteEndereco": 1,
    "idUnidadeNegocio": "15347602000197",
    "cep": "01014001",
    "logradouro": "Rua Boa Vista",
    "numero": "185",
    "complemento": "",
    "bairro": "Centro",
    "cidade": "São Paulo",
    "uf": "SP",
    "GPSLatitude": "-23.545885",
    "GPSLongitude": "-46.633751",
    "GPSData": "2018-01-07T11:05:53.000Z",
    "dataVisita": "2018-01-07T00:00:00.000Z",
    "statusRegistro": 2
}


Exemplo de Resposta Bem-Sucedida:

Será retornado o objeto atualizado

{
    "idHolding": "15347602000197",
    "idCliente": "000004",
    "idClienteEndereco": 1,
    "idUnidadeNegocio": "15347602000197",
    "idFornecedor": null,
    "idEndereco": null,
    "nomeLocal": null,
    "inscricaoRural": null,
    "cep": "01014001",
    "logradouro": "Rua Boa Vista",
    "numero": "185",
    "complemento": "",
    "bairro": "Centro",
    "cidade": "São Paulo",
    "uf": "SP",
    "referenciaEndereco": null,
    "telefone": null,
    "ramal": null,
    "GPSLatitude": "-23.545885",
    "GPSLongitude": "-46.633751",
    "GPSData": "2018-01-07T11:05:53.000Z",
    "ordemVisita": null,
    "dataVisita": "2018-01-07T00:00:00.000Z",
    "dataCompra": null,
    "dataVisualizacao": null,
    "statusRegistro": 2,
    "situacao": null,
    "operacao": 1,
    "ticket": null,
    "erro": null,
    "entrada": "2019-01-11T11:36:43.000Z",
    "transmissao": "2019-01-11T11:42:08.000Z",
    "backofficeMSG": null
}


Exemplo de Resposta com Erro:

Chave Estrangeira Inválida

Status: 500 INTERNAL SERVER ERROR

The UPDATE statement conflicted with the FOREIGN KEY constraint "FK__CondicaoPagament__44CA3770".

Campos obrigatórios não preenchidos

Status: 500 INTERNAL SERVER ERROR

Cannot insert the value NULL into column 'idUnidadeNegocio'

PATCH

O método PATCH altera os campos de um registro.

Alterar a senha de um Usuário

Este exemplo equivale a uma query SQL 

UPDATE [UsuarioAppDtl] 
SET    [senha] = 'a1b2c3d4' 
WHERE  [login] = 'usuario.dtl'

Endpoint:

PATCH https://api.fieldy.com.br/api/v1/15347602000197/UsuarioAppDtl/dtl.usuario

Header: 

Authorization: Basic <Credencial>

Parâmetros: 

{
    "senha": "a1b2c3d4"
}


Exemplo de Resposta Bem-Sucedida:

Será retornado o objeto atualizado

{
    "idHolding": "09912195000110",
    "login": "dtl.usuario",
    "senha": "a1b2c3d4",
    "cpf": "",
    "nome": "Usuário Fieldy",
    "sobrenome": "",
    "iniciais": "DTL",
    "conhecidoComo": "Dtl USER",
    "fotoDevice": "",
    "fotoCLOUDAX": "",
    "celularPessoal": "",
    "emailPessoal": "usuario.fieldy@gmail.com",
    "dataNascimento": "1999-12-31T00:00:00.000Z",
    "notas": "",
    "ativo": "0",
    "nivelAcesso": 0,
    "dataVisualizacao": null,
    "statusRegistro": 1,
    "situacao": null,
    "operacao": 1,
    "ticket": null,
    "erro": null,
    "entrada": "2019-01-24T14:06:23.200Z",
    "transmissao": null,
    "backofficeMSG": null
}

DELETE

O método DELETE realiza a exclusão lógica de um registro, definindo o campo operacao = 2.

Remover um Usuário

Este exemplo equivale a uma query SQL 

UPDATE [UsuarioAppDtl] 
SET    [operacao] = 2 
WHERE  [login] = 'dtl.usuario'

Endpoint:

DELETE https://api.fieldy.com.br/api/v1/15347602000197/UsuarioAppDtl/dtl.usuario

Header: 

Authorization: Basic <Credencial>


Exemplo de Resposta Bem-Sucedida:

Será retornado o objeto atualizado

{
    "idHolding": "09912195000110",
    "login": "dtl.usuario",
    "senha": "a1b2c3d4",
    "cpf": "",
    "nome": "Usuário Fieldy",
    "sobrenome": "",
    "iniciais": "DTL",
    "conhecidoComo": "Dtl USER",
    "fotoDevice": "",
    "fotoCLOUDAX": "",
    "celularPessoal": "",
    "emailPessoal": "usuario.fieldy@gmail.com",
    "dataNascimento": "1999-12-31T00:00:00.000Z",
    "notas": "",
    "ativo": "0",
    "nivelAcesso": 0,
    "dataVisualizacao": null,
    "statusRegistro": 1,
    "situacao": null,
    "operacao": 2,
    "ticket": null,
    "erro": null,
    "entrada": "2019-01-24T14:06:23.200Z",
    "transmissao": null,
    "backofficeMSG": null
}