Clientes

CRUD sobre el directorio de clientes. Cada cliente es la entidad a la que asocias ventas, ingresos y cuentas por cobrar.

El objeto Customer

{
  "id":         "65a1b2c3d4e5f6789012abcd",
  "name":       "Laura Méndez",
  "short_name": "Laura",
  "email":      "laura@example.com",
  "phone":      "+52 656 1234567",
  "birthdate":  "1985-04-22",
  "source":     "sitio_web",
  "notes":      "Cliente recurrente desde 2024.",
  "is_active":  true,
  "created_at": "2026-02-08T11:00:00Z",
  "updated_at": "2026-05-12T14:30:21Z"
}

Campos

Campo	Tipo	Descripción
id	string	ObjectId.
name	string	Nombre completo.
short_name	string	Apodo para mostrar (opcional).
email	string	Correo de contacto.
phone	string	Teléfono libre (recomendado formato E.164).
birthdate	string	Fecha en YYYY-MM-DD. Guardada como string, no se valida.
source	string	De dónde viene (sitio_web, referido, etc.). Libre.
notes	string	Anotaciones libres.
is_active	bool	Marca de archivado lógico.
created_at / updated_at	string	ISO 8601 UTC.

---

Listar clientes

GET/api/v1/customersread-customers

Query params: page, limit (igual que Productos).

cURL

curl 'https://developers.fi-nova.com/api/v1/customers' \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO'

JavaScript

const res = await fetch(
  'https://developers.fi-nova.com/api/v1/customers',
  { headers: { Authorization: 'Bearer finova_sk_TU_SECRETO' } }
);
const { data } = await res.json();

---

Obtener un cliente

GET/api/v1/customers/:idread-customers

---

Crear un cliente

POST/api/v1/customerscreate-customers

Campos aceptados en data: name, short_name, email, phone, birthdate, source, notes, is_active.

cURL

curl -X POST https://developers.fi-nova.com/api/v1/customers \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "name":   "Laura Méndez",
      "email":  "laura@example.com",
      "phone":  "+52 656 1234567",
      "source": "sitio_web"
    }
  }'

JavaScript

await fetch('https://developers.fi-nova.com/api/v1/customers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer finova_sk_TU_SECRETO',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      name:  'Laura Méndez',
      email: 'laura@example.com',
      phone: '+52 656 1234567',
      source: 'sitio_web',
    },
  }),
});

---

Actualizar un cliente

PATCH/api/v1/customers/:idupdate-customers

Solo manda los campos que cambian — los demás se conservan.

---

Eliminar un cliente

DELETE/api/v1/customers/:iddelete-customers

Borra el cliente. 204 No Content en éxito. Clientes con ingresos o cuentas por cobrar asociadas NO se pueden eliminar — usa is_active: false para archivarlos.

---

Errores específicos

error	Cuándo
validation_failed (422)	Email mal formado, name vacío.
not_found (404)	El id no existe o pertenece a otra empresa.
insufficient_scope (403)	Falta el scope.

Privacidad

Los datos de cliente incluyen PII (email, teléfono, fecha de nacimiento). Si tu integración los expone más allá de tu propio backoffice:

• Audita quién tiene acceso a las API keys con read-customers.
• Considera segmentar — una key separada para sincronización con tu ERP, sin permitir read-customers desde tu sitio público.
• Cumple con la regulación local de datos personales (en MX, LFPDPPP).