> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contazen.ro/llms.txt
> Use this file to discover all available pages before exploring further.
# Reserve Numbers
> Pre-allocate N invoice numbers from a locked series so the mobile device can emit invoices offline with correct numbering.
## 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](/api-reference/endpoints/invoice-series/lock)). Calling this on an unlocked series, or from a different device than the one holding the lock, returns `series_not_locked_to_device`.
## Body
Number of reservation slots to allocate. Maximum 50 per call — request again if the device needs more.
## Response
Returns a list of reservation objects.
Opaque token. Pass as `reservation_token` when emitting the invoice.
The pre-allocated sequence number within the series.
`pending`, `consumed`, `released`, or `expired`.
Device this reservation is bound to.
Unix timestamp (seconds).
Unix timestamp (seconds). Reservations expire after 30 days by default.
Unix timestamp when consumed, else `null`.
## 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
```text theme={null}
┌──────────────┐ consumed
reserve ────► │ pending │ ───────────────► consumed (by POST /invoices)
└──────────────┘
│
├─ released (by POST /invoice-series/reservations/{token}/release)
│
└─ expired (by TTL cron)
```
## OpenAPI
````yaml POST /invoice-series/{id}/reserve-numbers
openapi: 3.1.0
info:
title: Contazen API
version: 1.2.0
description: >
Build powerful integrations with the Contazen invoicing platform. The
Contazen API is organized around REST,
has predictable resource-oriented URLs, accepts JSON request bodies, returns
JSON-encoded responses,
and uses standard HTTP response codes, authentication, and verbs.
## Authentication
The API uses Bearer token authentication. Include your API key in the
Authorization header.
### Getting your API Key
1. Log in to your Contazen account
2. Navigate to Settings > API
3. Generate or copy your API key (starts with `sk_live_` for production or
`sk_test_` for testing)
### Using the API Key
Include your API key in the Authorization header:
```
Authorization: Bearer sk_live_YOUR_API_KEY
```
### Example Request with cURL
```bash
curl --request GET \
--url https://api.contazen.ro/v1/clients \
--header 'Authorization: Bearer sk_live_YOUR_API_KEY' \
--header 'Accept: application/json'
```
## Rate Limiting
- 1000 requests per hour per API key
- 100 create operations per minute per API key
Rate limit information is included in response headers:
- `X-RateLimit-Limit`: Maximum requests allowed
- `X-RateLimit-Remaining`: Requests remaining
- `X-RateLimit-Reset`: Reset time (Unix timestamp)
## Pagination
All list endpoints return paginated results with the following format:
```json
{
"success": true,
"data": {
"object": "list",
"data": [...],
"has_more": true,
"total": 245,
"page": 1,
"per_page": 50,
"total_pages": 5
},
"meta": {
"version": "v1",
"request_id": "req_1a2b3c4d",
"response_time": "23.45ms"
}
}
```
## Multi-Work-Point Access
API keys belong to a specific work point but can access data from all work
points
within the same parent company.
## Error Handling
The API uses conventional HTTP response codes to indicate success or
failure.
In general: 2xx codes indicate success, 4xx codes indicate an error due to
the
information provided, and 5xx codes indicate an error with Contazen's
servers.
## Expanding Nested Objects
Many endpoints support the `expand` parameter to include related objects in
the response.
This follows the Stripe API pattern. For example:
- `expand[]=lines` - Include invoice line items
- `expand[]=payments` - Include payment records
- `expand[]=client` - Include full client object
## Localization
The API supports multiple languages through:
- `locale` query parameter (en, ro)
- `Accept-Language` header
- Default: English
contact:
name: Contazen Support
email: support@contazen.ro
url: https://contazen.ro
license:
name: Proprietary
url: https://www.contazen.ro/termeni-si-conditii-de-utilizare/
servers:
- url: https://api.contazen.ro/v1
description: Production API server
security:
- bearerAuth: []
tags:
- name: Authentication
description: API authentication and test endpoints
- name: Clients
description: Manage your customers (B2B and B2C)
- name: Invoices
description: Create and manage invoices, proformas, and receipts
- name: Products
description: Manage your product and service catalog
- name: Expenses
description: Track and manage business expenses
- name: Expense Categories
description: Organize expenses with categories
- name: Suppliers
description: Manage expense suppliers and vendors
- name: Settings
description: API settings and configuration
- name: Payments
description: Payments received against invoices
- name: Receipts
description: Cash receipts (chitanțe) — standalone or paired with an invoice
- name: Company Lookup
description: Romanian company lookup (ANAF / VIES)
- name: Invoice Series
description: Manage invoice numbering series
- name: Bank Accounts
description: Manage IBAN bank accounts
- name: E-Factura
description: Romanian e-invoicing status and configuration
- name: Supplier Bills
description: Supplier invoices imported from the ANAF SPV inbox
- name: VAT Rates
description: Firm-scoped custom VAT rates on top of the Romanian catalog
- name: Currencies
description: Currencies enabled for the firm's bill templates
- name: Languages
description: Languages enabled for the firm's bill templates
- name: Conta
description: |
Public ANAF data for the firm's CUI: fiscal profile (TVA scope, RTVAI,
split TVA, status, e-Factura registration, CAEN) and annual balance
sheets (cifra de afaceri, profit, capitaluri, datorii, salariați).
Powered by the public ANAF webservices (no OAuth required for these
endpoints). The data is cached locally and refreshed on demand via
the `/sync` actions.
paths:
/invoice-series/{id}/reserve-numbers:
post:
tags:
- Invoice Series
summary: Pre-allocate numbers for offline emission
description: |
Returns `count` reservation tokens. Each token corresponds to a
pre-allocated invoice number on the series. The mobile device uses
the tokens to emit invoices while offline — passing
`reservation_token` to `POST /invoices` consumes the reservation and
assigns its pre-allocated number instead of calling `nextNumber()`.
Requires the series to already be locked to the calling device.
operationId: reserveInvoiceSeriesNumbers
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
count:
type: integer
minimum: 1
maximum: 50
default: 10
responses:
'201':
description: Reservations created
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
object:
type: string
example: list
data:
type: array
items:
$ref: '#/components/schemas/NumberReservation'
total:
type: integer
meta:
$ref: '#/components/schemas/ResponseMeta'
'401':
$ref: '#/components/responses/UnauthorizedError'
'409':
description: Series is not locked to this device
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
NumberReservation:
type: object
description: Pre-allocated invoice number held for a mobile device.
properties:
object:
type: string
example: number_reservation
token:
type: string
description: Opaque token — pass as `reservation_token` on POST /invoices.
series_id:
type: string
nullable: true
description: CzUid of the series the reservation belongs to.
number:
type: integer
description: The pre-allocated `number_idx` within the series.
status:
type: string
enum:
- pending
- consumed
- released
- expired
device_id:
type: string
reserved_at:
type: integer
nullable: true
expires_at:
type: integer
nullable: true
consumed_at:
type: integer
nullable: true
client_local_uuid:
type: string
nullable: true
ResponseMeta:
type: object
properties:
version:
type: string
default: v1
request_id:
type: string
format: uuid
description: Unique request identifier for debugging
response_time:
type: string
example: 23.45ms
ErrorResponse:
type: object
required:
- success
- error
properties:
success:
type: boolean
default: false
error:
type: object
required:
- message
- type
- code
properties:
message:
type: string
description: Human-readable error message
type:
type: string
enum:
- api_error
- authentication_error
- invalid_request_error
- rate_limit_error
- permission_error
- validation_error
code:
type: string
description: Machine-readable error code
param:
type: string
description: The parameter that caused the error
doc_url:
type: string
format: uri
description: URL to relevant documentation
meta:
$ref: '#/components/schemas/ResponseMeta'
responses:
UnauthorizedError:
description: API key is missing or invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Use your API key (sk_live_xxx or sk_test_xxx)
````