Produtos e Serviços

Neste capitulo serão descritos 2 tipos de itens diferentes. Os Serviços e os Protudos. Ambos partilham de atributos iguais mas têm diferentes rotas para realizar diferentes tipos de ações.

Produtos

Obter Produtos

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>

{
    // 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

Exemplo de Response
{
    "data": [
        {
            "type": "products",
            "id": "2",
            "attributes": {
                "item_code": "100",
                "item_description": "Isto é uma breve descrição",
                "sales_price": 2.0,
                "sales_price_includes_vat": false,
                "tax_code": "INT",
                "applied_tax_code": "INT",
                "notes": "Isto são notas de produtos",
                "is_merchandise": null,
                "location_in_warehouse": null,
                "sales_price_2": 4.0,
                "sales_price_3": null,
                "purchase_price": 5.0,
                "ean_barcode": "553214",
                "financial_cost": 2.0,
                "transport_cost": 1.0,
                "other_cost": 0.0,
                "customs_cost": 10.0,
                "estimated_total_cost": 18.0,
                "product_inventory_type": "P",
                "accounting_number": null,
                "service_group": null,
                "is_active": true,
                "sales_price_vat_display": 2.26,
                "sales_price_2_vat_display": 4.52,
                "sales_price_3_vat_display": null,
                "applied_tax_exemption_reason_id": null
            },
            "relationships": {
                "applied_tax_exemption_reason": {
                    "data": null
                },
                "company": {
                    "data": {
                        "type": "current_company",
                        "id": "800000046"
                    }
                },
                "item_families": {
                    "data": {
                        "type": "item_families",
                        "id": "3"
                    }
                },
                "tax_exemption_reasons": {
                    "data": null
                },
                "unit_of_measure": {
                    "data": {
                        "type": "units_of_measure",
                        "id": "5"
                    }
                }
            }
        }
    ]
}

Criar Produtos

Criar Produto

post

Criar Produto

Authorizations
Body
Responses
200
Sucesso
application/json
post
POST /api/products HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 209

{
  "data": {
    "attributes": {
      "item_code": 777777,
      "item_description": "Product with a family",
      "item_family_id": 4,
      "sales_price": 100,
      "sales_price_includes_vat": false,
      "tax_code": "NOR",
      "type": "Product"
    },
    "type": "products"
  }
}
200

Sucesso

{
  "data": {
    "attributes": {
      "accounting_number": null,
      "applied_tax_code": "NOR",
      "applied_tax_exemption_reason_id": null,
      "customs_cost": 0,
      "ean_barcode": null,
      "estimated_total_cost": 0,
      "financial_cost": 0,
      "is_active": true,
      "is_merchandise": null,
      "item_code": "777777",
      "item_description": "Product with a family",
      "location_in_warehouse": null,
      "notes": null,
      "other_cost": 0,
      "product_inventory_type": null,
      "purchase_price": null,
      "sales_price": 100,
      "sales_price_2": null,
      "sales_price_2_vat_display": null,
      "sales_price_3": null,
      "sales_price_3_vat_display": null,
      "sales_price_includes_vat": false,
      "sales_price_vat_display": 123,
      "service_group": null,
      "tax_code": "NOR",
      "transport_cost": 0
    },
    "id": "21",
    "relationships": {
      "applied_tax_exemption_reason": {
        "data": null
      },
      "company": {
        "data": {
          "id": "800000046",
          "type": "current_company"
        }
      },
      "item_families": {
        "data": {
          "id": "4",
          "type": "item_families"
        }
      },
      "tax_exemption_reasons": {
        "data": null
      },
      "unit_of_measure": {
        "data": {
          "id": "2",
          "type": "units_of_measure"
        }
      }
    },
    "type": "products"
  },
  "meta": {
    "observed": {
      "scalar": 1
    }
  }
}

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:

Payload
{
  "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)
    }
  }
}

Serviços

Criar Serviços

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)
    }
  }
}

Criar Serviço

post

Criar Serviço

Authorizations
Body
Responses
200
Sucesso
application/json
post
POST /api/services HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 303

{
  "data": [
    {
      "attributes": {
        "customs_cost": 0,
        "ean_barcode": "",
        "estimated_total_cost": 0,
        "financial_cost": 0,
        "item_code": "333333",
        "item_description": "Serviço NOR",
        "other_cost": 0,
        "purchase_price": 0,
        "sales_price": 10,
        "sales_price_2": 20,
        "sales_price_3": 30,
        "transport_cost": 0,
        "type": "Service"
      },
      "type": "services"
    }
  ]
}
200

Sucesso

