{b% load base_tags %}

Produtos

Um produto representa um artigo ou serviço que pode associar e lançar a documentos de venda, stock, etc...

API - Produtos:

Apresentamos alguns end-points que permitem consultar, criar e editar produtos.

  1. Listar Produtos
  2. Procurar Produto
  3. Criar Produto
  4. Obter Produto
  5. Alterar Produto
  6. Informação de Stocks de Produto
  7. Definir Preços do Produto
Parâmetros
code Código int Valores deverão ser compostos apenas por letras, números, caracteres sublinhado, hífenes, pontos ou barras.
Preenchimento Obrigatório*, Valor Único, Tamanho: 20
description Descrição string
Preenchimento Obrigatório*, Tamanho: 255
short_description Descrição Curta string Tamanho: 100
long_description Descrição Alargada string, Tamanho: 10000.

A utilização deste campo pode estar limitada por opções de configuração do CloudInvoice.

family Família int Relação com o campo 'id' da tabela 'Famílias de Produtos'.
Preenchimento Obrigatório*
product_type Tipo de Produto int. Preenchimento Obrigatório*
Pode tomar os valores:
  • 131 - Produto
  • 132 - Serviço
  • 134 - Pack
  • 135 - Transformado
  • 138 - Portes
  • 140 - Impostos
  • 141 - Outros
  • 143 - Adiantamento
  • 144 - Rapel
  • 146 - Impostos Especiais de Consumo
  • 147 - Menu

A utilização de alguns dos valores possíveis para este campo pode ser limitada por opções de configuração do CloudInvoice ou pelo tipo de licença que possui.

product_category Categoria de Produto int.
Pode tomar os valores:
  • 211 - Mercadorias
  • 212 - Matérias-primas, subsidiárias e de consumo
  • 213 - Produtos acabados e intermédios
  • 214 - Subprodutos, desperdícios e refugos
  • 215 - Produtos e trabalhos em curso
  • 217 - Outros (não contabilizável em Inventário)

Default: Mercadorias
bar_code_type Tipo de Código de Barras int Pode tomar os valores:
  • 151 - (Nenhum)
  • 152 - Fornecedor
  • 153 - Interno EAN13
  • 154 - Valor Incluído
  • 155 - Peso Incluído
  • 156 - Inclui Quantidade
  • 157 - Inclui Preço Unitário
  • 158 - Número de Série
  • 159 - Inclui Lote
  • 162 - Produtor

A utilização de alguns dos valores possíveis para este campo pode ser limitada pelo tipo de produto, opções de configuração do CloudInvoice ou pelo tipo de licença que possui.

Default: (Nenhum)
bar_code Código de Barras string O preenchimento deste campo é obrigatório quando bar_code_type != 151. Tamanho: 30
vat_tax Taxa de IVA int Relação com o campo 'id' da tabela 'Tabelas de Impostos'.
is_exempt_withholding Isento de Retenção na Fonte bool

A utilização deste campo pode estar limitada por opções de configuração do CloudInvoice.

Default: false
withholding_type Tipo de Retenção int Pode tomar os valores:
  • 1631 - Imposto sobre Rendimento de pessoas Singulares
  • 1632 - Imposto sobre Rendimento de pessoas Colectivas
  • 1633 - Imposto do Selo

A utilização deste campo pode estar limitada por opções de configuração do CloudInvoice.

measure_unit Unidade de Medida int Relação com o campo 'id' da tabela 'Unidades de Medida'.
do_stock_management Movimenta Stock bool Default: variável
can_have_negative_stock Pode ter stock negativo bool Aplicável apenas se do_stock_management = true. Default: false
use_serial_number Tem Nº de Série bool Incompatível com has_lots = true. Default: false
use_internal_serial_number Usar Nº de Série Interno bool Aplicável apenas se use_serial_number = true. Default: false
has_lots Tem Lotes bool Incompatível com use_serial_number = true. Default: false
gross_weight Peso Bruto decimal
net_weight Peso Líquido decimal
profit_margin Margem de Lucro de Referência decimal
max_discount Desconto Máximo decimal Valores: entre 0 e 100
obs Observações string Tamanho: 255

Listar Produtos /products GET

