NAV Navigation
Code

API Field Control

Esse documento descreve os recursos que compõe a API de Integração oficial do Field Control.

Introdução

A API do Field Control tem como base conceitos de arquitetura REST.

Os endpoints da API são organizados em torno de recursos, como ordens de serviço, comentários ou formulários. Os recursos são representados em JSON, ações pelos métodos do HTTP e os erros por HTTP status code.

Autenticação

Todas as requisições para a API são autenticadas fornecendo sua chave de API.

A chave da API deve ser fornecida como um cabeçalho HTTP chamado X-Api-Key.

Header

curl -H "X-Api-Key: SUA_KEY" https://carchost.fieldcontrol.com.br/

Como obtenho minha chave?

Usuários com perfil de administrador podem gerenciar as chaves de acesso ou API keys no Painel de gestão pelo link:
https://app.fieldcontrol.com.br/#/configuracoes/configuracao-para-desenvolvedores

Ao acessar o painel, na seção "Chave de integração", clique no link demonstrado na imagem abaixo.

Em seguida, dê um nome para sua chave e clique em "Criar".

Pronto! Sua chave foi criada.

Métodos HTTP

A API usa métodos padrões do HTTP para indicar a ação a ser executada em um recurso.

MétodoAção
GETRecupera um recurso existente
POSTCria um novo recurso
PUTAtualiza um recurso existente
DELETEExclui um recurso existente

Schema

O corpo das requisições e das respostas da API são representadas no formato JSON. Todos os timestamps são retornados no formato ISO 8601: YYYY-MM-DDTHH:MM:SSZ sempre em UTC.

Recursos individuais

Os recursos individuais são representados de forma singular. Ao lado, segue uma representação de um serviço.

Exemplo de resultado individual de serviço:

{
  "name": "Manutenção corretiva",
  "duration": 60,
  "archived": false
}

Lista de recursos

As listas de recursos são representadas por um membro de nível mais alto chamado items e no nível mais abaixo, encontram-se os recursos.

O membro totalCount representa o número total de registros do recurso solicitado.

Exemplo de resultado de uma listagem de serviços:

GET https://carchost.fieldcontrol.com.br/services

{
  "items": [
    {
      "name": "Instalação",
      "duration": 60,
      "archived": false
    },
    {
      "name": "Reparo",
      "duration": 30,
      "archived": false
    },
    {
      "name": "Reforma",
      "duration": 120,
      "archived": false
    }
  ],
  "totalCount": 3
}

Paginação, Filtros e Ordenação de resultados

Paginação

Os endpoints que retornam listas de recursos devem limitar o número de registros retornados em uma resposta. O parâmetro limit da query deve ser usado para alterar o número de registros retornados.

Um endpoint irá retornar 10 registros por padrão e permite, no máximo, retornar 100 registros.

O parâmetro offset da query deve ser usado para deslocar um conjunto de resultados. Esses parâmetros podem ser combinados para recuperar todos os recursos de uma lista por meio de uma série de requisições que incrementam o offset pelo valor do limit em cada uma delas.

Para utilizar os dois parâmetros na mesma requisição, basta separá-los com &, como por exemplo:

https://carchost.fieldcontrol.com.br/services?limit=20&offset=40.

ParâmetroDescrição
limitO número de resultados que devem ser retornados em cada página (padrão = 10; máximo = 100)
offsetO ponto de início do conjunto de resultados de uma página. O valor padrão do índice é 0

Por exemplo, se existem 345 registros e o parâmetro limit é igual ao valor padrão (10), use offset=20 para recuperar a próxima página de resultados.

O número total de registros em uma lista pode ser encontrado na propriedade totalCount da resposta.

Filtros

Os filtros permitem refinar a consulta de um determinada lista. Para aplicar um filtro, deve ser inserido ?q=chave:"valor" logo após o endpoint na URL. Cada recurso é compatível com um tipo de parâmetro.

Por exemplo, serviços podem ser filtrados por nome.

Serviços filtrados por nome

GET https://carchost.fieldcontrol.com.br/services?q=name:"Instalação"

{
  "items": [
    {
      "id": "NTox",
      "name": "Instalação",
      "duration": 60,
      "archived": false
    }
  ],
  "totalCount": 1
}

É possível aplicar mais de um filtro na mesma requisição, basta separar os parâmetros por espaço na query. Por exemplo:

Consulta com mais de um filtro

GET https://carchost.fieldcontrol.com.br/customer?q=name:"Luiz Freneda" document_number:"59784800870"

{
  "items": [
    {
      "id": "NTox",
      "name": "Luiz Freneda",
      "documentNumber": "59784800870",
      "contact": {
        "email": "luiz@fieldcontrol.com.br",
        "phone": "17996584235"
      },
      "address": {
        "zipCode": "15085480",
        "street": "Rua Padre Clemente Marton Segura",
        "number": "51",
        "neighborhood": "Higienópolis",
        "complement": "Sobrado amarelo",
        "city": "São José do Rio Preto",
        "state": "São Paulo",
        "coords": {
          "latitude": -20.836378,
          "longitude": -49.38591
        }
      },
      "statistics": {
        "updatedAt": null,
        "service": {
          "firstAt": null,
          "lastAt": null,
          "total": 0
        },
        "rating": {
          "averageStars": 0,
          "lastComment": null,
          "lastStar": 0
        }
      },
      "archived": false
    }
  ],
  "totalCount": 1
}

Alguns filtros podem utilizar de operadores condicionais, como o parâmetro created_at. Para aplicar o filtro com o operador condicional compatível, basta colocá-lo no final do nome do parâmetro.

Por exemplo, para filtrar os resultados de um recurso por data de criação maior ou igual a 2020-06-12 o filtro ficaria &q=created_at>=:2020-06-12. Para resultados exatos, utiliza-se o parâmetro sem operador condicional, como: &q=created_at:2020-06-12T15:20:00Z

Ordenação de resultados

Os endpoints que retornam listas de recursos podem ter seus resultados ordenados. Para aplicar uma ordenação, deve ser inserido &sort=valor após o endpoint na URL. Os dados podem ser organizados em ordem ascendente ou em ordem descendente, para isso, é necessário incluir - junto do valor de sort para que os resultados sejam mostrados em ordem descendente e somente valor para que os resultados sejam mostrados em ordem ascendente.

Por exemplo, as ordens de serviços podem ser ordenadas pela data de criação, então seria &sort=created_at para a ordenação ascendente dos resultados e &sort=-created_at para a ordenação descendente dos resultados.

Exemplo de requisição para recuperar lista de clientes em ordem descendente da data de criação (mais recente primeiro):

curl -X GET https://carchost.fieldcontrol.com.br/customers&limit=2&sort=-created_at \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "MTox",
      "name": "Eduardo Luiz Santos",
      "code": "e1eb7458ff84",
      "contact": {
        "email": "edu@fieldcontrol.com.br",
        "phone": "17996543210"
      },
      "address": {
        "zipCode": "05422010",
        "street": "Rua dos Pinheiros",
        "number": "383",
        "neighborhood": null,
        "complement": null,
        "city": "São Paulo",
        "state": "São Paulo",
        "coords": {
          "latitude": -23.565217,
          "longitude": -46.681819
        }
      },
      {
        "statistics": {
        "updatedAt": null,
        "service": {
          "firstAt": null,
          "lastAt": null,
          "total": 0
        },
        "rating": {
          "averageStars": 0,
          "lastComment": null,
          "lastStar": 0
        }
      },
      "createdAt": "2020-06-12T15:35:06Z"
    },
    {
      "id": "MTI0NTY2OjMyNjM1",
      "name": "Maria Luiza dos Reis",
      "code": "5adf68asf87h",
      "contact": {
        "email": "mluiza@gmail.com",
        "phone": "11996874231"
      },
      "address": {
        "zipCode": "06874139",
        "street": "Rua dos Trabalhadores",
        "number": "500",
        "neighborhood": null,
        "complement": null,
        "city": "São Paulo",
        "state": "São Paulo",
        "coords": {
          "latitude": -23.567891,
          "longitude": -46.64712
        }
      },
      {
        "statistics": {
        "updatedAt": null,
        "service": {
          "firstAt": null,
          "lastAt": null,
          "total": 0
        },
        "rating": {
          "averageStars": 0,
          "lastComment": null,
          "lastStar": 0
        }
      },
      "createdAt": "2020-06-10T1:00:06Z"
    }
  ],
  "totalCount": 200
}

Erros

A API utiliza o status code do HTTP para indicar que ocorreu um erro enquanto processava a requisição.

HTTP StatusCodeDescrição
401A API key é inválida
429Quantidade máxima de requisições por segundo ultrapassada
404O recurso não pode ser encontrado
422A requisição não pôde ser processada, possivelmente devido à falta de um parâmetro ou um parâmetro inválido

No caso do erro 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Segue o exemplo abaixo:

{
  'code': 'resourceValidationErr',
  'errors': [
    {
      'code': null,
      'reason': 'optional',
      'message': 'is missing and not optional',
      'property': '@.address'
    }
  ]
}

Rate Limits

A API permite que a aplicação cliente possa fazer uma requisição por segundo. Contas com alta demanda podem entrar em contato conosco para obter uma solução de limite personalizada.

