Índice

outline	true

Objetivos

Determinar os serviços que estarão disponíveis no Protheus para que haja compatibilidade entre o módulo de Ativo Fixo e o aplicativo ATF Mobile Meus Ativos Fixos.

GET /

...

wsatf001/entities

Retorna a lista de notas e ativos 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".

Parâmetro	Tipo	Descrição	Valor Default
searchKey	string	Filtra em diversos campos das notas e ativos	-
barcode	string	Filtra uma nota ou ativo pelo código de barras	-
type	number	Filtra entre ativos (0) ou notas(1)	-
page	number	Página inicial que será retornada	1
pageSize	number	Tamanho da página que será retornada	10

Retorno

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

Propriedade	Tipo	Descrição	Adicional
hasNext	booleano	Indica se há uma próxima página a ser retornada ou se atingiu a última página disponível	true = Há uma próxima página false = É a última página disponível
entities	Array	Lista com os objetos de notas e ativos retornados.	-
entities[].type	number	Indica se o objeto é uma nota ou um ativo	0 - ativo 1 - nota
entities[].asset	string	Código do ativo	Deve ser null se o objeto representa uma nota
entities[].item	string	Código do item do ativo	Deve ser null se o objeto representa uma nota
entities[].description	string	Descrição do item	Deve ser null se o objeto representa uma nota
entities[].invoice	string	Número da nota	Deve ser null se o objeto representa um ativo
entities[].series	string	Série da nota	Deve ser null se o objeto representa um ativo
entities[].supplier	Object	Objeto do fornecedor da nota	Deve ser null se o objeto representa um ativo
entities[].supplier.name	string	Nome do fornecedor	Deve ser null se o objeto representa um ativo
entities[].supplier.id	string	Código do fornecedor	Deve ser null se o objeto representa um ativo
entities[].unit	string	Código da loja	Deve ser null se o objeto representa um ativo

Exemplo de retorno da requisição:

GET /atfwsatf001/entities?page=1&pageSize=2&searchKey="Gr"

Bloco de código

language	js
theme	RDark
title	response.json
collapse	true

{
	"hasNext": true,
	"entities" : [
		{
			"type": 0,
			"asset": "00001",
			"item": "00001",
			"description": "Grua",
			"invoice": null,
			"series": null,
			"supplier": null,
			"unit": null
		},
		{
			"type": 1,
			"asset": null,
			"item": null,
			"description": null,
			"invoice": "000001",
			"series": "01",
			"supplier": {
				"name": "Grupo JLima",
				"id": "000001"
			},
			"unit": "0001"
		},
	]
}

...

GET /

...

wsatf001/assets/{asset}/{item}

Retorna os detalhes de um ativo identificado pelos parâmetros asset e item 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".

Parâmetro	Tipo	Descrição	Valor Default
fields	string	Lista de campos (separados por vírgula) que devem ser retornados.	-
language	string	Indica o formato que os labels dos campos solicitados devem ser retornados. Só são aceitos os valores: 'pt' para português, 'en' para inglês e 'es' para espanhol	'pt'

Retorno

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

Propriedade	Tipo	Descrição	Adicional
location	Object	Objeto indicando a localização do ativo	Caso o ativo esteja sem localização cadastrada, retornar null.
location.lat	number	Latitude da localização do ativo

latitude


location.lng	number	Longitude da localização do ativo


location.local.

addess

code

string

Localização do ativo no sistema

(código do N1_LOCAL)
location.local.description	string	Descrição da localização do ativo no sistema (NL_DESCRIC)
image	booleano	indicador se o ativo possui ou não uma imagem cadastrada no sistema


fields	Array	Lista com os campos disponíveis para este ativo


fields[].identifier	string	Identificador do campo no Protheus


fields[].type	string	Tipo (simplificado) do campo no Protheus	Só serão aceitos 5 tipos de campos: 'text', 'number', 'date', 'lookup', 'other'
fields[].value	string	Valor a ser exibido no campo


fields[].label	string	Label a ser exibido para o campo, traduzido conforme parâmetro enviado na requisição.


invoices	Array	Lista de notas vinculada à aquele ativo	Serão exibidas pelo mobile de acordo com a ordem enviada pelo serviço.
invoices[].name	string	Nome do fornecedor
invoices[].supplier	string

Fornecedor da nota

Código do fornecedor
invoices[].unit	string	Loja


invoices[].invoice	string	Número da nota


