Produtos
Cadastro de produtos e serviços usados em negócios, propostas, contratos e notas.
Produtos
Recurso do plano: Produtos e Serviços.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/products | Lista com paginação |
GET | /external/v1/products/:id | Busca um registro pelo ID |
POST | /external/v1/products | Cria um registro |
PUT | /external/v1/products/:id | Atualiza um registro |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
Exemplo com filtro (o valor de relations vai codificado para URL; aqui ele aparece legível: {"where":{"productType":"SERVICE"}}):
curl -G "https://erp-api.ideros.api.br/external/v1/products" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25" \
--data-urlencode 'relations={"where":{"productType":"SERVICE"}}'
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/products/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Criar
Responde 201 com o registro criado.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
code | string | Não | Código único de identificação do produto/serviço na empresa. Se vazio, será gerado automaticamente. |
title | string | Sim | Nome comercial ou título do produto/serviço. |
description | string | Não | Descrição detalhada do produto ou serviço. |
tags | string[] | Não | Tags para categorizar e filtrar o produto/serviço. |
productType | enum | Sim | Tipo de produto/serviço. Valores: LABOR, SERVICE, PARTS, OTHERS. |
unit | string | Não | Unidade de medida do produto (UN, HR, KG, M, M2, M3, L, CX, PCT, SV, etc.). |
imageUrl | string | Não | URL da imagem principal do produto (S3). |
thumbnailUrl | string | Não | URL do thumbnail do produto. |
brand | string | Não | Marca do produto. |
manufacturer | string | Não | Fabricante do produto. |
productCategoryId | string | Não | ID de categoria de produto. |
barcode | string | Não | Código de barras (EAN-13, EAN-8, etc.). |
sku | string | Não | SKU interno (Stock Keeping Unit). |
ncm | string | Não | NCM fiscal (Nomenclatura Comum do Mercosul, 8 dígitos). |
cfop | string | Não | CFOP fiscal (Código Fiscal de Operações e Prestações, 4 dígitos). |
origin | enum | Não | Origem da mercadoria (padrão SEFAZ, 1 dígito). Consulte GET /system-lookup/product-origin para a lista completa traduzida. Default: '0' (Nacional). Valores: 0, 1, 2, 3, 4, 5, 6, 7, 8. |
isStockControlled | boolean | Não | Se verdadeiro, habilita controle de saldo em estoque para este produto. |
minimumStock | number | Não | Estoque mínimo para alerta. |
maximumStock | number | Não | Estoque máximo. |
defaultDurationMinutes | number | Não | Duração padrão do serviço em minutos (usado na Booking Page). |
weight | number | Não | Peso do produto em quilogramas. |
width | number | Não | Largura do produto em centímetros. |
height | number | Não | Altura do produto em centímetros. |
depth | number | Não | Profundidade do produto em centímetros. |
serviceCode | string | Não | Código do serviço conforme LC 116/2003. Obrigatório para NFS-e. |
cest | string | Não | Código Especificador da Substituição Tributária (CEST). Obrigatório quando produto está sujeito a ICMS-ST. |
fiscalGroupId | string | Não | ID de grupo fiscal. Centraliza a classificação tributária do produto. |
ibsCbsCst | string | Não | CST do IBS/CBS (3 dígitos), da tabela oficial de CST (IT 2025.002). Nulo = herda. |
ibsCbsClassTrib | string | Não | Código de classificação tributária do IBS/CBS (cClassTrib, 6 dígitos), da tabela oficial (IT 2025.002). Precisa pertencer ao CST informado. Nulo = herda. |
ibsCbsIndOp | string | Não | Indicador da operação do IBS/CBS (indOp, 6 dígitos, Anexo VII da NFS-e). Só para serviço. Nulo = herda ou vem da sugestão oficial. |
ibsCbsOnerous | boolean | Não | Indica se a operação é onerosa (com contraprestação). Muda o indOp (regra do Anexo VIII). Só para serviço. |
ibsCbsAcquirerAbroad | boolean | Não | Indica se o adquirente está no exterior. Muda o indOp (regra do Anexo VIII). Nulo = deduz do país do tomador. |
isCst | string | Não | CST do Imposto Seletivo (3 dígitos). Só para produto sujeito ao IS. |
isClassTrib | string | Não | Classificação tributária do Imposto Seletivo (6 dígitos). Só para produto sujeito ao IS. |
isRate | number | Não | Alíquota ad valorem do Imposto Seletivo em fração decimal (ex.: 0.1 = 10%). |
isSpecificRate | number | Não | Alíquota específica do Imposto Seletivo em reais por unidade tributável. |
isUnit | string | Não | Unidade tributável do Imposto Seletivo (ex.: LT, KG, UN). |
simplesActivityCode | string | Não | Código da atividade no Simples Nacional (cAtvSN, NT SE/CGNFS-e 009): 7 a 14 ou 90. Usado pela NFS-e do optante a partir de 2027. |
taxReformPriceMode | enum | Não | Como o preço trata o IBS/CBS: ADDED = tributo acrescido ao preço; INCLUDED = embutido no preço. Nulo = herda da configuração fiscal da empresa. Valores: ADDED, INCLUDED. |
issWithheld | boolean | Não | Indica se o ISS é retido na fonte por padrão para este produto. Pode ser sobrescrito no item da nota. |
partNumber | string | Não | Código de peça do fabricante. Útil para revenda de componentes. |
gtin | string | Não | GTIN/EAN para NF-e. Quando produto não tem GTIN, o padrão na NF-e é enviar "SEM GTIN". |
extipiCode | string | Não | Código EX da TIPI para produtos com alíquota de IPI diferenciada. |
curl -X POST "https://erp-api.ideros.api.br/external/v1/products" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Consultoria em TI",
"productType": "SERVICE"
}'
Atualizar
Envie no corpo só os campos que mudam, com os mesmos nomes da tabela de criação. Responde 200 com o registro atualizado. Registro de outra empresa responde 403; registro inexistente, 404.
Ainda com dúvida?
A nossa equipe ajuda você a configurar e usar esse recurso.