Buscar Cliente por Documento

​

Autenticación

​

Uso Principal

• Buscar clientes existentes por su documento
• Validar si un cliente ya está registrado antes de crear uno nuevo
• Autocompletar datos del cliente en formularios

​

Parámetros del Body

​

Respuesta Exitosa (Cliente Encontrado)

​

Ejemplo de Solicitud

curl -X POST \
  https://tudominio.com/api/clientes/buscar-documento \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "documento": "20612706702",
    "empresa_id": 1
  }'

​

Ejemplo de Respuesta Exitosa

{
  "success": true,
  "data": {
    "id_cliente": 1,
    "documento": "20612706702",
    "tipo_doc": "6",
    "datos": "CORPORACION XYZ S.A.C.",
    "direccion": "Av. Los Pinos 123",
    "direccion2": "Urb. Los Jardines",
    "telefono": "01-4567890",
    "telefono2": "987654321",
    "email": "[email protected]",
    "foto_url": "/storage/clientes/cliente_1234567890.jpg",
    "id_empresa": 1,
    "ubigeo": "150101",
    "departamento": "Lima",
    "provincia": "Lima",
    "distrito": "Lima",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z",
    "empresa": {
      "id_empresa": 1,
      "comercial": "Santo Domingo",
      "ruc": "20612706702"
    }
  }
}

​

Cliente No Encontrado

{
  "success": false,
  "message": "Cliente no encontrado"
}

​

Flujo de Uso Recomendado

1. Usuario ingresa documento en el formulario de venta/factura
2. Frontend llama a este endpoint con el documento y empresa_id
3. Si el cliente existe:
   • Autocompletar formulario con datos del cliente
   • Permitir continuar con la venta
4. Si no existe (404):
   • Mostrar opción para crear nuevo cliente
   • O permitir continuar como cliente genérico (“Cliente Varios”)

​

Integración con Consulta SUNAT

1. Llamar primero a /api/clientes/buscar-documento
2. Si retorna 404, consultar API de SUNAT/RENIEC
3. Usar datos de SUNAT para crear cliente con POST /api/clientes

​

Códigos de Error

{
  "success": false,
  "message": "Cliente no encontrado"
}

{
  "success": false,
  "message": "Error de validación",
  "errors": {
    "documento": ["El campo documento es obligatorio"],
    "empresa_id": ["El campo empresa_id es obligatorio"]
  }
}

{
  "success": false,
  "message": "Error al buscar cliente",
  "error": "Mensaje de error específico"
}

​

Notas de Implementación

• La búsqueda es exacta (no parcial) sobre el campo documento
• El scope automático por empresa garantiza aislamiento multi-tenant
• Los clientes se buscan usando where()->first(), no findOrFail(), para control de errores personalizado