Referencia viva · versión 2026-04-01

La API de cobros recurrentes para SaaS europeo.

Suscripciones, prorrateos, impuestos por país y conciliación bancaria en un solo contrato REST. Una llamada, una respuesta, sin sorpresas en el cierre de mes.

Crear clave de prueba Abrir el probador

EUR · SEPA OSS / IOSS 27 países UE

Demo Punto API es una plataforma ficticia creada como prototipo de diseño. Ninguna llamada de esta página sale del navegador y ningún formulario envía datos a terceros.

Crear una suscripción

Petición

201 Created POST /v1/suscripciones · sandbox

Cabeceras

punto-request-id: req_3Xb9Tk2m
punto-version: 2026-04-01
punto-modo: sandbox
content-type: application/json; charset=utf-8

Cuerpo

{
  "id": "sus_4Rm7Yz",
  "objeto": "suscripcion",
  "cliente": "cli_8Kq2Nv",
  "plan": "plan_escala_mensual",
  "estado": "en_prueba",
  "moneda": "EUR",
  "periodo_actual_fin": "2026-09-19T00:00:00Z",
  "impuesto": { "regimen": "oss_ue", "tipo": 0.21, "pais": "ES" },
  "importe_periodo": 24000
}

Modelo de datos

Cinco objetos y una máquina de estados.

Todo lo que factura Punto API se apoya en cinco recursos. Si entiendes cómo encadenan, el resto de la referencia es vocabulario.

cliente

Cliente

La entidad que paga. Guarda el país de establecimiento y el NIF intracomunitario, que determinan el régimen fiscal de cada factura.

POST /v1/clientes plan

Plan

Precio, moneda e intervalo. Un plan es inmutable: para cambiar el importe se publica una versión nueva y se migran las suscripciones.

POST /v1/planes suscripcion

Suscripción

Une un cliente con un plan y avanza por una máquina de estados. Es el único objeto que genera facturas por sí solo.

POST /v1/suscripciones factura

Factura

Documento con líneas, impuestos y numeración correlativa por serie. Se emite al cerrar el periodo o al aplicar un prorrateo.

GET /v1/facturas evento

Evento

Registro inmutable de cada cambio. Es lo que se entrega por webhook y lo que puedes reproducir para reconstruir tu estado local.

GET /v1/eventos entrega

Entrega

Cada intento de enviar un evento a tu endpoint, con su código de respuesta y su firma. Seis reintentos con retroceso exponencial.

Ver webhooks

Ciclo de vida de una suscripción

en_pruebaSin cargo. Cuenta atrás de prueba_dias.
se agota la prueba · primer cobro
activaFactura cada intervalo. Admite prorrateos.
el cargo del ciclo es rechazado
pendiente_de_pagoServicio activo mientras quedan reintentos.
un reintento cobra → vuelve a activa
se agotan los 6 reintentos
canceladaEstado terminal. Las facturas impagadas se conservan.

Estados y transiciones

{
  "objeto": "suscripcion",
  "estados": ["en_prueba", "activa", "pendiente_de_pago", "cancelada"],
  "transiciones": [
    { "de": "en_prueba", "a": "activa", "evento": "suscripcion.activada" },
    { "de": "activa", "a": "pendiente_de_pago", "evento": "factura.cobro_fallido" },
    { "de": "pendiente_de_pago", "a": "activa", "evento": "factura.pagada" },
    { "de": "pendiente_de_pago", "a": "cancelada", "evento": "suscripcion.cancelada" },
    { "de": "en_prueba", "a": "cancelada", "evento": "suscripcion.cancelada" }
  ],
  "reintentos_max": 6
}

Probador

Ejecuta un escenario sin salir de la página.

Elige el endpoint, edita el cuerpo, fuerza el escenario que quieras reproducir y observa el código de estado, las cabeceras y el JSON que devolvería la API.

Sin red Todas las respuestas se construyen en tu navegador con JavaScript local. El probador no realiza ninguna petición de red, no envía tu JSON a ningún servidor y los tiempos que muestra son simulados.

Endpoint

Escenario

Algunos escenarios no aplican a todos los endpoints y aparecen desactivados.

POST /v1/suscripciones

Cuerpo de la petición · JSON

Tab inserta dos espacios · Esc y luego Tab mueve el foco fuera del editor · Ctrl+Intro ejecuta la simulación.

Respuesta simulada

En espera Pulsa «Ejecutar simulación»

Cabeceras

— sin ejecutar —

Cuerpo

— sin ejecutar —

Guía rápida · 5 pasos

De la clave de sandbox al primer cobro conciliado.

Selecciona un paso para ver su fragmento. Las pestañas de lenguaje cambian todos los ejemplos de la página a la vez y recuerdan tu elección.

