Objetivos 

Determinar os serviços que serão consumidos aplicativo Minha Gestão de Postos.

GET /rest/supervisorgs/checkin

Retorna a lista dos apontamentos disponíveis.

Parâmetros aceitos

Os parâmetros serão passados por queryParams e poderão ser utilizados em conjunto. Caso haja mais de um parâmetro enviado, a lógica utilizada dever ser "E".

Retorno

O serviço deve retornar as propriedades informadas, de acordo com os parâmetros passados na consulta.

checkin

checkin[].lat

checkin[].long

checkin[].hr

checkin[].obs

checkin[].selfie

checkin[].additionalphotos

count

Exemplo de retorno da requisição:

GET rest/SUPERVISORGS/checkin?cCode=000000000283&cInOut=1

{
   "checkin": [

1. Informações Gerais

...

Especificação

...

Produto

...

 Microsiga Protheus

...

Módulo

...

...

Segmento Executor

...

 Serviços

...

Projeto

...

IRM

...

Requisito

...

Subtarefa

2. Objetivo

Os serviços especificados neste documento serão consumidos pelo aplicativo TOTVS Supervisor de Postos

3. Definições de Serviços

Todos os serviços devem obedecer às boas práticas de implementação de APIs presentes no Guia de Implementação de APIs TOTVS.

Deve-se tomar um cuidado especial com os retornos da requisição, inserindo o status HTTP correto de acordo com o erro encontrado (não enviar um status http 200 em uma mensagem de erro, por exemplo).

3.1. GET /rest/SUPERVISORGS/checkin

Retorna a lista de checkins disponíveis para consulta, no formato indicado abaixo:

{
    "checkin": [
        {
			"lat": "-23.5083524",
			"long": "-46.6497187",
			"hr": "11:11",
			"obs": "",
			"selfie": “base64 da imagemi”
			"additionalphotos": [
				{Imagem 1},
				{Imagem 2},
				{Imagem 3}
			]
        }
    ],
    "count": 1
}

Descrição dos Campos:

...

{
			"lat": "-23.5083524",
			"long": "-46.6497187",
			"hr": "11:11",
			"obs": ""
			"selfie": “Aqui vem o base64 da imagem”
			"additionalphotos": []
        }
    ],
    "count": 1
}

GET /rest/supervisorgs/appointments

Retorna a lista dos apontaentos na url.

Parâmetros aceitos

Os parâmetros serão passados por queryParams e poderão ser utilizados em conjunto. Caso haja mais de um parâmetro enviado, a lógica utilizada dever ser "E".

Retorno

O serviço deve retornar as propriedades informadas, de acordo com os parâmetros passados na consulta.

appointments

appointments[x].code

appointments[x].attendant

appointments[x].schedule

appointments[x].realschedule

appointments[x].inout

appointments[x].desc

appointments[x].late

appointments[x].executed

GET /rest/SUPERVISORGS/appointments?cStation=00000001&cStart=&cEnd=

{
    "appointments": [
        {
			"code": "000000000283",
			"attendant": "MATHEUS LANDO RAIMUNDO",
			"schedule": "08:00",
			"realschedule": "",
			"inout": "1",
			"desc": "Entrada",
			"late": "1",
			"executed": " "
		},
		{
			"code": "000000000283",
			"attendant": "MATHEUS LANDO RAIMUNDO",
			"schedule": "12:00",
			"realschedule": "",
			"desc": "Saída",
			"late": "2",
			"inout": "2",
			"executed": " "
		}
    ],
    "count": 2
}

GET /rest/supervisorgs/stations

Retorna a lista das estações disponiveis na url.

Parâmetros aceitos

Os parâmetros serão passados por queryParams e poderão ser utilizados em conjunto. Caso haja mais de um parâmetro enviado, a lógica utilizada dever ser "E".

Retorno

O serviço deve retornar as propriedades informadas, de acordo com os parâmetros passados na consulta.

stations

stations[x].code

stations[x].desc

stations[x].type

stations[x].lat

stations[x].long

count

GET rest/SUPERVISORGS/stations?nSituation=3&cStart=&cEnd=&cMinutes=&cClients=&cPlaces=&cRegions

{
    "stations": [
        {
			"code": "00000001",
			"desc": "TOTVS SITE SP",
			"type": "2",
			"lat": "-23.5085024",
			"long": "-46.6527313"
		 }
	],
	"count": 1
}

GET /rest/supervisorgs/clients

Retorna a lista dos clientes disponiveis na url.

Parâmetros aceitos

Retorno

