Skip to content

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 ​

CampoTipoObligatorioDescripción y reglas
clientesarraySíLista de clientes a registrar o actualizar. Debe contener al menos uno.

clientes[] ​

CampoTipoObligatorioDescripción y reglas
documentoIdentidadClientestringSí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).
nombreRazonSocialClientestringSíNombre o razón social del cliente.
correoClientestringSíCorreo electrónico válido.
telefonoClientestringSí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.
direccionClientestringSí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"
    }
  ]
}
ClaveDescripción
total_clientes_agregadosCantidad de clientes nuevos creados.
clientes_agregadosClientes 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_actualizadosCantidad de clientes existentes que se actualizaron.
clientes_actualizadosClientes 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."
  ]
}
HTTPMensaje (ejemplo)Causa
400 / 401—Token ausente, mal formado, inválido o expirado. Ver Errores.
400El comercio indicado aún no está registrado.El negocio del token no está registrado.
400El campo clientes es obligatorio y debe contener al menos un cliente.Falta clientes, no es un arreglo o está vacío.
400Se 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, telefonoClienteCampos 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: V10000001Letra 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 12345678Falló el guardado de ese cliente.
500Error 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. V12345678 y J12345678 son 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 errores no 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.

API de Facturación · CG Imprenta Digital