Fornece uma lista de todos os produtos existentes.

                    
                        $ curl https://www.cloudinvoice.net/v3/products/
                    
                  
                    
                        {
    "results": [
        {
            "id": 1,
            "code": "PROD1",
            "description": "Produto Standard 1",
            "short_description": "Produto Standard 1",
            "family_id": 1,
            "family": "Família 1",
            "family_code": "FAM1",
            "family_description": "Família 1",
            "unit_price_raw": 100.0,
            "unit_price": "100.00 €",
            "unit_price_tax_inc_raw": 123.0,
            "unit_price_tax_inc": "123.00 €",
            "average_cost_price_raw": 0,
            "average_cost_price": "0.00 €",
            "last_cost_price_raw": 0,
            "last_cost_price": "0.00 €",
            "do_stock_management": 1,
            "physical_qty": 9.0,
            "use_serial_number": 0,
            "has_lots": 0,
            "read_weight_from_scale": 0
        },
        ...
    ],
    "count_total": 10
}

Procurar Produto /product-seek/<search> GET

Procurar produto por código.

Importante:
 Como o termo de procura é incluído no URL do pedido, deverá ser feito escape aos caracteres não alfanuméricos, substituindo os espaços por '+' (ex: "PT-Client+Demo"). 

                    
                        $ curl https://www.cloudinvoice.net/v3/product-seek/PROD1/
                    
                  
                    
                        {
    "id": 1,
    "code": "PROD1",
    "description": "Produto Standard 1",
    "short_description": "Produto Standard 1",
    "family_id": 1,
    "family": "Família 1 (FAM1)",
    "sub_family_id": null,
    "sub_family": "",
    "product_type": 131,
    "product_type_saft": 3271,
    "product_category": 211,
    "bar_code_type": 153,
    "bar_code": "2000000000015",
    "vat_tax_id": 1,
    "vat_tax": "Taxa Normal",
    "vat_tax_rate": 23.0,
    "vat_exemption_id": null,
    "unit_price": 100.0,
    "unit_price_tax_inc": 123.0,
    "last_cost_price": 0.0,
    "average_cost_price": 0.0,
    "profit_margin": 0.0,
    "do_stock_management": true,
    "can_have_negative_stock": true,
    "physical_qty": 9.0,
    "global_physical_qty": 9.0,
    "location_physical_qty": 9.0,
    "total_entry_qty": 0.0,
    "total_exit_qty": 1.0,
    "measure_unit_id": 1,
    "measure_unit": "Unidade",
    "measure_unit__code": "UNI",
    "product_group_id": null,
    "product_group": "",
    "product_section_id": null,
    "product_section": "",
    "supplier_id": null,
    "supplier": "",
    "use_serial_numbers": false,
    "has_lots": false,
    "is_obsolete": false,
    "obs": "",
    "prices": [
        {
            "price_line_id": 1,
            "price_line": "Preço de Venda 1",
            "unit_price": 100.0,
            "unit_price_tax_inc": 123.0
        }
    ],
    "alt_codes": [],
    ...
}

Criar Produto /products/new POST

Criar um novo produto.

