# Novedades de la API

Lo que cambia en la API v1 de las empresas, la API de socios y la conexión con un botón, con lo más nuevo primero.

<!--
  Para quien lo edita: este archivo se publica tal cual en el portal para desarrolladores
  (https://sistemafacturacionperu.com/desarrolladores/novedades/) con php artisan api:docs:publicar.
  Cada entrada: «## AAAA-MM-DD · Título», un párrafo corto y la lista de cambios; la más nueva primero.
  Solo lo que ya está en producción. En el texto visible, el nombre completo «Sistema Facturación Perú» (nunca «SFP»).
-->

Las versiones y las reglas de compatibilidad están en
[Límites, idempotencia, paginación y versiones](https://sistemafacturacionperu.com/desarrolladores/limites-y-versiones/).

## 2026-11-04 · Conectar con Sistema Facturación Perú

Tu sistema puede conectar la cuenta que tu cliente **ya tiene** en Sistema Facturación Perú con un botón, sin pedirle
claves ni ver su contraseña.

- OAuth 2.0 con *authorization code* y PKCE S256 obligatorio: `GET https://api.sistemafacturacionperu.com/conectar`,
  `POST /oauth/token` y `POST /oauth/revoke` (RFC 6749, 7636, 7009 y 9207).
- El token de acceso (`sfp_oat_`) dura 1 hora y solo vale en la API v1 de esa empresa (`empresa.api_url`); el de
  renovación (`sfp_ort_`) cambia en cada uso.
- En el Plan Básico la conexión sirve para emitir (facturas, boletas, notas y guías, su estado y archivos, anular y
  consultar RUC y DNI) dentro de sus 300 comprobantes; lo demás responde 403 `plan_insuficiente`. En PRO y Empresa, todo.
- Aviso firmado `conexion.revocada` cuando la empresa pulsa «Desconectar».

## 2026-11-04 · API de socios v1

Para programadores y empresas de software con muchos clientes propios: das de alta a tus clientes como empresas de
Sistema Facturación Perú y emites con la API v1 de cada una.

- Base `https://api.sistemafacturacionperu.com/socios/v1`, con token OAuth 2 *client_credentials* (`sfp_pat_`, 1 hora).
- Alta de empresas (`POST /empresas`), su estado, uso del mes, pausa y reactivación, y claves v1 por empresa.
- Bolsas prepago con IGV y 6 meses de validez: 3.300 = S/ 180, 5.500 = S/ 285 y 10.000 = S/ 480. Cuota de S/ 9 al
  mes con IGV por empresa que emitió. Lo que la empresa envía con su propio usuario SOL no descuenta de la bolsa.
- Sin saldo, la API v1 de la empresa responde 402 `saldo_agotado`; con una cuota vencida, 402 `cuota_pendiente`.
- Webhooks del socio: `empresa.lista`, `saldo.bajo`, `saldo.agotado`, `cuota.vencida` y más.
- La API antigua de reseller (`api/reseller/*`) se retiró: responde 410 `api_retirada`.

## 2026-11-04 · API v1 de las empresas

Una API nueva, en español y con el mismo formato en todo: `https://<tu-subdominio>.sistemafacturacionperu.com/api/v1`.
La API antigua (`/api/documents`, `/api/dispatches`…) sigue funcionando igual.

- Comprobantes (factura, boleta, notas de crédito y de débito): emitir, listar, buscar por serie y número, descargar
  PDF, XML y CDR, anular (el sistema elige baja o resumen), reenviar a SUNAT, enviar por correo o por el WhatsApp de la
  empresa y registrar cobros.
- Guías de remisión remitente (09) y transportista (31) en una sola llamada; retenciones, percepciones, liquidaciones
  de compra, notas de venta y cotizaciones.
- Clientes, productos, stock por almacén, lote y serie, y locales con sus series.
- Consultas de RUC, DNI y tipo de cambio.
- Claves `sfp_live_` y `sfp_test_` con alcances, vencimiento y registro de llamadas de 30 días.
- Modo pruebas en `https://pruebas.sistemafacturacionperu.com/api/v1`, contra la beta de SUNAT, sin tocar tus
  comprobantes ni tus correlativos.
- `Idempotency-Key` en todo `POST` y `PUT`: un reintento no emite dos veces.
- Errores con `code` estable y mensaje en español; webhooks firmados (`X-SFP-Signature: t=…,v1=…`) cuando SUNAT acepta,
  observa o rechaza.
- Límites: 120 llamadas por minuto por clave y 30 emisiones por minuto.

## 2026-11-03 · API antigua: límites con 429

- Pasarse del límite de llamadas responde 429 con `Retry-After` (antes podía responder 500), contado por clave de API
  o por la IP real.
- Los errores ya no muestran rutas ni líneas del servidor.