Negocio recurrente

Renovaciones de recurrentes

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

Calcula las renovaciones de los servicios recurrentes en un rango de fechas: cuántas veces renueva cada uno, en qué fechas y por qué importe.

Responde a la pregunta "¿qué renueva entre estas dos fechas y cuánto suma?". Cada periodicidad renueva las veces que le tocan dentro del rango: un mensual en un trimestre cuenta 3 renovaciones, un anual 1 o 0 según caiga su aniversario.

Los ciclos se calculan con el mismo criterio que el listado de recurrentes de Afer:

— El ciclo se ancla en la última facturación del recurrente (o en su inicio de vigencia si nunca facturó).
— Las periodicidades de 30 días o más avanzan por meses de calendario (mensual 1, bimensual 2, trimestral 3, semestral 6, anual 12); semanal y quincenal por bloques de 7/14 días.
— Los no anuales solo renuevan en sus meses activos, y siempre dentro de la vigencia (inicio/caducidad) del servicio.

Además de la previsión, la respuesta incluye las renovaciones ya generadas en el rango: los albaranes facturables emitidos desde cada recurrente. Con rangos pasados te dice lo que realmente se facturó; con rangos futuros, lo que tocará renovar.

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 rango (`YYYY-MM-DD`), incluido.
`fecha_fin`date obligatorio	Fin del rango (`YYYY-MM-DD`), incluido. Rango máximo: 5 años.

Ejemplo de petición

curl -X POST 'https://api.afer.pro/consultarRecurrentesRenovaciones' \
  -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-04-01",
    "fecha_fin": "2026-06-30"
}'

<?php

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

$ch = curl_init('https://api.afer.pro/consultarRecurrentesRenovaciones');
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/consultarRecurrentesRenovaciones', {
  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-04-01",
      "fecha_fin": "2026-06-30"
  })
});

const resultado = await respuesta.json();

Respuesta

Solo aparecen los recurrentes con actividad en el rango (renovaciones previstas o generadas). importe_por_renovacion es la base sin IVA de un ciclo; renovaciones_previstas.importe_total = número de ciclos × importe. por_periodicidad agrega la previsión por tipo.

200 · application/json

{
    "errorCode": 200,
    "errorMsg": "",
    "data": {
        "fecha_inicio": "2026-04-01",
        "fecha_fin": "2026-06-30",
        "renovaciones_previstas": {
            "num": 4,
            "importe_total": 1500
        },
        "renovaciones_generadas": {
            "num": 3,
            "importe_total": 300
        },
        "por_periodicidad": {
            "mensual": {
                "periodicidad_dias": 30,
                "previstas_num": 3,
                "previstas_importe": 300
            },
            "anual": {
                "periodicidad_dias": 365,
                "previstas_num": 1,
                "previstas_importe": 1200
            }
        },
        "recurrentes": [
            {
                "recurrenteId": "aBc123XyZ…",
                "descripcion": "Cuota mantenimiento web",
                "periodicidad": "mensual",
                "periodicidad_dias": 30,
                "importe_por_renovacion": 100,
                "cliente": {
                    "clienteId": "dEf456…",
                    "nombre_fiscal": "FERRER INTERIORS SL"
                },
                "renovaciones_previstas": {
                    "num": 3,
                    "fechas": [
                        "2026-04-15",
                        "2026-05-15",
                        "2026-06-15"
                    ],
                    "importe_total": 300
                },
                "renovaciones_generadas": {
                    "num": 3,
                    "importe_total": 300
                }
            },
            {
                "recurrenteId": "gHi789…",
                "descripcion": "Mantenimiento anual instalación",
                "periodicidad": "anual",
                "periodicidad_dias": 365,
                "importe_por_renovacion": 1200,
                "cliente": {
                    "clienteId": "jKl012…",
                    "nombre_fiscal": "TALLERES MARTORELL SL"
                },
                "renovaciones_previstas": {
                    "num": 1,
                    "fechas": [
                        "2026-05-01"
                    ],
                    "importe_total": 1200
                },
                "renovaciones_generadas": {
                    "num": 0,
                    "importe_total": 0
                }
            }
        ]
    }
}

Errores

Caso	Resultado
Sin credenciales de API key	`errorCode` 401, `errorMsg` "Error on service call: API key authentication required".
Fechas ausentes, mal formadas o `fecha_fin` anterior a `fecha_inicio`	`errorCode` 400 indicando el motivo.
Rango mayor de 5 años	`errorCode` 400, "El rango máximo es de 5 años".

Notas

La previsión es teórica según periodicidad, meses activos y vigencia; renovaciones_generadas refleja lo realmente emitido. En rangos pasados, comparar ambas señala renovaciones pendientes de facturar.
Los importes son base imponible sin IVA, el mismo criterio que consultarVentas.