Parâmetros Extra
unit_price_# Preço Unitário # decimal
Permite definir até 5 preços unitários de venda do produto no momento da criação. '#' pode tomar valores entre 1 e 5 e será associado à linha de preços com o mesmo índice.
Fornecer um valor ao campo, por exemplo, unit_price_1 não requer que o valor de unit_price_tax_inc_1 seja também fornecido. Supondo que usa, por exemplo, 3 linhas de preços distintas, fornecer um valor no campo unit_price_4 não terá qualquer efeito.
unit_price_tax_inc_# Preço Unitário com IVA # decimal
Permite definir até 5 preços unitários (com IVA) de venda do produto no momento da criação. '#' pode tomar valores entre 1 e 5 e será associado à linha de preços com o mesmo índice.
Fornecer um valor ao campo, por exemplo, unit_price_tax_inc_1 não requer que o valor de unit_price_1 seja também fornecido. Supondo que usa, por exemplo, 2 linhas de preços distintas, fornecer um valor no campo unit_price_tax_inc_3 não terá qualquer efeito. 
                    
                        $ curl -X POST https://www.cloudinvoice.net/v3/product/new/
    -d '{
        "code": "SAMPLE",
        "description": "Produto Exemplo",
        "family": 1,
        "product_type": 131,
        "do_stock_management": true,
        "can_have_negative_stock": true,
        "vat_tax": 1,
        "unit_price_1": 2.35
    }'
                    
                  
                    
                        {
    "id": 30,
    "code": "SAMPLE",
    "description": "Produto Exemplo",
    "short_description": "Produto Exemplo",
    "family_id": 1,
    "family": "Família 1 (FAM1)",
    "sub_family_id": null,
    "sub_family": "",
    "product_type": 131,
    "product_type_saft": 3271,
    "product_category": 211,
    "bar_code_type": 151,
    "bar_code": null,
    "vat_tax_id": 1,
    "vat_tax": "Taxa Normal",
    "vat_tax_rate": 23.0,
    "vat_exemption_id": null,
    "unit_price": 2.35,
    "unit_price_tax_inc": 2.8905,
    "last_cost_price": 0.0,
    "average_cost_price": 0.0,
    "profit_margin": 0.0,
    "do_stock_management": true,
    "can_have_negative_stock": true,
    "physical_qty": 0.0,
    "global_physical_qty": 0.0,
    "location_physical_qty": 0.0,
    "total_entry_qty": 0.0,
    "total_exit_qty": 0.0,
    "measure_unit_id": 1,
    "measure_unit": "Unidade",
    "measure_unit__code": "UNI",
    "product_group_id": null,
    "product_group": "",
    "product_section_id": null,
    "product_section": "",
    "supplier_id": null,
    "supplier": "",
    "use_serial_numbers": false,
    "has_lots": false,
    "is_obsolete": false,
    "obs": "",
    "prices": [
        {
            "price_line_id": 1,
            "price_line": "Preço de Venda 1",
            "unit_price": 2.35,
            "unit_price_tax_inc": 2.8905
        }
    ],
    "alt_codes": [],
    ...
}

Obter Produto /product/<id> GET

Obter informação de um produto a partir do seu ID.

                    
                        $ curl https://www.cloudinvoice.net/v3/product/1/
                    
                  
                    
                        {
    "id": 1,
    "code": "PROD1",
    "description": "Produto Standard 1",
    "short_description": "Produto Standard 1",
    "family_id": 1,
    "family": "Família 1 (FAM1)",
    "sub_family_id": null,
    "sub_family": "",
    "product_type": 131,
    "product_type_saft": 3271,
    "product_category": 211,
    "bar_code_type": 153,
    "bar_code": "2000000000015",
    "vat_tax_id": 1,
    "vat_tax": "Taxa Normal",
    "vat_tax_rate": 23.0,
    "vat_exemption_id": null,
    "unit_price": 100.0,
    "unit_price_tax_inc": 123.0,
    "last_cost_price": 0.0,
    "average_cost_price": 0.0,
    "profit_margin": 0.0,
    "do_stock_management": true,
    "can_have_negative_stock": true,
    "physical_qty": 9.0,
    "global_physical_qty": 9.0,
    "location_physical_qty": 9.0,
    "total_entry_qty": 0.0,
    "total_exit_qty": 1.0,
    "measure_unit_id": 1,
    "measure_unit": "Unidade",
    "measure_unit__code": "UNI",
    "product_group_id": null,
    "product_group": "",
    "product_section_id": null,
    "product_section": "",
    "supplier_id": null,
    "supplier": "",
    "use_serial_numbers": false,
    "has_lots": false,
    "is_obsolete": false,
    "obs": "",
    "prices": [
        {
            "price_line_id": 1,
            "price_line": "Preço de Venda 1",
            "unit_price": 100.0,
            "unit_price_tax_inc": 123.0
        }
    ],
    "alt_codes": [],
    ...
}

Alterar Produto /product/<pk>/update POST

Alterar valores do produto.

