# Lista de produtos

Retorna lista de produtos cadastrados.

Endpoint: GET /api/v3/products
Version: 3.0.0
Security: OAuth2

## Header parameters:

  - `CPlug-Company-Id` (number, required)
    Id da Empresa (Company).

Você pode localizar os IDs das empresas no _endpoint_ de listagem de empresas.
    Example: 12

## Query parameters:

  - `products_id` (string)
    Filtra pelos IDs dos produtos. Pode passar mais de um ID numérico separado por virgula.
    Example: "1,2,3"

  - `search` (string)
    Filtra pelas principais propriedades do produto, incluindo name, sku, e description.
    Example: "Celular"

  - `name` (string)
    Filtra pelo nome do produto.
    Example: "Celular"

  - `sku` (string)
    Filtra pelo SKU do produto.
    Example: "ABC123"

  - `categories_id` (string)
    Filtra pelos IDs das categorias. Pode passar mais de um ID numérico separado por virgula.
    Example: "1,2,3"

  - `unit_ids` (array)
    Lista de IDs das unidades de medida para filtrar produtos.
    Example: [1,2,3]

  - `attribute_id` (number)
    Filtra produtos contendo uma variação com esse ID.
    Example: 123

  - `price_list_ids` (string)
    Filtra produtos associados a alguma lista de preços dentre os IDs informados. Permitido passar mais de um ID numérico separado por virgula.
    Example: "1,2,3"

  - `price_list_ids_filter_type` (string)
    Altera o comportamento do filtro price_list_ids.
- include: Retorna produtos que estão associados a alguma lista de preços dentre os IDs informados.
- exclude: Exclui produtos que estão associados a alguma lista de preços dentre os IDs informados.
    Enum: "include", "exclude"

  - `barcode` (string)
    Filtra pelo código de barra do produto.
    Example: "1502298184770"

  - `min_price` (number)
    Filtra produtos com preço maior ou igual ao valor informado.
    Example: 10.5

  - `max_price` (number)
    Filtra produtos com preço menor ou igual ao valor informado.
    Example: 100

  - `app_ids` (string)
    Filtra produtos disponíveis nos aplicativos informados. Pode passar mais de um ID numérico separado por vírgula.
    Example: "1,2,3"

  - `app_ids_filter_type` (string)
    Altera o comportamento do filtro app_ids.
- include: Retorna produtos que estão disponíveis nos aplicativos informados.
- exclude: Exclui produtos que estão disponíveis nos aplicativos informados.
    Enum: "include", "exclude"

  - `is_available_for_sale` (boolean)
    Filtra produtos disponíveis para venda nos aplicativos informados.
Obrigatório informar app_ids quando este filtro for utilizado.

  - `with_attributes` (boolean)
    Filtro que seleciona produtos que contenham atributos.

  - `with_grid` (boolean)
    Filtro que seleciona produtos pelos atributos tipo grid.

  - `with_optionals` (boolean)
    Filtro que seleciona produtos pelos opcionais.

  - `with_stock` (boolean)
    Filtro que seleciona produtos pelo estoque.

  - `with_price_list` (boolean)
    Filtro permite retornar a listagem de listas de preços associados no produto.

  - `order_by_field` (string)
    Ordena pelo campo.
Exemplo:
  - date Data
  - id Código da transferência
    Enum: "date", "id"

  - `order_by_type` (string)
    Tipo de ordenação.
Exemplo:
  - asc Ascendente
  - desc Descendente
    Enum: "asc", "desc"

  - `types` (string)
    Filtro que seleciona produtos pelos tipos. Permitido passar mais de um tipo separado por virgula, sem espaços.

- simple: Produto simples.
- combo: Produto combo.
- production_process: Processo produtivo.
- automatic_production: Produção automática.
- component: Insumo.
    Example: "simple,combo"

  - `page` (number)
    Indica a página da paginação.

  - `per_page` (number)
    Indica a quantidade de itens por página.

  - `updated_from` (string)
    Filtra por dados que foram atualizadas a partir de uma data. (Formato: YYYY-MM-DDThh:mm:ss+hh:mm).

  - `created_from` (string)
    Filtra por dados que foram atualizadas a partir de uma data. (Formato: YYYY-MM-DDThh:mm:ss+hh:mm).

  - `deleted` (string)
    Filtro para indicar se deve retornar dados apagados ou não.
    Enum: "not_include", "include", "only"

## Response 200 fields (application/json):

  - `data` (object)

  - `data.products` (array)
    Representa a lista de produtos.

  - `data.products.id` (integer, required)
    Identificador único do produto.
    Example: 123

  - `data.products.name` (string, required)
    Nome do produto.
    Example: "Nome do produto"

  - `data.products.type` (string)
    Tipo do produto.