Bibliotecas oficiais

As bibliotecas oficiais da API Field Control permitem simplificar e reduzir o montante de código que você precisa escrever para utilizar os recursos disponíveis.

As bibliotecas oficiais são de código aberto e ao clicar nos logos abaixo você será redirecionado para a página do repositório no GitHub. Lá, você encontrará todas as instruções de como instalar e utilizar a biblioteca.

Confira as bibliotecas oficias disponíveis:

Clientes

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

Parâmetros

NomeTipoDescrição
idstringIdentificador do cliente
name*stringNome do cliente
codestringCódigo do cliente
contact.emailstringE-mail principal de contato do cliente (somente leitura)
contact.phonestringTelefone principal de contato do cliente (apenas números e somente leitura)
address.zipCode*stringCEP - Código de endereço postal (apenas números)
address.city*stringNome da cidade referente ao CEP
address.state*stringNome do estado referente ao CEP
address.neighborhoodstringNome do bairro referente ao CEP
address.street*stringNome do logradouro referente ao CEP
address.number*stringNúmero da residência/prédio
address.complementstringInformação adicional do endereço
address.coords.latitude*floatLatitude - Coordenada geográfica do local de atendimento
address.coords.longitude*floatLongitude - Coordenada geográfica do local de atendimento
statistics.updatedAtstringData da última atualização dos dados estatísticos (somente leitura)
statistics.service.firstAtstringData do primeiro atendimento feito ao cliente (somente leitura)
statistics.service.lastAtstringData do último atendimento feito ao cliente (somente leitura)
statistics.service.totalintegerNúmero total de atendimentos feitos ao cliente (somente leitura)
statistics.rating.averageStarsintegerNota média (0 a 5) de todas as avaliação feita pelo cliente (somente leitura)
statistics.rating.lastCommentstringÚltimo comentário feito pelo cliente (somente leitura)
statistics.rating.lastStarintegerNota (0 a 5) da última avaliação feita pelo cliente (somente leitura)
archived*booleanIndica se o cliente está arquivado

Atenção: As propriedades com * são obrigatórias

Usuários podem gerenciar os clientes no Painel de gestão pelo link: https://app.fieldcontrol.com.br/#/clientes

Caso seu sistema não possua dados de geolocalização para seus clientes, veja essa seção.

Criar um cliente

Cria um novo cliente

MétodoEndpoint
POSThttps://carchost.fieldcontrol.com.br/customers
Status CodeDescrição
201Cliente criado com sucesso
422Cliente enviado contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para criação de um cliente:

curl -X POST https://carchost.fieldcontrol.com.br/customers \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "name": "Nicola Zagari",
    "code": "22f30236efad",
    "address": {
      "zipCode": "05432070",
      "street": "R. Fidalga",
      "number": "66",
      "neighborhood": "Vila Madalena",
      "complement": "Prédio branco",
      "city": "São Paulo",
      "state": "SP",
      "coords": {
        "latitude": -23.558418,
        "longitude": -46.688081
      }
    }
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "NTc4NTQ1OjIyOTE1",
  "name": "Nicola Zagari",
  "code": "22f30236efad",
  "documentNumber": null,
  "contact": {
    "email": null,
    "phone": null
  },
  "address": {
    "zipCode": "05432070",
    "street": "R. Fidalga",
    "number": "66",
    "neighborhood": "Vila Madalena",
    "complement": "Prédio branco",
    "city": "São Paulo",
    "state": "SP",
    "coords": {
      "latitude": -23.558418,
      "longitude": -46.688081
    }
  },
  "statistics": {
    "updatedAt": null,
    "service": {
      "firstAt": null,
      "lastAt": null,
      "total": 0
    },
    "rating": {
      "averageStars": 0,
      "lastComment": null,
      "lastStar": 0
    }
  }
}

Recuperar um cliente

Recupera um cliente existente por id.

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/customers/:id
Status CodeDescrição
200Cliente recuperado com sucesso
404Cliente não encontrado
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar um cliente:

curl -X GET https://carchost.fieldcontrol.com.br/customers/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "id": "MTox",
  "name": "Eduardo Luiz Santos",
  "code": "ef2bf873154c",
  "contact": {
    "email": "edu@fieldcontrol.com.br",
    "phone": "17996543210"
  },
  "address": {
    "zipCode": "05422010",
    "street": "Rua dos Pinheiros",
    "number": "383",
    "neighborhood": null,
    "complement": null,
    "city": "São Paulo",
    "state": "São Paulo",
    "coords": {
      "latitude": -23.565217,
      "longitude": -46.681819
    }
  },
  {
    "statistics": {
    "updatedAt": null,
    "service": {
      "firstAt": null,
      "lastAt": null,
      "total": 0
    },
    "rating": {
      "averageStars": 0,
      "lastComment": null,
      "lastStar": 0
    }
  }
}

Atualizar um cliente

Atualiza um cliente existente

MétodoEndpoint
PUThttps://carchost.fieldcontrol.com.br/customers/:id
Status CodeDescrição
200Cliente atualizado com sucesso
422Cliente enviado contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para atualização de um cliente:

curl -X PUT https://carchost.fieldcontrol.com.br/customers/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "name": "Luiz Freneda",
    "code": "05e67c054594",
    "documentNumber": "27032236881",
    "address": {
      "zipCode": "15085480",
      "street": "Rua Padre Clemente Marton Segura",
      "number": "51",
      "neighborhood": "Higienópolis",
      "complement": "Sobrado amarelo",
      "city": "São José do Rio Preto",
      "state": "São Paulo",
      "coords": {
        "latitude": -20.836378,
        "longitude": -49.38591
      }
    }
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "NTAxMDc0OjIyOTE1",
  "name": "Luiz Freneda",
  "code": "05e67c054594",
  "documentNumber": "27032236881",
  "contact": {
    "email": "luiz@fieldcontrol.com.br",
    "phone": "17996584235"
  },
  "address": {
    "zipCode": "15085480",
    "street": "Rua Padre Clemente Marton Segura",
    "number": "51",
    "neighborhood": "Higienópolis",
    "complement": "Sobrado amarelo",
    "city": "São José do Rio Preto",
    "state": "São Paulo",
    "coords": {
      "latitude": -20.836378,
      "longitude": -49.38591
    }
  },
  "statistics": {
    "updatedAt": null,
    "service": {
      "firstAt": null,
      "lastAt": null,
      "total": 0
    },
    "rating": {
      "averageStars": 0,
      "lastComment": null,
      "lastStar": 0
    }
  }
}

Listar clientes

Lista clientes existentes

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/customers/
Status CodeDescrição
200Clientes recuperados com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Filtros disponíveis para a listagem de clientes:

ParâmetroOperadoresDescrição
archivedNenhumArquivado
nameNenhumNome do cliente
document_numberNenhumDocumento do cliente
codeNenhumCódigo do cliente
created_at>=, <=, > e <Data de criação

Valores disponíveis para ordenação de resultados:

ValorDescrição
created_atData de criação em ordem ascendente
-created_atData de criação em ordem descendente

Exemplo de requisição para recuperar lista de clientes:

curl -X GET https://carchost.fieldcontrol.com.br/customers \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "MTox",
      "name": "Eduardo Luiz Santos",
      "code": "e1eb7458ff84",
      "contact": {
        "email": "edu@fieldcontrol.com.br",
        "phone": "17996543210"
      },
      "address": {
        "zipCode": "05422010",
        "street": "Rua dos Pinheiros",
        "number": "383",
        "neighborhood": null,
        "complement": null,
        "city": "São Paulo",
        "state": "São Paulo",
        "coords": {
          "latitude": -23.565217,
          "longitude": -46.681819
        }
      },
      {
        "statistics": {
        "updatedAt": null,
        "service": {
          "firstAt": null,
          "lastAt": null,
          "total": 0
        },
        "rating": {
          "averageStars": 0,
          "lastComment": null,
          "lastStar": 0
        }
      },
      "createdAt": "2020-06-12T15:35:06Z"
    }
  ],
  "totalCount": 1
}

Informações de contato

As informações de contato de um cliente são compostas por telefone e e-mail.

Telefones

São todos os telefones associados a um cliente.

Parâmetros

NomeTipoDescrição
idstringIdentificador do telefone
number*stringNúmero do telefone
type*stringTipo do telefone
primarybooleanSe o telefone é o principal, com valor padrão false

Atenção: As propriedades com * são obrigatórias

Usuários podem gerenciar os clientes no Painel de gestão pelo link: https://app.fieldcontrol.com.br/#/clientes

Parâmetro type e seus valores

ValorDescrição
homeTelefone domiciliar
mobileTelefone móvel
workTelefone de trabalho

Criar um telefone

Cria um telefone.

MétodoEndpoint
POSThttps://carchost.fieldcontrol.com.br/customers/:id/phones
Status CodeDescrição
201Telefone criado com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para criação de um telefone de um cliente:

curl -X POST https://carchost.fieldcontrol.com.br/customers/:id/phones \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "number": "17996085421",
    "type": "mobile",
    "primary": true
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "NmJlZTk4ZWQtNGRjZC00MTYyLTgwYWYtODFjNzk3OGNhN2FhOjE=",
  "number": "17996085421",
  "type": "mobile",
  "primary": true
}

