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étodo | Rota | O que faz |
|---|---|---|
GET | /external/v1/activities | Lista com paginação |
GET | /external/v1/activities/:id | Busca um registro pelo ID |
POST | /external/v1/activities | Cria um registro |
PUT | /external/v1/activities/:id | Atualiza 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.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
dealId | string | Não | ID de negócio. |
leadId | string | Não | ID de lead. |
financialEntryId | string | Não | ID de lançamento financeiro. Vincula a atividade como follow-up de cobrança do título. |
chargeId | string | Não | ID de cobrança. Vincula a atividade como follow-up da cobrança. |
personId | string | Não | ID de pessoa. |
workspaceId | string | Não | ID de workspace. |
businessUnitId | string | Não | ID de unidade de negócio. |
authorId | string | Sim | ID de usuário da empresa. |
subject | string | Sim | Assunto ou título breve da atividade. |
notes | string | Não | Notas detalhadas sobre a atividade |
type | enum | Sim | Tipo de atividade. Valores: CALL, EMAIL, MEETING, TASK. |
dueDate | string (data ISO 8601) | Sim | Data e hora de vencimento ou agendamento da atividade. |
completedAt | string (data ISO 8601) | Não | Data e hora em que a atividade foi concluída. |
metadata | object | Não | Objeto JSON livre. |
tags | string[] | Não | Tags livres para categorizar a atividade (lista de textos). |
appointment | object | Não | Dados 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étodo | Rota | O que faz |
|---|---|---|
GET | /external/v1/deal-items | Lista com paginação |
GET | /external/v1/deal-items/:id | Busca um registro pelo ID |
POST | /external/v1/deal-items | Cria um registro |
PUT | /external/v1/deal-items/: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":{"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.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
dealId | string | Sim | ID de negócio. |
productId | string | Não | ID 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. |
productPriceTableId | string | Não | ID 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. |
itemCode | string | Não | Código de referência do item. Se não informado e houver produto vinculado, será preenchido com o code do produto. |
title | string | Não | Nome/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. |
description | string | Não | Descrição detalhada do item. Se não informada e houver produto vinculado, herda do produto. |
tags | string[] | Não | Tags para categorizar o item. |
itemType | enum | Não | Tipo 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. |
billingMode | enum | Sim | Modo 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. |
unit | string | Não | Unidade 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. |
ncm | string | Não | NCM 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. |
cfop | string | Não | CFOP 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. |
origin | string | Não | Origem 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. |
quantityOfItem | number | Sim | Quantidade total de unidades do item no Deal. |
totalContractTimeInMonths | number | Sim | Duração total do contrato em meses. Para billingMode=ONE_SHOT use 1. Para RECURRING/MEASURED indica por quantos meses o item se aplica. |
monthlyQuantity | number | Não | Quantidade prevista de consumo por mês. Aplica-se a billingMode=MEASURED para estimativa do faturamento mensal. |
installmentsCount | number | Não | Quantidade de parcelas do pagamento. Aplica-se a billingMode=ONE_SHOT para vendas parceladas (cartão/boleto). Quando omitido em ONE_SHOT, considera pagamento à vista. |
startDate | string (data ISO 8601) | Não | Data de início da vigência do item, quando diferente do Deal. Opcional para RECURRING/MEASURED. |
endDate | string (data ISO 8601) | Não | Data de fim da vigência do item, quando diferente do Deal. Opcional para RECURRING/MEASURED. |
dateAddedOfProduct | string (data ISO 8601) | Sim | Data em que o produto/serviço foi adicionado ao Deal. |
warrantyStartDate | string (data ISO 8601) | Não | Data de início da garantia do produto/serviço. |
warrantyDurationMonths | number | Não | Duração da garantia em meses, contada a partir de warrantyStartDate. Define implicitamente a data final da garantia. |
valueType | enum | Sim | Formato 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. |
originalUnitPrice | number | Não | Preç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. |
minimumUnitPrice | number | Não | Preç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). |
unitPrice | number | Sim | Preço unitário negociado. Em valueType=AMOUNT é valor em reais. Em valueType=PERCENTAGE é o percentual (ex: 7 = 7%) aplicado sobre originalUnitPrice. |
totalDiscountAmount | number | Não | Valor total do desconto concedido para o item. |
discountRate | number | Não | Taxa de desconto percentual aplicada. |
totalPrice | number | Não | Preço total final do item. Calculado automaticamente pelo servidor. |
monthlyInstallmentPrice | number | Não | Valor da parcela mensal. Calculado automaticamente pelo servidor. |
feeRate | number | Não | Taxa de tarifa percentual aplicada. |
totalFeeAmount | number | Não | Valor total da tarifa (fee) calculada. |
taxRate | number | Não | Taxa de imposto percentual aplicada. |
totalTaxAmount | number | Não | Valor total do imposto calculado. |
bonusRate | number | Não | Taxa de bônus/incentivo percentual. |
totalBonusAmount | number | Não | Valor total do bônus/incentivo calculado. |
responsibleUserId | string | Não | ID de usuário da empresa. Responsável técnico/comercial pelo item. Se omitido, usa o usuário logado. |
metadata | object | Não | Objeto 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étodo | Rota | O que faz |
|---|---|---|
GET | /external/v1/deal-pipelines | Lista com paginação |
GET | /external/v1/deal-pipelines/:id | Busca 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:
| Campo | Tipo | Descrição |
|---|---|---|
name | string | Nome do pipeline de negócios. |
description | string | Descrição detalhada do propósito deste pipeline. |
dealType | enum | Tipo 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.
A nossa equipe ajuda você a configurar e usar esse recurso.