# Criar negócio

`POST /api/v1/deals`

Cria um negócio no workspace da chave e retorna o registro criado.

## Autenticação

Envie a chave em `Authorization: Bearer pf_live_…`.

## Corpo da requisição

Content-Type: `application/json`

```json
{
  "name": "Proposta de consultoria",
  "contactFirstName": "Ana",
  "contactLastName": "Silva",
  "email": "ana@example.com",
  "value": 1500,
  "currency": "BRL"
}
```

### Campos

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `name` | `string` | Não | Aceita null. Até 255 caracteres. |
| `phone` | `string` | Não | Telefone do contato, opcional. Sem telefone, o negócio pode não ter contato; um nome ou e-mail permite criar um contato sem telefone. Aceita null. |
| `contactName` | `string` | Não | Nome completo do contato, dividido no primeiro espaço em firstName/lastName. Ignorado quando contactFirstName ou contactLastName é enviado. Aceita null. Até 255 caracteres. |
| `contactFirstName` | `string` | Não | Aceita null. Até 255 caracteres. |
| `contactLastName` | `string` | Não | Aceita null. Até 255 caracteres. |
| `email` | `string` | Não | Formato: email. Aceita null. Até 255 caracteres. |
| `notes` | `string` | Não | Aceita null. Até 2000 caracteres. |
| `value` | `number` | Não | Aceita null. Mínimo: 0. |
| `closeProbability` | `integer` | Não | Aceita null. Mínimo: 0. Máximo: 100. |
| `expectedCloseAt` | `string` | Não | Formato: date-time. Aceita null. |
| `currency` | `string` | Não | Padrão: BRL. Aceita null. Até 3 caracteres. |
| `stageId` | `string` | Não | Padrão: primeira etapa do funil. Aceita null. |
| `companyId` | `string` | Não | Aceita null. |
| `channelId` | `string` | Não | Aceita null. |
| `responsibleUserId` | `string` | Não | Aceita null. |
| `useAssignmentStrategy` | `boolean` | Não | Aceita null. |
| `customFields` | `object` | Não | Aceita null. |
| `company` | `object` | Não | Aceita null. |
| `company.name` | `string` | Sim | Até 255 caracteres. |
| `company.domain` | `string` | Não | Aceita null. Até 255 caracteres. |
| `company.cnpj` | `string` | Não | Aceita null. Até 30 caracteres. |
| `company.industry` | `string` | Não | Aceita null. Até 255 caracteres. |
| `company.website` | `string` | Não | Aceita null. Até 500 caracteres. |
| `company.logoUrl` | `string` | Não | Aceita null. Até 500 caracteres. |
| `company.notes` | `string` | Não | Aceita null. Até 2000 caracteres. |
| `tracking` | `object` | Não | Aceita null. |
| `tracking.utmContent` | `string` | Não | Aceita null. |
| `tracking.utmMedium` | `string` | Não | Aceita null. |
| `tracking.utmCampaign` | `string` | Não | Aceita null. |
| `tracking.utmSource` | `string` | Não | Aceita null. |
| `tracking.utmTerm` | `string` | Não | Aceita null. |
| `tracking.utmReferrer` | `string` | Não | Aceita null. |
| `tracking.referrer` | `string` | Não | Aceita null. |
| `tracking.gclientid` | `string` | Não | Aceita null. |
| `tracking.gclid` | `string` | Não | Aceita null. |
| `tracking.fbclid` | `string` | Não | Aceita null. |
| `tracking.metaLeadId` | `string` | Não | Aceita null. |
| `tracking.fbp` | `string` | Não | Aceita null. |
| `tracking.fbc` | `string` | Não | Aceita null. |
| `tracking.clientIpAddress` | `string` | Não | Aceita null. |
| `tracking.clientUserAgent` | `string` | Não | Aceita null. |
| `tracking.ctwaClid` | `string` | Não | Aceita null. |
| `metadata` | `object` | Não | Metadados adicionais do negócio. Aceita null. |

## Respostas

### 201

Criado

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `data` | `DealResponse` | Não | Negócio resumido retornado na criação ou atualização. |
| `data.id` | `string` | Não |  |
| `data.seq` | `integer` | Não |  |
| `data.name` | `string` | Não |  |
| `data.contactId` | `string` | Não | Aceita null. |
| `data.responsibleUserId` | `string` | Não |  |
| `data.companyId` | `string` | Não | Aceita null. |
| `data.pipelineId` | `string` | Não |  |
| `data.stageId` | `string` | Não |  |
| `data.value` | `number` | Não |  |
| `data.currency` | `string` | Não |  |
| `data.closeProbability` | `integer` | Não |  |
| `data.source` | `string` | Não |  |
| `data.status` | `string` | Não | open \| won \| lost |
| `data.coOwnerUserId` | `string` | Não | Aceita null. |
| `data.expectedCloseAt` | `string` | Não | Formato: date-time. Aceita null. |
| `data.stageChangedAt` | `string` | Não | Formato: date-time. |
| `data.closedAt` | `string` | Não | Formato: date-time. Aceita null. |
| `data.lostReason` | `string` | Não | Aceita null. |
| `data.customFields` | `object` | Não |  |
| `data.createdAt` | `string` | Não | Formato: date-time. |
| `data.tracking` | `object` | Não | Aceita null. |
| `data.tracking.utmContent` | `string` | Não | Aceita null. |
| `data.tracking.utmMedium` | `string` | Não | Aceita null. |
| `data.tracking.utmCampaign` | `string` | Não | Aceita null. |
| `data.tracking.utmSource` | `string` | Não | Aceita null. |
| `data.tracking.utmTerm` | `string` | Não | Aceita null. |
| `data.tracking.utmReferrer` | `string` | Não | Aceita null. |
| `data.tracking.referrer` | `string` | Não | Aceita null. |
| `data.tracking.gclientid` | `string` | Não | Aceita null. |
| `data.tracking.gclid` | `string` | Não | Aceita null. |
| `data.tracking.fbclid` | `string` | Não | Aceita null. |
| `data.tracking.metaLeadId` | `string` | Não | Aceita null. |
| `data.tracking.fbp` | `string` | Não | Aceita null. |
| `data.tracking.fbc` | `string` | Não | Aceita null. |
| `data.tracking.clientIpAddress` | `string` | Não | Aceita null. |
| `data.tracking.clientUserAgent` | `string` | Não | Aceita null. |
| `data.tracking.ctwaClid` | `string` | Não | Aceita null. |
| `message` | `string` | Não | Aceita null. |

```json
{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/DealResponse"
    },
    "message": {
      "type": "string",
      "nullable": true
    }
  }
}
```

### 400

Falha de validação dos campos; `fieldErrors` contém os erros.

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "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"
  ]
}
```

### 401

Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo.

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "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"
  ]
}
```

### 409

Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota.

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "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"
  ]
}
```

### 429

Limite de requisições excedido por workspace ou IP.

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "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"
  ]
}
```