{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-account-import-upload-schema.json",
  "title": "AccountImportUpload",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beel-es-accountimports-api-openapi.yml#/components/schemas/AccountImportUpload",
  "type": "object",
  "required": [
    "accounts_file"
  ],
  "properties": {
    "accounts_file": {
      "type": "string",
      "format": "binary",
      "description": "CSV with one managed account per row, in the format of `GET /v1/templates/account-import`: UTF-8, header names matched case-insensitively, and `,`, `;` or tab accepted as separator.\n\nThe header row does not have to be the first line. A spreadsheet almost never starts on it — there is a title, sometimes a blank line — and that preamble travels ahead of the data when the sheet is exported. Everything before the first line carrying the required columns is ignored, within the first 20 lines. Reported `row_number`s still count from the top of the file, so they match what you see when you open it."
    },
    "customers_file": {
      "type": "string",
      "format": "binary",
      "description": "Optional CSV of customers to apply to **every** account of this import, in the format of `GET /v1/templates/customer-import`. Idempotent by tax id. Its preamble is skipped the same way — it comes out of the same spreadsheet."
    },
    "options": {
      "$ref": "#/$defs/AccountImportOptions"
    }
  },
  "$defs": {
    "AccessLevel": {
      "type": "string",
      "description": "How much access an actor has to an account or a company. The same three values are used everywhere access is granted or reported — whether the actor is a member of the account or a provisioner managing it on someone's behalf.\n\n`NONE` — no access to the data.\n`VIEW` — read invoices, customers, products, series and fiscal data.\n`OPERATE` — everything in `VIEW`, plus creating and editing them. In Live, issuing invoices for an account you manage additionally requires a signed fiscal representation from the account holder (see `/v1/companies/{company_id}/representation`). In Test you can issue from the start.\n\nAccess level never affects billing: whoever provisioned an account pays for its subscription regardless of the level they keep over it.",
      "enum": [
        "NONE",
        "VIEW",
        "OPERATE"
      ]
    },
    "AccountImportOptions": {
      "type": "object",
      "description": "Settings that apply to **every row** of the file. They live here and not as columns because an agency onboards all of its managed accounts the same way: a column nobody varies is a column everybody mistypes.\n\nTravels as an `application/json` part named `options` inside the multipart body — send it with its own `Content-Type: application/json` (`-F 'options=…;type=application/json'` in curl). Omit the part entirely to take the defaults.",
      "properties": {
        "access_level": {
          "allOf": [
            {
              "$ref": "#/$defs/AccessLevel"
            }
          ],
          "description": "The access you keep over every account of this file. Defaults to `OPERATE` — not to `NONE` as in `POST /v1/accounts`, and the difference is deliberate: a file-driven import is re-run to reconcile what is missing, and reconciling an account's series and customers is a write that `VIEW` cannot do. An account you already manage with less than this is reported `BLOCKED` and skipped: once its holder has claimed it, only they can raise your access again."
        },
        "series": {
          "type": "array",
          "maxItems": 8,
          "description": "Invoice series every account must end up with, declared once. Each entry is a `CreateSeriesRequest` exactly as `POST /v1/companies/{company_id}/series` takes it, with one addition: the token `{REF}` in `name` and `format` is replaced with the row's `external_ref` **before** the series is created, which is how a single declaration numbers every account distinguishably. `{REF}` is vocabulary of this endpoint only — what reaches the series is a literal format, so nothing downstream has to learn a new variable. A row whose `external_ref` would produce a format outside the series grammar (uppercase letters, digits, `-`, `_`, `/`, `:`) is reported and its series left alone.\n\nLeave it out and each account keeps the default series its activation seeds.",
          "items": {
            "$ref": "#/$defs/CreateSeriesRequest"
          }
        },
        "apply_customers_to_own_company": {
          "type": "boolean",
          "default": false,
          "description": "Load the shared customers file into **your own** company too, not only into the managed accounts the file describes. Off by default: an import of accounts writes on the accounts it imports, and a file that quietly also wrote on your own customers would be a surprise nobody asked for.\n\n**Your own company is the one in focus for this request** — the same one every company-scoped write of the API uses, and never one this endpoint picks for you. With several NIFs and none in focus the whole import is refused with `403` `ACTIVE_COMPANY_REQUIRED`, decided **before the files are read**: no account is provisioned and nothing is billed. Sending the option without `customers_file` is a `422`, decided in the same place — there is nothing to apply.\n\nWith an API key it needs `customers:write` on top of the `accounts:write` the operation already requires. It writes customers; a key that may not write customers must not get to through an accounts import. A dashboard session is governed by the role's capabilities over the company in focus, as everywhere else.\n\nWhat it did comes back in `own_company_customers`, apart from the per-account counters."
        }
      }
    },
    "CounterReset": {
      "type": "string",
      "enum": [
        "NEVER",
        "ANNUAL",
        "MONTHLY"
      ],
      "description": "Counter reset policy:\n- NEVER: Counter never resets (continuous numbering)\n- ANNUAL: Counter resets yearly\n- MONTHLY: Counter resets monthly\n"
    },
    "CreateSeriesRequest": {
      "type": "object",
      "description": "Request to create an invoice series. `document_type` is required: a new series always has\na type, and `UNASSIGNED` is rejected with `422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED`.\nCorrective invoices need a series of their own (`CORRECTIVE`).\n",
      "required": [
        "document_type",
        "name",
        "code",
        "format"
      ],
      "properties": {
        "document_type": {
          "$ref": "#/$defs/DocumentType"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Descriptive name of the series"
        },
        "code": {
          "$ref": "#/$defs/SeriesCode"
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 1000,
          "description": "Optional series description"
        },
        "format": {
          "$ref": "#/$defs/SeriesFormat"
        },
        "counter_reset": {
          "allOf": [
            {
              "$ref": "#/$defs/CounterReset"
            }
          ],
          "default": "ANNUAL",
          "description": "When this series' counter resets. Defaults to `ANNUAL` when omitted — so a format\nwithout a year token must come with `counter_reset: NEVER`.\n"
        },
        "initial_number": {
          "type": "integer",
          "format": "int64",
          "minimum": 1,
          "maximum": 999999,
          "default": 1,
          "description": "Initial number for this series counter.\nUseful when migrating from another system and wanting to continue existing numbering.\nFor example, if the last invoices were 2024-0150, you can set initial_number=151.\nDefault value is 1.\nIt applies only to the first period in which the series issues an invoice: with\n`counter_reset: ANNUAL` or `MONTHLY`, every later year or month starts at 1. With\n`NEVER` there is a single period, so numbering simply continues from it.\n"
        },
        "active": {
          "type": "boolean",
          "default": true,
          "description": "Whether the series is active"
        },
        "default_series": {
          "type": "boolean",
          "default": false,
          "description": "Whether this is the default series for its document_type.\n\n**Auto-promotion:** the domain guarantees that, while at least one\nseries exists for a given `(document_type, environment)`, exactly one\nof them is the default. So if you create the **first** series of a\n`document_type` (no default exists yet for that type and environment),\nit is marked as default **even if you send `false`** — the response\nwill then return `default_series: true`. Send `true` to also unmark\nthe current default of that type.\n"
        }
      }
    },
    "DocumentType": {
      "type": "string",
      "enum": [
        "UNASSIGNED",
        "STANDARD",
        "SIMPLIFIED",
        "CORRECTIVE",
        "SIMPLIFIED_CORRECTIVE",
        "PROFORMA"
      ],
      "description": "Document type associated with a series. Values mirror `InvoiceType`,\nso the series a document needs is named exactly like the document:\n- UNASSIGNED: Legacy value of series created before types existed. A series numbers only\n  documents of its own type, so an `UNASSIGNED` series numbers none\n  (`422 SERIES_INCOMPATIBLE_DOC_TYPE`); give it a type to keep using it. No series can be\n  created with it or moved to it (`422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED`). The live\n  ones were given the type they numbered most.\n- STANDARD: Standard invoice\n- SIMPLIFIED: Simplified invoice\n- CORRECTIVE: Corrects or cancels a previous standard invoice (R1–R4)\n- SIMPLIFIED_CORRECTIVE: Corrects a simplified invoice (R5). Spanish law requires R5 to be\n  numbered apart from R1–R4, so they have a series type of their own\n- PROFORMA: Proforma (commercial document, non-fiscal numbering)\n"
    },
    "SeriesCode": {
      "type": "string",
      "pattern": "^[A-Z0-9\\-_]{1,50}$",
      "minLength": 1,
      "maxLength": 50,
      "description": "Alphanumeric series code (used in {CODIGO} variable).\nAllows uppercase letters, numbers, hyphens and underscores.\n"
    },
    "SeriesFormat": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^[A-Z0-9\\-_/{}:]*$",
      "description": "Format template with available variables (UPPERCASE ONLY):\n- {CODIGO}: Series code (e.g., \"FAC\")\n- {YYYY}: Year with 4 digits (e.g., \"2025\")\n- {YY}: Year with 2 digits (e.g., \"25\")\n- {MM}: Month with 2 digits (e.g., \"01\")\n- {NUM}: Sequential number without padding (e.g., \"1\")\n- {NUM:X}: Sequential number with padding (e.g., {NUM:4} → \"0001\")\n\n**REQUIRED**: Must contain at least {NUM} or {NUM:X}\n**IMPORTANT**: Only uppercase (rejects {yy}, {mm}, {codigo}, etc.)\n\nValid examples:\n- \"{CODIGO}-{YYYY}-{NUM:4}\" → \"FAC-2025-0001\"\n- \"{CODIGO}/{NUM:6}\" → \"FAC/000001\"\n- \"{YYYY}{MM}-{NUM:3}\" → \"202501-001\"\n\nThe generated number is the invoice number sent to the AEAT, which accepts at most 60\nprintable ASCII characters and none of `\"`, `'`, `<`, `>`, `=`. A format whose longest\npossible number breaks that rule is rejected with `422 SERIES_FORMAT_NUMBER_TOO_LONG` or\n`SERIES_FORMAT_INVALID_CHARACTERS`. The counter counts as at least 9 digits, with or without\npadding: `{NUM:X}` is a minimum width, not a maximum.\n"
    }
  }
}