O serviço deve retornar as propriedades informadas, de acordo com os parâmetros passados na consulta.

clients

clients[x].code

clients[x].desc

clients[x].store

clients[x].check

hasNext

count

GET rest/SUPERVISORGS/clients

Parâmetros aceitos:

• page e pageSize

Utilizados para fazer paginação.

A primeira página é a 1.

Se não for enviado um page, considerar a página 1.

Se não for passado um pageSize, considerar o tamanho de página como 10.

TODA requisição de lista deve retornar um atributo hasNext indicando se atingiu a última página ou não.

Exemplos (Supondo que existam 32 registros na base):

• • GET /gct/contracts -> Retorna a página padrão (1) com tamanho padrão (10) (registro do 1 ao 10, hasNext = true)
  • GET /gct/contracts?page=1 -> Retorna a página 1 com tamanho padrão (10) (registro de 1 ao 10, hasNext = true)
  • GET /gct/contracts?pageSize=3 -> Retorna a página padrão (1) com tamanho 3 (registro de 1 ao 3, hasNext = true)
  • GET /gct/contracts?page=2&pageSize=4 -> Retorna a página (2) com tamanho (4) (registro do 5 ao 8, hasNext = true)
  • GET /gct/contracts?page=4&pageSize=10 -> Retorna a página (4) com tamanho (10) (registro do 31 ao 40 -> irá retornar só o 31 e o 32, hasNext = false)
  • etc.

• Filtros

Deve suportar filtrar os resultados de acordo com alguns parâmetros:

• • searchKey: Filtro chave, capaz de filtrar em diversos campos diferentes do contrato, como cliente ou fornecedor, número, descrição, etc (máximo de lugares possíveis).
  • _type: Tipo de contrato, indica se é um contrato de compra (type=1) ou de venda (type=0). Caso não seja informado, retornar todos os tipos.
  • customer: Cliente relacionado ao contrato. Deve ser considerado apenas se o parâmetro type for enviado com o valor 0 (venda).
  • supplier: Fornecedor relacionado ao contrato. Deve ser considerado apenas se o parâmetro type for enviado com o valor 1 (compra).
  • unit: Loja do cliente ou do fornecedor relacionado ao contrato. Deve ser considerado apenas se o parâmetro customer ou supplier for enviado em conjunto.

3.2. GET /wscnta300/contracts/{contractID}/{rev}

Este serviço deve retornar somente um contrato, com os detalhes do mesmo. O contrato que deve ser retornado será indicado pelos parâmetros contractID e rev, presentes na URL da requisição.

Exemplo de chamada: GET /gct/contracts/0192390283/1

Exemplo de retorno:

{
    "number" : "0192390283",
    "rev" : "1",
    "type" : 1,
    "startDate" : "20171103",
    "endDate" : "20180615",
    "description" : "Contrato de Compra fixo",
    "balance": {
        "symbol" : "R$",
        "total" : 43000.1
    },
    "current_value": {
        "symbol" : "R$",
        "total" : 127000
    },
    "spreadsheets" : [
        {
            "number" : "0001",
            "description" : "FIXO/FINANCEIRO",
            "related" : "GRUPO JLIMA",
            "balance" : {
                "symbol" : "R$",
                "total" : 21000.1
            }
        },
        {
            "number" : "0002",
            "description" : "SERVIÇOS",
            "related" : "GRUPO JLIMA",
            "balance" : {
                "symbol" : "R$",
                "total" : 22000
            }
        }
    ]
}

Descrição dos Campos:

• number: Número do contrato
• rev: Revisão do contrato
• type: Tipo de contrato (1=compra e 0=venda)
• startDate: Data de início da vigência
• endDate: Data de fim da vigência
• description: Descrição do contrato
• balance: Objeto do saldo do contrato
• balance.symbol: Símbolo da moeda referente ao saldo retornado
• balance.total: Valor total do saldo do contrato
• current_value: Valor atual do contrato
• current_value.symbol: Símbolo da moeda referente ao valor atual retornado
• current_value.total: Valor total do valor atual do contrato
• spreadsheets: Array com as planilhas do contrato
• spreadsheets[n].number: Número da planilha
• spreadsheets[n].description: Descrição da planilha
• spreadsheets[n].related: Cliente ou fornecedor relacionado à planilha
• spreadsheets[n].balance: Objeto do saldo da planilha
• spreadsheets[n].balance.symbol: Símbolo da moeda referente ao saldo retornado
• spreadsheets[n].balance.total: Valor total do saldo da planilha

Parâmetros aceitos:

Este endpoint não irá aceitar nenhum parâmetro.

