Pular para o conteúdo principal

CRM — Complementar

Recursos de apoio ao CRM: atividades comerciais, itens de um negócio e pipelines (com suas etapas).

Atividades​

Recurso do plano: Atividades de Vendas.

MétodoRotaO que faz
GET/external/v1/activitiesLista com paginação
GET/external/v1/activities/:idBusca um registro pelo ID
POST/external/v1/activitiesCria um registro
PUT/external/v1/activities/:idAtualiza um registro

Listar​

Aceita page, limit e relations, como descrito em Paginação e filtros.

curl -G "https://erp-api.ideros.api.br/external/v1/activities" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25"

Buscar por ID​

curl "https://erp-api.ideros.api.br/external/v1/activities/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.

CampoTipoObrigatórioDescrição
dealIdstringNãoID de negócio.
leadIdstringNãoID de lead.
financialEntryIdstringNãoID de lançamento financeiro. Vincula a atividade como follow-up de cobrança do título.
chargeIdstringNãoID de cobrança. Vincula a atividade como follow-up da cobrança.
personIdstringNãoID de pessoa.
workspaceIdstringNãoID de workspace.
businessUnitIdstringNãoID de unidade de negócio.
authorIdstringSimID de usuário da empresa.
subjectstringSimAssunto ou título breve da atividade.
notesstringNãoNotas detalhadas sobre a atividade
typeenumSimTipo de atividade. Valores: CALL, EMAIL, MEETING, TASK.
dueDatestring (data ISO 8601)SimData e hora de vencimento ou agendamento da atividade.
completedAtstring (data ISO 8601)NãoData e hora em que a atividade foi concluída.
metadataobjectNãoObjeto JSON livre.
tagsstring[]NãoTags livres para categorizar a atividade (lista de textos).
appointmentobjectNãoDados para criar um compromisso a partir da atividade (apenas tipo MEETING). Transitório: não é persistido na atividade — gera o Appointment vinculado.
curl -X POST "https://erp-api.ideros.api.br/external/v1/activities" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"dealId": "ID_DO_NEGOCIO",
"authorId": "ID_DO_USUARIO",
"subject": "Ligação de follow-up",
"type": "CALL",
"dueDate": "2026-11-20T14:30:00Z"
}'

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.

Itens do negócio​

Recurso do plano: Negócios ou Ordens de Serviço.

MétodoRotaO que faz
GET/external/v1/deal-itemsLista com paginação
GET/external/v1/deal-items/:idBusca um registro pelo ID
POST/external/v1/deal-itemsCria um registro
PUT/external/v1/deal-items/:idAtualiza 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":{"dealId":"ID_DO_NEGOCIO"}}):

curl -G "https://erp-api.ideros.api.br/external/v1/deal-items" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25" \
--data-urlencode 'relations={"where":{"dealId":"ID_DO_NEGOCIO"}}'

Buscar por ID​

curl "https://erp-api.ideros.api.br/external/v1/deal-items/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.

