Skip to main content
POST
/
invoice-series
/
{id}
/
reserve-numbers
Pre-allocate numbers for offline emission
curl --request POST \
  --url https://api.contazen.ro/v1/invoice-series/{id}/reserve-numbers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "count": 10
}'
{
  "success": true,
  "data": {
    "object": "list",
    "data": [
      {
        "object": "number_reservation",
        "token": "<string>",
        "series_id": "<string>",
        "number": 123,
        "device_id": "<string>",
        "reserved_at": 123,
        "expires_at": 123,
        "consumed_at": 123,
        "client_local_uuid": "<string>"
      }
    ],
    "total": 123
  },
  "meta": {
    "version": "v1",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "response_time": "23.45ms"
  }
}

​
Overview

Pulls count sequential numbers off the series counter and hands back one reservation token per slot. The caller mobile device carries these tokens in local storage and spends them when creating invoices offline. When the device later syncs the drafts with POST /invoices, it includes reservation_token in the body — the backend uses the reservation’s pre-allocated number_idx instead of incrementing the counter again. This keeps invoice numbers gapless even across long offline periods.
The series must be locked to the calling device first (see Lock Series). Calling this on an unlocked series, or from a different device than the one holding the lock, returns series_not_locked_to_device.

​
Body

​
count
integer
default:"10"
required
Number of reservation slots to allocate. Maximum 50 per call — request again if the device needs more.

​
Response

Returns a list of reservation objects.
​
data
array

​
Behavior after TTL

If a reservation expires without being consumed, the pre-allocated number becomes a gap in the series. Romanian fiscal practice accepts gaps when documented — keep the reservation TTL generous (default 30 days) and refresh the pool whenever the device comes back online. The cleanup cron flips expired rows to status = 'expired' but does not renumber downstream invoices.

​
Lifecycle

                 ┌──────────────┐    consumed
  reserve ────►  │  pending     │ ───────────────► consumed (by POST /invoices)
                 └──────────────┘
                        │
                        ├─ released (by POST /invoice-series/reservations/{token}/release)
                        │
                        └─ expired  (by TTL cron)

Authorizations

​
Authorization
string
header
required

Use your API key (sk_live_xxx or sk_test_xxx)

Path Parameters

​
id
string
required

Body

application/json
​
count
integer
default:10
Required range: 1 <= x <= 50

Response

Reservations created

​
success
boolean
​
data
object
​
meta
object