Skip to main content
POST
/
api
/
clientes
Crear Cliente
curl --request POST \
  --url https://api.example.com/api/clientes \
  --header 'Content-Type: application/json' \
  --data '
{
  "documento": "<string>",
  "tipo_doc": "<string>",
  "datos": "<string>",
  "direccion": "<string>",
  "direccion2": "<string>",
  "telefono": "<string>",
  "telefono2": "<string>",
  "email": "<string>",
  "id_empresa": 123,
  "ubigeo": "<string>",
  "departamento": "<string>",
  "provincia": "<string>",
  "distrito": "<string>"
}
'
{
  "422": {},
  "500": {},
  "success": true,
  "message": "<string>",
  "data": {
    "id_cliente": 123,
    "documento": "<string>",
    "tipo_doc": "<string>",
    "datos": "<string>",
    "foto_url": "<string>",
    "empresa": {}
  }
}

​
Autenticación

Este endpoint requiere autenticación mediante token Bearer y el permiso clientes.create.

​
Parámetros del Body

​
documento
string
required
Número de documento (RUC/DNI). Debe ser único por empresa. Máximo 15 caracteres.
​
tipo_doc
string
Tipo de documento: ‘1’ (DNI), ‘6’ (RUC), ‘4’ (otros). Si no se proporciona, se detecta automáticamente según la longitud del documento.
​
datos
string
required
Nombre o razón social del cliente. Máximo 245 caracteres.
​
direccion
string
Dirección principal. Máximo 245 caracteres.
​
direccion2
string
Dirección secundaria o referencia. Máximo 220 caracteres.
​
telefono
string
Número de teléfono principal. Máximo 200 caracteres.
​
telefono2
string
Número de teléfono secundario. Máximo 200 caracteres.
​
email
string
Correo electrónico válido. Máximo 200 caracteres.
​
foto
file
Imagen del cliente. Formatos aceptados: jpeg, png, jpg, gif. Tamaño máximo: 2MB.
​
id_empresa
integer
required
ID de la empresa a la que pertenece el cliente. Debe existir en la tabla empresas.
​
ubigeo
string
Código de ubigeo de 6 dígitos.
​
departamento
string
Nombre del departamento. Máximo 100 caracteres.
​
provincia
string
Nombre de la provincia. Máximo 100 caracteres.
​
distrito
string
Nombre del distrito. Máximo 100 caracteres.

​
Formato de Solicitud

Para subir una foto, utilice multipart/form-data: 
curl -X POST \
  https://tudominio.com/api/clientes \
  -H 'Authorization: Bearer TU_TOKEN' \
  -F 'documento=20612706702' \
  -F 'datos=CORPORACION XYZ S.A.C.' \
  -F 'direccion=Av. Los Pinos 123' \
  -F 'telefono=01-4567890' \
  -F '[email protected]' \
  -F 'foto=@/ruta/a/imagen.jpg' \
  -F 'id_empresa=1' \
  -F 'ubigeo=150101' \
  -F 'departamento=Lima' \
  -F 'provincia=Lima' \
  -F 'distrito=Lima'

​
Respuesta

​
success
boolean
Indica si la operación fue exitosa
​
message
string
Mensaje de confirmación: “Cliente creado exitosamente”
​
data
object
Datos del cliente creado con la relación de empresa cargada

​
Ejemplo de Respuesta Exitosa

{
  "success": true,
  "message": "Cliente creado exitosamente",
  "data": {
    "id_cliente": 45,
    "documento": "20612706702",
    "tipo_doc": "6",
    "datos": "CORPORACION XYZ S.A.C.",
    "direccion": "Av. Los Pinos 123",
    "direccion2": "Urb. Los Jardines",
    "telefono": "01-4567890",
    "telefono2": null,
    "email": "[email protected]",
    "foto_url": "/storage/clientes/cliente_1709645834.jpg",
    "id_empresa": 1,
    "ubigeo": "150101",
    "departamento": "Lima",
    "provincia": "Lima",
    "distrito": "Lima",
    "created_at": "2024-03-05T16:30:34.000000Z",
    "updated_at": "2024-03-05T16:30:34.000000Z",
    "empresa": {
      "id_empresa": 1,
      "comercial": "Santo Domingo",
      "ruc": "20612706702"
    }
  }
}

​
Errores de Validación

​
422
object
Error de validación
{
  "success": false,
  "message": "Error de validación",
  "errors": {
    "documento": [
      "Este documento ya está registrado para esta empresa"
    ],
    "email": [
      "El email no es válido"
    ],
    "foto": [
      "La imagen no debe exceder 2MB"
    ]
  }
}

​
Detección Automática de Tipo de Documento

Si no se proporciona tipo_doc, el sistema lo detecta automáticamente:
  • 11 dígitos → tipo_doc = ‘6’ (RUC)
  • 8 dígitos → tipo_doc = ‘1’ (DNI)
  • Otros → tipo_doc = ‘4’ (Documento extranjero u otros)

​
Almacenamiento de Imágenes

Las fotos se almacenan en storage/app/public/clientes/ con el formato: 
cliente_{timestamp}.{extension}
Ejemplo: cliente_1709645834.jpg La URL retornada en foto_url es accesible públicamente mediante el enlace simbólico de Laravel Storage.

​
Códigos de Error

​
422
object
Error de validación (ver ejemplo arriba)
​
500
object
Error interno del servidor
{
  "success": false,
  "message": "Error al crear cliente",
  "error": "Mensaje de error específico"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us