- simple: Produto simples.
- combo: Produto combo.
- production_process: Processo produtivo.
- automatic_production: Produção automática.
- component: Insumo.
    Enum: "simple", "combo", "production_process", "automatic_production", "component"

  - `data.products.option_type` (object)
    Informações sobre as opções do produto.

  - `data.products.option_type.type` (string)
    Tipo de opção do produto.

- simple: Produto sem variações ou grades.
- composition: Produto com variações.
- grid: Produto com grades.
    Enum: "simple", "composition", "grid"

  - `data.products.option_type.count` (integer)
    Quantidade de opções disponíveis para este produto.

Para cada type temos:

- simple: Sempre será 0
- composition: Será a quantidade de variações disponíveis para este produto.
- grid: Será a quantidade de grades disponíveis para este produto.

  - `data.products.sku` (string, required)
    Código SKU do produto. 

Esse código deve ser único.

Exemplo: COD-CP-01
    Example: "COD-CP-01"

  - `data.products.unitary_value` (object, required)
    Preço do produto. 

Esse campo pode ser opcional quando o produto for do tipo "Combo".

  - `data.products.unitary_value.amount` (number, required)
    Valor expresso como um número decimal das principais unidades monetárias
    Example: 99.95

  - `data.products.unitary_value.currency` (string, required)
    Código de moeda de 3 letras conforme definido pela ISO-4217
    Example: "BRL"

  - `data.products.category` (object, required)
    Categoria do produto.

  - `data.products.category.id` (integer)
    Identificador único da categoria.
    Example: 1

  - `data.products.category.name` (string)
    Nome da categoria.
    Example: "Nome da categoria"

  - `data.products.unit` (object, required)
    Unidade de medida do produto.

  - `data.products.unit.id` (integer)
    Identificador único da unidade de medida.
    Example: 1

  - `data.products.unit.name` (string)
    Nome da unidade de medida, exemplo "quilos".
    Example: "Kilos"

  - `data.products.unit.abbreviation` (string)
    A abreviatura da unidade, exemplo "kg".
    Example: "kg"

  - `data.products.unit.precision` (integer)
    Um número inteiro entre 0 e 6 que representa o número máximo de posições permitidas após o decimal em quantidades medidas com esta unidade.
Por exemplo:
  - se a precisão for 0, a quantidade pode ser 1, 2, 3, etc.
  - se a precisão for 1, a quantidade pode ser 0.1, 0.2, 0.3, etc.
  - se a precisão for 2, a quantidade pode ser 0.01, 0.02, 0.03, etc.
    Example: 1

  - `data.products.description` (null,string)
    Descrição do produto.
    Example: "Descrição do produto."

  - `data.products.barcodes` (array)
    Lista dos códigos de barras do produto.
    Example: ["6683713903949"]

  - `data.products.attributes` (array)
    Lista de atributos relacionado com o produto.

Produtos do tipo "Combo" não podem conter atributos.

  - `data.products.attributes.attribute_id` (integer)
    Identificador único do atributo.
    Example: 123

  - `data.products.attributes.name` (string)
    Nome do atributo.
    Example: "Nome do atributo"

  - `data.products.attributes.code` (string)
    Código do atributo. Esse código deve ser único. Exemplo: COD-CP-01
    Example: "COD-CP-01"

  - `data.products.attributes.price_calculation_type` (string)
    Tipo de calculo de preço a ser aplicado nas opções do atributo.

- highest: calcula pelo maior valor.
- average: calcula pela média dos valores.
- proportional: calcula proporcionalmente os valores.
- cumulative: calcula a soma dos valores.
    Enum: "highest", "average", "proportional", "cumulative"

  - `data.products.attributes.min_choices` (integer)
    Número mínimo de opções que devem ser seleciona no atributo.

Se o número mínimo for 0 torna a seleção de atributos opcional, se o número for maior que 0 torna a seleção de atributos obrigatória até o número mínimo de opções selecionadas.

  - `data.products.attributes.max_choices` (integer)
    Número máximo de opções que devem ser seleciona no atributo.

O número máximo deve ser igual ou maior que o número mínimo.
    Example: 1

  - `data.products.attributes.charge_from_quantity` (integer)
    Indica a partir de qual quantidade de atributos deve iniciar o calculo de cobrança pelo atributo selecionado.

