Create Client

Creates a new client for a specific company. The client must have a unique combination of company_id, tipo_documento, and numero_documento.

Authentication

This endpoint requires authentication using a Bearer token.

Authorization: Bearer {your_token}

Request Body

company_id

integer

ID of the company this client belongs to. If not provided, will be associated with the authenticated user’s company.

tipo_documento

string

required

Document type code. Valid values:

1 - DNI (National ID)
4 - Carnet de Extranjería (Foreign ID)
6 - RUC (Tax ID)
7 - Passport
0 - DOC.TRIB.NO.DOM.SIN.RUC (Foreign Tax Document)

numero_documento

string

required

Document number (max 20 characters). Must be unique per company and document type.

Legal name of the client (max 255 characters)

nombre_comercial

string

Commercial or trade name (max 255 characters)

direccion

string

Physical address (max 255 characters)

ubigeo

string

6-digit UBIGEO code identifying the geographic location in Peru

distrito

string

District name (max 100 characters)

provincia

string

Province name (max 100 characters)

departamento

string

Department name (max 100 characters)

telefono

string

Phone number (max 20 characters)

string

Email address (max 255 characters). Must be a valid email format.

activo

boolean

default:"true"

Whether the client is active

Response

success

boolean

Indicates if the request was successful

message

string

Success or error message

data

object

The created client object

integer

Client ID

company_id

integer

Associated company ID

tipo_documento

string

Document type code

numero_documento

string

Document number

Legal name

nombre_comercial

string

Commercial name

direccion

string

Address

ubigeo

string

UBIGEO code

distrito

string

District

provincia

string

Province

departamento

string

Department

telefono

string

Phone

string

activo

boolean

Active status

created_at

string

Creation timestamp

updated_at

string

Last update timestamp

company

object

Associated company information

integer

Company ID

ruc

string

Company RUC

Company legal name

errors

object

Validation errors (only present when success is false)

Example Request

cURL

curl -X POST "https://api.example.com/api/v1/clients" \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "company_id": 1,
    "tipo_documento": "6",
    "numero_documento": "20123456789",
    "razon_social": "EMPRESA DEMO S.A.C.",
    "nombre_comercial": "Empresa Demo",
    "direccion": "Av. Los Comerciantes 123",
    "ubigeo": "150101",
    "distrito": "Lima",
    "provincia": "Lima",
    "departamento": "Lima",
    "telefono": "01-2345678",
    "email": "[email protected]",
    "activo": true
  }'

JavaScript

const response = await fetch('https://api.example.com/api/v1/clients', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_token_here',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    company_id: 1,
    tipo_documento: '6',
    numero_documento: '20123456789',
    razon_social: 'EMPRESA DEMO S.A.C.',
    nombre_comercial: 'Empresa Demo',
    direccion: 'Av. Los Comerciantes 123',
    ubigeo: '150101',
    distrito: 'Lima',
    provincia: 'Lima',
    departamento: 'Lima',
    telefono: '01-2345678',
    email: '[email protected]',
    activo: true
  })
});

const data = await response.json();

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.example.com/api/v1/clients');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer your_token_here',
    'Content-Type: application/json',
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'company_id' => 1,
    'tipo_documento' => '6',
    'numero_documento' => '20123456789',
    'razon_social' => 'EMPRESA DEMO S.A.C.',
    'nombre_comercial' => 'Empresa Demo',
    'direccion' => 'Av. Los Comerciantes 123',
    'ubigeo' => '150101',
    'distrito' => 'Lima',
    'provincia' => 'Lima',
    'departamento' => 'Lima',
    'telefono' => '01-2345678',
    'email' => '[email protected]',
    'activo' => true
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Example Response

201 Created

{
  "success": true,
  "message": "Cliente creado exitosamente",
  "data": {
    "id": 1,
    "company_id": 1,
    "tipo_documento": "6",
    "numero_documento": "20123456789",
    "razon_social": "EMPRESA DEMO S.A.C.",
    "nombre_comercial": "Empresa Demo",
    "direccion": "Av. Los Comerciantes 123",
    "ubigeo": "150101",
    "distrito": "Lima",
    "provincia": "Lima",
    "departamento": "Lima",
    "telefono": "01-2345678",
    "email": "[email protected]",
    "activo": true,
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z",
    "company": {
      "id": 1,
      "ruc": "20987654321",
      "razon_social": "MI EMPRESA S.A.C."
    }
  }
}

422 Validation Error

{
  "success": false,
  "message": "Errores de validación",
  "errors": {
    "tipo_documento": [
      "The tipo_documento field is required."
    ],
    "numero_documento": [
      "The numero_documento field is required."
    ],
    "razon_social": [
      "The razon_social field is required."
    ],
    "email": [
      "The email must be a valid email address."
    ]
  }
}

400 Duplicate Client

{
  "success": false,
  "message": "Ya existe un cliente con el mismo tipo y número de documento en esta empresa"
}

404 Company Not Found

{
  "success": false,
  "message": "La empresa especificada no existe o está inactiva"
}

500 Error

{
  "success": false,
  "message": "Error al crear cliente: Database connection failed"
}

The combination of company_id, tipo_documento, and numero_documento must be unique. If you try to create a client with a document that already exists for the same company, you’ll receive a 400 error.

The ubigeo field is a standardized 6-digit code used in Peru to identify geographic locations. The first 2 digits represent the department, the next 2 the province, and the last 2 the district.

Validation Rules

company_id: Must reference an existing, active company
tipo_documento: Must be one of: 1, 4, 6, 7, or 0
numero_documento: Required, max 20 characters, must be unique per company/document type
razon_social: Required, max 255 characters
nombre_comercial: Optional, max 255 characters
direccion: Optional, max 255 characters
ubigeo: Optional, must be exactly 6 digits
distrito: Optional, max 100 characters
provincia: Optional, max 100 characters
departamento: Optional, max 100 characters
telefono: Optional, max 20 characters
email: Optional, must be valid email format, max 255 characters
activo: Optional boolean, defaults to true

Authentication

Companies & Branches

Clients

Electronic Documents

Consultations

Configuration

Authentication

Request Body

Response

Example Request

Example Response

Validation Rules

Build docs developers (and LLMs) love

Authentication

Companies & Branches

Clients

Electronic Documents

Consultations

Configuration

​Authentication

​Request Body

​Response

​Example Request

​Example Response

​Validation Rules

Build docs developers (and LLMs) love

Authentication

Request Body

Response

Example Request

Example Response

Validation Rules