{
  "data": [
    {
      "attributes": {
        "accounting_number": null,
        "applied_tax_code": null,
        "applied_tax_exemption_reason_id": null,
        "customs_cost": 0,
        "ean_barcode": "",
        "estimated_total_cost": 0,
        "financial_cost": 0,
        "is_active": true,
        "is_merchandise": null,
        "item_code": "333333",
        "item_description": "Serviço NOR",
        "location_in_warehouse": null,
        "notes": null,
        "other_cost": 0,
        "product_inventory_type": null,
        "purchase_price": 0,
        "sales_price": 10,
        "sales_price_2": 20,
        "sales_price_2_vat_display": null,
        "sales_price_3": 30,
        "sales_price_3_vat_display": null,
        "sales_price_includes_vat": null,
        "sales_price_vat_display": null,
        "service_group": null,
        "tax_code": null,
        "transport_cost": 0
      },
      "id": "19",
      "relationships": {
        "applied_tax_exemption_reason": {
          "data": null
        },
        "company": {
          "data": {
            "id": "800000046",
            "type": "current_company"
          }
        },
        "item_families": {
          "data": null
        },
        "tax_exemption_reasons": {
          "data": null
        },
        "unit_of_measure": {
          "data": {
            "id": "2",
            "type": "units_of_measure"
          }
        }
      },
      "type": "services"
    }
  ],
  "meta": {
    "observed": {
      "scalar": 1
    }
  }
}

Obter Todos os Serviços

GET /services

Path Parameters

Name
Type
Description

filter[item_code]

String

<item_code>

{
    // Response
}

Obter Serviço

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

Obter Todos os Serviços

get

Obter Todos os Serviços

Authorizations
Responses
200
Sucesso
application/json
get
GET /api/services HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
200

Sucesso

{
  "data": [
    {
      "attributes": {
        "accounting_number": null,
        "applied_tax_code": "NOR",
        "applied_tax_exemption_reason_id": null,
        "customs_cost": 0,
        "ean_barcode": "",
        "estimated_total_cost": 0,
        "financial_cost": 0,
        "is_active": true,
        "is_merchandise": null,
        "item_code": "54321",
        "item_description": "Serviço1",
        "location_in_warehouse": null,
        "notes": "Notas de Serviço",
        "other_cost": 0,
        "product_inventory_type": null,
        "purchase_price": 0,
        "sales_price": 10,
        "sales_price_2": 20,
        "sales_price_2_vat_display": 24.6,
        "sales_price_3": 30,
        "sales_price_3_vat_display": 36.9,
        "sales_price_includes_vat": false,
        "sales_price_vat_display": 12.3,
        "service_group": "G1",
        "tax_code": "NOR",
        "transport_cost": 0
      },
      "id": "7",
      "relationships": {
        "applied_tax_exemption_reason": {
          "data": null
        },
        "company": {
          "data": {
            "id": "800000046",
            "type": "current_company"
          }
        },
        "item_families": {
          "data": {
            "id": "4",
            "type": "item_families"
          }
        },
        "tax_exemption_reasons": {
          "data": null
        },
        "unit_of_measure": {
          "data": {
            "id": "5",
            "type": "units_of_measure"
          }
        }
      },
      "type": "services"
    }
  ]
}

Associar Famílias de Itens a Produtos

Já teve de ser criado previamente uma Família de Itens.

Pode consultar mais em: Família de Itens

Atualizar Produto

patch

Atualizar Produto

Authorizations
Body
Responses
200Success
patch
PATCH /api/products HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "data": {
    "attributes": {
      "item_family_id": 4
    },
    "id": "6",
    "type": "products"
  }
}
200Success
No content
Payload
{
    "data": {
        "type": "products",
        "id": "6",
        "attributes": {
            "item_family_id": 4
        }
    }
}

Associar Famílias de Itens a Serviços

Já teve de ser criado previamente uma Família de Itens.

Pode consultar mais em: Família de Itens

Atualizar Serviço

patch

Atualizar Serviço

Authorizations
Body
Responses
200Success
patch
PATCH /api/services HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "data": {
    "attributes": {
      "item_family_id": 4
    },
    "id": "7",
    "type": "services"
  }
}
200Success
No content
Payload
{
    "data": {
        "type": "services",
        "id": "7",
        "attributes": {
            "item_family_id": 4
        }
    }
}

Associar Unidades de Medida a Produtos

Já teve de ser criado previamente uma Unidade de Medida.

Pode consultar mais em: Unidades de Medida

Atualizar Produto

patch

Atualizar Produto

Authorizations
Body
Responses
200Success
patch
PATCH /api/products HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "data": {
    "attributes": {
      "item_family_id": 4
    },
    "id": "6",
    "type": "products"
  }
}
200Success
No content
PATCH
https://api/v1.toconline.com/api/products
Payload
{
    "data": {
        "type": "products",
        "id": "6",
        "attributes": {
            "item_family_id": 4
        }
    }
}

Associar Unidades de Medida a Serviços

Atualizar Produto

patch

Atualizar Produto

Authorizations
Body
Responses
200Success
patch
PATCH /api/products HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "data": {
    "attributes": {
      "item_family_id": 4
    },
    "id": "6",
    "type": "products"
  }
}
200Success
No content
PATCH
https://api/v1.toconline.com/api/services
Payload
{
    "data": {
        "type": "service",
        "id": "6",
        "attributes": {
            "item_family_id": 4
        }
    }
}

PreviousFornecedores, Morada e E-mailNextVendas

Last updated