Bootstrap the default series of a company
Leave a company able to issue documents in one call: for every document type of the public surface (invoice, quote, delivery_note, proforma) that has no active series, create its default series with the canonical code and name. No request body.
What comes back
- One entry per document type, with a
statusofcreated,existingorno_default. no_defaultmeans the type has active series but none marked as default — archiving the default demotes it without promoting a replacement — and the company still cannot issue that document.- Treat
no_defaultas work still to do, not as success: the active series arrive incandidatesand you resolve it withPOST /v1/series/{id}/default.
Why it does not choose for you
Picking which series numbers a company's documents has registry consequences only you can decide, so the bootstrap never promotes one for you.
Calling it twice
- Idempotent by business rule: a second call creates nothing, fails nothing and reports the state again.
- INDEPENDENT of the
Idempotency-Keyheader: with the header, a repeated key replays the original body —createdentries included — instead of reporting the current state.
In: header
Header Parameters
Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns 409 idempotency_key_reused. See the Idempotency guide.
1 <= length <= 255Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.
dateOperate on behalf of a child company (gestoría master key): pass its public id (UUID v7) and the request runs against that child's data without changing the key's scope, tier or environment (omit to use the key's own company). Invalid UUID → 400 parameter_invalid_uuid; unknown or non-owned id → 404 profile_not_found. See the Acting on behalf guide.
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
import { Factuarea } from "@factuarea/sdk";const factuarea = new Factuarea({ apiKey: process.env.FACTUAREA_API_KEY! });const result = await factuarea.series.bootstrap();{
"data": {
"results": [
{
"document_type": "invoice",
"status": "created",
"series_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b01",
"code": "F",
"candidates": []
},
{
"document_type": "quote",
"status": "existing",
"series_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02",
"code": "P",
"candidates": []
},
{
"document_type": "delivery_note",
"status": "no_default",
"series_id": null,
"code": null,
"candidates": [
{
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03",
"code": "ALB"
},
{
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b04",
"code": "ALB-2026"
}
]
},
{
"document_type": "proforma",
"status": "created",
"series_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b05",
"code": "PRF",
"candidates": []
}
]
}
}{
"error": {
"type": "authentication_error",
"code": "missing_api_key",
"message": "No se ha proporcionado una API key válida en el header Authorization.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
"request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
}
}{
"error": {
"type": "authorization_error",
"code": "insufficient_scope",
"message": "Esta API key no tiene el scope requerido para esta operación.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
"request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
}
}{
"error": {
"type": "idempotency_error",
"code": "idempotency_key_reused",
"message": "La cabecera `Idempotency-Key` ya se usó con un body distinto. Usa una clave nueva o reenvía exactamente el mismo body.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
"request_id": "req_01HKQS5NHT9A4U7R2E3F8GZWTJ"
}
}{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
"request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
}
}{
"error": {
"type": "api_error",
"code": "internal_error",
"message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
"request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
}
}