3.3. GET /wscnta300/customers

Retorna a lista de clientes disponíveis para filtrar os contratos exibidos, no seguinte formato:

{
    "hasNext": true,
    "clients": [
        {
            "id			"code": "0000001001",
            "name			"store": "TOTVS SA01",
            "unit			"check": "01false",
			"desc":        "CLIENTE 001"
		},
        {
            "id		{
			"code": "0000002000001",
            "name			"store": "OUTRO CLIENTE01",
            "unit			"check": "false",
			"desc": "CLIENTE PADRAO P/ ORCAMENTO"
		},
		{
			"code": "EX0001",
			"store": "01",
        }			"check": "false",
			"desc": "CLIENTE EXTERIOR 001"
		}
    ],

    "hasNext": "false",
    ]"count": 3
}

Descrição dos Campos:

• hasNext: Indica se existe mais uma página de resultados ou se já está na última página (ver mais detalhes nos parâmetros aceitos: page e pageSize).
• clients: Array de clientes.
• clients[n].id: Código de identificação do cliente
• clients[n].name: Nome do cliente
• clients[n].unit: Loja do cliente

Os parâmetros aceitos serão: searchKey, page e pageSize.

3.4. GET /wscnta300/suppliers

GET /rest/supervisorgs/regions

Retorna a lista das regioes disponiveis na url.

Parâmetros aceitos

Não são aceitos parâmetros de URL para esta requisição.

Retorno

O serviço deve retornar as propriedades informadas, de acordo com os parâmetros passados na consulta.

regions

regions[x].code

regions[x].desc

count

GET rest/SUPERVISORGS/clientsRetorna a lista de fornecedores disponíveis para filtrar os contratos exibidos, no seguinte formato:

{
    "hasNextregions": true,
    "suppliers": [
        {
            "id			"code": "0000001001",
            "name			"desc": "TOTVS SANorte",
            "unit
		},
		{
			"code": "002",
			"desc": "01Sul"
        		},
        {
            "id		{
			"code": "0000002003",
            "name			"desc": "OUTRO CLIENTE",
            "unitLeste"
		},
		{
			"code": "01004",
        }
    ]
}

Descrição dos Campos:

• hasNext: Indica se existe mais uma página de resultados ou se já está na última página (ver mais detalhes nos parâmetros aceitos: page e pageSize).
• suppliers: Array de fornecedores.
• suppliers[n].id: Código de identificação do fornecedor
• suppliers[n].name: Nome do fornecedor
• suppliers[n].unit: Loja do fornecedor

Os parâmetros aceitos serão: searchKey, page e pageSize.

3.5. GET /wscnta121/measurements

Retorna a lista de medições disponíveis para aprovação do usuário logado, no formato indicado abaixo:

			"desc": "Oeste"
		},
		{
			"code": "005",
			"desc": "Centro"
		},
		{
			"code": "006",
			"desc": "Centro oeste"
		}
	],
	"count": 5
}

GET /rest/supervisorgs/places

Retorna a lista dos locais disponiveis na url.

Parâmetros aceitos

Não são aceitos parâmetros de URL para esta requisição.

Retorno

O serviço deve retornar as propriedades informadas, de acordo com os parâmetros passados na consulta.

regions

regions[x].code

regions[x].desc

count

GET rest/SUPERVISORGS/places