Se charge_from_quantity for 2, e o forem seleciona 3 opções para o atributo no valor de 10 BRL com o tipo de calculo cumulative, o valor do atributo será equivalente à 10 BRL, e não 30 BRL, pois ele só começa a ser calculado a partir da opção número 3.

  - `data.products.attributes.position` (integer)
    Indica a posição de ordenação do atributo em listagens
    Example: 1

  - `data.products.attributes.options` (array)
    Lista de opções do atributo.

  - `data.products.attributes.options.option_id` (integer)
    Identificador único da opção.
    Example: 123

  - `data.products.attributes.options.barcode` (string)
    Código de barras da opção do atributo.
    Example: "1234567890123"

  - `data.products.attributes.options.name` (string)
    Nome da opção.
    Example: "Nome da opção"

  - `data.products.attributes.options.code` (string)
    Código da opção. Esse código deve ser único. Exemplo: COD-CP-01
    Example: "COD-CP-01"

  - `data.products.attributes.options.description` (string)
    Descrição da opção.
    Example: "Descrição da opção"

  - `data.products.attributes.options.unitary_value` (object)
    Valor unitário da opção na associação do atributo com o produto.

Esse valor pode ser diferente do valor do template da opção.

  - `data.products.attributes.options.image_url` (null,string)
    URL da imagem da opção.
    Example: "https://images.connectplug.com.br/4f01c1252eea.jpg"

  - `data.products.attributes.options.position` (integer)
    Indica a posição de ordenação da opção em listagens.
    Example: 1

  - `data.products.attributes.options.created_at` (string)
    Data da última criação.
    Example: "2020-01-01T09:00:00-03:00"

  - `data.products.attributes.options.updated_at` (string)
    Data da última atualização.
    Example: "2020-01-01T09:00:00-03:00"

  - `data.products.attributes.options.components` (array)
    Lista de opções do atributo.

  - `data.products.attributes.options.components.amount` (integer)
    Quantidade de componentes associados à opção.
    Example: 1

  - `data.products.attributes.options.components.is_optional` (boolean)
    Indica se a opção é opcional.

  - `data.products.attributes.options.components.product` (object)
    Componente associado à opção.

  - `data.products.attributes.options.components.product.id` (integer)
    Identificador único do componente.
    Example: 123

  - `data.products.attributes.options.components.product.name` (string)
    Nome do componente.
    Example: "Componente 1"

  - `data.products.components` (array)
    Lista de componentes do produto.

  - `data.products.components.id` (integer)
    Identificador único da associação do componente com o produto.

Esse compo é readOnly na criação e pode ser informado na edição para atualização.
    Example: 123

  - `data.products.components.amount` (number)
    Quantidade de itens do componente na venda do produto principal (Ex: combo).
    Example: 1

  - `data.products.components.waste_amount` (number)
    Quantidade de desperdício do componente para geração da venda do produto principal (Ex: produto de produção).
    Example: 0.5

  - `data.products.components.position` (integer)
    Indica a posição de ordenação do componente em listagens
    Example: 1

  - `data.products.components.product` (object)
    Dados do produto que Compõe o produto principal.

  - `data.products.components.created_at` (string)
    Data de criação.
    Example: "2020-01-01T09:00:00-03:00"

  - `data.products.grids` (array)
    Lista de grade de preços do produto.

Apenas produtos do tipo "Simples" podem conter grade de preços.

  - `data.products.grids.id` (integer)
    Identificador único da grade de preço.

Esse compo é readOnly na criação e pode ser informado na edição para atualização.
    Example: 123

  - `data.products.grids.product_id` (integer)
    Identificador único do produto relacionado a grade de preço.
    Example: 123

  - `data.products.grids.order` (integer)
    Ordem da grade de preço.

  - `data.products.grids.unitary_value` (object)
    Valor unitário do produto na grade de preço.

_Também pode ser interpretado como valor unitário do produto para o conjuntos das opções contida em options desse objeto_.

Esse valor pode ser diferente do valor do valor original do produto.

  - `data.products.grids.status` (string)
    Status da grade de preço.

- active: grade de preço disponíveis para venda.
- inactive: grade de preço não disponíveis para venda.
    Enum: "active", "inactive"

  - `data.products.grids.barcode` (string)
    Código de barras da grade de preço.
    Example: "1234567890123"

  - `data.products.grids.image` (string)
    URL da imagem da grade de preço.
    Example: "https://images.connectplug.com.br/4f01c1252eea.jpg"

  - `data.products.grids.options` (array)
    Lista de opções que compõe a grade de preço.

  - `data.products.grids.options.order` (integer)
    Ordem do item na grade de preço.

  - `data.products.additionals` (object)
    Configurações dos produtos adicionais de um produto.

  - `data.products.additionals.min_choices` (integer, required)
    Número mínimo de produtos adicionais que devem ser selecionado.

Se o número mínimo for 0 torna a seleção de produtos adicionais opcional, se o número for maior que 0 torna a seleção obrigatória até o número mínimo de opções selecionadas.

  - `data.products.additionals.max_choices` (integer, required)
    Número máximo de produtos adicionais que devem ser selecionado.

O número máximo deve ser igual ou maior que o número mínimo.
    Example: 1

  - `data.products.additionals.charge_from_quantity` (integer)
    Indica a partir de qual quantidade de adicionais deve iniciar o calculo de cobrança.

