Consultas e informes

Listar clientes

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.

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 POST 'https://api.afer.pro/listarClientes' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: afer_tk_TU_TOKEN' \
  -H 'X-API-SECRET: afer_sk_TU_SECRET' \
  -d '{
    "busqueda": "ferrer",
    "pagina": 1,
    "por_pagina": 100
}'

<?php

$data = [
  'busqueda' => 'ferrer',
  'pagina' => 1,
  'por_pagina' => 100,
];

$ch = curl_init('https://api.afer.pro/listarClientes');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    '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/listarClientes', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'afer_tk_TU_TOKEN',
    'X-API-SECRET': 'afer_sk_TU_SECRET'
  },
  body: JSON.stringify({
      "busqueda": "ferrer",
      "pagina": 1,
      "por_pagina": 100
  })
});

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.

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"
            }
        ]
    }
}

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.