Parâmetros Extra
is_obsolete Obsoleto bool Default: false 
                    
                        $ curl -X POST https://www.cloudinvoice.net/v3/product/30/update/
    -d '{
        "bar_code_type": 152,
        "bar_code": "5605566000126"
    }'
                    
                  
                    
                        {
    "id": 30,
    "code": "SAMPLE",
    "description": "Produto Exemplo",
    "short_description": "Produto Exemplo",
    "family_id": 1,
    "family": "Família 1 (FAM1)",
    "sub_family_id": null,
    "sub_family": "",
    "product_type": 131,
    "product_type_saft": 3271,
    "product_category": 211,
    "bar_code_type": 152,
    "bar_code": "5605566000126",
    "vat_tax_id": 1,
    "vat_tax": "Taxa Normal",
    "vat_tax_rate": 23.0,
    "vat_exemption_id": null,
    "unit_price": 2.35,
    "unit_price_tax_inc": 2.8905,
    "last_cost_price": 0.0,
    "average_cost_price": 0.0,
    "profit_margin": 0.0,
    "do_stock_management": true,
    "can_have_negative_stock": true,
    "physical_qty": 0.0,
    "global_physical_qty": 0.0,
    "location_physical_qty": 0.0,
    "total_entry_qty": 0.0,
    "total_exit_qty": 0.0,
    "measure_unit_id": 1,
    "measure_unit": "Unidade",
    "measure_unit__code": "UNI",
    "product_group_id": null,
    "product_group": "",
    "product_section_id": null,
    "product_section": "",
    "supplier_id": null,
    "supplier": "",
    "use_serial_numbers": false,
    "has_lots": false,
    "is_obsolete": false,
    "obs": ""
    ...
}

Informação de Stocks de Produto /product/<pk>/stocks GET

Obter informação relativo aos stocks de um produto.

                    
                        $ curl https://www.cloudinvoice.net/v3/product/1/stocks/
                    
                  
                    
                        {
    "company_code": "demo",
    "product": "PROD1 - Produto Standard 1",
    "physical_qty": 10.0
    "warehouses": [
        {
            "id": 1,
            "description": "Armazém 1",
            "physical_qty": 10.0,
            "available_qty": 10.0,
            "cust_ordered_qty": 0.0
        }
    ]
}

Definir Preços do Produto /product/<pk>/prices GET POST

Endpoint usado para actualizar as diferentes linhas de preços de um produto.

Nas repostas, os campos são dados com um sufixo '_#', em que o cardinal (#) corresponde a um valor numérico (exemplo: _1).
Os campos que partilhem o mesmo sufixo dizem respeito à mesma Linha de Preços.
Isto é, os campos unit_price_pu_1 e unit_price_tax_inc_pu_1 são, respectivamente, os preços unitários sem IVA e com IVA da 1ª Linha de Preços, cujo nome se encontrará no campo price_line_pu_1.

Parâmetros
price_line_pu_# Nome da Linha de Preços # string, Campo Apenas de Leitura
unit_price_pu_# Preço Unitário sem IVA # decimal
Fornecer um valor neste campo, por exemplo unit_price_pu_1, não requer que o respectivo valor com IVA seja também fornecido ao campo unit_price_tax_inc_pu_1. Esse será automaticamente calculado tendo em conta a Taxa de IVA do Produto.
unit_price_tax_inc_pu_# Preço Unitário com IVA # decimal
Fornecer um valor neste campo, por exemplo unit_price_tax_inc_pu_1, não requer que o respectivo valor sem IVA seja também fornecido ao campo unit_price_pu_1. Esse valor será automaticamente calculado tendo em conta a Taxa de IVA do Produto.
profit_margin_pu_# Margém de Lucro # decimal, Campo Apenas de Leitura
Este valor é calculado automaticamente com base no Preço de Custo Último do Produto 
                    
                        $ curl https://www.cloudinvoice.net/v3/product/1/prices/
                    
                  
                    
                        {
  "instance": {
    "id": 1,
    "price_line_pu_1": "Preço de Venda 1",
    "unit_price_pu_1": 100.0,
    "unit_price_tax_inc_pu_1": 123.0,
    "profit_margin_pu_1": 100.0,
    "price_line_pu_2": "Preço Especial",
    "unit_price_pu_2": 80.0,
    "unit_price_tax_inc_pu_2": 98.4,
    "profit_margin_pu_2": 60.0,
  },
  "form": {
    ...
  }
}
                    
                  
                    
                        $ curl -X POST https://www.cloudinvoice.net/v3/product/1/prices/
    -d '{
        "unit_price_pu_2": 75.0
    }'
                    
                  
                    
                        {
  "id": 1,
  "price_line_pu_1": "Preço de Venda 1",
  "unit_price_pu_1": 100.0,
  "unit_price_tax_inc_pu_1": 123.0,
  "profit_margin_pu_1": 100.0,
  "price_line_pu_2": "Preço Especial",
  "unit_price_pu_2": 75.0,
  "unit_price_tax_inc_pu_2": 92.25,
  "profit_margin_pu_2": 50.0
}