Listar clientes

GET https://api.afer.pro/api/v1/customers

Alias en castellano (v0, sigue operativo): POST https://api.afer.pro/listarClientes

Devuelve los clientes de facturación de tu cuenta, paginados y con identificadores cifrados, con buscador y filtro por fecha de alta.

El listado de tu cartera de clientes, pensado para sincronizar catálogos o alimentar selectores en tus aplicaciones. Cada cliente llega con su clienteId cifrado y sus datos fiscales y de contacto.

Si tu cuenta forma parte de un grupo y tiene activada la cartera compartida con la empresa matriz, el listado devuelve los clientes de la matriz (los mismos que ves en Afer); la respuesta lo indica con cartera_compartida_matriz.

Si tu cuenta tiene el portal del cliente configurado, cada cliente incluye su url_portal_cliente: el acceso directo a su área privada con la sesión iniciada. Sin portal configurado, llega null.

Los resultados se ordenan por nombre fiscal y se sirven paginados (100 por página por defecto, máximo 500).

Autenticación

Envía tus claves API en las cabeceras X-API-KEY y X-API-SECRET. La cuenta sobre la que se opera se resuelve automáticamente a partir de la clave. Cómo obtener tus claves →

Este endpoint requiere autenticación con API key: sin credenciales responde 401.

Parámetros del cuerpo

El cuerpo de la petición es un objeto JSON con Content-Type: application/json.

`busqueda`string opcional	Texto libre. Busca en nombre fiscal, nombre comercial, CIF, email, código contable, teléfono y móvil.
`fecha_alta_desde`date opcional	Solo clientes dados de alta a partir de esta fecha (`YYYY-MM-DD`).
`fecha_alta_hasta`date opcional	Solo clientes dados de alta hasta esta fecha (`YYYY-MM-DD`).
`pagina`int opcional	Página a devolver. Por defecto `1`.
`por_pagina`int opcional	Resultados por página. Por defecto `100`, máximo `500`.

Ejemplo de petición

curl -X GET 'https://api.afer.pro/api/v1/customers?busqueda=ferrer&pagina=1&por_pagina=100' \
  -H 'X-API-KEY: afer_tk_TU_TOKEN' \
  -H 'X-API-SECRET: afer_sk_TU_SECRET'

<?php

$ch = curl_init('https://api.afer.pro/api/v1/customers?busqueda=ferrer&pagina=1&por_pagina=100');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: afer_tk_TU_TOKEN',
    'X-API-SECRET: afer_sk_TU_SECRET',
]);

$respuesta = json_decode(curl_exec($ch), true);
curl_close($ch);

const respuesta = await fetch('https://api.afer.pro/api/v1/customers?busqueda=ferrer&pagina=1&por_pagina=100', {
  method: 'GET',
  headers: {
    'X-API-KEY': 'afer_tk_TU_TOKEN',
    'X-API-SECRET': 'afer_sk_TU_SECRET'
  }
});

const resultado = await respuesta.json();

Respuesta

total_clientes es el total de la consulta (todas las páginas). cartera_compartida_matriz indica si el listado proviene de la empresa matriz del grupo.

Cada cliente llega con sus vías de contacto (email, telefono, movil) y sus consentimientos RGPD por canal. Cada permiso tiene tres estados: true consintió, false lo denegó y null nunca se le preguntó — no es un sí ni un no. El detalle, aquí.

200 · application/json

{
    "errorCode": 200,
    "errorMsg": "",
    "data": {
        "total_clientes": 1,
        "pagina": 1,
        "por_pagina": 100,
        "num_paginas": 1,
        "cartera_compartida_matriz": false,
        "clientes": [
            {
                "clienteId": "aBc123XyZ…",
                "nombre_fiscal": "FERRER INTERIORS SL",
                "nombre_comercial": "Ferrer Interiors",
                "cif": "B07123456",
                "codigo_contable": "43000123",
                "email": "admin@ferrerinteriors.com",
                "telefono": "971123456",
                "movil": "+34600111222",
                "direccion": "C/ Major 12",
                "cp": "07001",
                "poblacion": "Palma",
                "provincia": "Illes Balears",
                "pais": "España",
                "fecha_alta": "2024-05-12",
                "tarifa": 1,
                "rgpd": {
                    "comunicaciones_email": true,
                    "comunicaciones_whatsapp": false,
                    "comunicaciones_sms": null,
                    "tratamiento_imagenes": null
                },
                "url_portal_cliente": "https://clientes.aferapp.com/mi-empresa/?loginToken=aBc123XyZ…"
            }
        ]
    }
}

Errores

Caso	Resultado
Sin credenciales de API key	`errorCode` 401, `errorMsg` "Error on service call: API key authentication required".
Fecha con formato inválido	`errorCode` 400 indicando el parámetro.

Notas

El clienteId cifrado es estable: guárdalo para referenciar al cliente en llamadas posteriores.
url_portal_cliente da acceso directo al área privada del cliente con sesión iniciada: entrégala solo a su titular y por un canal privado.