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>

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

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

HTTPcURLJavaScriptPython

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

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

Response

Response

{
    "meta": {
        "observed": {
            "scalar": 1
        }
    },
    "data": {
        "type": "products",
        "id": "3",
        "attributes": {
            "item_code": "PTEST",
            "item_description": "Test product",
            "sales_price": 100,
            "sales_price_includes_vat": false,
            "tax_code": "NOR",
            "applied_tax_code": "NOR",
            "notes": null,
            "is_merchandise": null,
            "location_in_warehouse": null,
            "sales_price_2": null,
            "sales_price_3": null,
            "purchase_price": null,
            "ean_barcode": null,
            "financial_cost": 0.0,
            "transport_cost": 0.0,
            "other_cost": 0.0,
            "customs_cost": 0.0,
            "estimated_total_cost": 0.0,
            "product_inventory_type": null,
            "accounting_number": null,
            "service_group": null,
            "is_active": true,
            "sales_price_vat_display": 123.00,
            "sales_price_2_vat_display": null,
            "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": null
            },
            "tax_exemption_reasons": {
                "data": null
            },
            "unit_of_measure": {
                "data": {
                    "type": "units_of_measure",
                    "id": "2"
                }
            }
        }
    }
}

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

HTTPcURLJavaScriptPython

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>

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

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

HTTPcURLJavaScriptPython

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

HTTPcURLJavaScriptPython

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

Payload

{
    "data": {
        "type": "products",
        "id": "6",
        "attributes": {
            "item_family_id": 4
        }
    }
}

Response

Response

{
    "meta": {
        "observed": {
            "scalar": 1
        }
    },
    "data": {
        "type": "products",
        "id": "6",
        "attributes": {
            "item_code": "123456",
            "item_description": "Test product with family",
            "sales_price": 100,
            "sales_price_includes_vat": false,
            "tax_code": "NOR",
            "applied_tax_code": "NOR",
            "notes": null,
            "is_merchandise": null,
            "location_in_warehouse": null,
            "sales_price_2": null,
            "sales_price_3": null,
            "purchase_price": null,
            "ean_barcode": null,
            "financial_cost": 0.0,
            "transport_cost": 0.0,
            "other_cost": 0.0,
            "customs_cost": 0.0,
            "estimated_total_cost": 0.0,
            "product_inventory_type": null,
            "accounting_number": null,
            "service_group": null,
            "is_active": true,
            "sales_price_vat_display": 123.00,
            "sales_price_2_vat_display": null,
            "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": "4"
                }
            },
            "tax_exemption_reasons": {
                "data": null
            },
            "unit_of_measure": {
                "data": {
                    "type": "units_of_measure",
                    "id": "2"
                }
            }
        }
    }

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

HTTPcURLJavaScriptPython

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

Payload

{
    "data": {
        "type": "services",
        "id": "7",
        "attributes": {
            "item_family_id": 4
        }
    }
}

Response

Response

{
    "meta": {
        "observed": {
            "scalar": 1
        }
    },
    "data": {
        "type": "services",
        "id": "7",
        "attributes": {
            "item_code": "54321",
            "item_description": "Serviço1",
            "sales_price": 10.0,
            "sales_price_includes_vat": false,
            "tax_code": "NOR",
            "applied_tax_code": "NOR",
            "notes": "Notas de Serviço",
            "is_merchandise": null,
            "location_in_warehouse": null,
            "sales_price_2": 20.0,
            "sales_price_3": 30.0,
            "purchase_price": 0.0,
            "ean_barcode": "",
            "financial_cost": 0.0,
            "transport_cost": 0.0,
            "other_cost": 0.0,
            "customs_cost": 0.0,
            "estimated_total_cost": 0.0,
            "product_inventory_type": null,
            "accounting_number": null,
            "service_group": "G1",
            "is_active": true,
            "sales_price_vat_display": 12.30,
            "sales_price_2_vat_display": 24.60,
            "sales_price_3_vat_display": 36.90,
            "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": "4"
                }
            },
            "tax_exemption_reasons": {
                "data": null
            },
            "unit_of_measure": {
                "data": {
                    "type": "units_of_measure",
                    "id": "5"
                }
            }
        }
    }
}

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

HTTPcURLJavaScriptPython

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

Payload

{
    "data": {
        "type": "products",
        "id": "6",
        "attributes": {
            "item_family_id": 4
        }
    }
}

Response

Response

{
    "meta": {
        "observed": {
            "scalar": 1
        }
    },
    "data": {
        "type": "products",
        "id": "6",
        "attributes": {
            "item_code": "123456",
            "item_description": "Test product with family",
            "sales_price": 100,
            "sales_price_includes_vat": false,
            "tax_code": "NOR",
            "applied_tax_code": "NOR",
            "notes": null,
            "is_merchandise": null,
            "location_in_warehouse": null,
            "sales_price_2": null,
            "sales_price_3": null,
            "purchase_price": null,
            "ean_barcode": null,
            "financial_cost": 0.0,
            "transport_cost": 0.0,
            "other_cost": 0.0,
            "customs_cost": 0.0,
            "estimated_total_cost": 0.0,
            "product_inventory_type": null,
            "accounting_number": null,
            "service_group": null,
            "is_active": true,
            "sales_price_vat_display": 123.00,
            "sales_price_2_vat_display": null,
            "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": "4"
                }
            },
            "tax_exemption_reasons": {
                "data": null
            },
            "unit_of_measure": {
                "data": {
                    "type": "units_of_measure",
                    "id": "2"
                }
            }
        }
    }

Associar Unidades de Medida a Serviços

Atualizar Produto

patch

Atualizar Produto

Authorizations

Body

Responses

200Success

patch

HTTPcURLJavaScriptPython

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

Payload

{
    "data": {
        "type": "service",
        "id": "6",
        "attributes": {
            "item_family_id": 4
        }
    }
}

Response

Response

{
    "meta": {
        "observed": {
            "scalar": 1
        }
    },
    "data": {
        "type": "services",
        "id": "7",
        "attributes": {
            "item_code": "54321",
            "item_description": "Serviço1",
            "sales_price": 10.0,
            "sales_price_includes_vat": false,
            "tax_code": "NOR",
            "applied_tax_code": "NOR",
            "notes": "Notas de Serviço",
            "is_merchandise": null,
            "location_in_warehouse": null,
            "sales_price_2": 20.0,
            "sales_price_3": 30.0,
            "purchase_price": 0.0,
            "ean_barcode": "",
            "financial_cost": 0.0,
            "transport_cost": 0.0,
            "other_cost": 0.0,
            "customs_cost": 0.0,
            "estimated_total_cost": 0.0,
            "product_inventory_type": null,
            "accounting_number": null,
            "service_group": "G1",
            "is_active": true,
            "sales_price_vat_display": 12.30,
            "sales_price_2_vat_display": 24.60,
            "sales_price_3_vat_display": 36.90,
            "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": "4"
                }
            },
            "tax_exemption_reasons": {
                "data": null
            },
            "unit_of_measure": {
                "data": {
                    "type": "units_of_measure",
                    "id": "5"
                }
            }
        }
    }
}