# Produtos e Serviços

## Produtos

### Obter Produtos

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

<mark style="color:blue;">`GET`</mark> `/products`

#### Path Parameters

| Name                | Type   | Description   |
| ------------------- | ------ | ------------- |
| filter\[item\_code] | String | \<item\_code> |

{% tabs %}
{% tab title="200: OK Toda a informação sobre o produto" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

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

<details>

<summary>Exemplo de Response</summary>

```json
{
    "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"
                    }
                }
            }
        }
    ]
}
```

</details>

###

### Criar Produtos

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/products" method="post" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

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:

{% tabs %}
{% tab title="Payload" %}
{% code title="Payload" %}

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

{% endcode %}

{% endtab %}

{% tab title="Response" %}
{% code title="Response" %}

```json
{
    "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"
                }
            }
        }
    }
}
```

{% endcode %}

{% endtab %}
{% endtabs %}

###

## 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

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

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/services" method="post" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

###

### Obter Todos os Serviços

<mark style="color:blue;">`GET`</mark> `/services`

#### Path Parameters

| Name                | Type   | Description   |
| ------------------- | ------ | ------------- |
| filter\[item\_code] | String | \<item\_code> |

{% tabs %}
{% tab title="200: OK Toda a informação sobre o serviço" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

###

### Obter Serviço

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

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/services" method="get" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

## &#x20;

***

### Associar Famílias de Itens a Produtos

{% hint style="info" %}
Já teve de ser criado previamente uma Família de Itens.&#x20;

Pode consultar mais em: [familia-de-itens](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens "mention")
{% endhint %}

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/products" method="patch" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

{% tabs %}
{% tab title="Payload" %}
{% code title="Payload" %}

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

{% endcode %}
{% endtab %}

{% tab title="Response" %}
{% code title="Response" %}

```json
{
    "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"
                }
            }
        }
    }
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Associar Famílias de Itens a Serviços

{% hint style="info" %}
Já teve de ser criado previamente uma Família de Itens.&#x20;

Pode consultar mais em: [familia-de-itens](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens "mention")
{% endhint %}

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/services" method="patch" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

{% tabs %}
{% tab title="Payload" %}
{% code title="Payload" %}

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

{% endcode %}
{% endtab %}

{% tab title="Response" %}
{% code title="Response" %}

```json
{
    "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"
                }
            }
        }
    }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

##

### Associar Unidades de Medida a Produtos

{% hint style="info" %}
Já teve de ser criado previamente uma Unidade de Medida.&#x20;

Pode consultar mais em: [unidades-de-medida](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida "mention")
{% endhint %}

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/products" method="patch" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

{% code title="PATCH" %}

```
https://api/v1.toconline.com/api/products
```

{% endcode %}

{% tabs %}
{% tab title="Payload" %}
{% code title="Payload" %}

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

{% endcode %}
{% endtab %}

{% tab title="Response" %}
{% code title="Response" %}

```json
{
    "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"
                }
            }
        }
    }
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Associar Unidades de Medida a Serviços

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/products" method="patch" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

{% code title="PATCH" %}

```
https://api/v1.toconline.com/api/services
```

{% endcode %}

{% tabs %}
{% tab title="Payload" %}
{% code title="Payload" %}

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

{% endcode %}
{% endtab %}

{% tab title="Response" %}
{% code title="Response" %}

```json
{
    "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"
                }
            }
        }
    }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}