API de socios

Si tienes un sistema con muchos clientes propios (un ERP, un POS, una app de reservas), la API de socios te deja darlos de alta como empresas de Sistema Facturación Perú y emitir sus comprobantes con la API v1 de cada una. Tus clientes no tienen que contratar nada: tú pagas por lo que emiten, con bolsas prepago.

1. Das de alta a tu cliente con POST /empresas (RUC, razón social, administrador y, si quieres, certificado y usuario SOL).
2. Creas una clave v1 para esa empresa con POST /empresas/{id}/claves.
3. Emites con esa clave en https://<subdominio>.sistemafacturacionperu.com/api/v1, igual que en la API v1.

• Base: https://api.sistemafacturacionperu.com/socios/v1 (siempre este host, nunca el subdominio de una empresa).
• Formato: el mismo de la API v1 ({"success": true, "data": …} o {"success": false, "code": …, "message": …}).

Precios

Pagas por adelantado con bolsas de comprobantes, para todas tus empresas juntas. Precios con IGV incluido:

Más una cuota de S/ 9 al mes con IGV por cada empresa activa: la que emitió al menos un comprobante en el mes, por cualquier vía. Cubre lo que no es el envío a SUNAT: la base de datos de cada empresa, guardar sus XML, PDF y constancias los años que pide SUNAT, el servidor y el soporte.

• Cada bolsa vale 6 meses desde la compra. Si emites más, compras varias: no hay bolsas más grandes.
• Se consume primero la bolsa que vence antes.
• La compra de bolsas se coordina con nosotros (transferencia o Yape) y la registramos en el momento. Por ahora no hay pago en línea de bolsas.

Qué descuenta de la bolsa

Descuenta 1 todo lo que sale por nuestro PSE:

• cada factura, boleta, nota de crédito, nota de débito, retención, percepción y liquidación de compra;
• cada resumen diario de boletas;
• cada baja (comunicación de baja o resumen de anulación);
• cada guía de remisión.

Se descuenta una sola vez por documento, aunque se reintente el envío. En el entorno de pruebas de SUNAT no se descuenta nada.

Si la empresa envía directo a SUNAT con su propio usuario SOL (mandaste certificado y sol en el alta), no descuenta nada de tu bolsa: esa empresa solo paga la cuota de S/ 9 los meses en que emite.

Sin saldo

• Antes de crear un comprobante o una guía de una empresa que envía por nuestro PSE, si tu saldo es 0, su API v1 responde 402 saldo_agotado y no se crea nada (tampoco desde la web de esa empresa). Lo ya emitido no se toca.
• Los resúmenes y las bajas de lo ya emitido sí se envían sin saldo (dejar boletas sin informar sería peor): se descuentan igual y el negativo sale de tu siguiente recarga.
• Te avisamos al usar el 80 % y el 95 % de tus bolsas vigentes (saldo.bajo) y al llegar a 0 (saldo.agotado), por webhook y por correo.
• La cuota mensual se calcula el día 1 y vence a los 10 días. Vencida e impaga, tus empresas no emiten por API (402 cuota_pendiente); su web sigue funcionando. Al pagarla, vuelven al instante.

GET /saldo te da el saldo, tus bolsas, el próximo vencimiento, las cuotas pendientes y los precios; GET /movimientos los consumos y las recargas, filtrables por tipo, empresa_id, desde y hasta.

1. Pide un token

Te damos una credencial: client_id (sfp_partner_…) y client_secret (sfp_secret_…, se muestra una vez). El token dura 1 hora: pide otro cuando venza (401 token_vencido).

curl -s https://api.sistemafacturacionperu.com/socios/v1/token \
  -u "$SFP_CLIENT_ID:$SFP_CLIENT_SECRET" \
  -d grant_type=client_credentials

<?php
$ch = curl_init('https://api.sistemafacturacionperu.com/socios/v1/token');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('SFP_CLIENT_ID') . ':' . getenv('SFP_CLIENT_SECRET'),
    CURLOPT_POSTFIELDS => http_build_query(['grant_type' => 'client_credentials']),
]);
$token = json_decode(curl_exec($ch), true)['access_token'];

