Skip to main content

​
Overview

The Clients API manages customer information for sales operations. Clients are identified by their document number (primary key) and can be natural persons or legal entities.

​
Model Structure

​
Cliente Model

Table: clientes
Primary Key: documento (string, non-incrementing)

​
Attributes

​
documento
string
required
Unique document identifier (CC, NIT, CE, etc.). Max 40 characters.
​
nombre
string
required
Full name or company name. Max 150 characters.
​
id_tipo_cliente
integer
required
Foreign key to tipos_cliente. Indicates if client is natural person or company.
​
id_tipo_documento
integer
required
Foreign key to tipos_documento. Document type (CC, NIT, CE, Passport, etc.).
​
direccion
string
Physical address. Max 200 characters.
​
telefono
string
Contact phone number. Max 30 characters.
​
correo
string
Email address. Max 150 characters. Must be valid email format.
​
created_at
timestamp
Record creation timestamp.
​
updated_at
timestamp
Last update timestamp.

​
Relationships

​
tipoCliente
BelongsTo
Related TipoCliente model. Contains client type classification.
​
tipoDocumento
BelongsTo
Related TipoDocumento model. Contains document type information.
​
ventas
HasMany
Collection of Venta records. All sales/separations for this client.
​
apartamentos
HasMany
Collection of Apartamento records owned by this client.

​
List All Clients

curl -X GET "https://api.coreprojects.com/clientes" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

​
Response

[
  {
    "documento": "1234567890",
    "nombre": "Juan Pérez García",
    "id_tipo_cliente": 1,
    "id_tipo_documento": 1,
    "direccion": "Calle 123 #45-67",
    "telefono": "+57 300 123 4567",
    "correo": "[email protected]",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z",
    "tipo_cliente": {
      "id_tipo_cliente": 1,
      "tipo_cliente": "Persona Natural",
      "descripcion": "Cliente individual"
    },
    "tipo_documento": {
      "id_tipo_documento": 1,
      "tipo_documento": "CC",
      "descripcion": "Cédula de Ciudadanía"
    },
    "ventas": []
  }
]

​
Get Client by Document

curl -X GET "https://api.coreprojects.com/clientes/{documento}" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

​
Path Parameters

​
documento
string
required
Client document identifier (e.g., “1234567890”)

​
Response

{
  "documento": "1234567890",
  "nombre": "Juan Pérez García",
  "id_tipo_cliente": 1,
  "id_tipo_documento": 1,
  "direccion": "Calle 123 #45-67",
  "telefono": "+57 300 123 4567",
  "correo": "[email protected]",
  "tipo_cliente": {
    "id_tipo_cliente": 1,
    "tipo_cliente": "Persona Natural"
  },
  "tipo_documento": {
    "id_tipo_documento": 1,
    "tipo_documento": "CC"
  },
  "ventas": [
    {
      "id_venta": 1,
      "fecha_venta": "2024-01-15",
      "valor_total": 250000000,
      "tipo_operacion": "venta",
      "proyecto": {
        "id_proyecto": 1,
        "nombre": "Torres del Parque"
      },
      "apartamento": {
        "id_apartamento": 101,
        "numero": "301"
      }
    }
  ]
}

​
Error Responses

​
404
error
Client not found with provided document.

​
Create Client

curl -X POST "https://api.coreprojects.com/clientes" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "María López",
    "id_tipo_cliente": 1,
    "id_tipo_documento": 1,
    "documento": "9876543210",
    "direccion": "Carrera 45 #23-10",
    "telefono": "+57 301 234 5678",
    "correo": "[email protected]"
  }'

​
Request Body

​
nombre
string
required
Client full name or company name. Max 150 characters.
​
id_tipo_cliente
integer
required
Client type ID. Must exist in tipos_cliente table.
​
id_tipo_documento
integer
required
Document type ID. Must exist in tipos_documento table.
​
documento
string
required
Unique document number. Max 40 characters. Must be unique.
​
direccion
string
Physical address. Max 200 characters.
​
telefono
string
Contact phone. Max 30 characters.
​
correo
string
Email address. Max 150 characters. Must be valid email format.
​
redirect_to
string
Optional redirect URL after creation (used in web interface).

​
Validation Rules

  • nombre: Required, string, max 150 characters
  • id_tipo_cliente: Required, must exist in tipos_cliente table
  • id_tipo_documento: Required, must exist in tipos_documento table
  • documento: Required, string, max 40 chars, must be unique
  • direccion: Optional, string, max 200 characters
  • telefono: Optional, string, max 30 characters
  • correo: Optional, valid email format, max 150 characters

​
Response

{
  "documento": "9876543210",
  "nombre": "María López",
  "id_tipo_cliente": 1,
  "id_tipo_documento": 1,
  "direccion": "Carrera 45 #23-10",
  "telefono": "+57 301 234 5678",
  "correo": "[email protected]",
  "created_at": "2024-01-20T14:25:00.000000Z",
  "updated_at": "2024-01-20T14:25:00.000000Z"
}

​
Error Responses

​
422
validation_error
Validation failed. Common errors:
  • Document already exists
  • Invalid email format
  • Missing required fields
  • Invalid tipo_cliente or tipo_documento ID

​
Update Client

curl -X PUT "https://api.coreprojects.com/clientes/{documento}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "María López Rodríguez",
    "direccion": "Carrera 45 #23-10 Apto 502",
    "telefono": "+57 301 234 5678",
    "correo": "[email protected]"
  }'

​
Path Parameters

​
documento
string
required
Client document identifier

​
Request Body

​
nombre
string
required
Updated client name
​
id_tipo_cliente
integer
required
Updated client type ID
​
id_tipo_documento
integer
required
Updated document type ID
​
direccion
string
Updated address
​
telefono
string
Updated phone
​
correo
string
Updated email
The documento field cannot be updated as it’s the primary key.

​
Response

{
  "documento": "9876543210",
  "nombre": "María López Rodríguez",
  "id_tipo_cliente": 1,
  "id_tipo_documento": 1,
  "direccion": "Carrera 45 #23-10 Apto 502",
  "telefono": "+57 301 234 5678",
  "correo": "[email protected]",
  "updated_at": "2024-01-20T15:30:00.000000Z"
}

​
Delete Client

curl -X DELETE "https://api.coreprojects.com/clientes/{documento}" \
  -H "Authorization: Bearer {token}"

​
Path Parameters

​
documento
string
required
Client document identifier to delete
Deleting a client may fail if there are associated sales records due to foreign key constraints. Consider soft deleting or archiving instead.

​
Response

{
  "message": "Cliente eliminado correctamente"
}

​
Error Responses

​
404
error
Client not found
​
409
error
Cannot delete client with existing sales records

​
Business Logic

​
Client Types

Clients are classified by type (id_tipo_cliente):
  • Persona Natural: Individual buyers
  • Persona Jurídica: Companies or legal entities

​
Document Types

Supported document types (id_tipo_documento):
  • CC: Cédula de Ciudadanía (National ID)
  • NIT: Número de Identificación Tributaria (Tax ID)
  • CE: Cédula de Extranjería (Foreign ID)
  • Pasaporte: Passport
  • Otro: Other

​
Usage in Sales

  • Each Venta (sale) or Separacion (separation) must reference a valid client
  • Client document serves as the foreign key in sales records
  • Eager load client data when querying sales for performance

​
Data Integrity

  • Document numbers must be unique across all clients
  • Email validation ensures proper format
  • Phone and address fields are optional but recommended
  • Client type and document type are required for legal compliance

Build docs developers (and LLMs) love

Get started for freeTalk to us