Ventas por taxonomía
https://api.afer.pro/api/v1/reports/sales-by-taxonomy
POST https://api.afer.pro/consultarVentasPorTaxonomia
Las ventas miradas por taxonomía de producto: total, desglose, serie por meses y productos más vendidos, en una sola llamada.
Pensado para pintar un cuadro de mando de un cliente sin encadenar cinco llamadas. Devuelve a la vez:
total_ventasynum_documentosdel periodo,por_taxonomia: el desglose, con el porcentaje sobre el total,por_mes: la serie temporal,top_productos: los que más venden, con sus unidades,por_cliente: quién compra más (solo si no fijas un cliente).
Sin fechas, los últimos doce meses.
Los importes son base imponible, sin IVA, con el mismo criterio que el panel: albaranes facturables más facturas directas, nunca de serie proforma, sumando líneas y descartando suplidos, líneas de porcentaje sobre la base y líneas de control.
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.
fecha_iniciostringopcional | Desde esta fecha (YYYY-MM-DD). Por defecto, un año antes de fecha_fin. |
fecha_finstringopcional | Hasta esta fecha (YYYY-MM-DD). Por defecto hoy. |
clienteIdstring|integeropcional | Solo las ventas de este cliente. |
tipostring|integeropcional | Desglosar por los términos de este tipo de taxonomía (marca, categoría). Sin él, por todas. |
taxonomiaIdstring|integeropcional | Solo lo vendido de productos con esta taxonomía. |
familiaIdstring|integeropcional | Solo lo vendido de productos de esta familia. |
Ejemplo de petición
curl -X GET 'https://api.afer.pro/api/v1/reports/sales-by-taxonomy?clienteId=xYz987%E2%80%A6&tipo=marca' \
-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/reports/sales-by-taxonomy?clienteId=xYz987%E2%80%A6&tipo=marca');
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/reports/sales-by-taxonomy?clienteId=xYz987%E2%80%A6&tipo=marca', {
method: 'GET',
headers: {
'X-API-KEY': 'afer_tk_TU_TOKEN',
'X-API-SECRET': 'afer_sk_TU_SECRET'
}
});
const resultado = await respuesta.json();
Respuesta
{
"errorCode": 200,
"errorMsg": "",
"data": {
"periodo": {
"desde": "2025-10-16",
"hasta": "2026-10-15"
},
"total_ventas": 48250.75,
"num_documentos": 96,
"moneda": "EUR",
"por_taxonomia": [
{
"taxonomiaId": "aBc123…",
"titulo": "Bosch",
"tipo": "Marca",
"total": 31100,
"porcentaje": 64.5
},
{
"taxonomiaId": "dEf456…",
"titulo": "Makita",
"tipo": "Marca",
"total": 17150.75,
"porcentaje": 35.5
}
],
"por_mes": [
{
"mes": "2025-11",
"total": 3980.2
},
{
"mes": "2025-12",
"total": 4410
}
],
"top_productos": [
{
"articuloId": "gHi789…",
"descripcion": "Taladro percutor 750W",
"total": 8990,
"unidades": 100
}
]
}
}
- El desglose puede pasarse del total: un producto con dos marcas cuenta en las dos. El total bueno es
total_ventas, que se calcula aparte. La respuesta lo recuerda enaviso_desglose. - El desglose trae como mucho 50 taxonomías, 20 clientes y 20 productos, siempre los de más importe.
- Para el total de ventas sin mirar producto, usa consultarVentas.