Paso 1 · Autentica la clave

Respuesta abreviada

Referencia

Catálogo de endpoints.

Seis recursos cubren el ciclo completo. Todos aceptan Punto-Version y devuelven importes en la unidad mínima de la moneda.

POST /v1/clientes

Crea un cliente facturable. El par país + NIF fija el régimen fiscal de todas sus facturas futuras; si el NIF no valida contra el censo intracomunitario, la respuesta marca nif_verificado: false y se aplica IVA local.

Parámetros de POST /v1/clientes
Parámetro	Tipo	Obl.	Descripción
email	string	sí	Destino de las facturas y de los avisos de impago.
pais	string · ISO 3166-1	sí	País de establecimiento. Determina el tipo impositivo aplicable.
nombre	string	no	Razón social que aparecerá en el PDF de la factura.
nif	string	no	NIF intracomunitario. Activa la inversión del sujeto pasivo en operaciones B2B entre estados miembros.
metadatos	object	no	Hasta 20 pares clave-valor propios. No se usan en el cálculo fiscal.

Ejemplo

201 Created

{
  "id": "cli_8Kq2Nv",
  "objeto": "cliente",
  "email": "finanzas@nortavia.eu",
  "pais": "ES",
  "nif": "ESB12345678",
  "nif_verificado": true,
  "regimen_fiscal": "iva_local",
  "creado": "2026-09-05T09:41:22Z"
}

POST /v1/planes

Publica un plan. Los planes son inmutables: cambiar el importe exige crear otro plan y migrar las suscripciones, lo que mantiene auditable el precio con el que se emitió cada factura histórica.

Parámetros de POST /v1/planes
Parámetro	Tipo	Obl.	Descripción
clave	string	sí	Identificador legible y único, p. ej. `plan_escala_mensual`.
importe	integer	sí	Unidad mínima de la moneda. 24000 = 240,00 €.
moneda	string · ISO 4217	sí	Solo EUR en sandbox.
intervalo	mensual · anual	sí	Longitud del ciclo de facturación.
impuesto_incluido	boolean	no	Si es `true`, el importe se interpreta con impuestos incluidos y se desglosa al facturar.

Ejemplo

201 Created

{
  "id": "plan_escala_mensual",
  "objeto": "plan",
  "importe": 24000,
  "moneda": "EUR",
  "intervalo": "mensual",
  "impuesto_incluido": false,
  "version": 3
}

POST /v1/suscripciones

Suscribe un cliente a un plan. Envía siempre Punto-Idempotencia: si tu proceso reintenta tras un timeout, recibirás la misma suscripción en lugar de un alta duplicada.

Parámetros de POST /v1/suscripciones
Parámetro	Tipo	Obl.	Descripción
cliente	string · cli_	sí	Identificador devuelto por `/v1/clientes`.
plan	string	sí	Clave del plan a suscribir.
prueba_dias	integer · 0–90	no	Días sin cargo antes del primer cobro. Fuera de rango devuelve 400.
metodo_pago	string · pm_	no	Si se omite, la suscripción queda en `en_prueba` hasta que se adjunte uno.
cupon	string	no	Descuento aplicado antes de impuestos.

Ejemplo

402 Payment Required

{
  "error": {
    "tipo": "error_de_pago",
    "codigo": "tarjeta_rechazada",
    "motivo_emisor": "fondos_insuficientes",
    "mensaje": "El emisor rechazó el cargo de 240,00 EUR.",
    "factura": "fac_7Hb2Ls",
    "request_id": "req_9Tf4Wn1c"
  }
}

POST /v1/suscripciones/{id}/previsualizar_prorrateo

Calcula el cambio de plan sin aplicarlo. Devuelve la línea de crédito por los días no consumidos del plan actual, la línea de cargo del plan nuevo y el impuesto resultante. No genera factura ni evento.

Parámetros de la previsualización de prorrateo
Parámetro	Tipo	Obl.	Descripción
plan_nuevo	string	sí	Plan de destino. Puede ser de importe inferior: el crédito se arrastra al ciclo siguiente.
fecha_efecto	string · YYYY-MM-DD	no	Por defecto, hoy. Debe caer dentro del periodo en curso.
prorratear	boolean	no	Con `false` el cambio se aplica al inicio del siguiente ciclo y no hay líneas de ajuste.

Ejemplo

200 OK

{
  "objeto": "previsualizacion_prorrateo",
  "dias_restantes": 16,
  "dias_periodo": 30,
  "lineas": [
    { "concepto": "credito_plan_escala", "importe": -12800 },
    { "concepto": "cargo_plan_corporativo", "importe": 32000 }
  ],
  "subtotal": 19200,
  "impuesto": { "tipo": 0.21, "importe": 4032 },
  "total_a_cobrar": 23232
}

