Ir para o conteúdo
Pipefácil

Atualizar negócio

Ver como MarkdownConfigurar agente
PATCH/api/v1/deals/{seq}

Atualiza parcialmente o negócio e pode movê-lo entre etapas. Mover para uma etapa de perda exige um lostReason válido; mover para uma etapa de ganho encerra o negócio.

Exemplos

A URL usa o servidor de produção. Defina PIPEFACIL_API_KEY e as variáveis de caminho (como SEQ ou ID) com os identificadores reais. Ajuste o corpo antes de executar: requisições de escrita alteram dados do workspace.

cURL

curl --request PATCH \
  --url "https://pipefacil-server.matchsales.com.br/api/v1/deals/$SEQ" \
  --header "Authorization: Bearer $PIPEFACIL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "notes": "Contato pediu uma proposta revisada."
}'
JavaScript
const response = await fetch(`https://pipefacil-server.matchsales.com.br/api/v1/deals/${process.env.SEQ}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.PIPEFACIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "notes": "Contato pediu uma proposta revisada."
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const text = await response.text();
const data = text ? JSON.parse(text) : null;
Python
import os
import json
import requests

response = requests.request(
    "PATCH",
    f"https://pipefacil-server.matchsales.com.br/api/v1/deals/{os.environ['SEQ']}",
    headers={"Authorization": f"Bearer {os.environ['PIPEFACIL_API_KEY']}"},
    json=json.loads("{\n  \"notes\": \"Contato pediu uma proposta revisada.\"\n}"),
)
response.raise_for_status()
data = response.json() if response.content else None

Parâmetros

NomeLocalTipoObrigatórioDescrição
seqpathintegerSimNúmero sequencial do negócio dentro do workspace.

Corpo da requisição

Content-Type: application/json · obrigatório

{
  "notes": "Contato pediu uma proposta revisada."
}
CampoTipoObrigatório no objetoDescrição
namestringNãoAceita null. Até 255 caracteres.
valuenumberNãoAceita null. Mínimo: 0.
currencystringNãoAceita null. Até 3 caracteres.
closeProbabilityintegerNãoAceita null. Mínimo: 0. Máximo: 100.
expectedCloseAtstringNãoFormato: date-time. Aceita null.
stageIdstringNãoAceita null.
companyIdstringNãoAceita null.
responsibleUserIdstringNãoAceita null.
coOwnerUserIdstringNãoAceita null.
lostReasonstringNãoObrigatório ao mover para uma etapa de perda. Aceita null. Até 255 caracteres.
notesstringNãoAceita null. Até 2000 caracteres.
tagIdsarrayNãoAceita null.
customFieldsobjectNãoAceita null.
contactobjectNãoCampos opcionais do contato para atualizar junto com o negócio. Aceita null.
trackingobjectNãoAceita null.
tracking.utmContentstringNãoAceita null.
tracking.utmMediumstringNãoAceita null.
tracking.utmCampaignstringNãoAceita null.
tracking.utmSourcestringNãoAceita null.
tracking.utmTermstringNãoAceita null.
tracking.utmReferrerstringNãoAceita null.
tracking.referrerstringNãoAceita null.
tracking.gclientidstringNãoAceita null.
tracking.gclidstringNãoAceita null.
tracking.fbclidstringNãoAceita null.
tracking.metaLeadIdstringNãoAceita null.
tracking.fbpstringNãoAceita null.
tracking.fbcstringNãoAceita null.
tracking.clientIpAddressstringNãoAceita null.
tracking.clientUserAgentstringNãoAceita null.
tracking.ctwaClidstringNãoAceita null.
Esquema OpenAPI
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 255,
      "nullable": true
    },
    "value": {
      "type": "number",
      "minimum": 0,
      "nullable": true
    },
    "currency": {
      "type": "string",
      "maxLength": 3,
      "nullable": true
    },
    "closeProbability": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100,
      "nullable": true
    },
    "expectedCloseAt": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    },
    "stageId": {
      "type": "string",
      "nullable": true
    },
    "companyId": {
      "type": "string",
      "nullable": true
    },
    "responsibleUserId": {
      "type": "string",
      "nullable": true
    },
    "coOwnerUserId": {
      "type": "string",
      "nullable": true
    },
    "lostReason": {
      "type": "string",
      "maxLength": 255,
      "nullable": true,
      "description": "Obrigatório ao mover para uma etapa de perda."
    },
    "notes": {
      "type": "string",
      "maxLength": 2000,
      "nullable": true
    },
    "tagIds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "nullable": true
    },
    "customFields": {
      "type": "object",
      "additionalProperties": true,
      "nullable": true
    },
    "contact": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "Campos opcionais do contato para atualizar junto com o negócio."
    },
    "tracking": {
      "allOf": [
        {
          "$ref": "#/components/schemas/DealTracking"
        }
      ],
      "nullable": true
    }
  },
  "example": {
    "notes": "Contato pediu uma proposta revisada."
  }
}

Respostas

200Sucesso
CampoTipoDescrição
dataDealResponseNegócio resumido retornado na criação ou atualização.
data.idstring—
data.seqinteger—
data.namestring—
data.contactIdstringAceita null.
data.responsibleUserIdstring—
data.companyIdstringAceita null.
data.pipelineIdstring—
data.stageIdstring—
data.valuenumber—
data.currencystring—
data.closeProbabilityinteger—
data.sourcestring—
data.statusstringopen | won | lost
data.coOwnerUserIdstringAceita null.
data.expectedCloseAtstringFormato: date-time. Aceita null.
data.stageChangedAtstringFormato: date-time.
data.closedAtstringFormato: date-time. Aceita null.
data.lostReasonstringAceita null.
data.customFieldsobject—
data.createdAtstringFormato: date-time.
data.trackingobjectAceita null.
data.tracking.utmContentstringAceita null.
data.tracking.utmMediumstringAceita null.
data.tracking.utmCampaignstringAceita null.
data.tracking.utmSourcestringAceita null.
data.tracking.utmTermstringAceita null.
data.tracking.utmReferrerstringAceita null.
data.tracking.referrerstringAceita null.
data.tracking.gclientidstringAceita null.
data.tracking.gclidstringAceita null.
data.tracking.fbclidstringAceita null.
data.tracking.metaLeadIdstringAceita null.
data.tracking.fbpstringAceita null.
data.tracking.fbcstringAceita null.
data.tracking.clientIpAddressstringAceita null.
data.tracking.clientUserAgentstringAceita null.
data.tracking.ctwaClidstringAceita null.
messagestringAceita null.
Esquema OpenAPI
{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/DealResponse"
    },
    "message": {
      "type": "string",
      "nullable": true
    }
  }
}
400Falha de validação dos campos; `fieldErrors` contém os erros.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
401Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
404Recurso não encontrado ou fora da visibilidade do membro.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
429Limite de requisições excedido por workspace ou IP.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
OpenAPI JSONMarkdown desta operação

Precisa de ajuda?

Encontrou um problema ou ficou com uma dúvida? Fale com a equipe pelo WhatsApp.

Chamar no WhatsApp
Pipefácil