#Billing

Clarisfy cobra por asiento de RFC: cada Fiscal Entity con la conexión activa ocupa un asiento de tu plan y se sincroniza con el SAT. Estos endpoints gestionan esa facturación por RFC.

#Uso del plan

GET/billing/plan-usage

Devuelve la identidad de tu plan y la ocupación de asientos RFC de tu organización (sin montos). Un asiento usado es un RFC con la conexión activa.

#Ejemplo

curl https://api.clarisfy.com/api/v1/billing/plan-usage \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "plan_code": "ent_bronze",
  "plan_name": "Enterprise Bronce",
  "api_access": true,
  "has_fixed_quota": true,
  "seats_contracted": 50,
  "seats_used": 52,
  "seats_available": 0,
  "overage": 2,
  "subscription_status": "active",
  "trial_started": true,
  "trial_days_remaining": 0,
  "trial_ends_at": null
}

Campo	Tipo	Descripción
`plan_code`	string	Clave del plan (p. ej. `ent_bronze`).
`plan_name`	string	Nombre del plan.
`api_access`	boolean	`true` si el plan otorga acceso a la API.
`has_fixed_quota`	boolean	`true` si hay cuota contratada (>0); `false` = pago por uso.
`seats_contracted`	integer	Asientos RFC contratados.
`seats_used`	integer	Asientos RFC ocupados (RFCs activos).
`seats_available`	integer	Asientos libres.
`overage`	integer	Excedente: RFCs usados por encima de la cuota.
`subscription_status`	string	`trialing`, `active`, `past_due`, `cancelled` o `expired`.
`trial_started`	boolean	`true` si la prueba única ya se redimió (con el primer RFC activo).
`trial_days_remaining`	integer	Días enteros restantes de la prueba (`0` fuera de prueba).
`trial_ends_at`	string \| null	Fin de la ventana de prueba (ISO 8601), o `null`.

#Activa o suspende un RFC

PATCH/billing/rfcs/{fiscal_entity_id}

Activa o suspende la conexión de tu organización a un RFC:

active: true → la conexión pasa a active y se sincroniza con el SAT (ocupa un asiento).
active: false → la conexión pasa a suspended: se detienen las sincronizaciones futuras. Si el RFC ya sincronizó este mes, sigue contando para el cobro de este mes.

#Parámetros de ruta

Parámetro	Tipo	Descripción
`fiscal_entity_id`	string	Identificador de la `FiscalEntity` (`fe_…`). También se acepta el UUID crudo.

#Cuerpo de la petición

Campo	Tipo	Descripción
`active`	boolean	Requerido. `true` activa (sincroniza), `false` suspende.

#Ejemplo

curl -X PATCH https://api.clarisfy.com/api/v1/billing/rfcs/fe_9a1c2b3d4e5f6071 \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

Respuesta 200 OK — la fila de facturación del RFC actualizada:

{
  "fiscal_entity_id": "6f0f1d3e-2b3c-4d5e-8f90-1a2b3c4d5e6f",
  "rfc": "VECJ880326XYZ",
  "name": "Mi empresa",
  "active": false,
  "billable_this_month": true
}

Campo	Tipo	Descripción
`fiscal_entity_id`	string	Identificador de la `FiscalEntity`.
`rfc`	string	RFC del contribuyente.
`name`	string	Nombre a mostrar: apodo, razón social o el RFC.
`active`	boolean	`true` = conexión activa (sincroniza); `false` = suspendida.
`billable_this_month`	boolean	`true` si el RFC tuvo al menos una sincronización exitosa este mes.

#Errores

Código HTTP	Causa
`400`	`fiscal_entity_id` con formato inválido.
`402`	Activar el RFC excede los asientos contratados de tu plan. La respuesta trae un link de pago (`checkout_url`) para el asiento adicional; el RFC no se activa hasta que el pago se confirma.
`404`	Tu organización no tiene una conexión (no eliminada) a esa `FiscalEntity`.

Ejemplo de respuesta 402:

{
  "status": "payment_required",
  "message": "Alcanzaste el límite de RFC de tu plan. Paga el asiento adicional para activar este RFC.",
  "checkout_url": "https://checkout.clip.mx/..."
}