CampoTipoObrigatórioDescrição
dealIdstringSimID de negócio.
productIdstringNãoID de produto. Opcional. Quando informado, o item da venda fica vinculado ao produto cadastrado e o sistema valida se o produto pertence à company. Se omitido, o item é considerado avulso e exige itemType para auditoria.
productPriceTableIdstringNãoID de tabela de preço. Opcional. Quando informado, valida se a tabela de preço pertence ao produto, é do tipo SALE, está ativa e vigente. Também ativa a validação silenciosa do preço mínimo cadastrado.
itemCodestringNãoCódigo de referência do item. Se não informado e houver produto vinculado, será preenchido com o code do produto.
titlestringNãoNome/título do produto ou serviço adicionado ao Deal. Se não informado e houver produto vinculado, será preenchido com o title do produto.
descriptionstringNãoDescrição detalhada do item. Se não informada e houver produto vinculado, herda do produto.
tagsstring[]NãoTags para categorizar o item.
itemTypeenumNãoTipo do item (Produto, Serviço, Mão de obra, Outros). Obrigatório para item avulso (sem productId) — direciona quais campos fiscais aparecem na UI. Quando há productId vinculado, é preenchido automaticamente com o productType do produto. Valores: LABOR, SERVICE, PARTS, OTHERS.
billingModeenumSimModo de cobrança do item. ONE_SHOT: venda fechada (à vista ou parcelada via installmentsCount). RECURRING: mensalidade fixa pelo período de totalContractTimeInMonths. MEASURED: faturamento variável por medição. Valores: ONE_SHOT, RECURRING, MEASURED.
unitstringNãoUnidade de medida do item (UN, HR, KG, M, M2, M3, L, CX, PCT, SV). Se não informada e houver produto vinculado, herda do produto.
ncmstringNãoNCM do item (snapshot fiscal no momento da venda). Se não informado e houver produto vinculado, herda do produto. Não é fonte fiscal para emissão de NF — a NF re-busca do cadastro do produto.
cfopstringNãoCFOP do item (snapshot da natureza da operação no momento da venda). Pode ser sobrescrito pelo vendedor quando a operação difere do default cadastrado no produto.
originstringNãoOrigem da mercadoria (snapshot). Se não informada e houver produto vinculado, herda do produto. 0-Nacional, 1-Importação direta, 2-Importação por terceiros, etc.
quantityOfItemnumberSimQuantidade total de unidades do item no Deal.
totalContractTimeInMonthsnumberSimDuração total do contrato em meses. Para billingMode=ONE_SHOT use 1. Para RECURRING/MEASURED indica por quantos meses o item se aplica.
monthlyQuantitynumberNãoQuantidade prevista de consumo por mês. Aplica-se a billingMode=MEASURED para estimativa do faturamento mensal.
installmentsCountnumberNãoQuantidade de parcelas do pagamento. Aplica-se a billingMode=ONE_SHOT para vendas parceladas (cartão/boleto). Quando omitido em ONE_SHOT, considera pagamento à vista.
startDatestring (data ISO 8601)NãoData de início da vigência do item, quando diferente do Deal. Opcional para RECURRING/MEASURED.
endDatestring (data ISO 8601)NãoData de fim da vigência do item, quando diferente do Deal. Opcional para RECURRING/MEASURED.
dateAddedOfProductstring (data ISO 8601)SimData em que o produto/serviço foi adicionado ao Deal.
warrantyStartDatestring (data ISO 8601)NãoData de início da garantia do produto/serviço.
warrantyDurationMonthsnumberNãoDuração da garantia em meses, contada a partir de warrantyStartDate. Define implicitamente a data final da garantia.
valueTypeenumSimFormato do preço. AMOUNT: unitPrice é valor em reais. PERCENTAGE: unitPrice é percentual aplicado sobre originalUnitPrice (caso típico de medição por % sobre base, ex: 7% sobre folha). Valores: PERCENTAGE, AMOUNT.
originalUnitPricenumberNãoPreço unitário original/cheio do item (preço de tabela). Quando valueType=PERCENTAGE, representa a base sobre a qual o percentual é calculado e é obrigatório. Quando valueType=AMOUNT, é o preço cheio antes de descontos (opcional). Se houver tabela de preço vinculada, é preenchido com o priceBase da tabela.
minimumUnitPricenumberNãoPreço unitário mínimo permitido para o item. Quando houver productPriceTableId vinculado, este valor é IGNORADO — o sistema usa o minimumPrice cadastrado na tabela de preço (validação silenciosa, valor não é exposto na resposta).
unitPricenumberSimPreço unitário negociado. Em valueType=AMOUNT é valor em reais. Em valueType=PERCENTAGE é o percentual (ex: 7 = 7%) aplicado sobre originalUnitPrice.
totalDiscountAmountnumberNãoValor total do desconto concedido para o item.
discountRatenumberNãoTaxa de desconto percentual aplicada.
totalPricenumberNãoPreço total final do item. Calculado automaticamente pelo servidor.
monthlyInstallmentPricenumberNãoValor da parcela mensal. Calculado automaticamente pelo servidor.
feeRatenumberNãoTaxa de tarifa percentual aplicada.
totalFeeAmountnumberNãoValor total da tarifa (fee) calculada.
taxRatenumberNãoTaxa de imposto percentual aplicada.
totalTaxAmountnumberNãoValor total do imposto calculado.
bonusRatenumberNãoTaxa de bônus/incentivo percentual.
totalBonusAmountnumberNãoValor total do bônus/incentivo calculado.
responsibleUserIdstringNãoID de usuário da empresa. Responsável técnico/comercial pelo item. Se omitido, usa o usuário logado.
metadataobjectNãoObjeto JSON livre.

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.

Pipelines​

Recurso do plano: Pipelines de Vendas.

MétodoRotaO que faz
GET/external/v1/deal-pipelinesLista com paginação
GET/external/v1/deal-pipelines/:idBusca um registro pelo ID

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: {"include":{"Step":true}}):

curl -G "https://erp-api.ideros.api.br/external/v1/deal-pipelines" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25" \
--data-urlencode 'relations={"include":{"Step":true}}'

Buscar por ID​

curl "https://erp-api.ideros.api.br/external/v1/deal-pipelines/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).

Campos do registro​

Além de id, isActive, createdAt e updatedAt, o registro traz:

CampoTipoDescrição
namestringNome do pipeline de negócios.
descriptionstringDescrição detalhada do propósito deste pipeline.
dealTypeenumTipo do pipeline de negócios Valores: COMMERCIAL, SERVICE.

Para trazer as etapas junto, use include em relations. O nome da relação segue o modelo de dados da plataforma; se o include não for aceito, a resposta é 400.

Ainda com dúvida?

A nossa equipe ajuda você a configurar e usar esse recurso.