Base URL https://api.afer.pro Referencia aferapp.com Reservar demo

Ventas por taxonomía

GET https://api.afer.pro/api/v1/reports/sales-by-taxonomy
Alias en castellano (v0, sigue operativo): 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_ventas y num_documentos del 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.

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.

fecha_iniciostring
opcional
Desde esta fecha (YYYY-MM-DD). Por defecto, un año antes de fecha_fin.
fecha_finstring
opcional
Hasta esta fecha (YYYY-MM-DD). Por defecto hoy.
clienteIdstring|integer
opcional
Solo las ventas de este cliente.
tipostring|integer
opcional
Desglosar por los términos de este tipo de taxonomía (marca, categoría). Sin él, por todas.
taxonomiaIdstring|integer
opcional
Solo lo vendido de productos con esta taxonomía.
familiaIdstring|integer
opcional
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

200 · application/json
{
    "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
            }
        ]
    }
}
Notas
  • 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 en aviso_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.