Crear recurrente
https://api.afer.pro/api/v1/recurring-invoices
POST https://api.afer.pro/crearRecurrente
Crea una plantilla de facturación recurrente para un cliente (mensual, trimestral, anual…): una suscripción que Afer facturará automáticamente.
Da de alta una facturación recurrente con la periodicidad que indiques en pedido.periodicidad (semanal, quincenal, mensual, bimensual, trimestral, semestral o anual) y desde pedido.fecha_inicio. Sin ellas, anual (365 días) y desde hoy. El cliente se resuelve por CIF como en el resto de endpoints de venta.
Si una línea referencia un artículo (articulo_fk) y no envías importe_unitario, la línea toma automáticamente el PVP, el IVA y la descripción del artículo del catálogo — ideal para suscripciones a productos con tarifa mantenida en Afer.
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 →
Parámetros del cuerpo
El cuerpo de la petición es un objeto JSON con Content-Type: application/json.
clienteobjectobligatorio | Cliente de facturación. Mismos campos que en crearFactura; deduplicación por CIF. |
pedidoobjectobligatorio | Cabecera de la recurrencia. |
comisionistaIdstringopcional | Comisionista interno (listarComisionistas). Por defecto el de la ficha del cliente; 0 = ninguno. |
comisionistaExternoIdstringopcional | Comisionista externo, el colaborador de fuera que acompaña la operación. Por defecto el de la ficha del cliente; 0 = ninguno. |
obrastringobligatorio | Descripción de la recurrencia (p. ej. "Suscripción anual Plan Pro"). |
periodicidadint|stringopcional | Cada cuánto se factura, en días o en palabra: 7 semanal, 14 quincenal, 30 mensual, 60 bimensual, 90 trimestral, 180 semestral o 365 anual. Por defecto 365. Otro valor devuelve 400. |
fecha_iniciodateopcional | Desde cuándo factura (YYYY-MM-DD). Por defecto, hoy. |
detallesarrayobligatorio | Líneas de la recurrencia. |
cantidadnumberobligatorio | Unidades. |
articulo_fkintopcional | Artículo del catálogo. Si se envía sin importe_unitario, la línea hereda PVP, IVA y descripción del artículo. |
descripcionstringopcional | Descripción de la línea. Obligatoria si no hay artículo. |
importe_unitarionumberopcional | Precio unitario sin IVA. Si se omite, se toma del artículo. |
ivanumberopcional | Tipo de IVA. Si se omite, se toma del artículo. |
Ejemplo de petición
curl -X POST 'https://api.afer.pro/api/v1/recurring-invoices' \
-H 'X-API-KEY: afer_tk_TU_TOKEN' \
-H 'X-API-SECRET: afer_sk_TU_SECRET' \
-H 'Content-Type: application/json' \
-d '{
"cliente": {
"nombre_fiscal": "Talleres Martorell SL",
"cif": "B07123456",
"email": "admin@talleresmartorell.com"
},
"pedido": {
"obra": "Suscripción mantenimiento",
"periodicidad": "mensual",
"fecha_inicio": "2026-11-01"
},
"detalles": [
{
"cantidad": 1,
"articulo_fk": 4521
}
]
}'
<?php
$data = [
'cliente' => [
'nombre_fiscal' => 'Talleres Martorell SL',
'cif' => 'B07123456',
'email' => 'admin@talleresmartorell.com',
],
'pedido' => [
'obra' => 'Suscripción mantenimiento',
'periodicidad' => 'mensual',
'fecha_inicio' => '2026-11-01',
],
'detalles' => [
0 => [
'cantidad' => 1,
'articulo_fk' => 4521,
],
],
];
$ch = curl_init('https://api.afer.pro/api/v1/recurring-invoices');
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, [
'X-API-KEY: afer_tk_TU_TOKEN',
'X-API-SECRET: afer_sk_TU_SECRET',
'Content-Type: application/json',
]);
$respuesta = json_decode(curl_exec($ch), true);
curl_close($ch);
const respuesta = await fetch('https://api.afer.pro/api/v1/recurring-invoices', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-KEY': 'afer_tk_TU_TOKEN',
'X-API-SECRET': 'afer_sk_TU_SECRET'
},
body: JSON.stringify({
"cliente": {
"nombre_fiscal": "Talleres Martorell SL",
"cif": "B07123456",
"email": "admin@talleresmartorell.com"
},
"pedido": {
"obra": "Suscripción mantenimiento",
"periodicidad": "mensual",
"fecha_inicio": "2026-11-01"
},
"detalles": [
{
"cantidad": 1,
"articulo_fk": 4521
}
]
})
});
const resultado = await respuesta.json();
Respuesta
Devuelve el identificador cifrado de la recurrente creada.
{
"errorCode": 200,
"errorMsg": "",
"data": "aBc123XyZ456…"
}
- Sin
periodicidad, la recurrente es anual (365 días), como hasta ahora. Se crea con los doce meses activos, así que cuenta en el MRR sea cual sea la periodicidad. - Acepta la cabecera
X-IDEMPOTENCY-KEYcontra dobles clicks y reintentos.