---
title: "Crear o editar un cliente"
method: POST
path: "/clients"
tags: ["Clientes"]
---

# Crear o editar un cliente

`POST /clients`

## Request

- Base URL: `https://api.pirpos.com`
- URL: `https://api.pirpos.com/clients`
- Auth: HTTP bearer

Crea un nuevo cliente o edita uno existente para el negocio actual.

**Autenticación requerida:** Este endpoint requiere autenticación Bearer Token.
Usar el campo `tokenCurrent` obtenido del servicio de login (/login) en el header:
`Authorization: Bearer {tokenCurrent}`

**Permiso requerido:** `CL_POST` (Crear/Editar)

**Comportamiento:**
- Si se envía `_id`, se busca el cliente existente y se actualiza con los datos del body.
- Si no se envía `_id` (o no existe), se crea un nuevo cliente con `points: 0`.
- Respeta la configuración de compartir clientes con negocio padre.
- Registra el historial de cambios (creación o actualización).
- Notifica via WebSocket a todos los usuarios del negocio.

## Ejemplos de Uso

### 1. Crear nuevo cliente
```json
POST /clients
Authorization: Bearer tu_token_aqui
Content-Type: application/json

{
  "name": "Juan",
  "lastName": "Pérez",
  "document": "12345678",
  "idDocumentType": "CC",
  "phone": "+57 300 123 4567",
  "email": "juan@email.com",
  "address": "Calle 123 #45-67"
}
```

### 2. Editar cliente existente
```json
POST /clients
Authorization: Bearer tu_token_aqui
Content-Type: application/json

{
  "_id": "507f1f77bcf86cd799439021",
  "name": "Juan",
  "lastName": "García",
  "phone": "+57 300 999 8888"
}
```

## Request body

- object
  - `_id` string: ID del cliente. Si se envía y existe, el cliente se actualiza; si no, se crea uno nuevo.
  - `name` string: Nombre del cliente
  - `lastName` string: Apellido del cliente
  - `document` string: Número de documento de identidad
  - `idDocumentType` 11 | 12 | 13 | 21 | 22 | 31 | 41 | 42 | 43 | 47 | 48: Código numérico del tipo de documento. Valores válidos: - `11` = Registro civil (RC) - Persona - `12` = Tarjeta de identidad (TI) - Persona - `13` = Cédula de ciudadanía (CC) - Persona - `21` = Tarjeta de extranjería (TE) - Persona - `22` = Cédula de extranjería (CE) - Persona - `31` = NIT - Empresa - `41` = Pasaporte (PS) - Persona - `42` = Documento de identificación extranjero (DE) - Persona - `43` = Sin identificación del exterior o uso exclusivo de la DIAN (SIDIAN) - Empresa - `47` = Permiso Especial de Permanencia (PEP) - Persona - `48` = Permiso Protección Temporal (PPT) - Persona
  - `documentName` string: Nombre del tipo de documento (texto descriptivo)
  - `checkDigit` integer: Dígito de verificación numérico (para NIT)
  - `phone` string: Teléfono de contacto
  - `email` string, email: Correo electrónico
  - `address` string: Dirección
  - `city` string: Ciudad
  - `cityDetail` object: Detalle de ciudad (objeto completo)
  - `notes` string: Notas adicionales del cliente
  - `birthdate` string, date: Fecha de nacimiento
  - `isSocialReason` boolean: Si el cliente es una razón social (empresa)
  - `isVATCompanyType` boolean: Si el cliente es contribuyente de IVA
  - `responsibilities` string: Responsabilidades fiscales del cliente (texto libre)
  - `responsibilityName` string: Nombre de la responsabilidad fiscal
  - `contact` object: Persona de contacto del cliente (para empresas)
    - `firstName` string: Nombre del contacto
    - `lastName` string: Apellido del contacto
    - `email` string: Email del contacto
    - `phone` string: Teléfono del contacto

## Response `200`

Cliente creado o actualizado exitosamente

- Client
  - `_id` string: ID único del cliente
  - `business` string: ID del negocio al que pertenece el cliente
  - `isSocialReason` boolean: Indica si es una razón social (empresa)
  - `responsibilities` string: Responsabilidades tributarias
  - `responsibilityName` string: Nombre de la responsabilidad tributaria
  - `name` string: Nombre del cliente
  - `lastName` string: Apellido del cliente
  - `idDocumentType` number: Tipo de documento de identidad
  - `documentName` string: Nombre del tipo de documento
  - `document` string: Número de documento
  - `checkDigit` number: Dígito verificador del documento
  - `isVATCompanyType` boolean: Indica si es una empresa con IVA
  - `email` string, email: Correo electrónico del cliente
  - `phone` string: Número de teléfono del cliente
  - `address` string: Dirección del cliente
  - `cityDetail` object: Detalles de la ciudad
    - `countryCode` string: Código del país
    - `stateCode` string: Código del departamento
    - `stateName` string: Nombre del departamento
    - `cityCode` string: Código de la ciudad
    - `cityName` string: Nombre de la ciudad
  - `city` string: Ciudad del cliente (deprecado)
  - `postalCode` string: Código postal
  - `notes` string: Notas adicionales sobre el cliente
  - `deleted` boolean: Indica si el cliente está eliminado
  - `deletedInfo` object: Información de eliminación
    - `isDeleted` boolean: Indica si está eliminado
    - `deletedBy` string: Usuario que eliminó el cliente
    - `date` string, date-time: Fecha de eliminación
  - `modifiedOn` string, date-time: Fecha de última modificación
  - `createdOn` string, date-time: Fecha de creación
  - `birthdate` string, date: Fecha de nacimiento del cliente
  - `points` number: Puntos de fidelidad del cliente
  - `creditMovement` object[]: Historial de movimientos de crédito
    - `paymentMethod` object
      - `internalId` string: ID del método de pago
      - `name` string: Nombre del método de pago
    - `date` string, date-time: Fecha del movimiento
    - `total` number: Monto del movimiento
    - `notes` string: Notas del movimiento

## Other responses

- `401`: Token de autorización inválido o faltante
- `403`: Sin permisos para crear/editar clientes
- `500`: Error interno del servidor

---

[API](https://skmtc.dev/loggro/apis/restobar-servicios-del-m-dulo-de-restobar.md) - [All operations](https://skmtc.dev/loggro/apis/restobar-servicios-del-m-dulo-de-restobar/llms.txt) - [OpenAPI document](https://skmtc.dev/loggro/apis/restobar-servicios-del-m-dulo-de-restobar/revisions/9d4431a3cddc?raw)