Atualizar um telefone

Atualiza um telefone existente.

MétodoEndpoint
PUThttps://carchost.fieldcontrol.com.br/customers/:id/phones/:phone_id
Status CodeDescrição
200Telefone atualizado com sucesso
404Cliente ou telefone não encontrado
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para atualizar um telefone:

curl -X GET https://carchost.fieldcontrol.com.br/customers/:id/phones/:phone_id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'
  --data-binary \
  '{
    "number": "17996089867",
    "type": "mobile"
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "NmJlZTk4ZWQtNGRjZC00MTYyLTgwYWYtODFjNzk3OGNhN2FhOjE=",
  "number": "17996089867",
  "type": "mobile"
  "primary": true
}

Listar telefones

Lista todos os telefones do cliente.

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/customers/:id/phones
Status CodeDescrição
200Telefones listados com sucesso
404Cliente não encontrado
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para listar os telefones de um cliente:

curl -X GET https://carchost.fieldcontrol.com.br/customers/:id/phones \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  items: [
    {
      "id": "Y2U4M2YyOTgtZTg1Ni00YjRlLTk0OTMtOWEwODEyN2E4ZWQwOjE=",
      "number": "17996854723",
      "type": "work",
      "primary": false
    },
    {
      "id": "MGUwYzdmYzQtZGZhZS00OWFiLThlNzYtNjJjYWYyNDk4NWFhOjE=",
      "number": "17996325412",
      "type": "mobile",
      "primary": true
    }
  ],
  totalCount: 2
}

Remover um telefone

Remove um telefone existente.

MétodoEndpoint
DELETEhttps://carchost.fieldcontrol.com.br/customers/:id/phones/:phone_id
Status CodeDescrição
204Telefone removido com sucesso (corpo da resposta é vazio)
404Cliente ou telefone não encontrado

Exemplo de requisição para remover um telefone de um cliente:

curl -X GET https://carchost.fieldcontrol.com.br/customers/:id/phones/:phone_id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

E-mails

São todos os e-mails associados a um cliente.

Parâmetros

NomeTipoDescrição
idstringIdentificador do e-mail
address*stringEndereço eletrônico
type*stringTipo do e-mail
primarybooleanSe o e-mail é o principal e seu valor padrão é false

Atenção: As propriedades com * são obrigatórias

Usuários podem gerenciar os clientes no Painel de gestão pelo link: https://app.fieldcontrol.com.br/#/clientes

Parâmetro type e seus valores

ValorDescrição
personalE-mail pessoal
workE-mail de trabalho

Criar um e-mail

Cria um e-mail.

MétodoEndpoint
POSThttps://carchost.fieldcontrol.com.br/customers/:id/emails
Status CodeDescrição
201E-mail criado com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para criação de um e-mail de um cliente:

curl -X POST https://carchost.fieldcontrol.com.br/customers/:id/emails \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "address": "andre@gmail.com",
    "type": "personal",
    "primary": true
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "NmJlZTk4ZWQtNGRjZC00MTYyLTgwYWYtODFjNzk3OGNhN2FhOjE=",
  "address": "andre@gmail.com",
  "type": "personal",
  "primary": true
}

Atualizar um e-mail

Atualiza um e-mail existente.

MétodoEndpoint
PUThttps://carchost.fieldcontrol.com.br/customers/:id/emails/:email_id
Status CodeDescrição
200E-mail atualizado com sucesso
404Cliente ou e-mail não encontrado
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para atualizar um e-mail:

curl -X GET https://carchost.fieldcontrol.com.br/customers/:id/emails/:email_id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'
  --data-binary \
  '{
    "address": "andre@empresa.com.br",
    "type": "work"
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "NmJlZTk4ZWQtNGRjZC00MTYyLTgwYWYtODFjNzk3OGNhN2FhOjE=",
  "address": "andre@empresa.com.br",
  "type": "work"
  "primary": true
}

Listar e-mails

Lista todos os e-mails do cliente.

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/customers/:id/emails
Status CodeDescrição
200E-mails listados com sucesso
404Cliente não encontrado

Exemplo de requisição para listar os e-mails de um cliente:

curl -X GET https://carchost.fieldcontrol.com.br/customers/:id/emails \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  items: [
    {
      "id": "Y2U4M2YyOTgtZTg1Ni00YjRlLTk0OTMtOWEwODEyN2E4ZWQwOjE=",
      "address": "andre@empresa.com.br",
      "type": "work",
      "primary": false
    },
    {
      "id": "MGUwYzdmYzQtZGZhZS00OWFiLThlNzYtNjJjYWYyNDk4NWFhOjE=",
      "address": "andre@gmail.com",
      "type": "personal",
      "primary": true
    }
  ],
  totalCount: 2
}

Remover um e-mail

Remove um e-mail existente.

MétodoEndpoint
DELETEhttps://carchost.fieldcontrol.com.br/customers/:id/emails/:email_id
Status CodeDescrição
204E-mail removido com sucesso (corpo da resposta é vazio)
404Cliente ou e-mail não encontrado

Exemplo de requisição para remover um e-mail de um cliente:

curl -X GET https://carchost.fieldcontrol.com.br/customers/:id/emails/:email_id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Colaboradores

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

Parâmetros

NomeTipoDescrição
idstringIdentificador
name*stringNome do colaborador
avatarUrl*stringCaminho para a foto de avatar do colaborador

Usuários com perfil de administrador podem gerenciar os colaboradores no Painel de gestão pelo link: https://app.fieldcontrol.com.br/#/colaboradores

Recuperar um colaborador

Recupera um colaborador existente por id

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/employees/:id
Status CodeDescrição
200Colaborador recuperado com sucesso
404Colaborador não encontrado
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar um colaborador:

curl -X GET https://carchost.fieldcontrol.com.br/employees/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "id": "MTY0MTU6MjI5MTU=",
  "name": "Mauro Garcia",
  "avatarUrl": null
}

Listar colaboradores

Lista colaboradores existentes

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/employees/
Status CodeDescrição
200Colaboradores recuperados com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Filtros disponíveis para a listagem de colaboradores:

ParâmetroDescrição
nameNome do colaborador

Exemplo de requisição para recuperar lista de colaboradores:

curl -X GET https://carchost.fieldcontrol.com.br/employees \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "MTY0MTU6MjI5MTU=",
      "name": "Mauro Garcia",
      "avatarUrl": null
    },
    {
      "id": "MTY1NDk6MjI5MTU=",
      "name": "Renan Valentin",
      "avatarUrl": null
    },
    {
      "id": "MTY1NTU6MjI5MTU=",
      "name": "Felipe Zini",
      "avatarUrl": null
    }
  ],
  "totalCount": 3
}

Materiais

Materiais são os produtos ou peças utilizados na execução de uma ordem de serviço.

Parâmetros

NomeTipoDescrição
idstringIdentificador
name*stringNome do material
measure*stringUnidade de medida (unity, centimeter, meter, liter, milliliter)
archivedbooleanIndica se o material está arquivado

Criar um material

Cria um novo material

MétodoEndpoint
POSThttps://carchost.fieldcontrol.com.br/materials/
Status CodeDescrição
201Material criado com sucesso
422Material enviado contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para criação de um material:

curl -X POST https://carchost.fieldcontrol.com.br/materials \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "name": "Tomada Padrão americano RJ11",
    "measure": "unity"
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "MzUxMzE6MjI5MTU=",
  "name": "Tomada Padrão americano RJ11",
  "measure": "unity"
  "archived": false
}

Recuperar um material

Recupera um material existente por id

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/materials/:id
Status CodeDescrição
200Material recuperado com sucesso
404Material não encontrado
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar um material:

curl -X GET https://carchost.fieldcontrol.com.br/materials/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "id": "MzUxMzE6MjI5MTU=",
  "name": "Tomada Padrão americano RJ11",
  "measure": "unity"
  "archived": false
}

Atualizar um material

Atualiza um material existente

MétodoEndpoint
PUThttps://carchost.fieldcontrol.com.br/materials/:id
Status CodeDescrição
200Material atualizado com sucesso
422Material enviado contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para atualização de um material:

curl -X PUT https://carchost.fieldcontrol.com.br/materials/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "name": "Tomada Padrão americano RJ11",
    "measure": "unity"
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "MzUxMzE6MjI5MTU=",
  "name": "Tomada Padrão americano RJ11",
  "measure": "unity"
  "archived": false
}

Listar materiais

Lista materiais existentes

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/materials/
Status CodeDescrição
200Materiais recuperados com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Filtros disponíveis para a listagem de materiais:

ParâmetroDescrição
archivedArquivado
nameNome do material

Exemplo de requisição para recuperar lista de materiais:

curl -X GET https://carchost.fieldcontrol.com.br/materials \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "MzUxMzE6MjI5MTU=",
      "name": "Tomada Padrão americano RJ11",
      "measure": "unity"
      "archived": false
    }
  ],
  "totalCount": 1
}

Listar materiais de uma ordem de serviço

Materiais são os produtos ou peças utilizados na execução de uma ordem de serviço.

Parâmetros