invoices[].series	string	Série da nota


balances	Array	Saldos disponível para o item	Serão exibidos no mobile de acordo com a ordem enviada pelo serviço.
balances[].asset_type	string	Tipo do ativo	Ref: N3_TIPO
balances[].balance_type	string	Tipo do saldo	Ref: N3_TPSALDO
balances[].history	string	Histórico do saldo	Ref: N3_HISTOR
balances[].write_off	booleano	Indicador se o saldo está baixado ou não	Ref: N3_BAIXA
balances[].sequence	string	Sequência de aquisição	Ref: N3_SEQ

Exemplo de retorno da requisição:

GET /atfwsatf001/assets/00001/00001?language=pt&fields=name,description,quantity

Bloco de código

language	js
theme	RDark
title	response.json
collapse	true

{
	"location": {
		"lat": -23.5084952, 
		"lng": -46.6536569,
		"local": {
			"code": "0000001".
			"description": "BRAZ LEME"
		}
	},
	"image": true,
	"fields": [
		{
			"identifier": "N1_NOME",
			"type": "string",
			"value": "Grua",
			"label": "Nome"
		},
		{
			"identifier": "N1_DESC",
			"type": "string",
			"value": "Grua 20 metros amarela",
			"label": "Descrição"
		},
		{
			"identifier": "N1_QTDE",
			"type": "number",
			"value": "2",
			"label": "Quantidade"
		},
	],
	"invoices" : [
		{
		   "name": "Grupo JLima",
			"supplier": "000001",
			"unit": "000001",
			"invoice": "0000001",
			"series": "01"
		}
	],
	"balances": [
		{
			"asset_type": "0001",
			"balance_type": "00001",
			"history": '',
			"write_off": false,
			"sequence": "00001"
		}
	]
}

GET /wsatf001/assets/{asset}/{item}/image

Retorna a imagem vinculada ao ativo identificado pelos parâmetros asset e item na url.

Parâmetros aceitos

O parâmetro sera passados por queryParams.

Parâmetro	Tipo	Descrição	Valor Default
rawimage	string	Retorna a imagem no corpo da resposta com o content type correto	-

Retorno

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

Propriedade	Tipo	Descrição	Adicional
content	string	Base64 da imagem cadastrada no sistema para o ativo

Exemplo de retorno da requisição:

GET /wsatf001/assets/00001/00001/image

Bloco de código

language	js
theme	RDark
title	response.json
collapse	true

{
	"content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAagBqAAD/4RDc...........(continuação do conteúdo da imagem)"
}

GET /wsatf001/assets/{asset}/{item}/balances/{asset_type}/{balance_type}/{write_off}/{sequence}

Retorna os detalhes de um saldo do ativo.

O ativo será identificado pelos parâmetros asset e item e o saldo será identificado pelo parâmetros asset_type, balance_type, write_off e sequence.

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

Parâmetro	Tipo	Descrição	Valor Default
fields	string	Lista de campos (separados por vírgula) que devem ser retornados.	-
language	string	Indica o formato que os labels dos campos solicitados devem ser retornados. Só são aceitos os valores: 'pt' para português, 'en' para inglês e 'es' para espanhol	'pt'

Retorno

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

Propriedade	Tipo	Descrição	Adicional
fields	Array	Lista com os campos disponíveis para este saldo
fields[].identifier	string	Identificador do campo no Protheus
fields[].type	string	Tipo (simplificado) do campo no Protheus	Só serão aceitos 5 tipos de campos: C-Caracter; N-Numerico; D-Data; L-Logica.
fields[].value	string	Valor a ser exibido no campo
fields[].label	string	Label a ser exibido para o campo, traduzido conforme parâmetro enviado na requisição.

Exemplo de retorno da requisição:

GET /wsatf001/assets/00001/00001/balances/000001/000001/001/01?language=pt&fields=history,write_off

Bloco de código

language	js
theme	RDark
title	response.json
collapse	true

{
	"location": {
		"lat": -23.5084952, 
		"lng": -46.6536569,
		"local": "0000001"
	},
	"image": true,
	"fields": [
		{
			"identifier": "N3_HISTOR",
			"type": "string",
			"value": "01",
			"label": "Histórico"
		},
		{
			"identifier": "N3_BAIXA",
			"type": "string",
			"value": "false",
			"label": "Baixado"
		}
	]
}

GET /wsatf001/assets/{asset}/{item}/invoice