GET /v1/facturas

Lista facturas con paginación por cursor. Para conciliar contra un extracto bancario, filtra por estado=pagada y ordena por fecha_cobro; cada factura pagada incluye la referencia SEPA del abono.

Parámetros de consulta de GET /v1/facturas
Parámetro	Tipo	Obl.	Descripción
cliente	string · cli_	no	Limita el resultado a un cliente.
estado	borrador · abierta · pagada · impagada · anulada	no	Un valor no reconocido devuelve 400 con el parámetro señalado.
limite	integer · 1–100	no	Tamaño de página. Por defecto 20.
despues_de	string · fac_	no	Cursor: devuelve los elementos posteriores a ese identificador.

Ejemplo

200 OK

{
  "objeto": "lista",
  "tiene_mas": false,
  "datos": [
    {
      "id": "fac_7Hb2Ls",
      "estado": "pagada",
      "total": 29040,
      "moneda": "EUR",
      "fecha_cobro": "2026-09-02",
      "referencia_sepa": "PMT-2026-09-02-7HB2LS"
    }
  ]
}

GET /v1/eventos

Reproduce el histórico de eventos de los últimos 30 días. Es la vía de recuperación cuando tu endpoint ha estado caído más allá de la ventana de reintentos: pide los eventos por rango y aplícalos en orden.

Parámetros de consulta de GET /v1/eventos
Parámetro	Tipo	Obl.	Descripción
tipo	string	no	Admite comodín, p. ej. `factura.*`.
desde	string · ISO 8601	no	Marca temporal inclusiva. Máximo 30 días atrás.
entrega	todos · fallidos	no	Con `fallidos` solo devuelve eventos cuyas seis entregas fallaron.

Ejemplo

200 OK

{
  "objeto": "lista",
  "datos": [
    {
      "id": "evt_2Vh6Qp",
      "tipo": "factura.pagada",
      "creado": "2026-09-02T06:12:04Z",
      "entregas_fallidas": 2,
      "datos": { "objeto": "fac_7Hb2Ls" }
    }
  ]
}

Webhooks y reintentos

Entrega al menos una vez, firmada y con retroceso.

Un evento puede llegarte dos veces; nunca cero mientras queden reintentos. Verifica la firma, descarta por id y responde 2xx en menos de cinco segundos.

01 Cambio de estado Se cobra una factura y Punto API escribe un evento inmutable con su identificador.

02 Cola de entrega El evento se encola una vez por cada endpoint suscrito a ese tipo.

03 POST firmado a tu endpoint Cabecera Punto-Firma con marca temporal y HMAC del cuerpo en crudo.

04 2xx o reintento Cualquier otra respuesta, o más de 5 s, programa el siguiente intento.

Línea temporal de una entrega

Seis intentos con retroceso exponencial repartidos en algo menos de ocho horas. Cada intento reenvía el cuerpo idéntico con una firma nueva.

+0 s Primer intento, inmediato tras escribir el evento. 504 timeout
+30 s Segundo intento. 500 error
+2 min Tercer intento. Tu endpoint confirma y la entrega se cierra. 200 OK
+10 min Cuarto intento, solo si el tercero no fue 2xx. no ejecutado
+1 h Quinto intento. no ejecutado
+6 h Sexto y último. Después, el evento queda marcado como no entregado y solo se recupera por GET /v1/eventos. no ejecutado

Verificar la firma

Cuerpo entregado

{
  "id": "evt_2Vh6Qp",
  "objeto": "evento",
  "tipo": "factura.pagada",
  "creado": "2026-09-02T06:12:04Z",
  "intento": 3,
  "datos": {
    "objeto": {
      "id": "fac_7Hb2Ls",
      "total": 29040,
      "moneda": "EUR",
      "suscripcion": "sus_4Rm7Yz"
    }
  }
}

Tipos de evento publicados

Tipos de evento publicados por Punto API
Tipo	Se emite cuando	Objeto adjunto
suscripcion.activada	Termina la prueba y el primer cobro se liquida.	suscripcion
suscripcion.plan_cambiado	Se aplica un prorrateo previamente previsualizado.	suscripcion
factura.emitida	Se cierra el periodo y se numera la factura.	factura
factura.pagada	El cobro se liquida y llega la referencia SEPA.	factura
factura.cobro_fallido	Un intento de cargo es rechazado por el emisor.	factura
suscripcion.cancelada	Se agotan los reintentos o se cancela manualmente.	suscripcion

Precios por volumen

Se paga por transacción liquidada.

Los tramos son acumulativos dentro del mes natural: las primeras transacciones se facturan al precio del primer tramo y solo el excedente pasa al siguiente.

