Agregar items a una cuenta abierta

POST

https://app.recurrente.com/api/service_tabs/:service_tab_id/items

POST

/api/service_tabs/:service_tab_id/items

$ curl -X POST https://app.recurrente.com/api/service_tabs/service_tab_id/items \
>      -H "X-SECRET-KEY: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "items": [
>     {}
>   ]
> }'

1 {
2   "id": "st_du7dnfwt",
3   "status": "open",
4   "display_name": "Mesa 4",
5   "phone": "+50255551234",
6   "customer_id": "cus_3jfrywsf",
7   "currency": "GTQ",
8   "total_in_cents": 12500,
9   "payment_strategy": "card_on_file",
10   "opening_commitment": "products",
11   "items": [
12     {
13       "id": "it_eyJfcmFpbHMiOnsi",
14       "price_id": "price_hguxwfto",
15       "name": "Cerveza",
16       "quantity": 2,
17       "amount_in_cents": 5000,
18       "currency": "GTQ"
19     }
20   ],
21   "authorized_amount_in_cents": 0,
22   "authorization_expires_at": "2024-01-15T09:30:00Z",
23   "checkout_url": "https://app.recurrente.com/checkout-session/ch_ccydxmvm8fvhmxsn",
24   "opened_at": "2024-01-15T09:30:00Z",
25   "closed_at": "2024-01-15T09:30:00Z",
26   "created_at": "2024-01-15T09:30:00Z"
27 }

Un item nombra algo que ya vendes (price_id o product_id) o se define solo, con name y amount_in_cents. Son las mismas tres formas que aceptan los items de un checkout. Los precios recurrentes no se aceptan: una cuenta abierta solo cobra productos de pago único.

Agrega uno o más consumos a la cuenta. Cada item queda registrado por separado en el feed de actividad, igual que la cuenta que ve el cliente. La respuesta trae la cuenta completa con su nuevo total. Un item nombra algo que ya vendes (`price_id` o `product_id`) o se define solo, con `name` y `amount_in_cents`. Son las mismas tres formas que aceptan los items de un checkout. Los precios recurrentes no se aceptan: una cuenta abierta solo cobra productos de pago único.

Authentication

X-SECRET-KEYstring

Tu clave secreta de API.

Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.

Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.

Tu clave secreta de API. Una llave de cuenta (`sk_live_...`, `sk_test_...`) opera sobre su propia cuenta y, con `X-ACCOUNT-ID`, sobre sus cuentas conectadas. Una llave de organización (`sk_org_live_...`, `sk_org_test_...`) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con `X-ACCOUNT-ID`; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde `403` con `code: organization_key_unsupported`.

Path parameters

service_tab_idstringRequired

ID de la cuenta abierta

Request

This endpoint expects an object.

itemslist of objectsRequired

Response

Items agregados

idstringOptional

ID de la cuenta abierta

statusenumOptional

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_namestringOptional

Nombre con el que el comercio identifica la cuenta (mesa, cliente, cuarto)

phonestring or nullOptional

Teléfono del cliente al momento de abrir la cuenta

customer_idstringOptional

ID del cliente dueño de la cuenta

currencystringOptional

Moneda de la cuenta

total_in_centsintegerOptional

Total consumido hasta ahora, en centavos

payment_strategyenumOptional

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_commitmentenumOptional

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.

itemslist of objectsOptional

Líneas vigentes de la cuenta (los items anulados no aparecen)

authorized_amount_in_centsintegerOptional

Monto preautorizado con hold sobre la tarjeta, en centavos. 0 cuando no hay preautorización.

authorization_expires_atdatetime or nullOptional

Momento en que expira el hold de la preautorización

checkout_urlstring or nullOptional

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_atdatetimeOptional

Momento en que se abrió la cuenta

closed_atdatetime or nullOptional

Momento en que se cerró la cuenta

created_atdatetimeOptional

Errors

422

Unprocessable Entity Error