Retorna a nota vinculada de um ativo identificado pelos parâmetros asset e item.

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

Parâmetro	Tipo	Descrição	Valor Default
language	string	Indica o formato que os labels dos campos solicitados devem ser retornados. Só são aceitos os valores: 'pt' para português, 'en' para inglês e 'es' para espanhol	'pt'

Retorno

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

Propriedade	Tipo	Descrição	Adicional
fields	Array	Lista com os campos disponíveis para esta nota
fields[].identifier	string	Identificador do campo no Protheus
fields[].type	string	Tipo (simplificado) do campo no Protheus	Só serão aceitos 5 tipos de campos: 'text', 'number', 'date', 'lookup', 'other'
fields[].value	string	Valor a ser exibido no campo
fields[].label	string	Label a ser exibido para o campo, traduzido conforme parâmetro enviado na requisição.
items	Array	Array com os itens da nota
items[].item	string	Item da nota fiscal
items[].product	string	Descrição do produto
items[].quantity	number	Quantidade comprada do produto
assets	Array	Array de ativos vinculados à nota
assets[].asset	string	Código do ativo
assets[].item	string	Código do item
assets[].description	string	Descrição do item

Exemplo de retorno da requisição:

GET /wsatf001/assets/00001/00001/invoice?fields=numnota,serie

Bloco de código

language	js
theme	RDark
title	response.json
collapse	true

{
	"fields": [
		{
			"identifier": "NUMNOTA",
			"type": "string",
			"value": "000001",
			"label": "Número da nota"
		},
		{
			"identifier": "SERIE",
			"type": "string",
			"value": "01",
			"label": "Série da nota"
		}
	],
	"items" : [
			"item": "01",
			"product" : "Grua",
			"quantity" : 2
	],
	"assets": [
		"asset" : "000001",
		"item": "00001",
		"description" : "Grua"
	]
}

GET /wsatf001/invoices/{supplier}/{unit}/{invoice}/{series}

Retorna a nota vinculada identificada pelos parâmetros supplier e unit, invoice e series.

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

Parâmetro	Tipo	Descrição	Valor Default
language	string	Indica o formato que os labels dos campos solicitados devem ser retornados. Só são aceitos os valores: 'pt' para português, 'en' para inglês e 'es' para espanhol	'pt'

Retorno

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

Propriedade	Tipo	Descrição	Adicional
fields	Array	Lista com os campos disponíveis para esta nota
fields[].identifier	string	Identificador do campo no Protheus
fields[].type	string	Tipo (simplificado) do campo no Protheus	Só serão aceitos 5 tipos de campos: 'text', 'number', 'date', 'lookup', 'other'
fields[].value	string	Valor a ser exibido no campo
fields[].label	string	Label a ser exibido para o campo, traduzido conforme parâmetro enviado na requisição.
items	Array	Array com os itens da nota
items[].item	string	Item da nota fiscal
items[].product	string	Descrição do produto
items[].quantity	number	Quantidade comprada do produto
assets	Array	Array de ativos vinculados à nota
assets[].asset	string	Código do ativo
assets[].item	string	Código do item
assets[].description	string	Descrição do item

Exemplo de retorno da requisição:

GET /wsatf001/assets/invoices/00001/00001/000001/01?fields=numnota,serie

Bloco de código

language	js
theme	RDark
title	response.json
collapse	true

{
	"fields": [
		{
			"identifier": "NUMNOTA",
			"type": "string",
			"value": "000001",
			"label": "Número da nota"
		},
		{
			"identifier": "SERIE",
			"type": "string",
			"value": "01",
			"label": "Série da nota"
		}
	],
	"items" : [
			"item": "01",
			"product" : "Grua",
			"quantity" : 2
	],
	"assets": [
		"asset" : "000001",
		"item": "00001",
		"description" : "Grua"
	]
}

GET /wsatf001/fields/{fieldType}

Retorna os campos disponíveis para um tipo específico identificado pelo fieldType.

Os fieldTypes aceitos são: 'assets', 'balances', 'invoices', correspondendo assim à 3 endpoints distintos:

GET /wsatf001/fields/assets
GET /wsatf001/fields/balances

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

Parâmetro	Tipo	Descrição	Valor Default
language	string	Indica o formato que os labels dos campos solicitados devem ser retornados. Só são aceitos os valores: 'pt' para português, 'en' para inglês e 'es' para espanhol	'pt'

Retorno

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

