Cuentas — Listado y Detalle

Consulta cuentas de clientes con filtrado, y obtené perfiles completos de cuenta con productos y campos dinámicos.

---

Listar cuentas

GET/apidev/v1/accounts

PermisoAPICLI_ACCOUNTS_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.
client_id	string	No	—	Filtra por ID de cliente. Longitud máxima 30.
provider_id	string	No	—	Filtra por ID de proveedor. Longitud máxima 30.
country_id	string	No	—	Filtra por ID de país. Longitud máxima 30.
department_id	string	No	—	Filtra por ID de departamento. Longitud máxima 30.
city_id	string	No	—	Filtra por ID de ciudad. Longitud máxima 30.
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 de la cuenta.
external_code	string | null	Código del sistema externo.
name	string | null	Nombre de la cuenta.
business_name	string | null	Razón social.
tax_id	string | null	Número de identificación fiscal.
document	string | null	Número de documento.
phone	string | null	Número de teléfono.
mobile	string | null	Teléfono móvil.
email	string | null	Dirección de correo electrónico.
image_url	string | null	URL de la imagen.
status	string | null	Estado de la cuenta.
service_time_min	number | null	Tiempo de servicio en el lugar por defecto para esta cuenta, en minutos (lo usa el planificador).
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.
notes	string | null	Notas de texto libre.
start_date	string | null	Fecha de inicio, YYYY-MM-DD.
end_date	string | null	Fecha de fin, YYYY-MM-DD.
birth_date	string | null	Fecha de nacimiento, YYYY-MM-DD. Si la cuenta no tiene fecha cargada llega null (las fechas vacías heredadas del sistema anterior, tipo 0001-01-01, se normalizan).
client_name	string | null	Nombre del cliente asociado.
country_name	string | null	Nombre del país.
department_name	string | null	Nombre del departamento.
city_name	string | null	Nombre de la ciudad.

Ejemplos de código

cURL

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

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/accounts?status=A&search=acme&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/accounts",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
    params={"status": "A", "search": "acme", "limit": 10},
)
data = response.json()

Respuesta de ejemplo

{
  "success": true,
  "data": [
    {
      "id": "982710394857201664",
      "external_code": "EXT-001",
      "name": "Acme Corp",
      "business_name": "Acme Corporation S.A.",
      "tax_id": "214100001019",
      "document": null,
      "phone": "+59821234567",
      "mobile": "+59899123456",
      "email": "contact@acme.com",
      "image_url": null,
      "status": "A",
      "service_time_min": 15,
      "address": {
        "street": "Av. Rivera",
        "door_number": "1234",
        "apartment": "Of. 301",
        "corner": "Soca",
        "zip_code": "11300",
        "latitude": "-34.9011",
        "longitude": "-56.1645"
      },
      "notes": "Premium customer",
      "start_date": "2024-01-15",
      "end_date": null,
      "birth_date": null,
      "client_name": "Regional Distributors",
      "country_name": "Uruguay",
      "department_name": "Montevideo",
      "city_name": "Montevideo"
    }
  ],
  "meta": {
    "total": 87,
    "limit": 10,
    "offset": 0
  }
}

---

Detalle de cuenta

GET/apidev/v1/accounts/{id}

PermisoAPICLI_ACCOUNTS_READ

Límite de solicitudes10 solicitudes/min

Caché30s

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
id	string	Sí	Identificador único de la cuenta.

Campos adicionales de la respuesta

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

Campo	Tipo	Descripción
client_id	string | null	ID del cliente asociado.
country_id	string | null	ID del país.
department_id	string | null	ID del departamento.
city_id	string | null	ID de la ciudad.
products	array	Productos asociados a la cuenta.
dynamic_fields	array	Campos dinámicos personalizados configurados para el tenant.

Ejemplos de código

cURL

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

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/accounts/982710394857201664`,
  {
    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/accounts/982710394857201664",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
)
data = response.json()

Respuesta de ejemplo

{
  "success": true,
  "data": {
    "id": "982710394857201664",
    "external_code": "EXT-001",
    "name": "Acme Corp",
    "business_name": "Acme Corporation S.A.",
    "tax_id": "214100001019",
    "document": null,
    "phone": "+59821234567",
    "mobile": "+59899123456",
    "email": "contact@acme.com",
    "image_url": null,
    "status": "A",
    "service_time_min": 15,
    "address": {
      "street": "Av. Rivera",
      "door_number": "1234",
      "apartment": "Of. 301",
      "corner": "Soca",
      "zip_code": "11300",
      "latitude": "-34.9011",
      "longitude": "-56.1645"
    },
    "notes": "Premium customer",
    "start_date": "2024-01-15",
    "end_date": null,
    "birth_date": null,
    "client_id": "982710394857200005",
    "client_name": "Regional Distributors",
    "country_id": "1",
    "country_name": "Uruguay",
    "department_id": "10",
    "department_name": "Montevideo",
    "city_id": "100",
    "city_name": "Montevideo",
    "products": [
      {
        "id": "982710394857201700",
        "provider_id": "982710394857200030",
        "provider_name": "National Insurance Co.",
        "product_type_id": "8",
        "product_type_name": "Vehicle Insurance",
        "coverage_id": "12",
        "coverage_name": "Full Coverage",
        "start_date": "2025-01-01",
        "end_date": "2026-12-31",
        "status": "A"
      }
    ],
    "dynamic_fields": [
      {
        "field_id": "10",
        "name": "Customer Tier",
        "type": "lista",
        "order": 1,
        "value": "Premium"
      },
      {
        "field_id": "11",
        "name": "Contract Signed",
        "type": "boolean",
        "order": 2,
        "value": true
      }
    ]
  },
  "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 Cuentas
• API de Clientes
• Paginación
• Límites de solicitudes
• Manejo de errores