Instalação

npm install fieldcontrol --save

Uso

:exclamation: | Lembre-se de manter em segredo a sua chave de API. Não a compartilhe e tome cuidado para não expô-la publicamente no código do lado do cliente (client-side). ---: | :---

const FieldControl = require('fieldcontrol')
const client = new FieldControl({
  apiKey: 'ssssssssssshhhhhhhhhhhh:x~'
})

Recursos

• Clientes
• Colaboradores
• Tipos de atividades
• Solicitação de serviço
• Ordens de serviço
• Atividades

Clientes

Clientes (customers) são os consumidores finais dos serviços prestados (tipos de atividades), seja ele uma pessoa física ou jurídica.

// Criar um novo cliente
const response = await client.customers.create({
  name: 'Luiz Freneda',
  code: '05e67c054594',
  documentNumber: '27032236881',
  address: {
    zipCode: '15085480',
    street: 'Rua dos Pinheiros',
    number: '383',
    neighborhood: 'Pinheiros',
    complement: 'Edificio Alamac',
    city: 'São Paulo',
    state: 'SP',
    coords: {
      latitude: -23.565249,
      longitude: -46.681838
    }
  }
})

// Recuperar um cliente por id
const response = await client.customers.get('MTY0MTU6MjI5MTU=')

// Listar clientes
const response = await client.customers.list({
  filter: {
    name: 'Luiz'
  },
  pagination: {
    limit: 1,
    offset: 2
  }
})

Colaboradores

Colaboradores (employees) são os profissionais que trabalham externamente usando o app Field Control.

// Recuperar um colaborador por id
const response = await client.employees.get('MTY1NDk6MjI5MTU=')

// Listar colaboradores
const response = await client.employees.list({
  pagination: {
      limit: 10,
      offset: 0
  }
})

Tipos de atividades

Tipos de atividades (services) são serviços prestados pela empresa. Exemplos: instalação, manutenção, reparo, etc..

// Recuperar tipo de atividade por id
const response = await client.services.get('MzUxMzE6MjI5MTU=')

// Criar um novo tipo de atividade
const response = await client.services.create({
  name: 'Instalação',
  duration: 120
})

// Atualizar um tipo de atividade
const response = await client.services.update('MzA0ODY6MjI5MTU=', {
  id: 'MzA0ODY6MjI5MTU=',
  name: 'Manutenção',
  duration: 60
})

// Listar tipos de atividade
const response = await client.services.list()

Solicitação de serviço

Uma solicitação de serviço é, basicamente, um pedido de atendimento, ele pode ser um novo negócio, um problema de um cliente já existente e entre outras utilizações.

// Criar uma nova solicitação de serviço
const response = await client.tickets.create({
  name: 'Luiz Freneda',
  message: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
  subject: 'Manutenção preventiva',
  contact: {
    email: '[email protected]',
    phone: '11963427191'
  }
})

// Atualizar uma solicitação de serviço existente
const response = await client.tickets.update('M2JlYTAyNDctODAyNC00Mzc5LTkwNWQtYTM5ZWRhYWMzM2NmOjE=', {
  name: 'Luiz Freneda',
  message: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
  subject: 'Manutenção preventiva',
  contact: {
    email: '[email protected]',
    phone: '11963427191'
  }
})

// Listar solicitações de serviço por nome e com configurações de paginação
const response = await client.tickets.list({
  filter: {
    name: 'Freneda'
  },
  pagination: {
    limit: 10,
    offset: 1
  }
})

Ordens de serviço

Uma ordem de serviço (orders) é a formalização do serviço a ser prestado.

Na prática, funciona assim: o cliente chega até você com uma demanda, solicita um orçamento, há uma negociação e, assim que ela é concluída, é preciso emitir uma OS para organizar internamente o trabalho a ser realizado.

// Recuperar ordem de serviço por id
const response = await client.orders.get('NTVlMzYxMTktZWJiZjE=')

// Criar uma nova ordem de serviço (sempre é necessário criar com pelo menos UMA atividade)
const response = await client.orders.create({
  identifier: '695860',
  description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
  customer: {
    id: 'MTox'
  },
  service: {
    id: 'MTox'
  },
  address: {
    zipCode: '05005900',
    city: 'Sao Paulo',
    state: 'SP',
    street: 'Rua Turiassu',
    number: '902',
    complement: null,
    neighborhood: null,
    coords: {
      latitude: -23.52702,
      longitude: -46.680823
    }
  },
  tasks: [
    {
      employee: {
        id: 'MTAxOjE='
      },
      status: 'done',
      duration: 30,
      scheduling: {
        date: '2019-08-20',
        time: '15:00:00'
      },
      coords: {
        latitude: -23.52702,
        longitude: -46.680823
      }
    }
  ]
})

// Listar ordens de serviço por identificador e com configurações de paginação
const response = await client.orders.list({
  filter: {
    identifier: 'ABC'
  },
  pagination: {
    limit: 50,
    offset: 50
  }
})

// Listar anexos de uma ordem de serviço
const response = await client.orders.listAttachments('NTVlMzYxMTktZWJiZjE=')

// Listar atividades de uma ordem de serviço
const response = await client.orders.listTasks('NTVlMzYxMTktZWJiZjE=')

// Listar comentários de uma ordem de serviço
const response = await client.orders.listComments('NTVlMzYxMTktZWJiZjE=')

// Listar materiais usados em uma ordem de serviço
const response = await client.orders.listMaterials('NTVlMzYxMTktZWJiZjE=')

// Listar formulários respondidos para uma ordem de serviço
const response = await client.orders.listForms('NTVlMzYxMTktZWJiZjE=')

Atividades

Atividades (tasks) são os registros das visitas e serviços realizados aos clientes.

Na prática, funciona assim: dado uma ordem de serviço, agora é preciso agendar o atendimento até o local da prestação de serviço (cadastrado na OS).

É necessário atribuir uma data, opcionalmente um horário e um colaborador. As atividades são enviadas para os celulares dos técnicos formando sua agenda de atendimento. Vale ressaltar que é possível criar uma ou mais atividades (visitas) para a mesma ordem de serviço.

// Recuperar uma atividade por id
const response = await client.tasks.get('MzUxMzE6MjI5MTU=')

// Listar atividades por data de criação e com configurações de paginação
const response = await client.tasks.list({
  filter: {
    created_at: '2020-06-20'
  },
  pagination: {
    limit: 10,
    offset: 20
  }
})

Contribuições

• Testes unitários! Seu patch não será aceito se seu código não estiver testado :S
• Documentação. Garanta que o README atualizado!
• Branch feature. Se você quer contribuir com mais de uma funcionalidade, envie vários PR.