{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-customer-schema.json",
  "title": "Customer",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beel-es-companycustomers-api-openapi.yml#/components/schemas/Customer",
  "type": "object",
  "required": [
    "id",
    "legal_name",
    "address",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "legal_name": {
      "type": "string"
    },
    "trade_name": {
      "type": "string"
    },
    "nif": {
      "$ref": "#/$defs/NIF"
    },
    "address": {
      "allOf": [
        {
          "$ref": "#/$defs/AddressResponse"
        }
      ],
      "description": "Customer address as stored. Read shape: records registered before the street number\nwas collected have none, so no field is guaranteed.\n"
    },
    "phone": {
      "$ref": "#/$defs/Phone"
    },
    "email": {
      "type": [
        "string",
        "null"
      ],
      "format": "email",
      "minLength": 5,
      "maxLength": 255,
      "description": "Main contact address (minimum valid email is 5 chars, e.g. a@b.co). Invoice emails go\nhere only when the customer has no `billing_emails`.\n"
    },
    "website": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 255,
      "description": "Website URL",
      "pattern": "^(https?://.+|)$"
    },
    "billing_emails": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Email"
      },
      "description": "Addresses that receive the customer's invoice emails. When the send request names no\n`recipients` and the invoice has no `email_config` recipients, invoices go to these\naddresses, and not to `email`; `email` is used only when `billing_emails` is empty.\n"
    },
    "contact_person": {
      "type": "string"
    },
    "notes": {
      "type": "string",
      "maxLength": 1000
    },
    "preferred_payment_method": {
      "$ref": "#/$defs/PaymentInfo"
    },
    "general_discount": {
      "type": "number",
      "minimum": 0,
      "maximum": 100,
      "default": 0
    },
    "active": {
      "type": "boolean",
      "default": true
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "alternative_id": {
      "$ref": "#/$defs/AlternativeIdentifier"
    }
  },
  "$defs": {
    "AddressResponse": {
      "type": "object",
      "description": "An address as stored. Nothing is guaranteed: the address of a company created by signup\nis empty until onboarding fills it in, so every field may be absent. `Address` (the\nrequest shape) does require them — that is a rule of admission, not a fact about what\nis stored.\n",
      "properties": {
        "street": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Full address (street, number, floor, etc.)"
        },
        "number": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20,
          "description": "Street number. Absent when the stored address has none."
        },
        "floor": {
          "type": "string",
          "maxLength": 10,
          "description": "Floor or level"
        },
        "door": {
          "type": "string",
          "maxLength": 10,
          "description": "Door or apartment"
        },
        "postal_code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20,
          "description": "Postal code (5 digits for Spain, free format for other countries)"
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "City or town"
        },
        "province": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Province or state. Outside Spain an address may have none."
        },
        "country": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Country name: the Spanish name derived from `country_code`. Addresses stored before\nthe country was validated may hold the name as it was sent.\n"
        },
        "country_code": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "minLength": 2,
          "maxLength": 2,
          "description": "ISO 3166-1 alpha-2 country code"
        }
      }
    },
    "AlternativeIdentifier": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "type",
        "number"
      ],
      "description": "Alternative identifier for customers without Spanish Tax ID.\n\n### VeriFactu rules (checked when you send it, `422` on violation)\n- `country_code` is required, except for `PASSPORT` (03) and `NOT_REGISTERED` (07), the two\n  types AEAT accepts with `ES`: omitted, `ES` applies. Missing for any other type, the\n  identifier is rejected with `ALTERNATIVE_ID_COUNTRY_REQUIRED`, and `error.details` names\n  the field where it was sent: `alternative_id.country_code` on a customer,\n  `recipient.alternative_id.country_code` on an invoice recipient. Same code in both.\n- If `country_code = ES`, then `type` **must** be `PASSPORT` (03) or `NOT_REGISTERED` (07)\n  (`ALTERNATIVE_ID_SPAIN_INVALID_TYPE`).\n- If `type = NOT_REGISTERED` (07), then `country_code` **must** be `ES`\n  (`ALTERNATIVE_ID_REQUIRES_SPAIN`), and `number` **must** be a Spanish DNI or NIE: a\n  Spanish company is always registered (`RECIPIENT_UNREGISTERED_ID_MUST_BE_DNI_OR_NIE`).\n  That DNI or NIE must not be one the AEAT census identifies: if it is, the identifier is\n  rejected with `ALTERNATIVE_ID_ACTUALLY_IN_CENSUS` and has to be sent as `nif`. A customer\n  is checked when it is saved; an invoice recipient, when the invoice is issued with\n  VeriFactu. If the census does not answer, the identifier is not rejected.\n- If `type = NIF_IVA` (02), `country_code` **must** be an EU member state other than Spain\n  (`ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY`), and `number` **must** have that country's\n  EU VAT number structure as AEAT defines it: the country prefix (`EL` for Greece) followed\n  by the national number, e.g. `FR40303265045`, `DE123456789`, `EL094014201`\n  (`ALTERNATIVE_ID_VAT_INVALID_FORMAT`). Lowercase letters are accepted and stored in\n  uppercase. A customer from outside the EU is identified with another type, such as\n  `OTHER_DOCUMENT` or `COUNTRY_ID`.\n\nA `number` that is blank once trimmed is rejected with `ALTERNATIVE_ID_INVALID`.\n\nWell-formed is not the same as registered: an EU VAT number that is not in the VIES\ncensus is still rejected by VeriFactu after the invoice is issued.\n\nAn identifier returned in a response is the one stored. A customer saved before a rule\nexisted keeps its identifier and can still be read; issuing an invoice to it with an\nidentifier that breaks these rules is rejected with the same code, before a number is used.\n\n### Matrix of allowed combinations\n| `type`                 | `country_code = ES` | `country_code ≠ ES` |\n|------------------------|:-------------------:|:-------------------:|\n| `NIF_IVA` (02)         | ✗                   | EU member states only |\n| `PASSPORT` (03)        | ✓                   | ✓                   |\n| `COUNTRY_ID` (04)      | ✗                   | ✓                   |\n| `RESIDENCE_CERTIFICATE` (05) | ✗             | ✓                   |\n| `OTHER_DOCUMENT` (06)  | ✗                   | ✓                   |\n| `NOT_REGISTERED` (07)  | ✓                   | ✗                   |\n",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "NIF_IVA",
            "PASSPORT",
            "COUNTRY_ID",
            "RESIDENCE_CERTIFICATE",
            "OTHER_DOCUMENT",
            "NOT_REGISTERED",
            "02",
            "03",
            "04",
            "05",
            "06",
            "07"
          ],
          "description": "Identifier type. Use descriptive names:\n- **NIF_IVA**: EU VAT number (intra-community) — *only for an EU member state other than Spain, with that country's VAT number structure*\n- **PASSPORT**: Passport — *allowed for any country*\n- **COUNTRY_ID**: Country of residence ID — *not allowed when `country_code = ES`*\n- **RESIDENCE_CERTIFICATE**: Residence certificate — *not allowed when `country_code = ES`*\n- **OTHER_DOCUMENT**: Other supporting document — *not allowed when `country_code = ES`*\n- **NOT_REGISTERED**: Not registered in AEAT — *requires `country_code = ES`*\n\n**⚠️ DEPRECATED numeric codes** (will be removed in v2):\n02, 03, 04, 05, 06, 07 — use the descriptive names above instead.\n"
        },
        "number": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20,
          "description": "Identifier number. For `NIF_IVA`, the full EU VAT number with its country prefix\n(e.g. `FR40303265045`); see the VeriFactu rules on the parent schema.\n"
        },
        "country_code": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "minLength": 2,
          "maxLength": 2,
          "description": "ISO 3166-1 alpha-2 code of the country that issued the document. Required except for\n`PASSPORT` and `NOT_REGISTERED`, where omitting it means `ES`. Constrains the allowed\n`type` values; see the VeriFactu rules on the parent schema.\n"
        }
      }
    },
    "Email": {
      "type": "string",
      "format": "email",
      "minLength": 5,
      "maxLength": 255,
      "description": "Email address (minimum valid email is 5 chars, e.g. a@b.co)"
    },
    "IBAN": {
      "type": "string",
      "pattern": "^[A-Z]{2}\\d{2}[A-Z0-9]{1,30}$",
      "minLength": 15,
      "maxLength": 34,
      "description": "IBAN (International Bank Account Number).\nRequired when payment method is BANK_TRANSFER.\n"
    },
    "NIF": {
      "type": "string",
      "pattern": "^(\\d{8}[A-Z]|[ABCDEFGHJKLMNPQRSUVW]\\d{7}[A-Z0-9]|[XYZ]\\d{7}[A-Z])$",
      "minLength": 9,
      "maxLength": 9,
      "description": "Spanish Tax ID (9 characters, uppercase only). Structural validation:\n- DNI: 8 digits + 1 letter (e.g., 12345678A)\n- NIE: X/Y/Z + 7 digits + 1 letter (e.g., X1234567A)\n- CIF: Organization letter + 7 digits + 1 control digit/letter (e.g., B12345674)\n"
    },
    "PaymentInfo": {
      "type": "object",
      "properties": {
        "method": {
          "allOf": [
            {
              "$ref": "#/$defs/PaymentMethod"
            }
          ],
          "description": "Preferred payment method. Omitted, `BANK_TRANSFER` applies.\nIf NONE is selected, no payment information will be shown on the invoice.\n"
        },
        "iban": {
          "$ref": "#/$defs/IBAN"
        },
        "swift": {
          "$ref": "#/$defs/SWIFT"
        },
        "payment_term_days": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "maximum": 365,
          "description": "Payment term in days. When marking an invoice as paid, every field of this object\nthat travels replaces the stored one and every omitted field keeps its current value.\n"
        }
      }
    },
    "PaymentMethod": {
      "type": "string",
      "description": "Payment method shown on invoices and recurring invoices.\n\n- `NONE`: no payment information is shown.\n- `BANK_TRANSFER`: bank transfer to the IBAN of the payment details; the only method\n  that requires an IBAN.\n- `CARD`: card payment.\n- `CASH`: cash payment.\n- `CHECK`: payment by cheque.\n- `DIRECT_DEBIT`: direct debit from the customer's bank account.\n- `BIZUM`: payment through Bizum.\n- `OTHER`: any other method.\n",
      "enum": [
        "NONE",
        "BANK_TRANSFER",
        "CARD",
        "CASH",
        "CHECK",
        "DIRECT_DEBIT",
        "BIZUM",
        "OTHER"
      ]
    },
    "Phone": {
      "type": "string",
      "maxLength": 20,
      "description": "A phone number, as the record holds it: digits, spaces, dashes, parentheses and an\noptional leading `+`, up to 20 characters.\n\nThis is the schema a **response** carries, and the length above is the only rule it\nstates. It deliberately does not repeat the character rule, because a number can reach a\nrecord through a path that predates that rule or never passed through this API at all —\na payment provider's customer data, a bulk import. Read the field defensively and do not\nassume it parses.\n\nWhat a **request** has to satisfy is `PhoneInput`, which adds the rules this API enforces\non the way in.\n"
    },
    "SWIFT": {
      "type": "string",
      "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$",
      "minLength": 8,
      "maxLength": 11,
      "description": "SWIFT/BIC code"
    }
  }
}