Propriedade	Tipo	Descrição	Adicional
fields	Array	Lista com os campos disponíveis para o tipo selecionado
fields[].identifier	string	Identificador do campo no Protheus
fields[].type	string	Tipo (simplificado) do campo no Protheus	Só serão aceitos 5 tipos de campos: 'text', 'number', 'date', 'lookup', 'other'
fields[].label	string	Label a ser exibido para o campo, traduzido conforme parâmetro enviado na requisição.

Exemplo de retorno da requisição:

GET /wsatf001/fields/invoices?language=pt

Bloco de código

language	js
theme	RDark
title	response.json
collapse	true

{
	"fields": [
		{
			"identifier": "NUMNOTA",
			"type": "string",
			"label": "Número da nota"
		},
		{
			"identifier": "SERIE",
			"type": "string",
			"label": "Série da nota"
		}
	]
}

GET /wsatf001/requests

Retorna as solicitações do histórico disponíveis para consulta no aplicativo..

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

Parâmetro	Tipo	Descrição	Valor Default
operation	number	Indica o filtro do tipo de solicitação. Só são aceitos os valores: 0 para baixa, 1 para transferência e 2 para ampliação	Retornar todas
status	number	Indica o filtro do status da solicitação. O valor 0 indicará pendente, o valor 1 indicará finalizada, e o valor 2 indicará cancelada	Retornar todas
date	string	Filtra o retorno por mês e ano (YYYYMM)	-
page	number	Página que será retornada	1
pageSize	number	Tamanho da página que será retornada	10

Retorno

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

Propriedade	Tipo	Descrição	Adicional
hasNext	booleano	Indica se há ou não uma próxima página a ser retornada
requests	Array	Array de requests disponíveis
requests[].operation	number	Tipo de solicitação	0: Baixa 1: Transferência 2: Ampliação
requests[].status	number	Status da solicitação	0: Pendente 1: Finalizada 2: Cancelada
requests[].date	string	Data da solicitação, no formato YYYYMMDD
requests[].reason	string	Este campo muda seu conteúdo de acordo com o tipo de solicitação.	Se operation=0, será retornado o motivo. Se operation=1, serão retornados os detalhes Se operation=2, será retornada a observação
requests[].value	number	Valor	Só existe se operation for != 1
requests[].quantity	number	Quantidade que for baixada	Só existe se operation for 0
requests[].balance	Array	Array dos balances.
requests[].balance.type	string	Tipo do ativo
requests[].balance.balance_type	string	Saldo que foi baixado.	So existe se operation for 0

Exemplo de retorno da requisição:

GET /wsatf001/requests?page=1&pageSize=1

Bloco de código

language	js
theme	RDark
title	response.json
collapse	true

