Pular para o conteúdo principal

Negócios

Negócios do CRM. Itens do negócio, atividades e pipelines ficam em CRM — Complementar.

Negócios​

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

MétodoRotaO que faz
GET/external/v1/dealsLista com paginação
GET/external/v1/deals/:idBusca um registro pelo ID
POST/external/v1/dealsCria um registro
PUT/external/v1/deals/: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":{"status":"WINNER"},"orderBy":{"updatedAt":"desc"}}):

curl -G "https://erp-api.ideros.api.br/external/v1/deals" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25" \
--data-urlencode 'relations={"where":{"status":"WINNER"},"orderBy":{"updatedAt":"desc"}}'

Buscar por ID​

curl "https://erp-api.ideros.api.br/external/v1/deals/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
businessUnitIdstringNãoID de unidade de negócio. Se omitido e a feature FK_BSN_UNT estiver ativa, será resolvido automaticamente.
responsibleUserIdstringSimID de usuário da empresa.
workspaceIdstringNãoID de workspace.
customerIdstringNãoID de pessoa.
dealPipelineIdstringNãoID de pipeline.
dealPipelineStepIdstringNãoID de etapa do pipeline.
externalCodestringNãoCódigo de referência externo.
titlestringSimTítulo ou nome da oportunidade de negócio.
descriptionstringNãoDescrição detalhada do Deal e seu escopo.
tagsstring[]NãoTags para categorizar o Deal.
isExternallyVisiblebooleanSimIndica se o Deal é visível externamente.
dealTypeenumSimTipo de Negócio geral do Deal. Valores: COMMERCIAL, SERVICE.
deliveryModeenumNãoDefine o que o Deal materializa ao ser ganho e onde a medição ocorre. NONE: ainda não definido (padrão para venda COMMERCIAL). SELF: mede a própria venda. SERVICE_ORDER: gera uma ordem de serviço (Deal do tipo SERVICE). PROJECT: gera um projeto. Normalmente preenchido ao marcar o Deal como ganho. Valores: NONE, SELF, SERVICE_ORDER, PROJECT.
generatesContractbooleanNãoIndica se o Deal, ao ser ganho, gera um contrato de faturamento recorrente. Independente (ortogonal) do deliveryMode — o contrato fatura, mas nunca mede.
dealStageenumNãoEstágio de Negócio (SKETCH/EXECUTION/COMPLETED). DERIVADO do status pelo sistema — o valor enviado é ignorado. Valores: SKETCH, EXECUTION, COMPLETED.
statusenumNãoStatus do Deal. Se omitido, assume FILLING_IN por padrão. Valores: FILLING_IN, REVIEW_REQUESTED, APPROVED, DENIED, WINNER, LOST, CHURN, CANCELED.
serviceTermsstringNãoTermos e condições do serviço. Populado automaticamente a partir das configurações da empresa para deals do tipo SERVIÇO, se não informado.
warrantyDaysnumberNãoDias de garantia do serviço. Populado automaticamente a partir das configurações da empresa para deals do tipo SERVIÇO, se não informado.
isRenewalbooleanSimIndica se o Deal é referente a uma renovação de contrato/serviço.
curl -X POST "https://erp-api.ideros.api.br/external/v1/deals" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Licença anual — Tech Solutions",
"dealType": "COMMERCIAL",
"responsibleUserId": "ID_DO_USUARIO",
"customerId": "ID_DA_PESSOA",
"isExternallyVisible": false,
"isRenewal": false
}'

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.

Status e estágio

dealStage é calculado a partir do status e o valor enviado é ignorado. A mudança de status dispara o webhook deal.status_changed.

Ainda com dúvida?

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