{
    "places": [
        {
			"code": "00000001",
			"desc": "TOTVS SITE SP"
		},
		{
			"code": "00000002",
			"desc": "TOTVS MATRIZ - 1000"
		},
		{
			"code": "00000003",
			"desc": "CASA DO GUILHERME"
		},
		{
			"code": "00000004",
			"desc": "IBIRAPUERA"

{
    "measurements" : [
        {
            "number" : "297238",
            "contract" : {
                "number" : "0937491347",
                "rev" : "1"
            },
			"value" : {
				"symbol" : "R$",
				"total": 21000
			}
            "spreadsheet" : {
       }
     ],
    "numbercount" : "3",
                "description" : "FIXO/FINANCEIRO"
            },
			"competence": "11/2017",
			"history" : [
				{
					"name" : "RODRIGO TOLEDO",
					"date" : "20171023",
					"justification" : ""
				}
			],
            "items" : [
                {
                    "product_code" : "000001",
                    "product_description" : "PRODUTO 1",
            4
}

POST /rest/supervisorgs/operationalDecision

Envia requisição

Parâmetros aceitos

Não são aceitos parâmetros de URL para esta requisição.

Payload

O payload que será enviado na requisição conterá as seguintes propriedades:

cCode

Post /rest/SUPERVISORGS/operationalDecision

{
cCode: "000000000283", 
cObs: "teste"


}

GET /rest/supervisorgs/supervisor

Retorna a lista dos supervisores disponiveis na url.

Parâmetros aceitos

Não são aceitos parâmetros de URL para esta requisição.

Retorno

O serviço deve retornar as propriedades informadas, de acordo com os parâmetros passados na consulta.

supervisor

supervisor[x].code

supervisor[x].desc

count

GET rest/SUPERVISORGS/supervisor

{
    "supervisor": [
        "quantity" : 8,
					"discount" : "20,5 %{
            "code": "D MG  01000023",
            "desc": "FUNCIONARIO A"
      "unitary_value" : 16},
        {
            "total_valuecode" : 128,,
					"value_symbol" : "R$",
					"delivery_date" : "20171123"
"D MG  01000025",
            "desc":      },"FUNCIONARIO C"
        },
        {
            "code": "D MG      "product_code" : "00000201000029",
            "desc": "FUNCIONARIO AA"
      "product_description" : "OUTRO PRODUTO 2" },
        {
            "quantity" : 10code": "D MG  01000030",
            "desc": "FUNCIONARIO       "unitary_value" : 1.3,
					"discount" : "0 %",
                    "total_value" : 13,
					"value_symbol" : "R$",
					"delivery_date" : "20171123"
                }
            ]
        }
    ]
}

Descrição dos Campos:

• measurements: Array com as medições pendentes de aprovação do usuário logado.
• measurements[n].number: Número da medição
• measurements[n].contract: Objeto do contrato ao qual a medição está vinculada
• measurements[n].contract.number: Número do contrato
• measurements[n].contract.rev: Revisão do contrato
• measurements[n].value: Objeto do valor total da medição
• measurements[n].value.symbol: Símbolo da moeda do valor total da medição
• measurements[n].value.total: Valor total da medição
• measurements[n].spreadsheet: Objeto da planilha relacionada à medição
• measurements[n].spreadsheet.number: Número da planilha
• measurements[n].spreadsheet.description: Descrição da planilha
• measurements[n].competence: Mês da medição (YYYYMM)
• measurements[n].history: Array de histórico de aprovações da medição
• measurements[n].history[n].name: Nome do aprovador
• measurements[n].history[n].date: Data da aprovação
• measurements[n].history[n].justification: Justificativa (pode ser vazia)
• measurements[n].items: Array com os itens da medição
• measurements[n].items[n].product_code: Código do produto
• measurements[n].items[n].product_description: Descrição do produto
• measurements[n].items[n].quantity: Quantidade
• measurements[n].items[n].discount: Percentual de desconto
• measurements[n].items[n].unitary_value: Valor unitário
• measurements[n].items[n].total_value: Valor total

• measurements[n].items[n].value_symbol: Símbolo do valor a ser exibido

• measurements[n].items[n].delivery_date: Data de entrega (YYYYMMDD)

NÃO PRECISA MANDAR FILTROS, POIS COMO NÃO HÁ PAGINAÇÃO, APP PODE FILTRAR NO FRONT

Parâmetros aceitos, ao recebidos devem filtrar a lista de medições retornadas:

• contract: Número do contrato
• rev: Revisão contrato
• competence: Data da competência, no formato YYYYMM
• measurement: Número da medição
• searchKey: Filtro chave, capaz de filtrar em diversos campos diferentes da medição, como cliente ou fornecedor, número, descrição, etc (máximo de lugares possíveis).

Este endpoint não irá suportar paginação, logo não serão enviados os parâmetros page e pageSize, nem será necessário a utilização do hasNext.

3.6. PUT /wscnta121/contracts/{contractID}/{rev}/measurements/{measurementID}/approval_status

Este endpoint deverá efetuar a aprovação ou reprovação da medição por parte do usuário logado.

Ao ser requisitado, será enviado um payload junto à requisição, com o seguinte formato:

{
    "approval_status" : false,
    "justification" : "Justificativa"
}

Campos do payload da requisição:

• approval_status: Resultado a aprovação (true se o usuário aprovou a medição, false se o usuário reprovou a medição)
• justification: Justificativa do usuário em caso de reprovação (em caso de aprovação, este campo não é obrigatório)

O retorno da requisição deverá ser uma mensagem de OK (http 200) em caso de atualização com sucesso ou enviar no retorno a mensagem de erro resultante da operação (utilizar padrão de erro do framework). 

...

BB"
        }
    ],
    "hasNext": "false"
}