{
    "hasNext": false,
    "requests": [
        {
            "operation": "0",
            "status": "0",
            "reason": "fazer a baixa de quantidade 10 saldo tipo gerencial balanco gerencial                                                                                                                                                                                     ",
            "quantity": 10,
            "balances": [
                {
                    "type": "10",
                    "balance_type": "3"
                }
            ],
            "date": "20171010",
            "value": 0
        },
}

POST /wsatf001/assets/request/

Envia requisição para tranferência / baixa e ampliação do ativo.

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:

Propriedade	Tipo	Descrição	Adicional
operation	number	Indica qual solicitação está sendo requisitada.	0: Baixa 1: Transferência 2: Ampliação
asset	string	Código do ativo
item	string	Item do ativo
requests[].status	string	Status da solicitação	0: Pendente 1: Finalizada 2: Cancelada
requests[].date	data	Data da solicitação	Formato data Protheus "YYYYMMDD"
requests[].reason	string	Motivo (descrição)	Se operation=0 -> Motivo Se operation=1 -> Detalhes Se operation=2 -> Observação
requests[].value	number	Valor	Só existe se operation for 1
requests[].quantity	number	Quantidade que for baixada	Só existe se operation for 0
requests[].balance	string	Saldo que foi baixado	Só existe se operation for 0
requests[].type	string	Tipo de transferência	0: Física 1: Contábil

Exemplo de retorno da requisição:

- item: Código do item (mostrar sempre junto)

- status: Status da solicitação (0-Pendente, 1-Finalizada, 2-cancelada)

- date: Data da solicitação, formato data Protheus YYYYMMDD

- reason: Motivo

Se operation=0 -> Motivo

Se operation=1 -> Detalhes

Se operation=2 -> Observação

- value: (só não existe se operation=1)

- quantity: (só existe se operation=0)

- balances: Tipos de saldo disponíveis no bem (ver GET /assets) (só existe se operation=0)

- type: Tipo de transferência (0-física, 1-contábil) (só existe se for operation=1)

Post /wsatf001/assets/request

Bloco de código

language	js
theme	RDark
title	response.json
collapse	true

{
	"operation": 1,
	"asset": "000001",
	"item": "0001",
	"type": "0",
    "status" : 0,    
	"reason" : "teste",
	"value" : 100,
	"quantity" : 1,
    "balance": {
		"type": "10",
		"balance_type": "3"}
}

PUT /wsatf001/assets/{asset}/{item}

Grava a localização de um ativo identificado pelos parâmetros asset e item na url. Este serviço pode ser usado de duas formas: enviando lat e lng para atualizar a geolocalização, ou enviando o local para atualizar o N1_LOCAL.

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:

Propriedade	Tipo	Descrição	Adicional
location	array	Array com a Localização	-
lat	number	Latitude	-
lng	number	Longitude	-
local	string	Código do local

Exemplo de retorno da requisição:

- location: Array com a localização.

- lat: Latitude da localização do ativo.

- lng: Longitude da localização do ativo

- local: Código do local cadastrado no Protheus.

Put /wsatf001/assets/{assets}/{item}

Bloco de código

language	js
theme	RDark
title	response.json
collapse	true

Exemplo 1: Atualizando a geolocalização


{
 "type": "latlng",
 "location": {
 	"lat": -93.5084952,
 	"lng": -96.6536569
 }
}


Exemplo 2: Atualizando o N1_LOCAL:
{
 "type": "local",
 "location": {
 	"local": "000001"
 }
}

PUT /wsatf001/assets/{asset}/{item}/image

Grava a foto de um ativo identificado pelos parâmetros asset e item na url.

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:

Propriedade	Tipo	Descrição	Adicional
content	string	Base64 da imagem cadastrada no sistema para o ativo	-

Exemplo de retorno da requisição:

- location: Array com a localização.

Put /wsatf001/assets/{assets}/{item}

Bloco de código

language	js
theme	RDark
title	response.json
collapse	true

{
	"content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAagBqAAD/4RDc...........(continuação do conteúdo da imagem)"
}

GET /wsatf001/assets/locations

Serviço para retornar a lista de locais possíveis que podem ser selecionados ao atualizar a localização (N1_LOCAL) de um ativo.

O serviço deve aceitar os parâmetros page, pageSize e searchKey, que fará uma busca na descrição (description) e no código (code) do local. Os dados devem ser retornados em ordem alfabética crescente.

O retorno deve obedecer à estrutura:

Bloco de código

language	js
theme	RDark
collapse	true

{
         “hasNext”: true,
         “locations”: [
                   {
                            “code”: “0000001”,
                            “description”:“BRAZ LEME”
                   },
                   {
                            “code”:“0000002”,
                            “description”: “CANINDE”
                   }
         ]
}

O retorno da requisição, em caso de sucesso, deve ser um HTTP 200 OK.

Árvore de páginas

Histórico da Página

Versões comparadas

Versão antiga 3

Nova versão Atual

Chave

Objetivos

GET /

wsatf001/entities

Parâmetros aceitos

Retorno

GET /

wsatf001/assets/{asset}/{item}

Parâmetros aceitos

Retorno

GET /wsatf001/assets/{asset}/{item}/image

Parâmetros aceitos

Retorno

GET /wsatf001/assets/{asset}/{item}/balances/{asset_type}/{balance_type}/{write_off}/{sequence}

Parâmetros aceitos

Retorno

GET /wsatf001/assets/{asset}/{item}/invoice

Parâmetros aceitos

Retorno

GET /wsatf001/invoices/{supplier}/{unit}/{invoice}/{series}

Parâmetros aceitos

Retorno

GET /wsatf001/fields/{fieldType}

Parâmetros aceitos

Retorno

GET /wsatf001/requests

Parâmetros aceitos

Retorno

POST /wsatf001/assets/request/

Parâmetros aceitos

Payload

PUT /wsatf001/assets/{asset}/{item}

Parâmetros aceitos

Payload

PUT /wsatf001/assets/{asset}/{item}/image

Parâmetros aceitos

Payload

GET /wsatf001/assets/locations