Pular para o conteúdo
MModari

Negociações

Criar, listar, atualizar negociações (deals), mover de estágio e gerenciar anotações através da API do Modari.

Uma negociação (deal) representa uma oportunidade de venda vinculada a um contato e a um funil.

POST /api/deals
Authorization: Bearer elv_...
Content-Type: application/json

Criar uma negociação#

POST /api/deals
Campo Tipo Obrigatório Descrição
name string sim Nome da negociação.
contactId string sim ID do contato vinculado.
pipelineId string sim ID do funil.
description string não Descrição livre.
assigneeId string não ID do responsável (contato interno).
value number não Valor da negociação.
stageId string não Estágio inicial. Se omitido, usa o estágio padrão do funil.
origin string não Origem da negociação (mesmos valores de origem do contato).
briefingDate data não Data do briefing, ISO 8601.
presentationDate data não Data da apresentação, ISO 8601.

Exemplo#

{
  "name": "Negociação Empresa XYZ",
  "contactId": "677a8121849dfc001b863851",
  "pipelineId": "507f1f77bcf86cd799439011",
  "value": 5000,
  "origin": "meta"
}

Resposta — 201#

{
  "status": 201,
  "createdRegistry": {
    "_id": "6866fe673d11620018434523",
    "name": "Negociação Empresa XYZ",
    "contactId": "677a8121849dfc001b863851",
    "pipelineId": "507f1f77bcf86cd799439011",
    "stageId": "507f1f77bcf86cd799439012",
    "assigneeId": null,
    "value": 5000,
    "status": "open",
    "notes": [],
    "origin": "meta",
    "createdAt": "2025-07-18T14:15:13.321Z",
    "updatedAt": "2025-07-18T14:15:13.321Z"
  }
}

Listar negociações#

GET /api/deals

Suporta a paginação padrão da API, mais os filtros abaixo:

Filtro (query string) Tipo Descrição
pipelineId string Filtra por funil.
status string open, paused, won ou lost.
assigneeIds array Filtra por um ou mais responsáveis.
origin string Filtra por origem da negociação.
inactiveDays number Negociações sem atividade há N dias (baseado em updatedAt). 
{
  "status": 200,
  "registersList": [
    { "_id": "6866fe673d11620018434523", "name": "Negociação Empresa XYZ", "...": "..." }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalItems": 1,
    "itemsPerPage": 10,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

Buscar negociação por ID#

GET /api/deals/:dealId

Retorna 404 se a negociação não existir para a empresa dona da API key.

Atualizar negociação#

PATCH /api/deals/:dealId
Campo Tipo Obrigatório Descrição
name string não Nome da negociação.
description string não Descrição livre.
assigneeId string não ID do responsável.
value number não Valor da negociação.
origin string não Origem da negociação.
campaign string não Campanha de origem.
briefingDate data não Data do briefing, ISO 8601.
presentationDate data não Data da apresentação, ISO 8601.

Este endpoint não move a negociação de estágio nem de funil — para isso, use mover de estágio abaixo.

{
  "value": 7500,
  "assigneeId": "6512c0f2a3b1d4e5f6a7b8c9"
}

Mover para outro estágio#

Move a negociação para outro estágio dentro do mesmo funil.

PATCH /api/deals/:dealId/stage
Campo Tipo Obrigatório Descrição
stageId string sim ID do estágio de destino. Precisa pertencer ao funil atual da negociação. 
{ "stageId": "507f1f77bcf86cd799439012" }

Resposta — 200#

{
  "status": 200,
  "updatedRegistry": { "_id": "6866fe673d11620018434523", "stageId": "507f1f77bcf86cd799439012", "...": "..." }
}

Alterar o status#

Altera o status da negociação — é como se marca uma negociação como ganha ou perdida.

PATCH /api/deals/:dealId/status
Campo Tipo Obrigatório Descrição
status string sim Novo status: open, paused, won ou lost. 
{ "status": "won" }

Resposta — 200#

{
  "status": 200,
  "updatedRegistry": { "_id": "6866fe673d11620018434523", "status": "won", "...": "..." }
}

Um valor fora da lista acima responde 400.

Anotações da negociação#

Anotações (notes) são registros de texto livre vinculados a uma negociação — usados para histórico de contato, observações da equipe, etc.

Adicionar anotação#

POST /api/deals/:dealId/notes
Campo Tipo Obrigatório Descrição
text string sim Texto da anotação. 
{ "text": "Cliente demonstrou interesse no plano premium." }

Resposta — 201, retorna a negociação atualizada com a nova anotação em notes.

Listar anotações#

GET /api/deals/:dealId/notes
{
  "status": 200,
  "notes": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "text": "Cliente demonstrou interesse no plano premium.",
      "createdAt": "2025-07-18T14:15:13.321Z",
      "updatedAt": "2025-07-18T14:15:13.321Z"
    }
  ]
}

Exemplo com curl#

curl -X PATCH "https://moveis-api.smarktech.app.br/api/deals/6866fe673d11620018434523/stage" \
  -H "Authorization: Bearer $MODARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stageId": "507f1f77bcf86cd799439012" }'

Erros comuns#

Situação Resposta
contactId ou pipelineId que não existem na sua empresa 404
stageId que não pertence ao funil atual da negociação 400
dealId que não existe para a sua empresa 404
API key sem permissão para o endpoint 401

Atualizado em 05 de out. de 2026 · modari