NomeTipoDescrição
quantitynúmeroQuantidade do material utilizado
material.idstringIdentificador
material.name*stringNome do material
material.measure*stringUnidade de medida (unity, centimeter, meter, liter, milliliter)
MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/orders/:order_id/materials
Status CodeDescrição
200Materiais utilizados recuperados com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar lista de anexos de uma ordem de serviço:

curl -X GET https://carchost.fieldcontrol.com.br/orders/:order_id/materials \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      'id': 'YWY0MmZmZDktODY1NS00MTdjLTlkM2QtNDRkMDZlZmQ5Y2MzOjE=',
      'quantity': 25,
      'material': {
        'id': 'NzNjZTBiNDEtZjYwMC00YmU0LWFhMzEtNTE1MTQ1NTNmMjY5OjE=',
        'name': 'Fibra ótica',
        'measure': 'centimeter'
      }
    }
  ],
  "totalCount": 1
}

Equipamentos

Equipamentos são os aparelhos da ordem de serviço que recebem manutenções.

Parâmetros

NomeTipoDescrição
idstringIdentificador do equipamento
name*stringNome do equipamento
number*stringNúmero de série do equipamento
notesstringObservações do equipamento
qrCodestringCódigo QR do equipamento
archivedbooleanIndica se o equipamento está arquivado
avatarUrlstringCaminho para a foto de avatar do equipamento
customer.id*stringIdentificador do cliente
type.id*stringIdentificador do tipo de equipamento
customFieldsarrayLista dos campos customizados do equipamento (somente ao recuperar um equipamento)
createdAtstringData de criação do equipamento (somente leitura)

Recuperar um equipamento

Recupera um equipamento existente por id

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/equipments/:id
Status CodeDescrição
200Equipamento recuperado com sucesso
404Equipamento não encontrado
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar um material:

curl -X GET https://carchost.fieldcontrol.com.br/equipments/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "id": "YzkyMTA0MzgtNWVmNy00YjU4LTkxOWYtMjBmY2Y4ZDI1OTdiOjE=",
  "name": "Venax FI109",
  "number": "4as57n9c7",
  "notes": "Localizado no centro da cozinha",
  "archived": false,
  "qrCode": "5f40c7a6-3889-4b5c-afc2-8484af60bae6",
  "avatarUrl": null,
  "customer": {
    "id": "MTox"
  },
  "type": {
    "id": "NDFkNzk3MDctZDI3Yy00ZTM1LWJmZGQtYTNhMTUwNzEwNmNkOjE="
  },
  "customFields": [
    {
      "id": "ZDRhODlmNDYtOWE1MS00Njg1LThmMGUtNmU3MTIyZTJjY2MwOjIyOTE1",
      "name": "Qual a data de fabricação do forno?",
      "value": "2020-02-19T16:40:43.671Z",
      "position": 1
    },
    {
      "id": "ZWQ0NjE5MjgtNzhkMy00Y2YyLWI4NDAtMmZjZTI2ZGE4MjVjOjIyOTE1",
      "name": "Qual a potência do forno?",
      "value": "4.5",
      "position": 2
    },
    {
      "id": "ZjM4MDAwMDMtZjc2Zi00ODdlLWJlYjMtYzQyODczZTBiYWQ3OjIyOTE1",
      "name": "Selecione a marca:",
      "value": "Venax",
      "position": 3
    }
  ]
  "createdAt": "2020-07-01T12:34:12Z"
}

Listar equipamentos

Lista equipamentos existentes

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/equipments
Status CodeDescrição
200Equipamentos recuperados com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Filtros disponíveis para a listagem de equipamentos:

ParâmetroOperadoresDescrição
numberNenhumNúmero de série do equipamento
customer_idNenhumIdentificador do cliente
type_idNenhumIdentificador do tipo de equipamento
archivedNenhumEquipamento arquivado
created_at>=, <=, > e <Data de criação do equipamento

Exemplo de requisição para recuperar lista de equipamentos:

curl -X GET https://carchost.fieldcontrol.com.br/equipments \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "MTdjZDYxZWItODRmMy00ZjdhLTg1NDItZDMxMjczMzBkODhiOjE=",
      "name": "Ar condicionado split 9000 Btu",
      "number": "6amzdfds1",
      "notes": "",
      "archived": false,
      "qrCode": "7bdbc830-541e-468a-8d3a-62d10c3e6e5f",
      "avatarUrl": null,
      "customer": {
        "id": "MTox"
      },
      "type": {
        "id": "NDFkNzk3MDctZDI3Yy00ZTM1LWJmZGQtYTNhMTUwNzEwNmNkOjE="
      },
      "createdAt": "2020-07-01T15:37:10Z"
    },
    {
      "id": "YzkyMTA0MzgtNWVmNy00YjU4LTkxOWYtMjBmY2Y4ZDI1OTdiOjE=",
      "name": "Ar condicionado split 12000 Btu",
      "number": "4as57n9c7",
      "notes": "Localizado no canto esquerdo da sala de reuniões",
      "archived": false,
      "qrCode": "5f40c7a6-3889-4b5c-afc2-8484af60bae6",
      "avatarUrl": null,
      "customer": {
        "id": "MTox"
      },
      "type": {
        "id": "NDFkNzk3MDctZDI3Yy00ZTM1LWJmZGQtYTNhMTUwNzEwNmNkOjE="
      },
      "createdAt": "2020-07-01T12:34:12Z"
    }
  ],
  "totalCount": 2
}

Valores disponíveis para ordenação de resultados:

ValorDescrição
created_atData de criação em ordem ascendente
-created_atData de criação em ordem descendente

Campos customizados

Os campos customizados são questões personalizadas para um tipo de equipamento.

Parâmetros

NomeTipoDescrição
idstringIdentificador do campo customizado
namestringNome do campo customizado
valuestringValor do campo customizado
positionintegerPosição do campo customizado

Eles podem ser obtidos ao recuperar um equipamento, correspondente ao parâmetro customFields.

Tipos de Equipamentos

Os tipos de equipamentos definem o tipo do equipamento, por exemplo: ar condicionado, forno, freezer, etc.

Parâmetros

NomeTipoDescrição
idstringIdentificador do tipo de equipamento
name*stringNome do tipo de equipamento
archivedbooleanIndica se o tipo de equipamento está arquivado
createdAtstringData de criação do tipo de equipamento (somente leitura)

Listar tipos de equipamentos

Lista os tipos de equipamentos

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/equipment-types
Status CodeDescrição
200Tipos de equipamentos recuperados com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Filtros disponíveis para a listagem de equipamentos:

ParâmetroOperadoresDescrição
nameNenhumNome do tipo de equipamento
archivedNenhumTipo de equipamento arquivado

Exemplo de requisição para recuperar lista de equipamentos:

curl -X GET https://carchost.fieldcontrol.com.br/equipment-types \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "MGU5NWViYmYtNmFhNC00YjAyLTk2MjgtNGJkZTNhZjI0ZjNkOjE=",
      "name": "Computador",
      "archived": false,
      "createdAt": "2020-04-15T14:51:04.300Z"
    },
    {
      "id": "M2RjYTBhZDgtYjA3Yi00MGJkLTg3OWEtOTBkNmQzN2EyOTU0OjE=",
      "name": "Elevador",
      "archived": false,
      "createdAt": "2020-04-15T14:51:04.300Z"
    },
    {
      "id": "NDFkNzk3MDctZDI3Yy00ZTM1LWJmZGQtYTNhMTUwNzEwNmNkOjE=",
      "name": "Ar condicionado",
      "archived": false,
      "createdAt": "2020-04-15T14:51:04.300Z"
    }
  ],
  "totalCount": 3
}

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.

Parâmetros

NomeTipoDescrição
idstringIdentificador da solicitação de serviço
name*stringNome da solicitação de serviço
subject*stringAssunto para ser tratado
message*stringMensagem em texto longo
contact.emailstringE-mail do contato que abriu o chamado
contact.phonestringTelefone do contato que abriu o chamado

É possível visualizar as solicitações de serviço via Painel de gestão pelo link: https://app.fieldcontrol.com.br/#/chamados-e-oportunidades

Criar uma solicitação de serviço

Cria uma nova solicitação de serviço.

MétodoEndpoint
POSThttps://carchost.fieldcontrol.com.br/tickets/
Status CodeDescrição
201Solicitação de serviço criada com sucesso
422Solicitação de serviço enviada contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para criação de uma solicitação de serviço:

curl -X POST https://carchost.fieldcontrol.com.br/tickets \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "name": "Luiz Freneda",
    "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas posuere eget tellus vitae malesuada. Duis consequat pulvinar tincidunt. Aenean in enim tincidunt, auctor mauris a, tincidunt turpis.",
    "subject": "Manutenção preventiva",
    "contact": {
      "email": "email@fieldcontrol.com.br",
      "phone": "11963427191"
    }
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "M2JlYTAyNDctODAyNC00Mzc5LTkwNWQtYTM5ZWRhYWMzM2NmOjE=",
  "name": "Luiz Freneda",
  "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas posuere eget tellus vitae malesuada. Duis consequat pulvinar tincidunt. Aenean in enim tincidunt, auctor mauris a, tincidunt turpis.",
  "subject": "Manutenção preventiva",
  "contact": {
    "email": "email@fieldcontrol.com.br",
    "phone": "11963427191"
  }
}

Recuperar uma solicitação de serviço

