LOloggro
Clientes

Crear o editar un cliente

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

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

POST /clients
Authorization: Bearer tu_token_aqui
Content-Type: application/json

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

Request

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

Request body

_idstring

ID del cliente. Si se envía y existe, el cliente se actualiza; si no, se crea uno nuevo.

namestring

Nombre del cliente

lastNamestring

Apellido del cliente

documentstring

Número de documento de identidad

idDocumentType11 | 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
documentNamestring

Nombre del tipo de documento (texto descriptivo)

checkDigitinteger

Dígito de verificación numérico (para NIT)

phonestring

Teléfono de contacto

emailstring email

Correo electrónico

addressstring

Dirección

citystring

Ciudad

cityDetailobject

Detalle de ciudad (objeto completo)

notesstring

Notas adicionales del cliente

birthdatestring date

Fecha de nacimiento

isSocialReasonboolean

Si el cliente es una razón social (empresa)

isVATCompanyTypeboolean

Si el cliente es contribuyente de IVA

responsibilitiesstring

Responsabilidades fiscales del cliente (texto libre)

responsibilityNamestring

Nombre de la responsabilidad fiscal

Example request

{
  "_id": "507f1f77bcf86cd799439021",
  "name": "Juan",
  "lastName": "Pérez",
  "document": "12345678",
  "idDocumentType": 13,
  "documentName": "Cédula de Ciudadanía",
  "checkDigit": 5,
  "phone": "+57 300 123 4567",
  "email": "juan@email.com",
  "address": "Calle 123 #45-67",
  "city": "Bogotá",
  "notes": "Cliente preferencial",
  "birthdate": "1990-05-15",
  "responsibilities": "R-99-PN",
  "responsibilityName": "No aplica – Otros",
  "contact": {
    "firstName": "María",
    "lastName": "López",
    "email": "maria@empresa.com",
    "phone": "+57 300 111 2222"
  }
}

Response

Cliente creado o actualizado exitosamente

_idstring

ID único del cliente

businessstring

ID del negocio al que pertenece el cliente

isSocialReasonboolean

Indica si es una razón social (empresa)

responsibilitiesstring

Responsabilidades tributarias

responsibilityNamestring

Nombre de la responsabilidad tributaria

namestring

Nombre del cliente

lastNamestring

Apellido del cliente

idDocumentTypenumber

Tipo de documento de identidad

documentNamestring

Nombre del tipo de documento

documentstring

Número de documento

checkDigitnumber

Dígito verificador del documento

isVATCompanyTypeboolean

Indica si es una empresa con IVA

emailstring email

Correo electrónico del cliente

phonestring

Número de teléfono del cliente

addressstring

Dirección del cliente

citystring

Ciudad del cliente (deprecado)

postalCodestring

Código postal

notesstring

Notas adicionales sobre el cliente

deletedboolean

Indica si el cliente está eliminado

modifiedOnstring date-time

Fecha de última modificación

createdOnstring date-time

Fecha de creación

birthdatestring date

Fecha de nacimiento del cliente

pointsnumber

Puntos de fidelidad del cliente

Example response

{
  "_id": "507f1f77bcf86cd799439021",
  "business": "507f1f77bcf86cd799439012",
  "responsibilities": "R-99-PN",
  "responsibilityName": "Régimen Simplificado",
  "name": "Juan",
  "lastName": "Pérez",
  "idDocumentType": 1,
  "documentName": "Cédula de Ciudadanía",
  "document": "12345678",
  "checkDigit": 9,
  "email": "juan@email.com",
  "phone": "+57 300 123 4567",
  "address": "Calle 123 #45-67",
  "cityDetail": {
    "countryCode": "CO",
    "stateCode": "11",
    "stateName": "Bogotá D.C.",
    "cityCode": "11001",
    "cityName": "Bogotá"
  },
  "city": "Bogotá",
  "postalCode": "110111",
  "notes": "Cliente preferencial con descuentos especiales",
  "deletedInfo": {
    "deletedBy": "507f1f77bcf86cd799439020",
    "date": "2025-08-05T10:30:00.000Z"
  },
  "modifiedOn": "2025-08-05T10:30:00.000Z",
  "createdOn": "2025-08-05T10:00:00.000Z",
  "birthdate": "1990-05-15",
  "points": 150,
  "creditMovement": [
    {
      "paymentMethod": {
        "internalId": "507f1f77bcf86cd799439030",
        "name": "Efectivo"
      },
      "date": "2025-08-05T10:30:00.000Z",
      "total": 50000,
      "notes": "Abono a cuenta"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.