Esquema de filtro de clientes - Documentación Quentli

Este documento describe el esquema del parámetro filter para GET /v1/customers. filter no se envía como JSON literal: se envía como query string codificado con qs.

Formato general

Ejemplo mínimo:

GET /v1/customers?filter[name][contains]=juan

Ejemplo con composición lógica:

GET /v1/customers?filter[AND][0][email][contains]=@empresa.com&filter[OR][0][noPayments]=true

Esquema base

Conceptualmente, el esquema es:

{
  "id": "StringFilter",
  "createdAt": "DateTimeFilter",
  "updatedAt": "DateTimeFilter",
  "name": "StringFilter",
  "archivedAt": "NullableDateTimeFilter",
  "email": "StringFilter",
  "phoneNumber": "StringFilter",
  "secondaryPhoneNumber": "StringFilter",
  "username": "StringFilter",
  "tags": "TagListFilter",
  "invoices": "InvoiceListFilter",
  "receivedAnnouncements": "AnnouncementRecipientListFilter",
  "metadataItem": "MetadataItemFilter",
  "metadata": "MetadataListFilter",
  "assignee": "MemberFilter",
  "noPayments": "BooleanLikeFilter",
  "hasTaxProfiles": "BooleanLikeFilter",
  "AND": ["CustomerFilter"],
  "OR": ["CustomerFilter"]
}

Campos soportados

Puedes usar estos campos de primer nivel en filter:

id
createdAt
updatedAt
name
archivedAt
email
phoneNumber
secondaryPhoneNumber
username
tags
invoices
receivedAnnouncements
metadataItem
metadata
assignee
noPayments
hasTaxProfiles
AND
OR

Operadores comunes

Los operadores disponibles dependen del tipo de campo:

String (name, email, username, etc.): equals, contains, startsWith, endsWith, in, notIn
Fecha (createdAt, updatedAt, archivedAt): equals, gt, gte, lt, lte
Booleano (noPayments, hasTaxProfiles): equals

Para filtros relacionales (tags, invoices, metadata, assignee) usa operadores de lista/relación como some, every, none, según el objeto anidado.

Ejemplos

Filtrar por nombre

GET /v1/customers?filter[name][contains]=Alicia

Filtrar por correo exacto

GET /v1/customers?filter[email][equals]=alicia@ejemplo.com

Filtrar por clientes sin pagos

GET /v1/customers?filter[noPayments]=true

Combinar filtros con AND

GET /v1/customers?filter[AND][0][name][contains]=Alicia&filter[AND][1][hasTaxProfiles]=true

Combinar `AND` y `OR`

GET /v1/customers?filter[AND][0][name][contains]=Alicia&filter[AND][1][OR][0][email][contains]=@empresa.com&filter[AND][1][OR][1][noPayments]=true

Orden y paginacion junto con filtros

GET /v1/customers?filter[name][contains]=Alicia&orderBy=createdAt=desc&take=20&skip=0

Construccion recomendada con `qs`

import qs from 'qs';

const filter = {
  AND: [{ name: { contains: 'Alicia' } }, { hasTaxProfiles: { equals: true } }],
};

const query = qs.stringify({ filter, take: 20, skip: 0 }, { encodeValuesOnly: true });
// filter[AND][0][name][contains]=Alicia&filter[AND][1][hasTaxProfiles][equals]=true&take=20&skip=0

Recomendaciones

Usa un serializador qs para evitar errores de encoding y de arrays anidados.
Empieza con un filtro simple y agrega AND/OR solo cuando sea necesario.
Combina filtros con take, skip y orderBy para paginacion consistente.

Introducción a la API

Suscripciones de duración indefinida

​Formato general

​Esquema base

​Campos soportados

​Operadores comunes

​Ejemplos

​Filtrar por nombre

​Filtrar por correo exacto

​Filtrar por clientes sin pagos

​Combinar filtros con AND

​Combinar AND y OR

​Orden y paginacion junto con filtros

​Construccion recomendada con qs

​Recomendaciones