Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

Índice
outlinetrue

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âmetroTipoDescriçãoValor Default
searchKeystringFiltra em diversos campos das notas e ativos-
barcodestringFiltra uma nota ou ativo pelo código de barras-
typenumberFiltra entre ativos (0) ou notas(1)-
pagenumberPágina inicial que será retornada1
pageSizenumberTamanho da página que será retornada10


Retorno

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

PropriedadeTipoDescriçãoAdicional
hasNextbooleanoIndica 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

entitiesArrayLista com os objetos de notas e ativos retornados.-
entities[].typenumberIndica se o objeto é uma nota ou um ativo

0 - ativo

1 - nota

entities[].assetstringCódigo do ativoDeve ser null se o objeto representa uma nota
entities[].itemstringCódigo do item do ativoDeve ser null se o objeto representa uma nota
entities[].descriptionstringDescrição do itemDeve ser null se o objeto representa uma nota
entities[].invoicestringNúmero da notaDeve ser null se o objeto representa um ativo
entities[].seriesstringSérie da notaDeve ser null se o objeto representa um ativo
entities[].supplierObjectObjeto do fornecedor da notaDeve ser null se o objeto representa um ativo
entities[].supplier.namestringNome do fornecedorDeve ser null se o objeto representa um ativo
entities[].supplier.idstringCódigo do fornecedorDeve ser null se o objeto representa um ativo
entities[].unitstringCódigo da lojaDeve 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
languagejs
themeRDark
titleresponse.json
collapsetrue
{
	"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âmetroTipoDescriçãoValor Default
fieldsstringLista de campos (separados por vírgula) que devem ser retornados.-
languagestringIndica 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.

PropriedadeTipoDescriçãoAdicional
locationObjectObjeto indicando a localização do ativo

Caso o ativo esteja sem localização cadastrada, retornar null.

location.latnumberLatitude da localização do ativo
 latitude

location.lngnumberLongitude da localização do ativo
 


location.local.
addess
codestringLocalização do ativo no sistema
 
(código do N1_LOCAL)
location.local.descriptionstringDescrição da localização do ativo no sistema (NL_DESCRIC)
imagebooleanoindicador se o ativo possui ou não uma imagem cadastrada no sistema
 

fieldsArrayLista com os campos disponíveis para este ativo
 

fields[].identifierstringIdentificador do campo no Protheus
 

fields[].typestringTipo (simplificado) do campo no ProtheusSó serão aceitos 5 tipos de campos: 'text', 'number', 'date', 'lookup', 'other'
fields[].valuestringValor a ser exibido no campo
 

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

invoicesArrayLista de notas vinculada à aquele ativoSerão exibidas pelo mobile de acordo com a ordem enviada pelo serviço.
invoices[].namestringNome do fornecedor
invoices[].supplierstring
Fornecedor da nota 
Código do fornecedor
invoices[].unitstringLoja
 

invoices[].invoicestringNúmero da nota
 

invoices[].seriesstringSérie da nota
 

balancesArraySaldos disponível para o itemSerão exibidos no mobile de acordo com a ordem enviada pelo serviço.
balances[].asset_typestringTipo do ativoRef: N3_TIPO
balances[].balance_typestringTipo do saldoRef: N3_TPSALDO
balances[].historystringHistórico do saldoRef: N3_HISTOR
balances[].write_offbooleanoIndicador se o saldo está baixado ou nãoRef: N3_BAIXA
balances[].sequencestringSequência de aquisiçãoRef: N3_SEQ

Exemplo de retorno da requisição:

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

Bloco de código
languagejs
themeRDark
titleresponse.json
collapsetrue
{
	"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âmetroTipoDescriçãoValor Default
rawimagestringRetorna 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.

PropriedadeTipoDescriçãoAdicional
contentstringBase64 da imagem cadastrada no sistema para o ativo

Exemplo de retorno da requisição:

GET /wsatf001/assets/00001/00001/image

Bloco de código
languagejs
themeRDark
titleresponse.json
collapsetrue
{
	"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 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âmetroTipoDescriçãoValor Default
fieldsstringLista de campos (separados por vírgula) que devem ser retornados.-
languagestringIndica 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.

PropriedadeTipoDescriçãoAdicional
fieldsArrayLista com os campos disponíveis para este saldo
fields[].identifierstringIdentificador do campo no Protheus
fields[].typestringTipo (simplificado) do campo no ProtheusSó serão aceitos 5 tipos de campos: C-Caracter; N-Numerico; D-Data; L-Logica.
fields[].valuestringValor a ser exibido no campo
fields[].labelstringLabel 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
languagejs
themeRDark
titleresponse.json
collapsetrue
{
	"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âmetroTipoDescriçãoValor Default
languagestringIndica 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.

PropriedadeTipoDescriçãoAdicional
fieldsArrayLista com os campos disponíveis para esta nota
fields[].identifierstringIdentificador do campo no Protheus
fields[].typestringTipo (simplificado) do campo no ProtheusSó serão aceitos 5 tipos de campos: 'text', 'number', 'date', 'lookup', 'other'
fields[].valuestringValor a ser exibido no campo
fields[].labelstringLabel a ser exibido para o campo, traduzido conforme parâmetro enviado na requisição.
itemsArrayArray com os itens da nota
items[].itemstringItem da nota fiscal
items[].productstringDescrição do produto
items[].quantitynumberQuantidade comprada do produto
assetsArrayArray de ativos vinculados à nota
assets[].assetstringCódigo do ativo
assets[].itemstringCódigo do item
assets[].descriptionstringDescrição do item

Exemplo de retorno da requisição:

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

Bloco de código
languagejs
themeRDark
titleresponse.json
collapsetrue
{
	"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âmetroTipoDescriçãoValor Default
languagestringIndica 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.

PropriedadeTipoDescriçãoAdicional
fieldsArrayLista com os campos disponíveis para esta nota
fields[].identifierstringIdentificador do campo no Protheus
fields[].typestringTipo (simplificado) do campo no ProtheusSó serão aceitos 5 tipos de campos: 'text', 'number', 'date', 'lookup', 'other'
fields[].valuestringValor a ser exibido no campo
fields[].labelstringLabel a ser exibido para o campo, traduzido conforme parâmetro enviado na requisição.
itemsArrayArray com os itens da nota
items[].itemstringItem da nota fiscal
items[].productstringDescrição do produto
items[].quantitynumberQuantidade comprada do produto
assetsArrayArray de ativos vinculados à nota
assets[].assetstringCódigo do ativo
assets[].itemstringCódigo do item
assets[].descriptionstringDescrição do item

Exemplo de retorno da requisição:

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

Bloco de código
languagejs
themeRDark
titleresponse.json
collapsetrue
{
	"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âmetroTipoDescriçãoValor Default
languagestringIndica 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.

PropriedadeTipoDescriçãoAdicional
fieldsArrayLista com os campos disponíveis para o tipo selecionado
fields[].identifierstringIdentificador do campo no Protheus
fields[].typestringTipo (simplificado) do campo no ProtheusSó serão aceitos 5 tipos de campos: 'text', 'number', 'date', 'lookup', 'other'
fields[].labelstringLabel 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
languagejs
themeRDark
titleresponse.json
collapsetrue
{
	"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âmetroTipoDescriçãoValor Default
operationnumberIndica o filtro do tipo de solicitação. Só são aceitos os valores: 0 para baixa, 1 para transferência e 2 para ampliaçãoRetornar todas
statusnumberIndica o filtro do status da solicitação. O valor 0 indicará pendente, o valor 1 indicará finalizada, e o valor 2 indicará canceladaRetornar todas
datestringFiltra o retorno por mês e ano (YYYYMM)-
pagenumberPágina que será retornada1
pageSizenumberTamanho da página que será retornada10

Retorno

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


PropriedadeTipoDescriçãoAdicional
hasNextbooleanoIndica se há ou não uma próxima página a ser retornada
requestsArrayArray de requests disponíveis
requests[].operationnumberTipo de solicitação

0: Baixa

1: Transferência

2: Ampliação

requests[].statusnumberStatus da solicitação

0: Pendente

1: Finalizada

2: Cancelada

requests[].datestringData da solicitação, no formato YYYYMMDD
requests[].reasonstringEste 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[].valuenumberValorSó existe se operation for != 1
requests[].quantitynumberQuantidade que for baixadaSó existe se operation for 0
requests[].balanceArrayArray dos balances.
requests[].balance.typestringTipo do ativo
requests[].balance.balance_typestringSaldo 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
languagejs
themeRDark
titleresponse.json
collapsetrue
{
    "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:

PropriedadeTipoDescriçãoAdicional
operationnumberIndica qual solicitação está sendo requisitada.

0: Baixa

1: Transferência

2: Ampliação

assetstringCódigo do ativo
itemstringItem do ativo


requests[].statusstringStatus da solicitação

0: Pendente

1: Finalizada

2: Cancelada

requests[].datedataData da solicitaçãoFormato data Protheus "YYYYMMDD"
requests[].reasonstringMotivo (descrição)

Se operation=0 -> Motivo

Se operation=1 -> Detalhes

Se operation=2 -> Observação

requests[].valuenumberValorSó existe se operation for 1
requests[].quantitynumberQuantidade que for baixadaSó existe se operation for 0
requests[].balancestringSaldo que foi baixadoSó existe se operation for 0
requests[].typestringTipo 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
languagejs
themeRDark
titleresponse.json
collapsetrue
{
	"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:

PropriedadeTipoDescriçãoAdicional
locationarrayArray com a Localização-
latnumberLatitude-
lngnumberLongitude-
localstringCó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
languagejs
themeRDark
titleresponse.json
collapsetrue
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:

PropriedadeTipoDescriçãoAdicional
contentstringBase64 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
languagejs
themeRDark
titleresponse.json
collapsetrue
{
	"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 pagepageSize 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
languagejs
themeRDark
collapsetrue
{
         “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.