Histórico da Página
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:
| Bloco de código | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{
"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:
- contracts: Array com os contratos que o usuário logado tem acesso.
- contracts[n].number: Número do contrato
- contracts[n].rev: Revisão do contrato
- contracts[n]._type: Tipo de contrato (1=compra e 2=venda)
- contracts[n].startDate: Data de início da vigência
- contracts[n].endDate: Data de fim da vigência
- contracts[n].description: Descrição do contrato
- contracts[n].balance: Objeto do saldo do contrato
- contracts[n].balance.symbol: Símbolo da moeda referente ao saldo retornado
- contracts[n].balance.total: Valor total do saldo do contrato
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).
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:
| Bloco de código | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{
"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:
| Bloco de código | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{
"hasNext": true,
"clients": [
{
"id": "0000001",
"name": "TOTVS SA",
"unit": "01"
},
{
"id": "0000002",
"name": "OUTRO CLIENTE",
"unit": "01"
}
]
} |
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
Retorna a lista de fornecedores disponíveis para filtrar os contratos exibidos, no seguinte formato:
| Bloco de código | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{
"hasNext": true,
"suppliers": [
{
"id": "0000001",
"name": "TOTVS SA",
"unit": "01"
},
{
"id": "0000002",
"name": "OUTRO CLIENTE",
"unit": "01"
}
]
} |
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:
| Bloco de código | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{
"measurements" : [
{
"number" : "297238",
"contract" : {
"number" : "0937491347",
"rev" : "1"
},
"value" : {
"symbol" : "R$",
"total": 21000
}
"spreadsheet" : {
"number" : "3",
"description" : "FIXO/FINANCEIRO"
},
"competence": "11/2017",
"history" : [
{
"name" : "RODRIGO TOLEDO",
"date" : "20171023",
"justification" : ""
}
],
"items" : [
{
"product_code" : "000001",
"product_description" : "PRODUTO 1",
"quantity" : 8,
"discount" : "20,5 %",
"unitary_value" : 16,
"total_value" : 128,,
"value_symbol" : "R$",
"delivery_date" : "20171123"
},
{
"product_code" : "000002",
"product_description" : "OUTRO PRODUTO 2",
"quantity" : 10,
"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:
| Bloco de código | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
{
"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).
OBS: Caso o usuário aprove ou reprove a requisição e o Protheus rejeite esta operação, o retorno não poderá ser enviado em uma mensagem de sucesso (http 200).
Import HTML Content
Visão Geral
Conteúdo das Ferramentas