Recupera uma solicitação de serviço existente por id

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/tickets/:id
Status CodeDescrição
200Solicitação de serviço recuperada com sucesso
404Solicitação de serviço não encontrada
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar uma solicitação de serviço:

curl -X GET https://carchost.fieldcontrol.com.br/tickets/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "id": "ZTg1ZGRkYjctNWU0NS00MDg3LWIxODgtNTVjNGNmNTQ2NWFlOjE=",
  "name": "Luiz Freneda",
  "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas posuere eget tellus vitae malesuada. Duis consequat pulvinar tincidunt. Aenean in enim tincidunt, auctor mauris a, tincidunt turpis.",
  "subject": "Manutenção preventiva",
  "contact": {
    "email": "email@fieldcontrol.com.br",
    "phone": "11963427191"
  }
}

Atualizar uma solicitação de serviço

Atualiza uma solicitação de serviço existente

MétodoEndpoint
PUThttps://carchost.fieldcontrol.com.br/tickets/:id
Status CodeDescrição
200Solicitação de serviço atualizada com sucesso
422Solicitação de serviço enviada contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para atualização de uma solicitação de serviço:

curl -X PUT https://carchost.fieldcontrol.com.br/tickets/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "name": "Renan",
    "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas posuere eget tellus vitae malesuada. Duis consequat pulvinar tincidunt. Aenean in enim tincidunt, auctor mauris a, tincidunt turpis.",
    "subject": "Manutenção mensal",
    "contact": {
      "email": "renan@field.com.br",
      "phone": "17993528763"
    }
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "M2JlYTAyNDctODAyNC00Mzc5LTkwNWQtYTM5ZWRhYWMzM2NmOjE=",
  "name": "Renan",
  "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas posuere eget tellus vitae malesuada. Duis consequat pulvinar tincidunt. Aenean in enim tincidunt, auctor mauris a, tincidunt turpis.",
  "subject": "Manutenção mensal",
  "contact": {
    "email": "renan@field.com.br",
    "phone": "17993528763"
  }
}

Listar solicitações de serviço

Lista solicitações de serviço existentes

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/tickets/
Status CodeDescrição
200Solicitações de serviço recuperadas com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Filtros disponíveis para a listagem de solicitações de serviço:

ParâmetroDescrição
archivedArquivado
identifierIdentificador da solicitação de serviço
nameNome do cliente da solicitação de serviço

Exemplo de requisição para recuperar lista de solicitações de serviço:

curl -X GET https://carchost.fieldcontrol.com.br/tickets \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "MTgxYzhmMzQtMGJjMC00ODQwLWI5OTEtMDFlNzFjMWM5Nzk0OjE=",
      "name": "Eduardo Zagari",
      "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "subject": "Limpeza",
      "identifier": "15987264",
      "contact": {
        "email": "eduardo.zagari@fieldcontrol.com.br",
        "phone": "11963427098"
      }
    },
    {
      "id": "MWEwMWQzYjItZDcwMC00MjYzLTljNTktNDI0ZWMwMTFkYmRhOjE=",
      "name": "Nicola Zagari",
      "message": "Bacon ipsum dolor amet shoulder leberkas tenderloin cupim. Meatball chuck turkey biltong short loin. Boudin burgdoggen alcatra, pork belly flank ground round sausage frankfurter doner pig ham hock spare ribs drumstick.",
      "subject": "Limpeza",
      "identifier": "15987266",
      "contact": {
        "email": "zagari@fieldcontrol.com.br",
        "phone": "11963427098"
      }
    }
  ],
  "totalCount": 2
}

Atividades

Atividades 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.

Parâmetros

NomeTipoDescrição
idstringIdentificador da atividade
order.idstringIdentificador da ordem de serviço (somente leitura)
employee.idstringIdentificador do colaborador associado
archivedbooleanArquivado (somente leitura)
duration*integerDuração da atividade
position*integerPosição da atividade referente às outras atividades previamente cadastradas
status*stringEstado da atividade. Os valores possíveis são: scheduled, in-progess, done, canceled ou reported
startedAtstringData e hora de início da atividade (somente leitura)
completedAtstringData e hora de fechamento da atividade (somente leitura)
statusDescriptionstringDescrição de fechamento da atividade, por exemplo, detalhes dados pelo técnico sobre a atividade realizada
scheduling.type*stringTipo do agendamento. Os possíveis valores são: scheduled-date e scheduled-date-and-time
scheduling.date*stringData de agendamento da atividade
scheduling.timestringHora de agendamento da atividade (HH:mm)
coords.latitude*floatLatitude - Coordenada geográfica do local de atendimento
coords.longitude*floatLongitude - Coordenada geográfica do local de atendimento
createdAtstringData de criação da atividade (somente leitura)
receivedAtstringData de recebimento da atividade no app do colaborador (somente leitura)
viewedAtstringData de visualização da atividade pelo colaborador (somente leitura)

Atenção: As propriedades com * são obrigatórias

Recuperar uma atividade

Recupera uma atividade existente pelo identificador

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/tasks/:id
Status CodeDescrição
200Atividade recuperada com sucesso
404Atividade não encontrada
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar uma atividade:

curl -X GET https://carchost.fieldcontrol.com.br/tasks/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "id": "YTNhYjFmOGEtYTU4MS00OTg0LWJkOTYtNjhmYWIwNzI5OWRhOjE=",
  "duration": 60,
  "position": 1,
  "archived": false,
  "status": "scheduled",
  "startedAt": null,
  "completedAt": null,
  "statusDescription": null,
  "order": {
    "id": "MTox"
  },
  "employee": {
    "id": "Mzox"
  },
  "scheduling": {
    "type": "scheduled-date",
    "date": null,
    "time": null
  },
  "coords": {
    "latitude": -23.573005,
    "longitude": -46.695866
  },
  "createdAt": "2020-05-30T09:23:14Z",
  "receivedAt": "2020-05-30T09:24:36Z",
  "viewedAt": "2020-05-30T09:30:12Z"
}

Listar atividades

Lista atividades

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/tasks
Status CodeDescrição
200Atividades recuperados com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Filtros disponíveis para a listagem de atividades:

ParâmetroOperadoresDescrição
archivedNenhumArquivada
created_at>=, <=, > e <Data de criação da atividade
scheduled_date>=, <=, > e <Data de agendamento da atividade
statusNenhumSituação da atividade

Exemplo de requisição para recuperar lista de atividades:

curl -X GET https://carchost.fieldcontrol.com.br/tasks \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "NzFhYzUxNjYtNDNmYS00MGY4LWE1ZmMtOTE1MjZmNjJmZWM1OjE=",
      "duration": 60,
      "position": 1,
      "archived": false,
      "status": "scheduled",
      "startedAt": null,
      "completedAt": null,
      "statusDescription": null,
      "order": {
        "id": "MTox"
      },
      "employee": {
        "id": "Mzox"
      },
      "scheduling": {
        "type": "scheduled-date",
        "date": null,
        "time": null
      },
      "coords": {
        "latitude": -23.573005,
        "longitude": -46.695866
      },
      "createdAt": "2020-03-26T09:37:15Z",
      "receivedAt": null,
      "viewedAt": null
    },
    {
      "id": "YTNhYjFmOGEtYTU4MS00OTg0LWJkOTYtNjhmYWIwNzI5OWRhOjE=",
      "duration": 60,
      "position": 1,
      "archived": false,
      "status": "scheduled",
      "startedAt": null,
      "completedAt": null,
      "statusDescription": null,
      "order": {
        "id": "MTox"
      },
      "employee": {
        "id": "Mzox"
      },
      "scheduling": {
        "type": "scheduled-date",
        "date": null,
        "time": null
      },
      "coords": {
        "latitude": -23.573005,
        "longitude": -46.695866
      },
      "createdAt": "2020-02-25T12:56:00Z",
      "receivedAt": null,
      "viewedAt": null
    }
  ],
  "totalCount": 2
}

Valores disponíveis para ordenação de resultados:

ValorDescrição
created_atData de criação em ordem ascendente
-created_atData de criação em ordem descendente
scheduled_dateData de agendamento em ordem ascendente
-scheduled_dateData de agendamento em ordem descendente

Tipos de atividades

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

Parâmetros

NomeTipoDescrição
id*stringIdentificador
name*stringNome do tipo de atividade
duration*integerDuração estimada
archived*booleanIndica se o tipo de atividade está arquivado

Usuários com perfil de administrador podem gerenciar os tipos de atividades no Painel de gestão pelo link: https://app.fieldcontrol.com.br/#/tipos-de-atividade

Criar um tipo de atividade

Cria um novo tipo de atividade

MétodoEndpoint
POSThttps://carchost.fieldcontrol.com.br/services/
Status CodeDescrição
201Tipo de atividade criado com sucesso
422Tipo de atividade enviado contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para criação de um tipo de atividade:

curl -X POST https://carchost.fieldcontrol.com.br/services \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "name": "Instalação manual",
    "duration": 120
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "MzUxMzE6MjI5MTU=",
  "name": "Reparo",
  "duration": 120,
  "archived": false
}

Recuperar um tipo de atividade

Recupera um tipo de atividade existente por id

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/services/:id
Status CodeDescrição
200Tipo de atividade recuperado com sucesso
404Tipo de atividade não encontrado
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar um tipo de atividade:

