Consultas e informes

Ventas del período

POST https://api.afer.pro/consultarVentas

Devuelve las ventas entre dos fechas (albaranes + facturas directas), separando cuánto proviene de servicios recurrentes.

La cifra de ventas de tu cuenta con el mismo criterio que el panel de facturación de Afer:

— Albaranes con fecha en el rango, solo los facturables (o marcados como facturables en el futuro).
— Facturas directas con fecha en el rango: las que no provienen de albaranes (para no contar dos veces) y cuya serie no es proforma.
— Importes sin IVA, calculados desde las líneas: cantidad × importe_unitario × (1 − descuento/100).

Además, la respuesta separa la parte recurrente: los albaranes generados desde un servicio recurrente (cuotas, mantenimientos, suscripciones).

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_inicio`date obligatorio	Inicio del período (`YYYY-MM-DD`), incluido.
`fecha_fin`date obligatorio	Fin del período (`YYYY-MM-DD`), incluido.
`agrupar`string opcional	Añade a la respuesta el desglose para gráficos: `"mes"` (serie mensual), `"familia"` (por familia de artículo) o `"cliente"` (top 25 clientes por ventas).

Ejemplo de petición

curl -X POST 'https://api.afer.pro/consultarVentas' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: afer_tk_TU_TOKEN' \
  -H 'X-API-SECRET: afer_sk_TU_SECRET' \
  -d '{
    "fecha_inicio": "2026-01-01",
    "fecha_fin": "2026-06-30",
    "agrupar": "mes"
}'

<?php

$data = [
  'fecha_inicio' => '2026-01-01',
  'fecha_fin' => '2026-06-30',
  'agrupar' => 'mes',
];

$ch = curl_init('https://api.afer.pro/consultarVentas');
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/consultarVentas', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'afer_tk_TU_TOKEN',
    'X-API-SECRET': 'afer_sk_TU_SECRET'
  },
  body: JSON.stringify({
      "fecha_inicio": "2026-01-01",
      "fecha_fin": "2026-06-30",
      "agrupar": "mes"
  })
});

const resultado = await respuesta.json();

Respuesta

total_ventas = albaranes + facturas directas. ventas_recurrentes es la parte de ese total que proviene de servicios recurrentes, y ventas_no_recurrentes la diferencia. El desglose incluye el número de documentos de cada bloque.

200 · application/json

{
    "errorCode": 200,
    "errorMsg": "",
    "data": {
        "fecha_inicio": "2026-01-01",
        "fecha_fin": "2026-06-30",
        "total_ventas": 184230.55,
        "ventas_recurrentes": 42600,
        "ventas_no_recurrentes": 141630.55,
        "desglose": {
            "albaranes": {
                "total": 121480.3,
                "num_documentos": 342
            },
            "facturas_directas": {
                "total": 62750.25,
                "num_documentos": 96
            },
            "albaranes_recurrentes": {
                "total": 42600,
                "num_documentos": 127
            }
        },
        "agrupacion": {
            "por": "mes",
            "grupos": [
                {
                    "periodo": "2026-01",
                    "total": 28450.1
                },
                {
                    "periodo": "2026-02",
                    "total": 31200.45
                }
            ]
        }
    }
}

Errores

Caso	Resultado
Sin credenciales de API key	`errorCode` 401, `errorMsg` "Error on service call: API key authentication required".
`fecha_inicio` o `fecha_fin` ausentes o mal formadas	`errorCode` 400 indicando el parámetro.

Notas

Los importes son base imponible sin IVA, el mismo criterio que las tarjetas del panel de facturación de Afer.
Las facturas rectificativas (abonos) restan de forma natural, porque sus líneas son negativas.