Produtos e serviços

O atual capítulo tem como objetivo descrever as rotas da API responsáveis pela criação e gestão de produtos e serviços

Produtos

Os detalhes do pedido POST para a criação de produtos estão descritos de seguida, em formato OpenAPI, e em cURL.

curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/products'

No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o <payload JSON> deverá ter o seguinte formato

{
  "data": {
    "type": "products",                         // [OBRIGATÓRIO]
    "attributes": {
      "type": "Product",                        // [OBRIGATÓRIO]
      "item_code": "PTEST",                     // [OBRIGATÓRIO]
      "item_description": "Test product",       // [OBRIGATÓRIO]
      "sales_price": 100,                       // [OPCIONAL]
      "sales_price_includes_vat": false,        // [OPCIONAL] Por omissão, false; true, se o preço de venda do produto incluir IVA
      "tax_code": "NOR"                         // [OPCIONAL] Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento)
    }
  }
}

POST/products

Body

application/json

dataobject

Response

200

OK

Body

application/json

dataobject

Request

JavaScriptCurl

const response = await fetch('/products', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "data": {
    "type": "products",
    "attributes": {
      "item_code": "text",
      "item_description": "text",
      "sales_price_includes_vat": false,
      "tax_code": "text",
      "notes": "text",
      "is_active": false,
      "product_inventory_type": "text",
      "ean_barcode": "text",
      "sales_price_vat_display": "text",
      "sales_price_2_vat_display": "text",
      "sales_price_3_vat_display": "text"
    },
    "relationships": {
      "company": {
        "data": {
          "resource": "current_company"
        }
      },
      "unit_of_measure": {
        "data": {
          "resource": "units_of_measure"
        }
      },
      "item_families": {
        "data": {
          "resource": "item_families"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "resource": "tax_exemption_reasons"
        }
      }
    }
  }
}

De modo a obter informações sobre um dado produto, poderá realizar o seguinte pedido

GET /products

Path Parameters

Name	Type	Description
filter[item_code]	String	<item_code>

200: OK Toda a informação sobre o produto

{
    // Response
}

Neste, pode não indicar nenhum filtro, e obter todos os produtos disponíveis, ou então filtrar por qualquer um dos campos disponíveis, tal como no exemplo dado, e seguindo as convenções JSONAPI

Serviços

Os detalhes do pedido POST para a criação de serviços estão descritos de seguida, em formato OpenAPI, e em cURL.

curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/services'

No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o <payload JSON> deverá ter o seguinte formato

{
  "data": {
    "type": "services",                         // [OBRIGATÓRIO]
    "attributes": {
      "type": "Service",                        // [OBRIGATÓRIO]
      "item_code": "STEST",                     // [OBRIGATÓRIO]
      "item_description": "Test service",       // [OBRIGATÓRIO]
      "sales_price": 100,                       // [OPCIONAL]
      "sales_price_includes_vat": false,        // [OPCIONAL] Por omissão, false; true, se o preço de venda do produto incluir IVA
      "tax_code": "NOR"                         // [OPCIONAL] Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento)
    }
  }
}

POST/services

Body

application/json

dataobject

Response

200

OK

Body

application/json

dataobject

Request

JavaScriptCurl

const response = await fetch('/services', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "data": {
    "type": "services",
    "attributes": {
      "item_code": "text",
      "item_description": "text",
      "service_group": "text",
      "sales_price_includes_vat": false,
      "tax_code": "text",
      "notes": "text",
      "is_active": false,
      "sales_price_vat_display": "text",
      "sales_price_2_vat_display": "text",
      "sales_price_3_vat_display": "text"
    },
    "relationships": {
      "company": {
        "data": {
          "resource": "current_company"
        }
      },
      "unit_of_measure": {
        "data": {
          "resource": "units_of_measure"
        }
      },
      "item_families": {
        "data": {
          "resource": "item_families"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "resource": "tax_exemption_reasons"
        }
      }
    }
  }
}

De modo a obter informações sobre um dado serviço, poderá realizar o seguinte pedido

GET /services

Path Parameters

Name	Type	Description
filter[item_code]	String	<item_code>

200: OK Toda a informação sobre o serviço

{
    // Response
}

Neste, pode não indicar nenhum filtro, e obter todos os serviços disponíveis, ou então filtrar por qualquer um dos campos disponíveis, tal como no exemplo dado, e seguindo as convenções JSONAPI