Factuarea API
Sèries de documents

Crea les sèries per defecte d'una empresa

Deixa una empresa en condicions d'emetre documents en una sola crida: per a cada tipus de document de la superfície pública (invoice, quote, delivery_note, proforma) que no tingui sèrie activa, crea la seva sèrie per defecte amb el codi i el nom canònics. Sense cos de petició.

Què retorna

  • Una entrada per tipus de document, amb un status de created, existing o no_default.
  • no_default significa que el tipus té sèries actives però cap marcada per defecte — arxivar la sèrie per defecte la degrada sense promoure'n cap substituta — i l'empresa continua sense poder emetre aquell document.
  • Tracta no_default com a feina pendent, no com a èxit: les sèries actives arriben a candidates i ho resols amb POST /v1/series/{id}/default.

Per què no tria per tu

Triar quina sèrie numera els documents d'una empresa té conseqüències registrals que només tu pots decidir, així que el bootstrap no en promou mai cap en el teu lloc.

Si el crides dues vegades

  • Idempotent per regla de negoci: una segona crida no crea res, no falla i torna a informar de l'estat.
  • INDEPENDENT del header Idempotency-Key: amb el header, una clau repetida repeteix el cos original — entrades created incloses — en lloc d'informar de l'estat actual.
POST
/series/bootstrap

Authorization

AuthorizationBearer <token>

A: header

Paràmetres de capçalera

Idempotency-Key?string

Clau opaca generada pel client (fins a 255 caràcters; es recomana UUID v7) que fa segurs els reintents: la primera resposta es cacheja i es reprodueix a les repeticions sense tornar a executar la mutació. Reutilitzar una clau amb un cos diferent retorna 409 idempotency_key_reused. Consulta la guia d'Idempotency.

Longitud1 <= length <= 255
Factuarea-Version?string

Fixa la versió de l'API (YYYY-MM-DD, versionat per data estil Stripe) per a aquesta petició; omet-lo per usar la versió fixada de la clau, o l'última si no n'hi ha cap. Versió no suportada → 400 unsupported_api_version; mal formada → 400 parameter_invalid_format. La versió efectiva es reflecteix a la capçalera de resposta Factuarea-Version. Consulta la guia de Versioning.

Formatdate
X-Active-Profile?string

Opera en nom d'una empresa filla (API key mestra de gestoria): passa el seu id públic (UUID v7) i la petició s'executa contra les dades d'aquella filla sense canviar l'scope, el tier ni l'environment de la clau (omet-lo per usar la pròpia empresa de la clau). UUID no vàlid → 400 parameter_invalid_uuid; id desconegut o no propi → 404 profile_not_found. Consulta la guia d'Acting on behalf.

Formatuuid

Cos de la resposta

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"
  }
}
POST

Arxivar una sèrie

POST

Crea una sèrie