Apariencia
Registrar clientes
POST /api/Invoice/add_clients
Registra o actualiza clientes en la cartera de su negocio. Si ya existe un cliente con el mismo documento (letra y número: V12345678 y J12345678 son clientes distintos) se actualizan sus datos; si no, se crea. La operación es todo o nada: si algún cliente tiene errores, no se guarda ninguno.
Autenticación: Authorization: Bearer <token> (cómo obtenerlo) · Content-Type: application/json
Cuerpo de la solicitud
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
clientes | array | Sí | Lista de clientes a registrar o actualizar. Debe contener al menos uno. |
clientes[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
documentoIdentidadCliente | string | Sí | RIF o cédula: una letra V, E, P, J, G o C seguida de 8 a 10 dígitos, sin guiones ni espacios (ej. V12345678, J123456789). |
nombreRazonSocialCliente | string | Sí | Nombre o razón social del cliente. |
correoCliente | string | Sí | Correo electrónico válido. |
telefonoCliente | string | Sí | Teléfono con exactamente 11 dígitos (se ignoran espacios, guiones u otros caracteres no numéricos al contar; ej. 04141234567). Se guarda tal como se envía. |
direccionCliente | string | Sí | Dirección fiscal del cliente. |
Ejemplo de solicitud
json
{
"clientes": [
{
"documentoIdentidadCliente": "J123456789",
"nombreRazonSocialCliente": "Cliente Ejemplo C.A.",
"correoCliente": "contacto@example.com",
"telefonoCliente": "04141234567",
"direccionCliente": "Av. Principal, Caracas"
},
{
"documentoIdentidadCliente": "V12345678",
"nombreRazonSocialCliente": "Persona Ejemplo",
"correoCliente": "persona@example.com",
"telefonoCliente": "04241234567",
"direccionCliente": "Valencia, Carabobo"
}
]
}Respuesta exitosa
HTTP 200
json
{
"success": true,
"message": "Operación completada exitosamente.",
"total_clientes_agregados": 1,
"clientes_agregados": [
{
"documentoIdentidadCliente": "123456789",
"nombreRazonSocialCliente": "Cliente Ejemplo C.A.",
"correoCliente": "contacto@example.com",
"telefonoCliente": "04141234567",
"direccionCliente": "Av. Principal, Caracas",
"fk_document_type_id": 4
}
],
"total_clientes_actualizados": 1,
"clientes_actualizados": [
{
"documentoIdentidadCliente": "12345678",
"nombreRazonSocialCliente": "Persona Ejemplo",
"correoCliente": "persona@example.com",
"telefonoCliente": "04241234567",
"direccionCliente": "Valencia, Carabobo"
}
]
}| Clave | Descripción |
|---|---|
total_clientes_agregados | Cantidad de clientes nuevos creados. |
clientes_agregados | Clientes creados. documentoIdentidadCliente se devuelve solo con la parte numérica (sin la letra); fk_document_type_id indica el tipo de documento: 1 V, 2 E, 3 P, 4 J, 5 G, 7 C. |
total_clientes_actualizados | Cantidad de clientes existentes que se actualizaron. |
clientes_actualizados | Clientes actualizados (misma estructura, sin fk_document_type_id). |
Errores
Cuando hay errores de validación, la respuesta incluye un arreglo errores con un mensaje por problema:
json
{
"success": false,
"message": "Se encontraron errores en la validación. Corrija los datos de los clientes y vuelva a intentarlo.",
"errores": [
"El teléfono del cliente 1 debe tener exactamente 11 dígitos.",
"El correo del cliente 2 no es válido."
]
}| HTTP | Mensaje (ejemplo) | Causa |
|---|---|---|
| 400 / 401 | — | Token ausente, mal formado, inválido o expirado. Ver Errores. |
| 400 | El comercio indicado aún no está registrado. | El negocio del token no está registrado. |
| 400 | El campo clientes es obligatorio y debe contener al menos un cliente. | Falta clientes, no es un arreglo o está vacío. |
| 400 | Se encontraron errores en la validación. Corrija los datos de los clientes y vuelva a intentarlo. | Algún cliente no pasó la validación. Mensajes posibles en errores: |
Faltan los siguientes campos en el cliente 1: correoCliente, telefonoCliente | Campos obligatorios vacíos. | |
El correo del cliente 1 no es válido. | Correo con formato inválido. | |
El teléfono del cliente 1 debe tener exactamente 11 dígitos. | Teléfono con más o menos de 11 dígitos. | |
El campo Documento de Identidad del Cliente debe ser letra seguido de máximo 10 números. | Documento con formato inválido (debe ser letra + 8 a 10 dígitos). | |
Tipo de documento inválido en el cliente 1 (código: X12345678). Los valores válidos son: V, E, P, J, G, C. Ejemplo: V10000001 | Letra de documento no admitida. | |
El cliente con número de identificación V12345678 está duplicado en la solicitud (cliente 3). | Dos clientes de la solicitud con el mismo documento (letra y número); el mensaje lo muestra con la letra, p. ej. V12345678. | |
Error al registrar el cliente con número 12345678 / Error al actualizar el cliente con número 12345678 | Falló el guardado de ese cliente. | |
| 500 | Error en el servidor: ... | Error inesperado. |
Notas
- Identificación por letra y número: un cliente se considera existente (y se actualiza) si en su negocio ya hay otro con el mismo documento completo.
V12345678yJ12345678son clientes distintos (igual que al emitir facturas y retenciones). - Actualización completa: al actualizar se reemplazan nombre, tipo de documento, correo, teléfono y dirección con lo enviado.
- Todo o nada: ante cualquier error en
erroresno se registra ni actualiza ningún cliente. - No es obligatorio: Agregar factura crea o actualiza automáticamente el cliente de cada factura; este endpoint sirve para cargar la cartera por adelantado. Para consultar clientes use Consultar clientes.