Se charge_from_quantity for 2, e o forem seleciona 3 adicionais para o produto no valor de 10 BRL, o valor do atributo será equivalente à 10 BRL, e não 30 BRL, pois ele só começa a ser calculado a partir da opção número 3.

  - `data.products.additionals.items` (array, required)
    Lista de produtos adicionais

  - `data.products.additionals.items.amount` (number, required)
    Quantidade de itens do adicional na venda do produto principal.
    Example: 1

  - `data.products.additionals.items.waste_amount` (number)
    Quantidade de desperdício do adicional para geração da venda do produto principal.
    Example: 0.5

  - `data.products.additionals.items.max_choices` (integer)
    Número máximo de adicionais que devem ser selecionado.
    Example: 1

  - `data.products.additionals.items.position` (integer)
    Indica a posição de ordenação do produto adicional em listagens.
    Example: 1

  - `data.products.additionals.items.product` (object)
    Dados do produto adicional.

  - `data.products.recommendations` (array)
    Lista de produtos a serem sugeridos como recomendação na venda do produto principal.

  - `data.products.recommendations.position` (integer)
    Indica a posição de ordenação do produto recomendado nas listagens.
    Example: 1

  - `data.products.recommendations.product` (object)
    Dados do produto recomendado.

  - `data.products.image_url` (null,string)
    URL da imagem principal do produto.
    Example: "https://images.connectplug.com.br/4f01c1252eea.jpg"

  - `data.products.companies` (array)
    Lista de empresas que permite visualizar.

  - `data.products.companies.id` (integer)
    Identificador único da empresa
    Example: 1234

  - `data.products.companies.name` (string)
    Nome fantasia da empresa.
    Example: "CPlug"

  - `data.products.companies.company_name` (string,null)
    Razão social da empresa.
    Example: "CPlug Tecnologia da Informação"

  - `data.products.is_perishable` (boolean)
    Se este produto é perecível.
    Example: true

  - `data.products.stock_settings` (object)
    Configurações de estoque do produto.

  - `data.products.stock_settings.is_stock_control` (boolean)
    Se este produto possui um controle de estoque.
    Example: true

  - `data.products.stock_settings.is_stock_notification` (boolean)
    Se este produto tem notificação de estoque.

  - `data.products.stock_settings.min` (integer)
    Se is_stock_notification = true. Quantidade mínima no estoque.
    Example: 1

  - `data.products.stock_settings.max` (integer)
    Se is_stock_notification = true. Quantidade máxima no estoque.
    Example: 1

  - `data.products.kds` (array)
    Lista de KDS associados ao produto.

  - `data.products.kds.id` (integer)
    Identificador único do KDS na CPlug.
    Example: 1

  - `data.products.kds.name` (string)
    Nome do KDS.
    Example: "KDS Cozinha"

  - `data.products.price_lists` (array)
    Lista de preços do produto.

Nota: Esta propriedade só será carregada caso seja passado o filtro with_price_list na URL.

  - `data.products.price_lists.value` (object)

  - `data.products.price_lists.value.amount` (number)
    Valor do preço.
    Example: 99.95

  - `data.products.price_lists.value.currency` (string)
    Moeda do preço.
    Example: "BRL"

  - `data.products.price_lists.price_list` (object)

  - `data.products.price_lists.price_list.id` (integer)
    Identificador único da lista de preços.
    Example: 1

  - `data.products.price_lists.price_list.name` (string)
    Nome da lista de preços.
    Example: "Lista Padrão"

  - `meta` (object)
    Representa as informações de Metadado da paginação da listagem.

  - `meta.current_page` (integer, required)
    Página atual na paginação.
    Example: 1

  - `meta.last_page` (integer, required)
    Quantidade total de páginas.
    Example: 10

  - `meta.per_page` (integer, required)
    Quantidade de resultados por página.
    Example: 20

  - `meta.total` (integer, required)
    Quantidade total de itens.
    Example: 200

## Response 400 fields (application/json):

  - `code` (string, required)
    Código de erro.
    Example: "missing_headers"

  - `message` (string)
    Descrição do erro.
    Example: "error message"

  - `meta` (array)
    Dados adicionais sobre o erro.

## Response 422 fields (application/json):

  - `code` (string, required)
    Código de erro.
    Example: "uneditable_entity"

  - `message` (string)
    Descrição do erro.
    Example: "description error"

  - `meta` (array)
    Dados adicionais sobre o erro.

  - `meta.field` (string, required)
    Nome do campo no qual existe um erro de validação.
    Example: "name"

  - `meta.validations` (array)

  - `meta.validations.type` (string, required)
    Tipo da validação aplicada.
    Example: "Required"

  - `meta.validations.value` (array)
    Tipo de valor aplicável (esse campo pode ser vazio).


## Response 401 fields

## Response 404 fields