curl -X GET https://carchost.fieldcontrol.com.br/services/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "id": "MzA0ODY6MjI5MTU=",
  "name": "Reforma",
  "duration": 240,
  "archived": false
}

Atualizar um tipo de atividade

Atualiza um tipo de atividade existente

MétodoEndpoint
PUThttps://carchost.fieldcontrol.com.br/services/:id
Status CodeDescrição
200Tipo de atividade atualizado com sucesso
422Tipo de atividade enviado contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para atualização de um tipo de atividade:

curl -X PUT https://carchost.fieldcontrol.com.br/services/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "name": "Reforma",
    "duration": 240
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "MzA0ODY6MjI5MTU=",
  "name": "Reforma",
  "duration": 240,
  "archived": false
}

Listar tipos de atividade

Lista tipos de atividade existentes

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/services/
Status CodeDescrição
200Tipos de atividade recuperadas com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Filtros disponíveis para a listagem de tipos de atividade:

ParâmetroDescrição
archivedArquivado
nameNome do tipo de atividade

Exemplo de requisição para recuperar lista de tipos de atividade:

curl -X GET https://carchost.fieldcontrol.com.br/services \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "MzA0ODY6MjI5MTU=",
      "name": "Reforma",
      "duration": 240,
      "archived": false
    }
  ],
  "totalCount": 1
}

Ordem de Serviço (OS)

Uma ordem de serviço é 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.

O conteúdo de uma OS varia conforme a atividade exercida por sua empresa e o próprio serviço que será executado. Mas há algumas informações básicas e essenciais presentes em todo documento. Veja quais são elas:

Parâmetros

NomeTipoDescrição
idstringId da ordem de serviço
identifier*stringIdentificador da ordem de serviço, deve ser único entre todas as ordens de serviço
archivedbooleanIndica se a ordem de serviço está arquivada (somente leitura)
descriptionstringDescrição da ordem de serviço, por exemplo, detalhes da OS inseridos pelo gestor e que o técnico deve levar em consideração ao atender a OS
customer.id*stringId do cliente associado
service.id*stringId do serviço a ser prestado
address.zipCode*stringCEP - Código de endereçamento postal (apenas números)
address.city*stringNome da cidade refente ao CEP
address.state*stringNome do estado referente ao CEP
address.neighborhoodstringNome do bairro referente ao CEP
address.street*stringNome do logradouro
address.number*stringNúmero da residência/prédio
address.complementstringInformação adicional do endereço
address.coords.latitude*floatLatitude - Coordenada geográfica do local de atendimento
address.coords.longitude*floatLongitude - Coordenada geográfica do local de atendimento
createdAtstringData de criação da ordem de serviço (somente leitura)
tasksarrayAtividade(s) associada(s) à ordem de serviço. É necessário somente ao cadastrar uma nova ordem de serviço

Criar uma ordem de serviço

Cria uma nova ordem de serviço.

MétodoEndpoint
POSThttps://carchost.fieldcontrol.com.br/orders/
Status CodeDescrição
201Ordem de serviço criada com sucesso
422Ordem de serviço enviada contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Para criar uma ordem de serviço, é necessário criar ao menos uma atividade.

Exemplo de requisição para criação de uma ordem de serviço:

curl -X POST https://carchost.fieldcontrol.com.br/orders \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "identifier": "695860",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas posuere eget tellus vitae malesuada. Duis consequat pulvinar tincidunt. Aenean in enim tincidunt, auctor mauris a, tincidunt turpis.",
    "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
        }
      }
    ]
  }' \
  --compressed

Para facilitar, é possível definir um cliente (customer) e/ou um tipo de atividade (service) por nome na requisição.

Exemplo de requisição para criação de uma ordem de serviço com cliente (customer) e tipo de atividade (service) definidos por nome:

curl -X POST https://carchost.fieldcontrol.com.br/orders \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "identifier": "695860",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas posuere eget tellus vitae malesuada. Duis consequat pulvinar tincidunt. Aenean in enim tincidunt, auctor mauris a, tincidunt turpis.",
    "customer": {
      "name": "Luiz Freneda"
    },
    "service": {
      "name": "Instalação de Ar Condicionado"
    },
    "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
        }
      }
    ]
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "NDJiMWQ0YzQtOWNmOC00NWE2LTg2MjItYjNjNzZjZjk0MmM4OjE=",
  "identifier": "695860",
  "description": "Pork chop salami sausage bresaola turkey. Picanha tri-tip turkey, pork loin rump salami strip steak hamburger kevin cow shank leberkas. Andouille pastrami pig tongue, short ribs spare ribs rump.",
  "archived": false,
  "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
    }
  },
  "createdAt": "2020-06-12T12:00:15Z",
  "tasks": [
    {
      "order": {
        "id": "ZmY1Y2MwOWQtNjAzZi00NmQxLWJiYjUtNDE1OGU3MTEzNmQ1OjE="
      },
      "employee": {
        "id": "MTAxOjE="
      },
      "status": "done",
      "startedAt": "2020-02-29T11:38:54Z",
      "completedAt": "2020-02-29T12:12:26Z",
      "duration": 30,
      "scheduling": {
        "date": "2019-08-20",
        "time": "15:00:00"
      },
      "coords": {
        "latitude": -23.52702,
        "longitude": -46.680823
      }
    }
  ]
}

Recuperar uma ordem de serviço

Recupera uma ordem de serviço existente por id

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/orders/:id
Status CodeDescrição
200Ordem de serviço recuperada com sucesso
404Ordem de serviço não encontrada
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar uma ordem de serviço:

curl -X GET https://carchost.fieldcontrol.com.br/orders/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "id": "NTVlMzYxMTktZWJiZi00YmE5LTkzM2YtM2Q5MWU1NjlmMjliOjE=",
  "identifier": "695861",
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas posuere eget tellus vitae malesuada. Duis consequat pulvinar tincidunt. Aenean in enim tincidunt, auctor mauris a, tincidunt turpis.",
  "archived": false,
  "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.527028,
      "longitude": -46.680823
    }
  },
  "createdAt": "2020-06-12T13:20:15Z"
}

Atualizar uma ordem de serviço

Atualiza uma ordem de serviço existente

MétodoEndpoint
PUThttps://carchost.fieldcontrol.com.br/orders/:id
Status CodeDescrição
200Ordem de serviço atualizada com sucesso
422Ordem de serviço enviada contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para atualização de uma ordem de serviço:

curl -X PUT https://carchost.fieldcontrol.com.br/orders/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "identifier": "695869",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas posuere eget tellus vitae malesuada. Duis consequat pulvinar tincidunt. Aenean in enim tincidunt, auctor mauris a, tincidunt turpis.",
    "customer": {
      "id": "MTox"
    },
    "service": {
      "id": "MTox"
    },
    "address": {
      "zipCode": "15057560",
      "street": "Avenida Brasil",
      "number": "898",
      "neighborhood": null,
      "complement": null,
      "city": "Rio de Janeiro",
      "state": "RJ",
      "coords": {
        "latitude": -23.573005,
        "longitude": -46.695866
      }
    }
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "NTVlMzYxMTktZWJiZi00YmE5LTkzM2YtM2Q5MWU1NjlmMjliOjE=",
  "identifier": "695869",
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas posuere eget tellus vitae malesuada. Duis consequat pulvinar tincidunt. Aenean in enim tincidunt, auctor mauris a, tincidunt turpis.",
  "archived": false,
  "customer": {
    "id": "MTox"
  },
  "service": {
    "id": "MTox"
  },
  "address": {
    "zipCode": "15057560",
    "street": "Avenida Brasil",
    "number": "898",
    "neighborhood": null,
    "complement": null,
    "city": "Rio de Janeiro",
    "state": "RJ",
    "coords": {
      "latitude": -23.573005,
      "longitude": -46.695866
    }
  },
  "createdAt": "2020-06-12T16:00:00Z",
}

Listar ordens de serviço

Lista ordens de serviço existentes

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/orders/
Status CodeDescrição
200Ordens de serviços recuperadas com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Filtros disponíveis para a listagem de ordens de serviço:

ParâmetroOperadoresDescrição
identifierNenhumIdentificador da ordem de serviço
customer_idNenhumIdentificador do cliente da ordem de serviço
service_idNenhumIdentificador do tipo de atividade da ordem de serviço
created_at>=, <=, > e <Data de criação da ordem de serviço

Exemplo de requisição para recuperar lista de ordens de serviço:

