# Herramientas · Créditos

> Herramientas MCP de los créditos de reserva: saldo, extracto, conceder, ajustar y retirar créditos, y las reglas de la comunidad (acumulación, plazo de cancelación, cancelación tardía y ausencia). Rol mínimo y recetas.

Los [créditos](/monetizacao/creditos) con el asistente: ver el saldo y el extracto (el tuyo o el de cualquier miembro, para el equipo), conceder y ajustar créditos, retirarlos y leer o cambiar las reglas de la comunidad. Los créditos de los planes y de los productos se definen con [`create_plan` y `update_plan`](/mcp/ferramentas-vendas) (`monthly_credits`) y [`create_product` y `update_product`](/mcp/ferramentas-vendas) (`granted_credits` y `granted_credits_validity_days`); en una comunidad sin espacio de Reservas o de Agendamiento, el asistente explica que hay que crear uno primero.

Cada herramienta lleva un sello: <span class="tool-kind tool-kind-read">Solo consulta</span> no cambia nada, <span class="tool-kind tool-kind-write">Modifica</span> crea o cambia algo al momento, y <span class="tool-kind tool-kind-confirm">Pide confirmación</span> solo actúa después de tu sí a un resumen. Consulta [Dinero y confirmación](/mcp/dinheiro-e-confirmacao).

## En resumen