const basic = Buffer.from(`${process.env.SFP_CLIENT_ID}:${process.env.SFP_CLIENT_SECRET}`).toString('base64');
const res = await fetch('https://api.sistemafacturacionperu.com/socios/v1/token', {
  method: 'POST',
  headers: { Authorization: `Basic ${basic}`, 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({ grant_type: 'client_credentials' }),
});
const { access_token: token } = await res.json();

r = requests.post(
    "https://api.sistemafacturacionperu.com/socios/v1/token",
    auth=(os.environ["SFP_CLIENT_ID"], os.environ["SFP_CLIENT_SECRET"]),
    data={"grant_type": "client_credentials"},
    timeout=30,
)
token = r.json()["access_token"]

{ "success": true, "access_token": "sfp_pat_Q1w2…", "token_type": "Bearer", "expires_in": 3600, "expires_at": "2026-11-04T15:04:05-05:00" }

2. Da de alta a tu cliente

curl -s https://api.sistemafacturacionperu.com/socios/v1/empresas \
  -H "Authorization: Bearer $SFP_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: alta-20601030013" \
  -d '{
    "ruc": "20601030013",
    "razon_social": "FERRETERIA EL TORNILLO S.A.C.",
    "nombre_comercial": "El Tornillo",
    "direccion": { "direccion": "Av. Grau 123, Lima", "ubigeo": "150101" },
    "administrador": { "nombre": "Ana Quispe", "correo": "ana@tornillo.pe", "celular": "987654321" },
    "certificado": { "pfx_base64": "MIIK…", "clave": "clave-del-pfx" },
    "sol": { "usuario": "FACTURAS1", "clave": "clave-sol" }
  }'

Responde 201 al instante con "estado": "creando"; la empresa queda lista en 1 a 3 minutos (es la misma alta de la compra en la web). Consulta GET /empresas/{id} o espera el webhook empresa.lista.

• Sin administrador.contrasena, el administrador recibe el correo de bienvenida para crear la suya.
• Sin subdominio, lo armamos del nombre (el-tornillo).
• Con certificado y sol, la empresa envía directo a SUNAT con su SOL (no descuenta de tu bolsa). Sin ellos, o con "envio": "pse", envía por nuestro PSE, que activamos nosotros.
• Usa una Idempotency-Key como alta-<ruc>: si la red falla, el reintento no crea la empresa dos veces.
• Si el RUC ya tiene cuenta, responde 409 ruc_ya_registrado (sin decir de quién). Si es tu cliente, pídele que nos escriba para pasarla a tu cuenta de socio.

El estado de la empresa

pendientes dice qué falta: ficha_ruc (como toda empresa nueva, emite cuando su Ficha RUC queda verificada: el administrador la sube en Configuración › Empresa › Régimen tributario), produccion, certificado, usuario_sol o credenciales_pse (lo activamos nosotros).

3. Crea su clave v1 y emite

curl -s https://api.sistemafacturacionperu.com/socios/v1/empresas/15/claves \
  -H "Authorization: Bearer $SFP_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nombre": "Mi sistema · producción", "establecimiento": "0000"}'

{
  "success": true,
  "data": {
    "id": 3,
    "nombre": "Mi sistema · producción",
    "permisos": ["comprobantes.emitir", "comprobantes.leer", "comprobantes.anular", "guias.emitir", "guias.leer", "catalogo.leer", "catalogo.escribir", "consultas", "webhooks.gestionar"],
    "clave": "sfp_live_Ab12…",
    "api_v1": "https://el-tornillo.sistemafacturacionperu.com/api/v1",
    "aviso": "Guarda la clave ahora…"
  }
}

La clave se muestra una vez. Sin permisos, trae los de emitir y consultar. Con ella emites en api_v1 todo lo de la API v1: comprobantes, guías, notas, anulaciones, consultas y webhooks de esa empresa.

Más operaciones

Mientras una empresa está pausada, su API v1 responde 423 suspendida_por_socio al emitir; consultar sigue funcionando y su web no cambia.

Lo que un socio no puede: ver empresas que no son suyas (responden 404), bloquearlas por cobranza, cambiar su plan, entrar como su administrador ni usar el acceso de soporte. Eso es solo de la plataforma.

La empresa de un socio tiene emitir y consultar, no el ERP completo. Si tu cliente quiere el sistema completo (POS, inventario, compras, tienda), se pasa a un plan normal.

Webhooks del socio

curl -s https://api.sistemafacturacionperu.com/socios/v1/webhooks \
  -H "Authorization: Bearer $SFP_PARTNER_TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "https://tusistema.pe/webhooks/sfp", "eventos": ["empresa.lista", "saldo.bajo", "saldo.agotado", "cuota.vencida"]}'

Se firman y se reintentan igual que los webhooks de la API v1, y el cuerpo trae además socio_id.

Seguridad y límites

• El secreto y los tokens se guardan solo como hash. Para rotar sin corte te damos una segunda credencial, la cambias y revocamos la vieja. Una credencial puede limitarse a tus IP (403 ip_no_permitida desde otra).
• 120 llamadas por minuto por token y 10 intentos de token por minuto por IP y por client_id.
• Idempotency-Key en todo POST y PATCH; se recuerda 24 horas.

¿Tus clientes ya tienen cuenta en Sistema Facturación Perú? Entonces no los des de alta: conéctalos con un botón, con Conectar con Sistema Facturación Perú. Seguramente necesites las dos.