Calendario de prorrateo

Cambio de plan_escala (240,00 €/mes) a plan_corporativo (600,00 €/mes) el 15 de septiembre, dentro de un periodo de 30 días. Quedan 16 días por consumir.

Septiembre 2026 Periodo 01 → 30

123456 78910111213 14151617181920 21222324252627 282930

14 días consumidos en el plan Escala Día del cambio · fecha_efecto 16 días prorrateados al plan Corporativo

El cálculo, línea a línea

{
  "dias_restantes": 16,
  "dias_periodo": 30,
  "credito_plan_escala": -12800,
  "cargo_plan_corporativo": 32000,
  "subtotal": 19200,
  "impuesto_21_pct": 4032,
  "total_a_cobrar": 23232,
  "nota": "24000 * 16/30 = 12800 · 60000 * 16/30 = 32000"
}

232,32 € a cobrar hoy

La siguiente factura completa será de 600,00 € más impuestos, emitida el 1 de octubre.

Tramos de precio por volumen mensual de transacciones liquidadas
Tramo · transacciones liquidadas al mes	Por transacción	Cuota base	Incluye
0 – 2.000	0,29 €	0 €	Sandbox ilimitado, 1 endpoint de webhook, retención de eventos 30 días.
2.001 – 20.000	0,19 €	49 €	5 endpoints, reintentos configurables, exportación de facturas en CSV.
20.001 – 100.000	0,12 €	199 €	Conciliación bancaria automática, series de numeración por país, entorno de staging.
Más de 100.000	a convenir	a convenir	IBAN dedicado, límites de tasa ampliados, revisión trimestral de arquitectura.
Ejemplo · 12.000 transacciones	—	—	2.000 × 0,29 € + 10.000 × 0,19 € + 49 € = 2.529,00 € al mes.

Ficticio Las tarifas de esta tabla son ilustrativas y forman parte de un prototipo de diseño. No corresponden a ningún producto real ni constituyen una oferta.

Cumplimiento y seguridad

Lo que la API hace por ti y lo que sigue siendo tuyo.

Resumen de arquitectura, no asesoramiento legal ni certificación. Las obligaciones concretas dependen de tu entidad, tu país y tu adquirente.

Autenticación reforzada del cliente

Cuando el cobro requiere autenticación reforzada, la API responde con una acción pendiente en lugar de fallar en silencio. Tu integración redirige al titular, recibe el resultado por webhook y reintenta el cargo con la misma clave de idempotencia. Los cobros recurrentes iniciados por el comercio se marcan como tales para que el emisor pueda aplicar las exenciones que correspondan.

Marco europeo de servicios de pago

El modelo de datos sigue el marco europeo vigente de servicios de pago: separación entre iniciación y liquidación, trazabilidad del consentimiento del titular y registro del motivo de cada rechazo comunicado por el emisor. La descripción es genérica y deliberadamente independiente de proveedor; comprueba con tu asesoría qué obligaciones te aplican.

Tokenización de medios de pago

Tus servidores nunca ven el número de tarjeta. El formulario de recogida devuelve un token pm_ de un solo uso que se canjea por un método de pago persistente. En los registros y en los webhooks solo circulan los cuatro últimos dígitos, la marca y el país del emisor.

Residencia de datos y auditoría

Los datos de facturación se almacenan y procesan en centros ubicados en la Unión Europea, con cifrado en tránsito y en reposo. Cada llamada deja un registro de auditoría con su request_id, la clave usada y el resultado, consultable durante 24 meses desde el panel.

Alcance Punto API es una plataforma ficticia. Este apartado describe un modelo de arquitectura verosímil con fines de prototipado y no reproduce, cita ni resume la documentación de ningún proveedor real.

Alta en sandbox

Crea tu clave de prueba.

El entorno de sandbox reproduce la misma API con datos aislados: puedes forzar rechazos, saltar en el tiempo hasta el cierre del periodo y reenviar webhooks a tu máquina.

01Sin tarjeta ni datos de facturación reales.
02Reloj acelerado: un mes de ciclo en un minuto.
03Métodos de pago de prueba para cada tipo de rechazo.

Local Este formulario es una demostración. La validación y la clave se generan en tu navegador; nada se envía a un servidor ni a terceros.

Nombre

Empresa

Correo de trabajo

Volumen mensual estimado

Qué quieres probar primero

Suscripciones Prorrateos Impuestos UE Conciliación

Entiendo que esto es una demostración de diseño y que no se crea ninguna cuenta real.

Tu clave de sandbox simulada

sk_sandbox_—

Guárdala en una variable de entorno. Al ser una demostración, la clave se genera localmente y se pierde al recargar la página.