curl -X GET https://carchost.fieldcontrol.com.br/orders \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "MDRlYjVjY2YtZjBmZC00NjBjLTk2NWItOWI3MDBiNGJiYjgxOjE=",
      "identifier": "695865",
      "archived": false,
      "description": null,
      "customer": {
        "id": "MTox"
      },
      "service": {
        "id": "MTox"
      },
      "address": {
        "zipCode": "15085480",
        "street": "Rua dos Pinheiros",
        "number": "383",
        "neighborhood": null,
        "complement": null,
        "city": "Sao paulo",
        "state": "SP",
        "coords": {
          "latitude": "-23.573005",
          "longitude": "-46.695866"
        }
      },
      "createdAt": "2020-06-12T12:00:15Z"
    },
    {
      "id": "MDRlYjVjY2YtZjBmZC00NjBjLTk2NWItOWI3MDBiNGJiYjgyOjE=",
      "identifier": "695866",
      "description": null,
      "archived": false,
      "customer": {
        "id": "MTox"
      },
      "service": {
        "id": "MTox"
      },
      "address": {
        "zipCode": "15085480",
        "street": "Rua dos Pinheiros",
        "number": "383",
        "neighborhood": null,
        "complement": null,
        "city": "Sao paulo",
        "state": "SP",
        "coords": {
          "latitude": "-23.573005",
          "longitude": "-46.695866"
        }
      },
      "createdAt": "2020-06-12T12:00:15Z",
    }
  ],
  "totalCount": 205
}

Valores disponíveis para ordenação de resultados:

ValorDescrição
created_atData de criação em ordem ascendente
-created_atData de criação em ordem descendente

Criar uma atividade

Cria uma nova atividade para ordem de serviço

MétodoEndpoint
POSThttps://carchost.fieldcontrol.com.br/orders/:order_id/tasks
Status CodeDescrição
201Atividade criado com sucesso
422Atividade enviada contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para criação de uma atividade:

curl -X POST https://carchost.fieldcontrol.com.br/orders/:order_id/tasks \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "duration": 120,
    "position": 1,
    "status": "reported",
    "statusDescription": "O associado não atende as ligações",
    "employee": {
      "id": "MTox"
    },
    "scheduling": {
      "type": "scheduled-date",
      "date": "2019-07-01"
    },
    "coords": {
      "latitude": -20.811812,
      "longitude": -49.382726
    }
  }' \
  --compressed

Na criação da atividade é possível definir o colaborador (employee) por nome na requisição.

Exemplo de requisição para criação de uma atividade com colaborador (employee) definido por nome:

curl -X POST https://carchost.fieldcontrol.com.br/orders/:order_id/tasks \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "duration": 120,
    "position": 1,
    "status": "done",
    "employee": {
      "name": "Ronaldo Gaúcho"
    },
    "scheduling": {
      "type": "scheduled-date",
      "date": "2019-07-01"
    },
    "coords": {
      "latitude": -20.811812,
      "longitude": -49.382726
    }
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "ZDk5MDVmYTAtYzRhOC00MTY4LWI5NjgtNTUxZDJjZTIyN2ZmOjIyOTE1",
  "duration": 120,
  "position": 1,
  "status": "done",
  "archived": false,
  "startedAt": "2020-02-29T11:38:54Z",
  "completedAt": "2020-02-29T12:12:26Z",
  "statusDescription": null,
  "order": {
    "id": "MTox"
  },
  "employee": {
    "id": "NDoyMjkxNQ=="
  },
  "scheduling": {
    "type": "scheduled-date",
    "date": "2019-07-01",
    "time": null
  },
  "coords": {
    "latitude": -20.811812,
    "longitude": -49.382726
  },
  "createdAt": "2020-06-13T18:25:00Z",
  "receivedAt": null,
  "viewedAt": null
}

Recuperar uma atividade de uma OS

Recupera uma atividade de uma ordem de serviço

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/orders/:order_id/tasks/:task_id
Status CodeDescrição
200Atividade recuperada com sucesso
404Atividade não encontrada
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar uma atividade:

curl -X GET https://carchost.fieldcontrol.com.br/orders/:order_id/tasks/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "id": "YTNhYjFmOGEtYTU4MS00OTg0LWJkOTYtNjhmYWIwNzI5OWRhOjE=",
  "duration": 60,
  "position": 1,
  "archived": false,
  "status": "scheduled",
  "startedAt": null,
  "completedAt": null,
  "statusDescription": null,
  "order": {
    "id": "MTox"
  },
  "employee": {
    "id": "Mzox"
  },
  "scheduling": {
    "type": "scheduled-date",
    "date": null,
    "time": null
  },
  "coords": {
    "latitude": -23.573005,
    "longitude": -46.695866
  },
  "createdAt": "2020-05-30T09:23:14Z",
  "receivedAt": "2020-05-30T09:32:48Z",
  "viewedAt": null
}

Atualizar uma atividade

Atualiza uma atividade existente de uma ordem de serviço

MétodoEndpoint
PUThttps://carchost.fieldcontrol.com.br/orders/:order_id/tasks/:id
Status CodeDescrição
200Atividade atualizada com sucesso
422Atividade enviada contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para atualização de uma atividade:

curl -X POST https://carchost.fieldcontrol.com.br/orders/:order_id/tasks/:id \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here' \
  --data-binary \
  '{
    "duration": 120,
    "position": 1,
    "status": "done",
    "employee": {
      "name": "Ronaldo Gaúcho"
    },
    "scheduling": {
      "type": "scheduled-date",
      "date": "2019-07-01"
    },
    "coords": {
      "latitude": -20.811812,
      "longitude": -49.382726
    }
  }' \
  --compressed

Exemplo de resposta de sucesso:

{
  "id": "ZDk5MDVmYTAtYzRhOC00MTY4LWI5NjgtNTUxZDJjZTIyN2ZmOjIyOTE1",
  "duration": 120,
  "position": 1,
  "archived": false,
  "status": "done",
  "startedAt": "2020-02-29T11:38:54Z",
  "completedAt": "2020-02-29T12:12:26Z",
  "statusDescription": null,
  "order": {
    "id": "MTox"
  },
  "employee": {
    "id": "NDoyMjkxNQ=="
  },
  "scheduling": {
    "type": "scheduled-date",
    "date": "2019-07-01",
    "time": null
  },
  "coords": {
    "latitude": -20.811812,
    "longitude": -49.382726
  },
  "createdAt": "2020-04-01T10:40:39Z",
  "receivedAt": "2020-04-01T10:42:48Z",
  "viewedAt": null
}

Listar atividades de uma OS

Lista atividades de uma ordem de serviço

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/orders/:order_id/tasks
Status CodeDescrição
200Atividades recuperados com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Filtros disponíveis para a listagem de atividades:

ParâmetroOperadoresDescrição
archivedNenhumArquivada
created_at>=, <=, > e <Data de criação da atividade
scheduled_date>=, <=, > e <Data de agendamento da atividade
statusNenhumSituação da atividade

Exemplo de requisição para recuperar lista de atividades:

curl -X GET https://carchost.fieldcontrol.com.br/orders/:order_id/tasks \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "NzFhYzUxNjYtNDNmYS00MGY4LWE1ZmMtOTE1MjZmNjJmZWM1OjE=",
      "duration": 60,
      "position": 1,
      "archived": false,
      "status": "scheduled",
      "startedAt": null,
      "completedAt": null,
      "statusDescription": null,
      "order": {
        "id": "MTox"
      },
      "employee": {
        "id": "Mzox"
      },
      "scheduling": {
        "type": "scheduled-date",
        "date": null,
        "time": null
      },
      "coords": {
        "latitude": -23.573005,
        "longitude": -46.695866
      },
      "createdAt": "2020-03-26T09:37:15Z",
      "receivedAt": null,
      "viewedAt": null
    },
    {
      "id": "YTNhYjFmOGEtYTU4MS00OTg0LWJkOTYtNjhmYWIwNzI5OWRhOjE=",
      "duration": 60,
      "position": 1,
      "archived": false,
      "status": "scheduled",
      "startedAt": null,
      "completedAt": null,
      "statusDescription": null,
      "order": {
        "id": "MTox"
      },
      "employee": {
        "id": "Mzox"
      },
      "scheduling": {
        "type": "scheduled-date",
        "date": null,
        "time": null
      },
      "coords": {
        "latitude": -23.573005,
        "longitude": -46.695866
      },
      "createdAt": "2020-02-25T12:56:00Z",
      "receivedAt": null,
      "viewedAt": null
    }
  ],
  "totalCount": 2
}

Valores disponíveis para ordenação de resultados:

ValorDescrição
created_atData de criação em ordem ascendente
-created_atData de criação em ordem descendente
scheduled_dateData de agendamento em ordem ascendente
-scheduled_dateData de agendamento em ordem descendente

Anexos

Anexos são as imagens de uma ordem de serviço.

Parâmetros

NomeTipoDescrição
idstringIdentificador do anexo
path*stringCaminho do arquivo
titlestringTítulo do anexo
createdAtstringData e hora da criação do anexo (somente leitura)

Listar anexos

Lista anexos existentes para uma ordem de serviço

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/orders/:order_id/attachments
Status CodeDescrição
200Anexos recuperados com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar lista de anexos de uma ordem de serviço:

curl -X GET https://carchost.fieldcontrol.com.br/orders/:order_id/attachments \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "MTM3ODkyMTM6MQ==",
      "path": "https://s3.amazonaws.com/attachments.fieldcontrol.com.br/accounts/12/orders/f270e1c3-b8fa-4b4e-a0b5-48be831326fa/tasks/1efda45c-ddb8-4eab-8a40-c744507c123b/hgP2sCZNn.jpg",
      "title": "Limpeza do ar condicionado",
      "createdAt": "2018-08-27T15:30:15.000Z",
      "task": {
        "id": "YmY5Y2E2ZjktNjExYS00YzE5LTkwMTktYzllZjZhZWI2OTkzOjE="
      }
    }
  ],
  "totalCount": 1
}

