Clientes — Listado y Detalle

Consulta registros de clientes con búsqueda y filtrado, y obtené perfiles completos de cliente con sus cuentas asociadas.

---

Listar clientes

GET/apidev/v1/clients

PermisoAPICLI_CLIENTS_READ

Límite de solicitudes10 solicitudes/min

Caché60s

Parámetros de consulta

Parámetro	Tipo	Requerido	Por defecto	Descripción
status	string	No	—	Filtra por estado. Longitud máxima 10.
search	string	No	—	Búsqueda de texto libre. Longitud máxima 120.
limit	integer	No	25	Cantidad de registros por página (1–100). Un valor fuera de ese rango devuelve 400 VALIDATION_ERROR: no se ajusta en silencio.
offset	integer	No	0	Cantidad de registros a omitir para la paginación.

Campos de la respuesta

Campo	Tipo	Descripción
id	string	Identificador del cliente.
name	string | null	Nombre del cliente.
business_name	string | null	Razón social.
email	string | null	Dirección de correo electrónico.
phone	string | null	Número de teléfono.
image_url	string | null	URL de la imagen.
status	string | null	Estado del cliente.
document	string | null	Número de documento.
tax_id	string | null	Número de identificación fiscal.
external_code	string | null	Código del sistema externo.
associated_accounts	number | null	Cantidad de cuentas vinculadas.

Ejemplos de código

cURL

curl -s -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/clients?status=A&search=regional&limit=10"

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/clients?status=A&search=regional&limit=10`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': apiKey,
      'tenant': TENANT,
    },
  }
);
const { data, meta } = await res.json();

Python

import requests

response = requests.get(
    f"https://{TENANT}/apidev/v1/clients",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
    params={"status": "A", "search": "regional", "limit": 10},
)
data = response.json()

Respuesta de ejemplo

{
  "success": true,
  "data": [
    {
      "id": "982710394857200005",
      "name": "Regional Distributors",
      "business_name": "Regional Distributors S.A.",
      "email": "info@regionaldist.com",
      "phone": "+59821009876",
      "image_url": null,
      "status": "A",
      "document": null,
      "tax_id": "219900005018",
      "external_code": null,
      "associated_accounts": 12
    }
  ],
  "meta": {
    "total": 23,
    "limit": 10,
    "offset": 0
  }
}

---

Detalle del cliente

GET/apidev/v1/clients/{id}

PermisoAPICLI_CLIENTS_READ

Límite de solicitudes10 solicitudes/min

Caché30s

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
id	string	Sí	Identificador único del cliente.

Campos adicionales de la respuesta

Devuelve todos los campos del endpoint de Listado, más:

Campo	Tipo	Descripción
mobile	string | null	Teléfono móvil.
notes	string | null	Notas de texto libre.
document_type	number | null	Identificador del tipo de documento.
address	object	Anidado: street, door_number, apartment, corner, zip_code, latitude, longitude. latitude / longitude viajan como texto decimal (o null), nunca como número JSON, así no se pierden decimales.
country_id	string | null	ID del país.
department_id	string | null	ID del departamento.
accounts	array	Objetos de cuenta asociados con id, name, external_code, status.

Ejemplos de código

cURL

curl -s -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/clients/982710394857200005"

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/clients/982710394857200005`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': apiKey,
      'tenant': TENANT,
    },
  }
);
const { data } = await res.json();

Python

import requests

response = requests.get(
    f"https://{TENANT}/apidev/v1/clients/982710394857200005",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
)
data = response.json()

Respuesta de ejemplo

{
  "success": true,
  "data": {
    "id": "982710394857200005",
    "name": "Regional Distributors",
    "business_name": "Regional Distributors S.A.",
    "email": "info@regionaldist.com",
    "phone": "+59821009876",
    "mobile": "+59899876543",
    "image_url": null,
    "status": "A",
    "document": null,
    "tax_id": "219900005018",
    "external_code": null,
    "notes": null,
    "document_type": null,
    "address": {
      "street": "Bvar. Artigas",
      "door_number": "567",
      "apartment": null,
      "corner": "21 de Setiembre",
      "zip_code": null,
      "latitude": "-34.9103",
      "longitude": "-56.1708"
    },
    "country_id": "1",
    "department_id": "10",
    "associated_accounts": 3,
    "accounts": [
      {
        "id": "982710394857201664",
        "name": "Acme Corp",
        "external_code": "EXT-001",
        "status": "A"
      },
      {
        "id": "982710394857201665",
        "name": "Beta Industries",
        "external_code": null,
        "status": "A"
      },
      {
        "id": "982710394857201666",
        "name": "Gamma Solutions",
        "external_code": "EXT-003",
        "status": "I"
      }
    ]
  },
  "meta": {}
}

---

Errores

Código	HTTP	Descripción
VALIDATION_ERROR	400	Parámetros inválidos.
UNAUTHORIZED	401	tenant / Authorization / X-API-Key ausente, inválido o expirado
FORBIDDEN	403	El usuario no tiene el permiso requerido.
NOT_FOUND	404	Recurso no encontrado (endpoint de detalle).
RATE_LIMITED	429	Se superaron 10 solicitudes/min.
INTERNAL_ERROR	500	Error inesperado del servidor.

---

Relacionado

• Autenticación
• Crear y Actualizar Clientes
• API de Cuentas
• Paginación
• Límites de solicitudes
• Manejo de errores