| Herramienta | Qué hace | Rol mínimo | Tipo |
|---|---|---|---|
| [`get_credit_balance`](#get-credit-balance) | El saldo, lo que vence en 7 días y los lotes | Cualquiera (el suyo); equipo (de otro) | <span class="tool-kind tool-kind-read">Solo consulta</span> |
| [`list_credit_entries`](#list-credit-entries) | El extracto, del más nuevo al más antiguo | Cualquiera (el suyo); equipo (de otro) | <span class="tool-kind tool-kind-read">Solo consulta</span> |
| [`grant_credits`](#grant-credits) | Abre un lote nuevo de créditos, con motivo | Finanzas | <span class="tool-kind tool-kind-confirm">Pide confirmación</span> |
| [`adjust_credits`](#adjust-credits) | Suma créditos como corrección, con motivo | Finanzas | <span class="tool-kind tool-kind-confirm">Pide confirmación</span> |
| [`revoke_credits`](#revoke-credits) | Retira créditos (ajuste negativo) | Finanzas | <span class="tool-kind tool-kind-confirm">Pide confirmación</span> |
| [`get_credit_settings`](#get-credit-settings) | Las reglas de créditos de la comunidad | Moderador (o finanzas) | <span class="tool-kind tool-kind-read">Solo consulta</span> |
| [`update_credit_settings`](#update-credit-settings) | Cambia las reglas | Administrador | <span class="tool-kind tool-kind-write">Modifica</span> |

"Finanzas" aquí significa **propietario, administrador o finanzas**; el **moderador solo lee**. "Equipo" es el propietario, el administrador, el moderador y finanzas. Los roles son los de las rutas: el asistente nunca hace más de lo que la persona conectada haría en la pantalla. La variable de la plataforma que decide si una suscripción pausada o impagada sigue usando el saldo es del SuperAdmin y no tiene herramienta.

## `get_credit_balance`

<span class="tool-kind tool-kind-read">Solo consulta</span>

**El saldo.** El saldo utilizable (la suma de los lotes que no han vencido; puede ser negativo, lo que bloquea reservar), lo que vence en los próximos 7 días y los lotes, cada uno con su origen (**Plan**, **Producto** o **Equipo**), cuánto queda y cuándo vence. *Rol mínimo: cualquiera (el suyo); el equipo lee el de cualquier miembro.*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `profile_id` | id | No | Solo el equipo: de quién. Sin él, es el tuyo (un miembro que pide el de otro es rechazado) |

**Pídelo así:** *"¿Cuántos créditos tengo?"* · *"¿Cuál es el saldo de María Souza?"*

## `list_credit_entries`

<span class="tool-kind tool-kind-read">Solo consulta</span>

**El extracto.** Cada movimiento con su tipo (concesión, uso en una reserva, reembolso, ajuste, vencimiento, revocación), el valor con signo, el origen, la reserva, el producto o la suscripción detrás y el motivo. El libro solo crece: nada se edita ni se borra. Paginado.

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `profile_id` | id | No | Solo el equipo: de quién. Sin él, es el tuyo |
| `kind` | `GRANT`, `DEBIT`, `REFUND`, `ADJUSTMENT`, `EXPIRATION` o `REVOCATION` | No | Filtra por tipo |
| `page`, `limit` | número | No | Paginación (`limit` hasta 200) |

**Pídelo así:** *"Enséñame el extracto de créditos de María de este mes."*

## `grant_credits`

<span class="tool-kind tool-kind-confirm">Pide confirmación</span>

**Conceder créditos.** Abre un **lote nuevo** con **motivo obligatorio** y validez opcional (sin ella, no vencen). Antes de actuar, muestra un resumen y solo repite la llamada después de tu sí. Devuelve el nuevo saldo y el movimiento. *Rol mínimo: finanzas.*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `profile_id` | id | Sí | El miembro (`list_members`) |
| `amount` | entero, de 1 a 100.000 | Sí | Cuántos créditos |
| `reason` | texto (hasta 255) | Sí | El motivo: queda en el extracto |
| `expires_at` | fecha y hora futura | No | Cuándo vencen; sin ella o `null`, nunca |

**Pídelo así:** *"Dale 10 créditos de cortesía a Juan, válidos hasta fin de mes, porque recomendó a un miembro nuevo."*

## `adjust_credits`

<span class="tool-kind tool-kind-confirm">Pide confirmación</span>

**Ajustar hacia arriba.** Suma créditos como **corrección** (un movimiento de ajuste: es la forma de arreglar un error, ya que el libro nunca se edita). Mismos parámetros que `grant_credits` (hasta 100.000 por vez), y también pide confirmación. Para quitar créditos, usa [`revoke_credits`](#revoke-credits), que pide confirmación. *Rol mínimo: finanzas.*

## `revoke_credits`

<span class="tool-kind tool-kind-confirm">Pide confirmación</span>

**Retirar créditos.** Un ajuste negativo, con motivo obligatorio. Consume **primero los lotes que vencen antes** y **no supera el saldo utilizable** (si no, `409`: lee el saldo antes). Antes de actuar, muestra un resumen (cuánto, el saldo actual, el saldo después y el motivo) y solo repite la llamada con el `confirmation_token` después de un sí explícito. *Rol mínimo: finanzas.*

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `profile_id` | id | Sí | El miembro |
| `amount` | entero, 1 o más | Sí | Cuántos créditos quitar |
| `reason` | texto | Sí | El motivo |

## `get_credit_settings`

<span class="tool-kind tool-kind-read">Solo consulta</span>

**Las reglas.** Acumulación (activada, tope, meses), parte proporcional del primer mes, plazo de cancelación en horas, si la cancelación tardía y la ausencia pierden el crédito y los días de aviso de vencimiento. *Rol mínimo: moderador (o finanzas).*

## `update_credit_settings`

<span class="tool-kind tool-kind-write">Modifica</span>

**Cambiar las reglas.** Cambia solo lo que envíes. Vale desde el próximo cambio de mes y nunca altera un lote que ya existe. *Rol mínimo: administrador.*

| Parámetro | Tipo | Descripción |
|---|---|---|
| `rollover_enabled` | verdadero o falso | Acumular el crédito del plan para el mes siguiente (por defecto: no) |
| `rollover_cap` | entero o `null` | El tope de lo que pasa; `null`, sin tope |
| `rollover_max_cycles` | 1 a 12 | Por cuántos meses vale lo acumulado |
| `prorate_first_month` | verdadero o falso | Proporcional a los días restantes en el primer mes |
| `change_window_hours` | 0 a 720 | Plazo para cancelar o cambiar sin perder (por defecto: 24) |
| `late_cancel_loses_credits` | verdadero o falso | La cancelación tardía pierde el crédito (por defecto: sí) |
| `no_show_loses_credits` | verdadero o falso | La ausencia pierde el crédito (por defecto: sí) |
| `expiry_notice_days` | 0 a 30 | Días de aviso antes de vencer (0 = no avisa) |

**Pídelo así:** *"Activa la acumulación de créditos, con tope de 20, durante 2 meses, y deja el plazo de cancelación en 12 horas."*

## Relacionados

- [Créditos](/monetizacao/creditos)
- [Herramientas · Reservas y Agendamiento](/mcp/ferramentas-reservas)
- [Herramientas](/mcp/ferramentas)
- [Dinero y confirmación](/mcp/dinheiro-e-confirmacao)
- [Recetas](/mcp/receitas)