Comentários

Comentários são informações adicionais anexadas a uma ordem de serviço. Elas são usadas para registrar eventos e facilitar a comunicação entre gestores e colaboradores externos.

Parâmetros

NomeTipoDescrição
idstringIdentificador do comentário
employee.idstringIdentificador do colaborador
user.idstringIdentificador do usuário
message*stringMensagem do comentário
archivedbooleanSe o comentário está ou não arquivado e seu valor padrão é "false"

Listar comentários

Lista comentários existentes para uma ordem de serviço

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/orders/:order_id/comments
Status CodeDescrição
200Comentários recuperados com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar lista de comentários de uma ordem de serviço:

curl -X GET https://carchost.fieldcontrol.com.br/orders/:orders_id/comments \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "NmVjMTUzNGEtZDNmMC00MzQ0LWIzMWMtM2YxYWU2NDIwNDZiOjE=",
      "message": "A manutenção foi bem feita.",
      "archived": false,
      "employee": null,
      "user": null
    },
    {
      "id": "YzBjYTM0NGEtZTAzMC00NjU5LWFjOTYtMzY0MjViMjQ0NjNhOjE=",
      "message": "O técnico foi rápido",
      "archived": false,
      "employee": null,
      "user": null
    }
  ],
  "totalCount": 2
}

Formulários

Formulários são informações estruturadas por perguntas e respostas usadas para coletar e organizar informações sobre uma ordem de serviço

Parâmetros

NomeTipoDescrição
idstringIdentificador do formulário
name*stringNome do formulário
archived*booleanSe o formulário está arquivado ou não
questions*arrayTodas as perguntas do formulário
questions.type*stringTipo de resposta da pergunta. Os valores possíveis são: picture, short-answer, paragraph, dropdown, multiple-choice, checkboxes, numeric ou date.
questions.position*integerPosição que a pergunta deve ter dentre outras perguntas
questions.required*booleanSe a pergunta é obrigatória ou não
questions.title*stringTítulo da pergunta
questions.answer*stringResposta da pergunta
questions.optionsarrayTodas as opções de resposta para uma pergunta
questions.options.value*stringValor de uma opção de resposta para a pergunta
questions.options.position*stringPosição que a opção deve ter dentre outras opções

Recuperar um formulário

Recupera um formulário respondido existente por id

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/orders/:order_id/forms/:id
Status CodeDescrição
200Formulário recuperado com sucesso
404Formulário não encontrado
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar um formulário:

curl -X GET https://carchost.fieldcontrol.com.br/orders/:order_id/forms/ZTg1ZGRkYjctNWU0NS00MDg3LWIxODgtNTVjNGNmNTQ2NWFlOjE= \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "id": "NzU4MjJmYWItY2M0My00MWJlLWE1N2UtN2YzYjZlN2IxZDIxOjE=",
  "name": "Instalação de Internet",
  "archived": false,
  "questions": [
    {
      "type": "multiple-choice",
      "position": 1,
      "required": true,
      "title": "Qual era o meio de acesso à internet que o cliente possuía?",
      "answer": "ADSL",
      "options": [
        {
          "position": 1,
          "value": "ADSL"
        },
        {
          "position": 2,
          "value": "Fibra Ótica"
        },
        {
          "position": 3,
          "value": "Via Rádio"
        }
      ]
    },
    {
      "type": "short-answer",
      "position": 2,
      "required": false,
      "title": "Qual era a operadora de internet?",
      "answer": "NET"
    }
  ]
}

Listar formulários

Lista formulários respondidos existentes para uma ordem de serviço

MétodoEndpoint
GEThttps://carchost.fieldcontrol.com.br/orders/:order_id/forms
Status CodeDescrição
200Formulários respondidos recuperados com sucesso
422Requisição contém informações inválidas

Para retornos com http status code 422, um objeto de erro é retornado como resposta contendo uma descrição detalhada do erro ocorrido.

Exemplo de requisição para recuperar lista de formulários de uma ordem de serviço:

curl -X GET https://carchost.fieldcontrol.com.br/orders/:order_id/forms \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'X-Api-Key: token-here'

Exemplo de resposta de sucesso:

{
  "items": [
    {
      "id": "MDNiNDdhYTgtNzAxNC00NGEzLWJhYjItMTRjMjBjODQ1YTViOjE=",
      "name": "Instalação de ar-condicionado",
      "archived": false,
      "createdAt": "2019-08-07T11:10:45.366Z"
    },
    {
      "id": "NTA3ZjFiMWYtZDUzZC00MTdkLWFkMzAtNDE4ZjA2ZmZhYjQxOjE=",
      "name": "Instalação de internet",
      "archived": false,
      "createdAt": "2019-08-07T13:21:23.337Z"
    }
  ],
  "totalCount": 2
}

Webhooks

Webhooks são uma forma de uma aplicação fornecer informações em tempo real para outras aplicações.

As webhooks são frequentemente chamadas de API callback ou simplesmente notificações.

No Field Control você pode receber webhooks de diferentes tipos de eventos referentes a sua operação, como um formulário respondido ou uma visita concluída.

Sendo assim, as webhooks foram criados para permitir que seu sistema seja atualizado em tempo real sobre os principais eventos que ocorrem no Field Control.

Confira abaixo os eventos disponíveis:

EventoDescrição
order-form-createdCriação de um formulário
order-form-updatedAtualização de um formulário
order-attachment-createdCriação de um anexo
order-attachment-updatedAtualização de um anexo
order-createdCriação de uma ordem de serviço
order-updatedAtualização de uma ordem de serviço
task-createdCriação de uma atividade
task-updatedAtualização de uma atividade
task-startedAtividade iniciada pelo colaborador
task-reportedImpedimento da realização de alguma atividade
task-completedAtividade concluída com sucesso
task-ratedAvaliação de uma atividade
comment-createdCriação de um comentário
employee-createdCriação de um novo colaborador

Delivery Headers

Quando um desses eventos acontecer, será disparado uma requisição HTTP POST para a URL configurada via painel de gestão com os seguintes headers:

HeaderDescrição
X-FieldControl-EventNome do evento que foi disparado
X-FieldControl-DeliveryId único do envio
Content-TypeFormato do conteúdo da requisição, sempre será: application/json

Resumindo

Basicamente, ao receber um evento de webhook a aplicação consumidora deve:

Cada X-FieldControl-Event terá um request body correspondente. Por exemplo, para eventos do tipo task-created, o corpo da requisição será uma visita, para comment-created, o corpo será um comentário e assim por diante.

Como configuro a URL pelo painel de gestão?

Para definir a URL que receberá os eventos do Field Control, acesse o painel de gestão na seção "Webhooks integração" e clique no link correspondente ao da imagem abaixo.

Em seguida, defina a URL que você deseja e o método de autenticação caso exista.

Sem autenticaçãoCom autenticação

Pronto! Sua URL foi configurada.

Histórico de eventos

No painel de gestão você pode acompanhar os registros de todas as requisições feitas para sua URL com informações do evento. Na tela, são mostrados: o identificador da requisição, o evento e a data e hora de envio da requisição.

Para ver mais detalhes da requisição, você pode clicar no botão localizado na coluna Ver detalhes. Na aba Requisição, é possível visualizar as informações de cabeçalho e corpo da requisição.

Na aba Resposta, você pode visualizar as informações de resposta da sua aplicação.

Como no exemplo foi utilizado uma URL fictícia, o corpo da resposta sempre será um código de erro.

Serviços de Geolocalização

Coordenadas geográficas são dados obrigatórios no cadastro de um cliente dentro do Field Control.

Através dessa informação será possível estimar as visitas na linha do tempo e também ter a visão geográfica no mapa.

Caso você não possua dados de geolocalização (latitude/longitude) dos seus clientes e queira obtê-los para utilizar todos os recursos compatíveis do Field Control, existem algumas APIs de serviços de geolocalização que disponibilizam esses dados de forma gratuita.

Veja os principais serviços do mercado para que você possa integrar com seu sistema:

Google Maps

O serviço de mapas do Google é o mais popular dentre todos os outros serviços. Ele conta com uma ótima documentação, cota gratuita de utilização, além de seguir a conhecida qualidade dos serviços da empresa.

PreçoRequisições/segundoDocumentação
US$5,00 a cada 1000
Fornece US$200,00/mês para utilizar
Saiba mais
50Geocoding API

Azure Maps

O Azure Maps é um serviço de mapas da Microsoft que vem crescendo ao longo do tempo em questão de qualidade e adesão. Ele também oferece uma boa cota gratuita de utilização e uma documentação bem detalhada.

PreçoRequisições/segundoDocumentação
250.000 transações/mês
Para camada de serviço "Standard S0"
Saiba mais
50Maps Search API

HERE

O HERE já está no mercado há um tempo, fundado em 2012 pela Nokia, antiga proprietária. Atualmente, BMW, Audi e Daimler são proprietários da empresa e seus carros utilizam o serviço. Ele oferece uma boa cota gratuita de utilização e uma ótima documentação.

PreçoRequisições/segundoDocumentação
250.000 transações/mês
Para contas Freemium
Saiba mais
1Geocoding API