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étodo | Rota | O que faz |
|---|---|---|
GET | /external/v1/deals | Lista com paginação |
GET | /external/v1/deals/:id | Busca um registro pelo ID |
POST | /external/v1/deals | Cria um registro |
PUT | /external/v1/deals/: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":{"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.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
businessUnitId | string | Não | ID de unidade de negócio. Se omitido e a feature FK_BSN_UNT estiver ativa, será resolvido automaticamente. |
responsibleUserId | string | Sim | ID de usuário da empresa. |
workspaceId | string | Não | ID de workspace. |
customerId | string | Não | ID de pessoa. |
dealPipelineId | string | Não | ID de pipeline. |
dealPipelineStepId | string | Não | ID de etapa do pipeline. |
externalCode | string | Não | Código de referência externo. |
title | string | Sim | Título ou nome da oportunidade de negócio. |
description | string | Não | Descrição detalhada do Deal e seu escopo. |
tags | string[] | Não | Tags para categorizar o Deal. |
isExternallyVisible | boolean | Sim | Indica se o Deal é visível externamente. |
dealType | enum | Sim | Tipo de Negócio geral do Deal. Valores: COMMERCIAL, SERVICE. |
deliveryMode | enum | Não | Define 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. |
generatesContract | boolean | Não | Indica se o Deal, ao ser ganho, gera um contrato de faturamento recorrente. Independente (ortogonal) do deliveryMode — o contrato fatura, mas nunca mede. |
dealStage | enum | Não | Estágio de Negócio (SKETCH/EXECUTION/COMPLETED). DERIVADO do status pelo sistema — o valor enviado é ignorado. Valores: SKETCH, EXECUTION, COMPLETED. |
status | enum | Não | Status do Deal. Se omitido, assume FILLING_IN por padrão. Valores: FILLING_IN, REVIEW_REQUESTED, APPROVED, DENIED, WINNER, LOST, CHURN, CANCELED. |
serviceTerms | string | Não | Termos 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. |
warrantyDays | number | Não | Dias de garantia do serviço. Populado automaticamente a partir das configurações da empresa para deals do tipo SERVIÇO, se não informado. |
isRenewal | boolean | Sim | Indica 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.
dealStage é calculado a partir do status e o valor enviado é ignorado. A mudança de status dispara o webhook deal.status_changed.
A nossa equipe ajuda você a configurar e usar esse recurso.