---
title: "Abrir una cuenta"
method: POST
path: "/service_tabs"
tags: ["serviceTabs"]
---

# Abrir una cuenta

`POST /service_tabs`

Abre una cuenta para un cliente. Identifica al cliente con `customer_id`,
o con `phone` y `display_name` para crearlo si no existe.

El compromiso de apertura se infiere de lo que envíes: `items` abre la
cuenta ya con esos consumos, `estimated_amount` la abre con un monto
estimado sin items, y si no envías ninguno la cuenta queda vacía y le
agregas items después.

La estrategia de cobro es siempre `card_on_file`: al cerrar se cobra la
tarjeta guardada del cliente (o le entregas un link de pago). La
preautorización con hold solo se puede activar desde el dashboard,
porque requiere una autorización real del procesador.

Usa un `Idempotency-Key` único por cuenta abierta.

## Headers

- `X-SECRET-KEY` string, required

## Request body

- object
  - `customer_id` string — ID del cliente. Si lo omites, se resuelve o crea con `phone` y `display_name`.
  - `display_name` string — Nombre con el que identificas la cuenta (mesa, cliente, cuarto)
  - `phone` string — Teléfono del cliente
  - `currency` string — Moneda de la cuenta. Por defecto, la moneda principal de tu cuenta.
  - `estimated_amount` string — Monto estimado de consumo, en unidades de la moneda (no centavos)
  - `payment_method_id` string — Método de pago guardado del cliente que se cobrará al cerrar
  - `items` ServiceTabsPostRequestBodyContentApplicationJsonSchemaItemsItems[] — Consumos con los que abre la cuenta
    - `price_id` string — Precio existente a cobrar
    - `product_id` string — Producto existente; se cobra su precio vigente
    - `name` string — Nombre del cobro manual, cuando no mandas `price_id` ni `product_id`
    - `amount_in_cents` integer — Monto del cobro manual, en centavos
    - `currency` string — Moneda del cobro manual. Por defecto, la de la cuenta abierta. Una cuenta no puede mezclar monedas: un item en otra moneda se rechaza con `422`.
    - `quantity` integer — Entero mayor a 0. Un lote con un item inválido no agrega ninguno.

## Response `201`

Cuenta abierta

- ServiceTab
  - `id` string — ID de la cuenta abierta
  - `status` 'open' | 'closing' | 'paid' | 'voided' | 'abandoned' — Estado de la cuenta. `open` acepta items; `closing` ya está cerrada y espera el pago; `paid` se cobró; `voided` se anuló sin cobrar; `abandoned` se dejó vencer.
  - `display_name` string — Nombre con el que el comercio identifica la cuenta (mesa, cliente, cuarto)
  - `phone` string, nullable — Teléfono del cliente al momento de abrir la cuenta
  - `customer_id` string — ID del cliente dueño de la cuenta
  - `currency` string — Moneda de la cuenta
  - `total_in_cents` integer — Total consumido hasta ahora, en centavos
  - `payment_strategy` 'card_on_file' | 'preauthorization' — `card_on_file` cobra al cerrar la tarjeta guardada del cliente. `preauthorization` mantiene un hold del monto estimado y solo se puede activar desde el dashboard, porque requiere una autorización real del procesador.
  - `opening_commitment` 'none' | 'manual_amount' | 'product' | 'products' — Qué se comprometió al abrir la cuenta. Se infiere de la solicitud: `products` si mandaste `items`, `manual_amount` si mandaste `estimated_amount`, `none` si no mandaste ninguno.
  - `items` ServiceTabItem[] — Líneas vigentes de la cuenta (los items anulados no aparecen)
    - `id` string — ID del item, firmado y estable mientras el item exista
    - `price_id` string — ID del precio cobrado en esta línea
    - `name` string — Nombre del producto
    - `quantity` integer — Cantidad
    - `amount_in_cents` integer — Total de la línea (precio × cantidad), en centavos
    - `currency` string — Moneda de la línea
  - `authorized_amount_in_cents` integer — Monto preautorizado con hold sobre la tarjeta, en centavos. `0` cuando no hay preautorización.
  - `authorization_expires_at` string, date-time, nullable — Momento en que expira el hold de la preautorización
  - `checkout_url` string, nullable — Checkout que cierra la cuenta; pagarlo la marca como `paid`. Solo aparece mientras la cuenta se está cobrando (`closing` o `paid`): si un cobro con tarjeta se declina, la cuenta se reabre y el checkout de ese intento no se publica, porque el cliente no podría pagarlo.
  - `opened_at` string, date-time — Momento en que se abrió la cuenta
  - `closed_at` string, date-time, nullable — Momento en que se cerró la cuenta
  - `created_at` string, date-time

## Other responses

- `422` — Un item no nombra nada cobrable, o no es válido para una cuenta abierta

---

[API](https://skmtc.dev/recurrente/apis/referencia-api.md) · [All operations](https://skmtc.dev/recurrente/apis/referencia-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/recurrente/referencia-api/revisions/f494a078482c/schema)