{
  "openapi": "3.0.3",
  "info": {
    "title": "معتمد آسا — API نسخه ۲",
    "version": "1.0.0.213",
    "description": "Machine-readable description of ASA API v2, generated from the code. The human documentation, with the full field rules, is at https://api-v2.asatsp.ir/docs/."
  },
  "servers": [
    {
      "url": "https://api-v2.asatsp.ir"
    }
  ],
  "tags": [
    {
      "name": "احراز هویت"
    },
    {
      "name": "داده‌های مرجع و دسترسی"
    },
    {
      "name": "ثبت مشتری"
    },
    {
      "name": "صورتحساب"
    },
    {
      "name": "کارگزاران"
    },
    {
      "name": "کارپوشه مالیاتی"
    },
    {
      "name": "استعلام پرونده مالیاتی"
    }
  ],
  "paths": {
    "/api/auth/v2/token": {
      "post": {
        "tags": [
          "احراز هویت"
        ],
        "summary": "Exchanges client credentials (client_credentials grant) for a one-hour bearer JWT.",
        "operationId": "AuthV2_Token_post",
        "security": [],
        "description": "AllowAnonymous. client.LastUsedAt is updated on success. Form-urlencoded binds too (see auth.tokenEndpoint.requestFormat).\n\nError codes:\n- `https_required` (HTTP 400): plain http\n- `invalid_request` (HTTP 400): as Message of a Web API HttpError\n- `rate_limited` (HTTP 429): rate limit\n- `ip_not_allowed` (HTTP 403): IP restriction (code IP_NOT_ALLOWED)\n- `invalid_scope` (HTTP 403): scope malformed or not granted",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "description": "client_credentials (exact)"
                  },
                  "client_id": {
                    "type": "string",
                    "description": "v2-customer-{id} | v2-partner-{id}"
                  },
                  "client_secret": {
                    "type": "string"
                  },
                  "scope": {
                    "type": "string",
                    "description": "subset of the client's allowed scopes; empty = all"
                  }
                },
                "required": [
                  "grant_type",
                  "client_id",
                  "client_secret"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "credentials valid — oauth-style",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "type": "string"
                    },
                    "token_type": {
                      "type": "string",
                      "description": "Bearer"
                    },
                    "expires_in": {
                      "type": "integer",
                      "description": "seconds"
                    },
                    "scope": {
                      "type": "string",
                      "description": "Presence: alwaysNullable."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "not https — oauth-style | malformed request — web api default error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "https_required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "unknown client, wrong secret, revoked/inactive client or business (empty body) — other",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "403": {
            "description": "IP rule or scope — oauth-style",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "ip_not_allowed | invalid_scope"
                    },
                    "code": {
                      "type": "string",
                      "description": "IP_NOT_ALLOWED (ip_not_allowed only) Presence: omittedWhenNull."
                    },
                    "error_description": {
                      "type": "string",
                      "description": "ip_not_allowed only Presence: omittedWhenNull."
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "more than ServiceAuth:TokenRateLimitPerMinute (30) calls per minute for client_id + IP — oauth-style",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "rate_limited"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/v2/client-credentials": {
      "post": {
        "tags": [
          "احراز هویت"
        ],
        "summary": "Migration door: with the static Customer API key as bearer, creates (or, with rotate_secret, rotates) the business's v2 client credentials.",
        "operationId": "AuthV2_ClientCredentials_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "AllowAnonymous attribute, but authenticated by V2AuthService.AuthenticateLegacyForCredentials (the bearer is always read as a static key, never as a JWT). Adds Deprecation/Sunset/Warning headers. Becomes useless after the sunset.\n\nError codes:\n- `https_required` (HTTP 400): plain http\n- `invalid_request` (HTTP 400): body or credential_type missing (HttpError Message)\n- `invalid_credential_type` (HTTP 400): credential_type not customer/partner (HttpError Message)\n- `invalid_legacy_api_key` (HTTP 401): refused static key, partner kind, after the sunset, or IP refusal\n- `client_revoked` (HTTP 409): the credential is revoked or switched off",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "credential_type": {
                    "type": "string",
                    "description": "customer | partner (case-insensitive); partner is always refused since the static Partner key was removed"
                  },
                  "rotate_secret": {
                    "type": "boolean",
                    "description": "true issues a new client_secret for an existing client; default false"
                  },
                  "token": {
                    "type": "string",
                    "description": "agency token appended to the static key when looking up the business"
                  }
                },
                "required": [
                  "credential_type"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "static key valid before the sunset — oauth-style",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "(see nestedTypes.V2ClientCredentialsResult)": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/V2ClientCredentialsResult"
                        }
                      ],
                      "description": "client_secret only when created or rotated now, else null with a warning"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "not https — oauth-style | credential_type missing or unknown — web api default error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "https_required"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "the bearer is not an accepted static Customer key — oauth-style",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "invalid_legacy_api_key"
                    },
                    "message": {
                      "type": "string",
                      "description": "reason (no header, partner key removed, key expired, key unknown) Presence: alwaysNullable."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "the IP rule («محدودیت IP») refused the caller; the same body as /api/auth/v2/token (401 until 1.0.0.209) — oauth-style",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "ip_not_allowed"
                    },
                    "code": {
                      "type": "string",
                      "description": "IP_NOT_ALLOWED"
                    },
                    "error_description": {
                      "type": "string",
                      "description": "the IP refusal text"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "the credential is revoked or switched off; a static key never brings it back (1.0.0.199) — other",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "client_revoked"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/Currency": {
      "get": {
        "tags": [
          "داده‌های مرجع و دسترسی"
        ],
        "summary": "Lists the currency codes the system knows, code to display name.",
        "operationId": "Currency_Get_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.lookup.read`.\n\nAttribute-routed ([RoutePrefix(api/Currency)] + [Route(\"\")]), path case-insensitive. Not reachable as api/Currency/{id}: the conventional route matches that URL but an attribute-routed action is never selected by a conventional route, so it answers 404 {Message} (isolated probe).\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate",
        "responses": {
          "200": {
            "description": "authenticated — bare lookup | authentication failed: result -1 like the other result routes (result 0 from the safe exception filter until 1.0.0.209) — result family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "<currency code>": {
                      "type": "string",
                      "description": "map: key = Currency.Code (trimmed, first row per code by CurrencyId), value = 'Name, PersianName' or whichever exists"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/InvoiceItemUnit": {
      "get": {
        "tags": [
          "داده‌های مرجع و دسترسی"
        ],
        "summary": "Lists the unit table by internal UnitId to name (legacy; prefer /codes).",
        "operationId": "InvoiceItemUnit_Get_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.lookup.read`.\n\nInternal UnitIds are not the official codes; several ids equal another unit's official code (InvoiceController.cs:2739-2743). ToDictionary would throw on duplicate UnitId (not expected, primary key).\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate",
        "responses": {
          "200": {
            "description": "authenticated — bare lookup | authentication failed: result -1 like the other result routes (result 0 from the safe exception filter until 1.0.0.209) — result family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "<UnitId>": {
                      "type": "string",
                      "description": "map key = internal UnitId as text, value = Unit.Name"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/InvoiceItemUnit/codes": {
      "get": {
        "tags": [
          "داده‌های مرجع و دسترسی"
        ],
        "summary": "Lists the official unit codes (the value Body[].mu carries) with their names.",
        "operationId": "InvoiceItemUnit_GetCodes_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.lookup.read`.\n\nRows without a code are left out; a code held twice is listed once (first UnitId).\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate",
        "responses": {
          "200": {
            "description": "authenticated — bare lookup | authentication failed: result -1 like the other result routes (result 0 from the safe exception filter until 1.0.0.209) — result family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "official code (digits), numeric order"
                    },
                    "name": {
                      "type": "string",
                      "description": "Presence: alwaysNullable."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/stuffid/{code}": {
      "get": {
        "tags": [
          "داده‌های مرجع و دسترسی"
        ],
        "summary": "Looks up one goods/service id of the tax organisation's central catalogue (description, VAT rate, taxable).",
        "operationId": "StuffIdV2_Get_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.lookup.read`.\n\nUses the backend's StuffidController.CreateCentralCatalogController().GetAsync. Extra path segments (api/v2/stuffid/x/y) fall to the catch-all 404 ROUTE_NOT_FOUND (tests).\n\nError codes:\n- `INVALID_STUFFID` (HTTP 400): code not 13 digits after normalisation\n- `STUFFID_NOT_FOUND` (HTTP 404): not in the catalogue\n- `STUFFID_UNAVAILABLE` (HTTP 502): catalogue error\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Persian/Arabic digits are converted and non-digits dropped; the result must be 13 digits"
          }
        ],
        "responses": {
          "200": {
            "description": "found — result/code family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "integer",
                      "description": "1"
                    },
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/StuffIdV2Data"
                        }
                      ],
                      "description": "see nestedTypes.StuffIdV2Data"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "not 13 digits — result/code family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "integer",
                      "description": "0"
                    },
                    "code": {
                      "type": "string",
                      "description": "INVALID_STUFFID"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "authentication failed (403 when forbidden: wrong kind, scope or IP) — result/code family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "integer",
                      "description": "-1"
                    },
                    "code": {
                      "type": "string",
                      "description": "auth.ErrorCode, usually null Presence: alwaysNullable."
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "STUFFID_NOT_FOUND — result/code family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "502": {
            "description": "STUFFID_UNAVAILABLE: catalogue answered a non-404 HttpResponseException — result/code family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/client/ip-access": {
      "get": {
        "tags": [
          "داده‌های مرجع و دسترسی"
        ],
        "summary": "Reads the calling client's IP restriction, the address ASA sees it at and recent refusals.",
        "operationId": "ClientAccessV2_Get_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Any valid customer token (no scope checked: AuthenticateCustomer(db, null)).\n\nError codes:\n- `CLIENT_CREDENTIALS_REQUIRED` (HTTP 403): legacy static key or no client id\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule",
        "responses": {
          "200": {
            "description": "client credentials token — result/code family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "integer",
                      "description": "1"
                    },
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/IpAccessV2Data"
                        }
                      ],
                      "description": "see nestedTypes.IpAccessV2Data"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "authentication failed (403 when forbidden) — result/code family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "integer",
                      "description": "-1"
                    },
                    "code": {
                      "type": "string",
                      "description": "Presence: alwaysNullable."
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "CLIENT_CREDENTIALS_REQUIRED: static key used — result/code family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/client/ip-access/lock": {
      "post": {
        "tags": [
          "داده‌های مرجع و دسترسی"
        ],
        "summary": "Adds the caller's public address to the client's IP list and turns the rule on (never removes an address).",
        "operationId": "ClientAccessV2_Lock_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "No body is read.\n\nError codes:\n- `INVALID_IP_ACCESS` (HTTP 400): ApiClientAccessException (MegaPayBackend/Services/Auth/ApiClientAccess.cs:130-172)\n- `CLIENT_CREDENTIALS_REQUIRED` (HTTP 403): legacy static key\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule already excludes the caller",
        "responses": {
          "200": {
            "description": "locked — result/code family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "integer",
                      "description": "1"
                    },
                    "data": {
                      "$ref": "#/components/schemas/IpAccessV2Data"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "caller address not public/readable, rule switched off in the panel, or list full — result/code family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "integer",
                      "description": "0"
                    },
                    "code": {
                      "type": "string",
                      "description": "INVALID_IP_ACCESS"
                    },
                    "field": {
                      "type": "string",
                      "description": "callerIp | enabled | allowedIps"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "authentication failed (403 forbidden / CLIENT_CREDENTIALS_REQUIRED as for GET) — result/code family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/register": {
      "post": {
        "tags": [
          "ثبت مشتری"
        ],
        "summary": "A partner registers (or updates) a business by economic code and fiscal memory id and receives that business's v2 customer credentials.",
        "operationId": "Register_Register_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nProduction fiscal ids also get taxFileState/taxFileStatus/taxFileStatusTitle/taxFileMessage (tax-file inquiry). customerApiKey is always null since 1.0.0.107. A partner not yet in «همکاران API» passes PartnerAccess.Refusal (registry is a restriction only).\n\nError codes:\n- `FISCAL_ID_INVALID` (HTTP 200): result 0: fiscal id not active or of another economic code\n- `FISCAL_ID_INQUIRY_UNAVAILABLE` (HTTP 200): result 0: the inquiry did not run (TaxV2Host error, timeout)\n- `business_registered_elsewhere` (HTTP 200): result -2: an existing business this partner did not bring\n- `partner_suspended` (HTTP 200): result -1: partner registered in «همکاران API» but suspended (PartnerAccess.Refusal)\n- `capability_disabled` (HTTP 200): result -1: directRegister not enabled for the partner",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "integer",
                    "description": "UserType 1 person, 2 company, 3 mosharekat (civil partnership), 4 atba (foreign national); not validated. Omitted or null: a new business is saved with 0, an existing one keeps its type"
                  },
                  "fiscalId": {
                    "type": "string",
                    "description": "6 letters/digits (normalised to upper case; other values throw and answer result 0); must be ACTIVE at the organisation and belong to economicCode (TaxV2Host inquiry type 1)"
                  },
                  "economicCode": {
                    "type": "string",
                    "description": "matched digit by digit against the fiscal memory's economic code"
                  },
                  "name": {
                    "type": "string",
                    "description": "the default print template's company name"
                  },
                  "nationalCode": {
                    "type": "string",
                    "description": "omitted or null: an existing business keeps it; a value sent (even \"\") replaces it"
                  },
                  "mobile": {
                    "type": "string",
                    "description": "saved as the first user's confirmed mobile; not validated"
                  },
                  "autoSend": {
                    "type": "boolean",
                    "description": "omitted or null: a new business gets true, an existing one keeps its setting"
                  },
                  "valueAddedNotCalled": {
                    "type": "boolean",
                    "description": "true: business not VAT-registered (isVatable=false); null leaves it"
                  },
                  "sandBox": {
                    "type": "boolean",
                    "description": "true registers the fiscal memory for the sandbox; default production"
                  }
                },
                "required": [
                  "fiscalId",
                  "economicCode"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always (result says the outcome; an update that changes nothing is result 2, one that changes a field is 3) — register family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "(see nestedTypes.RegisterReturnData)": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/RegisterReturnData"
                        }
                      ],
                      "description": "data.serviceAuth carries client_id and, only when the client was created now, client_secret"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/send": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Registers 1 to 250 invoices written in the tax organisation's JSON (Header, Body, Payments) and queues each for sending according to send.",
        "operationId": "Invoice_Send_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nValidation runs twice: before authentication (structure) and with the company (V7.9 switches). In production the validator reads the bound model re-serialized, not the raw body (serializer.notes); exr keeps its decimals from the buffered body. Cancellations (Header.ins=3): Body optional; under V7.9 for the company every field outside the cancellation pattern (Body rows included) is dropped with a warning in warnings, and a missing setm takes the reference's settlement. Corrections and returns (ins 2/4): with strict V7.9 their out-of-pattern fields (buyer included) are dropped with a warning. Every referral first takes its chain's status from the organisation (PrepareReferral). A return's Body is the remaining rows (returnRows remaining, default) or the returned rows (returned); the server matches them to the reference. proforma=true registers a proforma: no fiscal memory, never sent, ins must be 1, no irtaxid, send must not be true. fiscalId (6 chars) / sandBox choose the fiscal memory; omitted send uses the business's API v2 auto-send setting. Type-1 original invoices whose pattern needs a buyer must give a buyer the backend can register (tob/tinb/bid/bpc).\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `V79_REQUIRED` (HTTP 200): strict V7.9 matrix: required field missing (only when InvoiceRules.V79.Enabled/StrictValidation are on for the company and pattern)\n- `V79_OUT_OF_PATTERN` (HTTP 200): field outside the pattern (matrix, or pattern 11 lists regardless of the flags)\n- `V79_CONTEXT_INVALID` (HTTP 200): type/pattern/subject/settlement/buyer combination invalid per the V7.9 engine\n- `V79_BODY_MAX_ONE` (HTTP 200): pattern 11 issue (always) or pattern 14 under strict V7.9: more than one Body row\n- `V79_AMOUNT_MUST_BE_ONE` (HTTP 200): strict V7.9, patterns 6 and 8: am must be 1\n- `V79_VAT_RATE_MUST_BE_ZERO` (HTTP 200): pattern 11: vra must be 0\n- `V79_VAT_AMOUNT_MUST_BE_ZERO` (HTTP 200): pattern 11: vam must be 0\n- `V79_SUBJECT_NOT_ALLOWED` (HTTP 200): pattern 11: ins=4 not allowed\n- `V79_CANCELLATION_BODY_OUT_OF_PATTERN` (HTTP 200): strict V7.9: cancellation with Body rows (normally the rows are dropped first with a warning)\n- `ARTICLE9_REGISTER_WITHOUT_SEND_RULE` (HTTP 200): indati2m sent without insr=1\n- `ARTICLE9_FEATURE_DISABLED` (HTTP 200): insr=1 while InvoiceRules.V79.Article9Enabled is off for the company\n- `ARTICLE9_INVOICE_TYPE_NOT_ALLOWED` (HTTP 200): Article 9 only for type 1 and 2\n- `ARTICLE9_INVOICE_SUBJECT_NOT_ALLOWED` (HTTP 200): Article 9 subject not valid\n- `ARTICLE9_REGISTER_REQUIRED` (HTTP 200): insr=1 without indati2m\n- `ARTICLE9_REGISTER_BEFORE_ISSUE` (HTTP 200): indati2m before indatim\n- `ARTICLE9_REGISTER_IN_FUTURE` (HTTP 200): indati2m in the future\n- `SHIPMENT_COUNTRY_REQUIRED` (HTTP 200): pattern 8: ocu/dco missing (simple model) — ShipmentLocationCoding\n- `SHIPMENT_COUNTRY_NOT_IN_CODING` (HTTP 200): pattern 8: country code not in the V7.9 appendix\n- `SHIPMENT_CITY_REQUIRED` (HTTP 200): pattern 8: Iran (033) needs a city code\n- `SHIPMENT_CITY_NOT_IN_CODING` (HTTP 200): pattern 8: city code not in the appendix\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "uuid": {
                    "type": "string",
                    "description": "GUID, max 64 chars; unique per business (see idempotency)"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/InvoiceApiRequestData"
                    },
                    "description": "1..250 members, each validated and saved independently"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean",
                    "description": "multi-invoice request: also ask the tax files of type-2 buyers (within the five-national-code budget)"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always, also for validation and authentication failures — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "(see nestedTypes.InvoiceApiReturnData)": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/InvoiceApiReturnData"
                        }
                      ],
                      "description": "data has one InvoiceApiReturnInfo per member, in order: a saved invoice as the inquiry describes it (plus warnings), a refused member with status 3 and error [path: message]"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "IP gate — result/code family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "415": {
            "description": "Content-Type not json/xml/form — web api default error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/salesWithBuyerData": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-1 sale invoices (pattern 1) with buyer.",
        "operationId": "Invoice_SalesWithBuyerData_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nSimple model: the server builds the official JSON (BuildClassicTaxInvoice, InvoiceController.cs:2095-2249) and computes every amount with floor: prdis=floor(qty*unitPrice), dis=floor(discount), adis=max(0,prdis-dis), vam=floor(vatBase*vatRate/100), odam=floor(adis*otherTaxRate/100), olam=floor(adis*govTaxRate/100), tsstam=adis+vam+odam+olam; header totals are the sums; settlement 1: cap=tbill, 2: insp=tbill, 3: cap=floor(payment) capped at tbill, insp=tbill-cap, tvop=floor(tvam*cap/tbill). The result is validated by the /send validator. The buyer is registered as a customer of the business. invoiceSubject 2/3/4 needs sourceInternalId or sourceTaxId (the chain's latest member is the reference) and the buyer object is still validated on this route. items are required for every subject (cancellation included). A row without stuffId whose items[].internalId names one of the business's goods takes that goods' stuffId, with a warning.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token for a combined static key; when empty the first non-empty data[].token is used"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer required (InvoiceBuyerRequirement type 1 pattern 1)"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "(see nestedTypes.InvoiceApiReturnData)": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/InvoiceApiReturnData"
                        }
                      ],
                      "description": "one data member per invoice, in order"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "IP gate — result/code family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/salesEndUser": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-2 sale invoices (pattern 1), buyer optional.",
        "operationId": "Invoice_SalesEndUser_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nAs salesWithBuyerData (type 2, pattern 1). A buyer, when given on an original invoice, is kept on the invoice; when it cannot be registered the invoice is saved without one and a warning says so (ResolveOptionalClassicBuyerId, InvoiceController.cs:2515-2552).\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token (or first data[].token)"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer optional"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/exchange": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-1 currency-sale invoices (pattern 2).",
        "operationId": "Invoice_Exchange_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nPattern 2 rules: items[].unit not required; currencyCode (or currency, max 3) and currencyRate > 0 required; currencyPurchaseRate > 0 and < currencyRate required; vatBaseAmount >= 0 required (sovat); unitPrice not sent as fee; the currency amount (cfee) is amountCurrency or else qty. buyer.passportNumber is accepted only here, with buyer.type 4, max 9 Latin letters/digits. declarationNo (1-14 digits) and officeCode (5 digits) optional.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer required"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/jewelry": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-1 gold, jewellery and platinum invoices (pattern 3).",
        "operationId": "Invoice_Jewelry_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nPattern 3: items[].wage, profit, commission required and >= 0 (consfee, spro, bros = floor; tcpbs = floor(sum)); carat is sent as cui.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer required"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/contracting": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-1 contracting invoices (pattern 4).",
        "operationId": "Invoice_Contracting_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nPattern 4: data[].contractCode required, exactly 12 digits (Header.crn).\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer required; contractCode required"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/utilityBill": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-1 utility-bill invoices (pattern 5).",
        "operationId": "Invoice_UtilityBill_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nPattern 5: data[].billNo required, 1-19 digits (Header.billid). The currency-amount check is skipped for this pattern. Strict V7.9 for pattern 5 additionally depends on InvoiceRules.V79.Pattern5Enabled.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer required; billNo required"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/flightTicket": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-1 airline-ticket invoices (pattern 6).",
        "operationId": "Invoice_FlightTicket_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nPattern 6: data[].flightInfo required (see nestedTypes.ClassicFlightInfoData). Header.bid comes from flightInfo.nationalId, else foreignId, else buyer.nationalCode; tinb from flightInfo.economicCode when given; bpn = flightInfo.passportNumber; ft = flightType; tinc = agentEconomicCode. Strict V7.9: every Body am must be 1.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer required; flightInfo required"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/export": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-1 export invoices (pattern 7), buyer optional.",
        "operationId": "Invoice_ProductsExport_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nPattern 7: items[].netWeight > 0, currencyValue > 0, currencyCode and currencyRate > 0 required (nw, sscv, ssrv=adis; header torv=tadis, tocv=sum(sscv), tonw=sum(nw)); tprdis/tdis/tadis not sent; bpc not sent. cottageNo optional 1-14 digits, cottageDate needs cottageNo; officeCode optional 5 digits. The validation copy drops cfee/prdis/dis/adis (ClassicExportPayloadPolicy). Return from sale is not allowed for this pattern (V7.9 engine).\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer optional (InvoiceBuyerRequirement excludes pattern 7)"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/billOfLading": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-1 bill-of-lading (transport) invoices (pattern 8).",
        "operationId": "Invoice_BillOfLading_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nPattern 8: data[].shipmentInfo required (see nestedTypes.ClassicShipmentInfoData); maps to lno, lrno, ocu, oci, dco, dci, tid, rid, lt, cno, did, tonw, sg. Strict V7.9: am must be 1. Return from sale not allowed for this pattern.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)\n- `SHIPMENT_COUNTRY_REQUIRED` (HTTP 200): origin/destination country missing\n- `SHIPMENT_COUNTRY_NOT_IN_CODING` (HTTP 200): country code unknown\n- `SHIPMENT_CITY_REQUIRED` (HTTP 200): Iran without city\n- `SHIPMENT_CITY_NOT_IN_CODING` (HTTP 200): city code unknown",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer required; shipmentInfo required"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/oilProducts": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-1 petroleum refining/distribution invoices (pattern 9).",
        "operationId": "Invoice_OilProducts_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nPattern 9: items[].vatBaseAmount optional, >= 0; a positive value is the VAT base (Body vba) instead of adis.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer required"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/commoditySecurities": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-1 commodity-exchange invoices (pattern 11), buyer optional.",
        "operationId": "Invoice_CommoditySecurities_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nPattern 11: saleAnnNo required (1-30 digits, Header.asn); saleAnnDate required, not after dateTime (Header.asd as Unix day); invoiceSubject 4 not allowed; one item only; items[].amountAfterDiscount (integer rials > 0, the deal value of the announcement) or unitPrice required, amountAfterDiscount wins over floor(qty*unitPrice); vatRate must be 0; carat optional (0 = none; >0, <=1000, 2 decimals). settlement 3 sends the cash share as cash. The response's InvoiceApiReturnInfo carries exchangeAnnouncement. Strict V7.9 for pattern 11 depends on InvoiceRules.V79.Pattern11Enabled.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)\n- `V79_OUT_OF_PATTERN` (HTTP 200): contractCode, billNo, tax17, payments, items[].discount/otherTaxRate/govTaxRate/contractNo/currency fields given (InvoiceController.cs:1720-1730)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer optional (V7.9 matrix: tob/tinb/bid optional in 1/11)"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/insurance": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-1 insurance-service invoices (pattern 13).",
        "operationId": "Invoice_Insurance_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nPattern 13: insPolicyNo required 9-12 digits (Header.In); extInsPolicyNo optional 9-12 digits (Header.an).\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer required; insPolicyNo required"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/chainSale": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-1 chain-sale invoices (pattern 14).",
        "operationId": "Invoice_ChainSale_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nPattern 14: one item only.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer required"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/jewelryEndUser": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-2 gold/jewellery/platinum invoices (pattern 3), buyer optional.",
        "operationId": "Invoice_JewelryEndUser_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nType 2, pattern 3: wage/profit/commission required as for jewelry; buyer handling as salesEndUser.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer optional"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/oilProductsEndUser": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-2 petroleum invoices (pattern 9), buyer optional.",
        "operationId": "Invoice_OilProductsEndUser_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nType 2, pattern 9: vatBaseAmount as oilProducts.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer optional"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/insuranceEndUser": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration of type-2 insurance-service invoices (pattern 13), buyer optional.",
        "operationId": "Invoice_InsuranceEndUser_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nType 2, pattern 13: insPolicyNo/extInsPolicyNo as insurance.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer optional; insPolicyNo required"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/simple/type/{invoiceType}/template/{template}": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Simple-model registration for any allowed invoice type and pattern given in the path.",
        "operationId": "Invoice_SimpleByTypeTemplate_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nSame engine and rules as the named routes; the pattern rules of the chosen template apply (see the named route for each pattern).\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid already used by this business (an InvoiceLog row with the uuid); result -2 (Models/ApiValidationError.cs:28)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): an active invoice of this business already has the internalId (member error)\n- `INVOICE_INTERNAL_ID_REPEATED_IN_REQUEST` (HTTP 200): the same internalId twice in one request (member error)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction refused: the chain's exchange sale announcement is confirmed (only cancellation allowed)\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 correction refused: the announcement status could not be read\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): an earlier send of the invoice has an unknown outcome (AmbiguousSendClaimFence)\n- `BUYER_TAX_FILE_NOT_FOUND` (HTTP 200): type-1 invoice to a natural buyer given by national code only: the organisation has no tax file\n- `BUYER_TAX_FILE_AMBIGUOUS` (HTTP 200): the buyer's national code has several tax files\n- `BUYER_TAX_FILE_SERVICE_OFF` (HTTP 200): the business's tax-file inquiry service is off or unpaid\n- `BUYER_TAX_FILE_LIMIT` (HTTP 200): more than five buyer national codes would be asked in one request (BuyerTaxFileBatchBudget; checkTypeTwoBuyers widens who is asked)\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): deadlock, lock timeout or dropped connection while saving; the invoice was not refused: inquire, then resend that invoice alone with a new uuid\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): correction/cancellation/return: the reference chain's status does not allow it (field carries the backend reason code); the backend's own code (for example INVOICE_REFERENCE_STATUS_UNAVAILABLE) when the status could not be taken (InvoiceController.Referral.cs:29-73)\n- `INVOICE_REFERRAL_BUYER_MISMATCH` (HTTP 200): backend save rule (MegaPayBackend/Models/Invoice/InvoiceReferralBuyerPolicy.cs:17). On the batch routes only the message reaches the client (AddBatchItemException keeps codes only for the codes listed above); editInvoice keeps an exception's Data[Code] (InvoiceController.Edit.cs:704-715). Whether this exception sets Data[Code] was not traced.\n- `INVOICE_RETURN_REFERENCE_INVALID` (HTTP 200): return reference not found among the business's active invoices, still sending, or not registered (InvoiceController.Return.cs:122-146)\n- `INVOICE_RETURN_ROW_INVALID` (HTTP 200): a return row does not match the reference (goods id, unit price, VAT rate, contract, quantity, discount)\n- `INVOICE_RETURN_ROW_AMBIGUOUS` (HTTP 200): returnRows=returned: the goods id matches reference rows of different kinds\n- `INVOICE_RETURN_NOTHING_RETURNED` (HTTP 200): no row is reduced (remaining mode) / no returned quantity (returned mode)\n- `INVOICE_RETURN_NEEDS_CANCELLATION` (HTTP 200): nothing would remain: send a cancellation instead\n- `INVOICE_RETURN_ROWS_MODE_INVALID` (HTTP 200): returnRows not remaining|returned, or given on a non-return (validator)",
        "parameters": [
          {
            "name": "invoiceType",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "route constraint int; 1 or 2 else route.invoiceType error"
          },
          {
            "name": "template",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "route constraint int; type 1: 1,2,3,4,5,6,7,8,9,11,13,14; type 2: 1,3,9,13; else route.template error"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicInvoiceData"
                    },
                    "description": "1..250; buyer required when InvoiceBuyerRequirement.IsRequired(type, template): type 1 except patterns 7 and 11"
                  },
                  "checkTypeTwoBuyers": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always; a disallowed type/template is result 0 with errors path route.invoiceType / route.template — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          },
          "404": {
            "description": "non-integer path segment (int constraint fails, catch-all answers ROUTE_NOT_FOUND) — unhandled-error envelope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/sendInvoice": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Queues already registered, unsent invoices (named by internalId) for sending to the tax organisation.",
        "operationId": "Invoice_SendInvoiceByInternalIds_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nUses the backend's SendCompanyInvoicesAsync for the authenticated business. Lookup by internalId: InvoiceLog.LogInvoiceId = numeric value or InvoiceLog.Code = text.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 correction send refused\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 status unreadable\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): earlier send of unknown outcome",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token"
                  },
                  "internalIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "1 to 500; more are refused on $.internalIds before any send (1.0.0.209); each non-empty; the chain's latest version is sent"
                  }
                },
                "required": [
                  "internalIds"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "result 1 and data (one inquiry per internalId) when every id was found and queued; result 0 with errors when any id failed, and data for the ids that were queued or read (null when none; data was always null on result 0 until 1.0.0.209) — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/cancelInvoice": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Registers a cancellation (subject 3) of a registered invoice named by internalId, built from the stored reference.",
        "operationId": "Invoice_CancelInvoice_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.cancel`.\n\nOnly a sent invoice with a TaxId (phase 3 or 4) is cancellable. The issue time is derived from the reference (ResolveCancellationDateTime). When the chain ends in a cancellation the organisation refused (definitive failure), it is removed the panel's way first and the new cancellation is registered from the restored member.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_DUPLICATE_REQUEST` (HTTP 200): uuid used before (result -2)\n- `INVOICE_INTERNAL_ID_DUPLICATE` (HTTP 200): cancelInternalId used before (result -2)\n- `PREVIOUS_CANCELLATION_UNSENT` (HTTP 200): the chain already ends in an unsent cancellation: send it with sendInvoice\n- `PREVIOUS_CANCELLATION_PENDING` (HTTP 200): the previous cancellation is in sending or has no final answer\n- `FAILED_CANCELLATION_DELETE_NOT_ALLOWED` (HTTP 200): removal of a refused cancellation refused by the panel rule\n- `INVOICE_NOT_FOUND` (HTTP 200): removal: cancellation not found\n- `FAILED_CANCELLATION_REMOVED_NEW_NOT_REGISTERED` (HTTP 200): a refused cancellation was removed (stays removed) but the new one was not registered; the following errors say why\n- `INVOICE_REFERENCE_ACTION_NOT_ALLOWED` (HTTP 200): chain status does not allow cancellation (or the backend's INVOICE_REFERENCE_* / EXCHANGE_ANNOUNCEMENT_* code)\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): replacement save refused\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): replacement save transient failure",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID; new per call"
                  },
                  "internalId": {
                    "type": "string",
                    "description": "internalId of the invoice to cancel (the chain's current member is cancelled)"
                  },
                  "cancelInternalId": {
                    "type": "string",
                    "description": "internalId for the cancellation; default internalId + '-cancel'"
                  },
                  "description": {
                    "type": "string"
                  },
                  "send": {
                    "type": "boolean",
                    "description": "null = the business's API v2 auto-send setting"
                  }
                },
                "required": [
                  "uuid",
                  "internalId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "result 1 with data [the cancellation]; result 0/-2 with errors — result/errors family | chain preparation or the save threw on a normal cancellation for any other reason than an unknown earlier send or a transient database failure (those two answer result 0 with errors[].code INVOICE_SEND_RESULT_UNKNOWN / INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE on path $ or $.internalId, since 1.0.0.209) — safe-exception family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/editInvoice": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Edits an invoice with a full invoice in the organisation's JSON: a new draft version, an in-place payment change, or (with explicit consent) a correction invoice.",
        "operationId": "Invoice_EditInvoice_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nRaw body is read strictly: duplicate property names and wrong JSON types (non-string token/uuid/internalId/taxId/confirmationToken/description, non-boolean send/confirmCorrection, non-object data) are errors. Fiscal memory, buyer description, print template and attachments stay the invoice's. Header.tins must be the business's economic code.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `V79_REQUIRED` (HTTP 200): strict V7.9 matrix: required field missing (only when InvoiceRules.V79.Enabled/StrictValidation are on for the company and pattern)\n- `V79_OUT_OF_PATTERN` (HTTP 200): field outside the pattern (matrix, or pattern 11 lists regardless of the flags)\n- `V79_CONTEXT_INVALID` (HTTP 200): type/pattern/subject/settlement/buyer combination invalid per the V7.9 engine\n- `V79_BODY_MAX_ONE` (HTTP 200): pattern 11 issue (always) or pattern 14 under strict V7.9: more than one Body row\n- `V79_AMOUNT_MUST_BE_ONE` (HTTP 200): strict V7.9, patterns 6 and 8: am must be 1\n- `V79_VAT_RATE_MUST_BE_ZERO` (HTTP 200): pattern 11: vra must be 0\n- `V79_VAT_AMOUNT_MUST_BE_ZERO` (HTTP 200): pattern 11: vam must be 0\n- `V79_SUBJECT_NOT_ALLOWED` (HTTP 200): pattern 11: ins=4 not allowed\n- `V79_CANCELLATION_BODY_OUT_OF_PATTERN` (HTTP 200): strict V7.9: cancellation with Body rows (normally the rows are dropped first with a warning)\n- `ARTICLE9_REGISTER_WITHOUT_SEND_RULE` (HTTP 200): indati2m sent without insr=1\n- `ARTICLE9_FEATURE_DISABLED` (HTTP 200): insr=1 while InvoiceRules.V79.Article9Enabled is off for the company\n- `ARTICLE9_INVOICE_TYPE_NOT_ALLOWED` (HTTP 200): Article 9 only for type 1 and 2\n- `ARTICLE9_INVOICE_SUBJECT_NOT_ALLOWED` (HTTP 200): Article 9 subject not valid\n- `ARTICLE9_REGISTER_REQUIRED` (HTTP 200): insr=1 without indati2m\n- `ARTICLE9_REGISTER_BEFORE_ISSUE` (HTTP 200): indati2m before indatim\n- `ARTICLE9_REGISTER_IN_FUTURE` (HTTP 200): indati2m in the future\n- `SHIPMENT_COUNTRY_REQUIRED` (HTTP 200): pattern 8: ocu/dco missing (simple model) — ShipmentLocationCoding\n- `SHIPMENT_COUNTRY_NOT_IN_CODING` (HTTP 200): pattern 8: country code not in the V7.9 appendix\n- `SHIPMENT_CITY_REQUIRED` (HTTP 200): pattern 8: Iran (033) needs a city code\n- `SHIPMENT_CITY_NOT_IN_CODING` (HTTP 200): pattern 8: city code not in the appendix\n- `INVOICE_EDIT_DUPLICATE_REQUEST` (HTTP 200): uuid used before (result -2)\n- `INVOICE_NOT_FOUND` (HTTP 200): no invoice of the business with the internalId/taxId\n- `INVOICE_EDIT_NOT_CURRENT` (HTTP 200): not the chain's current active version, or a state that cannot be edited\n- `INVOICE_EDIT_CANCELLED` (HTTP 200): invoice cancelled\n- `INVOICE_EDIT_CANCELLATION` (HTTP 200): a cancellation invoice\n- `INVOICE_EDIT_SEND_IN_PROGRESS` (HTTP 200): in the send queue\n- `INVOICE_EDIT_RESULT_PENDING` (HTTP 200): sent, result not known\n- `INVOICE_EDIT_REFERENCE_NOT_ALLOWED` (HTTP 200): chain preparation refused (or the backend's own code, e.g. INVOICE_REFERENCE_STATUS_UNAVAILABLE)\n- `EXCHANGE_ANNOUNCEMENT_CONFIRMED` (HTTP 200): pattern-11 announcement confirmed: only cancellation\n- `EXCHANGE_ANNOUNCEMENT_STATUS_UNAVAILABLE` (HTTP 200): pattern-11 status unreadable\n- `INVOICE_EDIT_FIELD_NOT_CORRECTABLE` (HTTP 200): type, pattern, goods id or VAT rate differs from the reference (field names the field)\n- `INVOICE_CORRECTION_CONFIRMATION_REQUIRED` (HTTP 200): the change issues a correction and no consent was given; edit.reason FIELDS_CHANGED | SETTLEMENT_CHANGED | CHANGES_BESIDES_PAYMENT\n- `INVOICE_EDIT_CONFIRMATION_INVALID` (HTTP 200): malformed confirmationToken\n- `INVOICE_EDIT_CONFIRMATION_EXPIRED` (HTTP 200): token older than 15 minutes\n- `INVOICE_EDIT_CONFIRMATION_STALE` (HTTP 200): invoice changed since the token\n- `INVOICE_EDIT_CONFIRMATION_MISMATCH` (HTTP 200): content differs from the confirmed content\n- `INVOICE_SEND_RESULT_UNKNOWN` (HTTP 200): save refused\n- `INVOICE_DATABASE_TEMPORARILY_UNAVAILABLE` (HTTP 200): transient save failure\n- `INVOICE_EDIT_INTERNAL_ERROR` (HTTP 200): unexpected failure or unreadable body",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token; must be a JSON string"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID, unique per business"
                  },
                  "internalId": {
                    "type": "string",
                    "description": "exactly one of internalId or taxId; max 255 Conditionally required."
                  },
                  "taxId": {
                    "type": "string",
                    "description": "exactly one of internalId or taxId; 22 letters/digits Conditionally required."
                  },
                  "send": {
                    "type": "boolean",
                    "description": "null = auto-send setting"
                  },
                  "confirmCorrection": {
                    "type": "boolean",
                    "description": "true: issue the correction in this request if one is needed"
                  },
                  "confirmationToken": {
                    "type": "string",
                    "description": "max 200; the token of an earlier confirmationRequired answer (15 minutes)"
                  },
                  "description": {
                    "type": "string",
                    "description": "when absent the invoice's own description is kept"
                  },
                  "data": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/InvoiceDto"
                      }
                    ],
                    "description": "full invoice (Header, Body, Payments); validated like /send with Header.ins and irtaxid set by the server (the draft's own subject, or 2 with the registered TaxId)"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always; result 1 done, 0 refused or confirmationRequired (with edit.confirmationToken), -1 auth, -2 duplicate uuid — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "edit": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/InvoiceEditResult"
                        }
                      ],
                      "description": "outcome unchanged | draftUpdated | paymentUpdated | correctionIssued | confirmationRequired Presence: omittedWhenNull."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/simple/editInvoice": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Edits an invoice with a full simple-model invoice; type and pattern stay the invoice's.",
        "operationId": "Invoice_EditSimpleInvoice_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nUnlike the simple batch routes, the converted JSON's validation errors keep code, field and ruleVersion here (InvoiceController.Edit.cs:979-989). Body binding is the model binder's (no strict raw reading).\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `V79_REQUIRED` (HTTP 200): strict V7.9 matrix: required field missing (only when InvoiceRules.V79.Enabled/StrictValidation are on for the company and pattern)\n- `V79_OUT_OF_PATTERN` (HTTP 200): field outside the pattern (matrix, or pattern 11 lists regardless of the flags)\n- `V79_CONTEXT_INVALID` (HTTP 200): type/pattern/subject/settlement/buyer combination invalid per the V7.9 engine\n- `V79_BODY_MAX_ONE` (HTTP 200): pattern 11 issue (always) or pattern 14 under strict V7.9: more than one Body row\n- `V79_AMOUNT_MUST_BE_ONE` (HTTP 200): strict V7.9, patterns 6 and 8: am must be 1\n- `V79_VAT_RATE_MUST_BE_ZERO` (HTTP 200): pattern 11: vra must be 0\n- `V79_VAT_AMOUNT_MUST_BE_ZERO` (HTTP 200): pattern 11: vam must be 0\n- `V79_SUBJECT_NOT_ALLOWED` (HTTP 200): pattern 11: ins=4 not allowed\n- `V79_CANCELLATION_BODY_OUT_OF_PATTERN` (HTTP 200): strict V7.9: cancellation with Body rows (normally the rows are dropped first with a warning)\n- `ARTICLE9_REGISTER_WITHOUT_SEND_RULE` (HTTP 200): indati2m sent without insr=1\n- `ARTICLE9_FEATURE_DISABLED` (HTTP 200): insr=1 while InvoiceRules.V79.Article9Enabled is off for the company\n- `ARTICLE9_INVOICE_TYPE_NOT_ALLOWED` (HTTP 200): Article 9 only for type 1 and 2\n- `ARTICLE9_INVOICE_SUBJECT_NOT_ALLOWED` (HTTP 200): Article 9 subject not valid\n- `ARTICLE9_REGISTER_REQUIRED` (HTTP 200): insr=1 without indati2m\n- `ARTICLE9_REGISTER_BEFORE_ISSUE` (HTTP 200): indati2m before indatim\n- `ARTICLE9_REGISTER_IN_FUTURE` (HTTP 200): indati2m in the future\n- `SHIPMENT_COUNTRY_REQUIRED` (HTTP 200): pattern 8: ocu/dco missing (simple model) — ShipmentLocationCoding\n- `SHIPMENT_COUNTRY_NOT_IN_CODING` (HTTP 200): pattern 8: country code not in the V7.9 appendix\n- `SHIPMENT_CITY_REQUIRED` (HTTP 200): pattern 8: Iran (033) needs a city code\n- `SHIPMENT_CITY_NOT_IN_CODING` (HTTP 200): pattern 8: city code not in the appendix\n- `(as /api/invoice/editInvoice)` (HTTP 200): same INVOICE_EDIT_* and confirmation codes",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token (falls back to data.token)"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID"
                  },
                  "internalId": {
                    "type": "string",
                    "description": "exactly one of internalId or taxId; max 255 Conditionally required."
                  },
                  "taxId": {
                    "type": "string",
                    "description": "22 letters/digits Conditionally required."
                  },
                  "send": {
                    "type": "boolean"
                  },
                  "confirmCorrection": {
                    "type": "boolean"
                  },
                  "confirmationToken": {
                    "type": "string",
                    "description": "max 200"
                  },
                  "data": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/ClassicInvoiceData"
                      }
                    ],
                    "description": "full invoice; data.token, internalId, invoiceSubject, invoiceIssue, sourceInternalId, sourceTaxId, send, fiscalId, sandBox, fiscalMemoryId are overwritten by the server; pattern rules of the invoice's template apply; errors under $.data"
                  }
                },
                "required": [
                  "uuid",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "as editInvoice — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/inquiryExchangeAnnouncement": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Reads the exchange sale announcement confirmation status of a pattern-11 invoice chain.",
        "operationId": "Invoice_InquiryExchangeAnnouncement_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\ncanChange is forced false unless the token has v2.invoice.send (or is a legacy key). The chain's latest member is followed, never onto a cancellation.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `EXCHANGE_ANNOUNCEMENT_REQUEST_INVALID` (HTTP 200): neither or both of internalId/taxId\n- `INVOICE_NOT_FOUND` (HTTP 200): no such invoice for the business\n- `EXCHANGE_ANNOUNCEMENT_NOT_APPLICABLE` (HTTP 200): not a pattern-11 chain (backend InvoiceExchangeAnnouncementException; codes of InvoiceExchangeAnnouncementCodes pass through)\n- `EXCHANGE_ANNOUNCEMENT_FORBIDDEN` (HTTP 200): backend refusal",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token"
                  },
                  "internalId": {
                    "type": "string",
                    "description": "exactly one of internalId or taxId Conditionally required."
                  },
                  "taxId": {
                    "type": "string",
                    "description": "exactly one of internalId or taxId Conditionally required."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "exchangeAnnouncement": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/InvoiceExchangeAnnouncementStatusResult"
                        }
                      ],
                      "description": "on success; data is [] Presence: omittedWhenNull."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/exchangeAnnouncement": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Records manually whether a pattern-11 chain's exchange sale announcement is confirmed.",
        "operationId": "Invoice_SetExchangeAnnouncement_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nChannel recorded as ApiV2; actor client id (or legacy-company:{id}).\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `EXCHANGE_ANNOUNCEMENT_REQUEST_INVALID` (HTTP 200): target, confirmed, note length or expectedVersion invalid\n- `INVOICE_NOT_FOUND` (HTTP 200): no such invoice\n- `EXCHANGE_ANNOUNCEMENT_NOTE_REQUIRED` (HTTP 200): backend requires a note\n- `EXCHANGE_ANNOUNCEMENT_VERSION_CONFLICT` (HTTP 200): expectedVersion stale\n- `EXCHANGE_ANNOUNCEMENT_NOT_APPLICABLE` (HTTP 200): not a pattern-11 chain\n- `EXCHANGE_ANNOUNCEMENT_FORBIDDEN` (HTTP 200): backend refusal\n- `SUPPORT_SESSION_READ_ONLY` (HTTP 200): backend code (not expected from API v2)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token"
                  },
                  "internalId": {
                    "type": "string",
                    "description": "exactly one of internalId or taxId Conditionally required."
                  },
                  "taxId": {
                    "type": "string",
                    "description": "exactly one of internalId or taxId Conditionally required."
                  },
                  "confirmed": {
                    "type": "boolean",
                    "description": "true confirmed, false not confirmed"
                  },
                  "note": {
                    "type": "string",
                    "description": "max 500; the backend may require it (EXCHANGE_ANNOUNCEMENT_NOTE_REQUIRED; rule not traced) Conditionally required."
                  },
                  "expectedVersion": {
                    "type": "string",
                    "description": "the version of the last inquiry (base64 of 8 bytes) for optimistic concurrency"
                  }
                },
                "required": [
                  "confirmed"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "exchangeAnnouncement": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/InvoiceExchangeAnnouncementStatusResult"
                        }
                      ],
                      "description": "the stored status after the call Presence: omittedWhenNull."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/registerPayment": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Adds payments to the latest invoice of a sent chain and registers them with the tax organisation's payment service.",
        "operationId": "Invoice_RegisterPayment_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nThe new payments are saved in place on a new version with the same TaxId (InvoicePaymentRegistrationFacade.AddPaymentsAsync); rows the organisation holds are locked.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_PAYMENT_REGISTRATION_DISABLED` (HTTP 200): payment registration switched off\n- `INVOICE_PAYMENT_DUPLICATE_REQUEST` (HTTP 200): uuid used before (result -2)\n- `INVOICE_NOT_FOUND` (HTTP 200): no invoice with the internalId\n- `INVOICE_PAYMENT_NOT_APPLICABLE` (HTTP 200): invoice not eligible; field carries INVOICE_CANCELLED | INVOICE_NOT_SENT | INVOICE_NOT_APPROVED | INVOICE_WITHOUT_TAX_ID | PATTERN_WITHOUT_PAYMENTS | CASH_SETTLEMENT (InvoicePaymentTaxRegistrationPolicy.cs:150-176; list may not be exhaustive)\n- `INVOICE_PAYMENT_DATE_BEFORE_ISSUE` (HTTP 200): payment before the invoice date\n- `INVOICE_PAYMENT_DATE_IN_FUTURE` (HTTP 200): payment in the future (official error 10013)\n- `INVOICE_PAYMENT_ROW_LOCKED` (HTTP 200): save touched a row the organisation holds\n- `INVOICE_PAYMENT_INTERNAL_ERROR` (HTTP 200): unexpected failure",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token"
                  },
                  "uuid": {
                    "type": "string",
                    "description": "GUID, unique per business"
                  },
                  "internalId": {
                    "type": "string",
                    "description": "internalId of the chain (its latest member gets the payments)"
                  },
                  "payments": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ClassicPaymentData"
                    },
                    "description": "1..50; per row: type 1..8 required, price > 0 up to 18 integer digits required, dateTime required (not before the invoice, not in the future); terminalNumber <= 8 digits, traceNo <= 14, cardNo <= 16, payerNationalCode <= 12, switchNumber <= 9, acquirerNumber <= 14 (Persian digits accepted)"
                  }
                },
                "required": [
                  "uuid",
                  "internalId",
                  "payments"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data[0].paymentRegistration": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/InvoicePaymentRegistrationInfo"
                        }
                      ],
                      "description": "Presence: omittedWhenNull."
                    },
                    "data[0].payments": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InvoicePaymentApiInfo"
                      },
                      "description": "Presence: omittedWhenNull."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/inquiryPayment": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Reads the payment rows of a chain's latest invoice with each row's registration state at the tax organisation.",
        "operationId": "Invoice_InquiryPayment_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nNo live inquiry (liveInquiry false).\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 200): legacy key or JWT refused by the IP rule inside the controller: result -1, errors[0].code IP_NOT_ALLOWED (a JWT is normally stopped earlier by the IP gate with HTTP 403)\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate (Services/ApiClientIpGate.cs) before the controller, customer JWT only\n- `INVOICE_NOT_FOUND` (HTTP 200): no invoice\n- `INVOICE_PAYMENT_INTERNAL_ERROR` (HTTP 200): unexpected failure",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token"
                  },
                  "internalId": {
                    "type": "string"
                  }
                },
                "required": [
                  "internalId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always; data[0] carries paymentRegistration and payments — result/errors family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnData"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/inquiryInternalId": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Describes the current state of an invoice named by internalId.",
        "operationId": "Invoice_InqueryInternalId_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nThe chain's latest version is described (LatestInvoiceId). Live inquiry: a registered invoice (phase 3) whose buyer status is empty or AWAITING_REACTION is first asked again through the panel's status inquiry (TaxV2Host) and the refreshed row is described.\n\nError codes:\n- `IP_NOT_ALLOWED` (HTTP 403): IP gate",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token"
                  },
                  "internalId": {
                    "type": "string",
                    "description": "matched to InvoiceLog.LogInvoiceId (when numeric > 0) or InvoiceLog.Code"
                  }
                },
                "required": [
                  "internalId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always; not found / auth failure = status 3 with error — inquiry family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnInfo"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/inquiryInternalIds": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Batch form of inquiryInternalId.",
        "operationId": "Invoice_InqueryInternalIds_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nEach id may trigger a live inquiry.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token"
                  },
                  "internalIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "1..250"
                  }
                },
                "required": [
                  "internalIds"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always; one member per id in order, or a single error member for auth/batch-size failures — inquiry family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/InvoiceApiReturnInfo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/inquiryNo": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Describes an invoice named by its serial number.",
        "operationId": "Invoice_InqueryNo_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nPanel proformas are excluded; follows Invoice2 (latest version); internalId is not filled; live inquiry as inquiryInternalId.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token"
                  },
                  "no": {
                    "type": "string",
                    "description": "trimmed; numeric: Invoice.NoNum equals it; otherwise Invoice.No equals it (no prefix match since 1.0.0.209); of several invoices with the number the oldest is taken (as before), then its chain's latest version"
                  }
                },
                "required": [
                  "no"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always; the answer's no is the requested value — inquiry family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnInfo"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/inquiryNos": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Batch form of inquiryNo.",
        "operationId": "Invoice_InqueryNosAsync_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nSequential lookups.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token"
                  },
                  "nos": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "1..250; each matched as in inquiryNo (trimmed; numeric: Invoice.NoNum equals it; otherwise Invoice.No equals it (no prefix match since 1.0.0.209); of several invoices with the number the oldest is taken (as before), then its chain's latest version)"
                  }
                },
                "required": [
                  "nos"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — inquiry family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/InvoiceApiReturnInfo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/inquiryTaxId": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Describes an invoice of the business named by its tax id.",
        "operationId": "Invoice_InqueryTaxId_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nSeveral versions can share a TaxId; the first match is taken and its LatestInvoiceId followed. internalId not filled. Live inquiry as inquiryInternalId.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token"
                  },
                  "taxId": {
                    "type": "string",
                    "description": "exact match within the authenticated business (since 2026-10-19)"
                  }
                },
                "required": [
                  "taxId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — inquiry family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceApiReturnInfo"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/inquiryTaxIds": {
      "post": {
        "tags": [
          "صورتحساب"
        ],
        "summary": "Batch form of inquiryTaxId.",
        "operationId": "Invoice_InqueryTaxIds_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "agency token"
                  },
                  "taxIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "1..250"
                  }
                },
                "required": [
                  "taxIds"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "always — inquiry family",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/InvoiceApiReturnInfo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/profile": {
      "get": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Reads the partner's registration in «همکاران API»: status, capabilities, allowed return origins, webhook and limits.",
        "operationId": "PartnerV2_GetProfile_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)",
        "responses": {
          "200": {
            "description": "registered partner — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerProfileDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/onboarding-sessions": {
      "post": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Creates a temporary hosted sign-up link for one taxpayer (optionally fixed to an economic code).",
        "operationId": "PartnerV2_CreateSession_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nAnswer status 201. Events onboarding.session.* follow by webhook and GET events.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `validation_failed` (HTTP 400): fieldErrors on body, economicCode (11/14 digits), nationalId (10/11/12 digits), mobile (09 + 9 digits), reference (<=100 of letters, digits . _ - : / # @), idempotencyKey (8-64 of Latin letters, digits . _ - :), returnUrl (https on an allowed origin)\n- `rate_limited` (HTTP 429): sessions in the last hour >= partner.HourlySessionLimit (default 100); envelope status TOO_MANY_REQUESTS\n- `idempotency_conflict` (HTTP 409): the key was used for a request with other data",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "(see nestedTypes.PartnerSessionCreateRequest)": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/PartnerSessionCreateRequest"
                      }
                    ],
                    "description": "a missing body is validation_failed (field body)"
                  }
                },
                "required": [
                  "(see nestedTypes.PartnerSessionCreateRequest)"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "created (or replayed by idempotency key); data.url is the link, only in this answer — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerSessionDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Lists the partner's sign-up sessions, newest first.",
        "operationId": "PartnerV2_ListSessions_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nItems carry no url.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `validation_failed` (HTTP 400): status unknown, from/to not ISO-8601",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "created | opened | in_progress | business_ready | completed | expired | cancelled"
          },
          {
            "name": "reference",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "exact partner reference (<=100)"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO-8601 instant (assumed UTC), created at or after"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO-8601 instant, created before"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "default 1, min 1"
          },
          {
            "name": "pageSize",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "default 20, 1..100"
          }
        ],
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerSessionListDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/onboarding-sessions/{sessionId}": {
      "get": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Reads one sign-up session of the partner.",
        "operationId": "PartnerV2_GetSession_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `not_found` (HTTP 404): no such session for this partner",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "GUID (route constraint guid; otherwise the catch-all answers 404 ROUTE_NOT_FOUND)"
          }
        ],
        "responses": {
          "200": {
            "description": "found — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerSessionDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/onboarding-sessions/{sessionId}/link": {
      "post": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Issues a new link for an open session (the old link stops working).",
        "operationId": "PartnerV2_RenewLink_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nBody optional.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `not_found` (HTTP 404): no such session\n- `session_closed` (HTTP 409): completed, expired or cancelled\n- `session_business_ready` (HTTP 409): panel already made",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "GUID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expiresInMinutes": {
                    "type": "integer",
                    "description": "10..10080; when given the expiry is moved"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "renewed; data.url is the new link — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerSessionDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/onboarding-sessions/{sessionId}/cancel": {
      "post": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Cancels an open sign-up session.",
        "operationId": "PartnerV2_Cancel_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nEvent onboarding.session.cancelled.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `not_found` (HTTP 404): no such session\n- `session_business_ready` (HTTP 409): business already made or completed\n- `session_closed` (HTTP 409): expired",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "GUID"
          }
        ],
        "responses": {
          "200": {
            "description": "cancelled (or already cancelled) — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerSessionDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/onboarding-sessions/{sessionId}/credentials": {
      "post": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Hands the partner the new business's API v2 customer credentials once, after the owner agreed on the hosted page.",
        "operationId": "PartnerV2_ClaimCredentials_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `not_found` (HTTP 404): no such session\n- `credentials_not_requested` (HTTP 403): session made without requestCredentials\n- `business_not_ready` (HTTP 409): panel not made yet\n- `consent_missing` (HTTP 403): owner did not agree\n- `credentials_already_claimed` (HTTP 409): claimed before (or made concurrently)\n- `business_inactive` (HTTP 409): business inactive",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "GUID"
          }
        ],
        "responses": {
          "200": {
            "description": "claimed; clientSecret only when a new client was made now — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerCredentialsDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/events": {
      "get": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Reads the partner's event feed (the same events the webhook delivers) after a sequence number.",
        "operationId": "PartnerV2_ListEvents_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nEvent types: onboarding.session.opened, onboarding.session.business_ready, onboarding.session.completed, onboarding.session.expired, onboarding.session.cancelled, ping (PartnerRules.cs:172-177). Webhook signature: Standard Webhooks (comment PartnerV2Controller.cs:27).\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)",
        "parameters": [
          {
            "name": "after",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "long, default 0: events with a larger sequence"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "default 50, 1..100"
          }
        ],
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerEventListDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/webhook/test": {
      "post": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Queues a ping event to the partner's webhook (also visible in the feed).",
        "operationId": "PartnerV2_SendTestEvent_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\ndata.data = {message, partnerCompanyId}.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)",
        "responses": {
          "202": {
            "description": "queued — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerEventDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/reports/overview": {
      "get": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Cooperation overview for a period: businesses, sign-ups, invoices, webhook, credentials, findings.",
        "operationId": "PartnerV2_GetReportOverview_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nRead with refresh=false (cached figures).\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `partner_not_found` (HTTP 404): the partner is not in «همکاران API» (PartnerWorkspaceService.cs:78, 143-146)\n- `period_invalid` (HTTP 400): period/key/from/to refused (InvoiceReportPeriods.Resolve; fieldErrors period)",
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "season (default) | month | year | range"
          },
          {
            "name": "key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "season 1405-3, month 1405-07, year 1405; empty season = current"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "range only: Jalali day 1405/07/01"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "range only: Jalali day"
          }
        ],
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerWorkspaceOverviewDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/reports/businesses": {
      "get": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "The businesses the partner brought, with their invoice figures and health, one page.",
        "operationId": "PartnerV2_GetReportBusinesses_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `partner_not_found` (HTTP 404): the partner is not in «همکاران API» (PartnerWorkspaceService.cs:78, 143-146)\n- `period_invalid` (HTTP 400): period/key/from/to refused (InvoiceReportPeriods.Resolve; fieldErrors period)\n- `validation_failed` (HTTP 400): health or sort unknown",
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "as reports/overview"
          },
          {
            "name": "key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "search (name/economic code; rule not traced)"
          },
          {
            "name": "health",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ok | attention | idle | inactive"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "invoices (default) | amount | errors | recent | name"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "default 1"
          },
          {
            "name": "pageSize",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "default 20, 1..100"
          }
        ],
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerWorkspaceBusinessListDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/reports/errors": {
      "get": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Errors of the saved invoices of the partner's businesses, by reason and day.",
        "operationId": "PartnerV2_GetReportErrors_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `partner_not_found` (HTTP 404): the partner is not in «همکاران API» (PartnerWorkspaceService.cs:78, 143-146)\n- `period_invalid` (HTTP 400): period/key/from/to refused (InvoiceReportPeriods.Resolve; fieldErrors period)",
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "as reports/overview"
          },
          {
            "name": "key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerWorkspaceErrorsDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/reports/rejections": {
      "get": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Requests API v2 refused before saving (by field, day, latest with traceId and internalId).",
        "operationId": "PartnerV2_GetReportRejections_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `partner_not_found` (HTTP 404): the partner is not in «همکاران API» (PartnerWorkspaceService.cs:78, 143-146)\n- `period_invalid` (HTTP 400): period/key/from/to refused (InvoiceReportPeriods.Resolve; fieldErrors period)",
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "as reports/overview"
          },
          {
            "name": "key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerWorkspaceRejectionsDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/reports/onboarding": {
      "get": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Sign-up funnel for a period: stages, conversion, stalled sessions, errors by day.",
        "operationId": "PartnerV2_GetReportOnboarding_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `partner_not_found` (HTTP 404): the partner is not in «همکاران API» (PartnerWorkspaceService.cs:78, 143-146)\n- `period_invalid` (HTTP 400): period/key/from/to refused (InvoiceReportPeriods.Resolve; fieldErrors period)",
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "as reports/overview"
          },
          {
            "name": "key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerWorkspaceFunnelDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/reports/usage": {
      "get": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Invoices per business per Jalali month.",
        "operationId": "PartnerV2_GetReportUsage_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `partner_not_found` (HTTP 404): the partner is not in «همکاران API» (PartnerWorkspaceService.cs:78, 143-146)\n- `period_invalid` (HTTP 400): period/key/from/to refused (InvoiceReportPeriods.Resolve; fieldErrors period)\n- `validation_failed` (HTTP 400): month format, from after to, more than 12 months, to in the future, before 1398",
        "parameters": [
          {
            "name": "fromMonth",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Jalali year-month 1405-07 (or 1405/07); default five months before toMonth"
          },
          {
            "name": "toMonth",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "default current month; not after it"
          }
        ],
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerWorkspaceUsageDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/reports/monthly": {
      "get": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "The monthly cooperation report (overview, funnel, businesses, errors) of one month.",
        "operationId": "PartnerV2_GetReportMonthly_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `partner_not_found` (HTTP 404): the partner is not in «همکاران API» (PartnerWorkspaceService.cs:78, 143-146)\n- `period_invalid` (HTTP 400): period/key/from/to refused (InvoiceReportPeriods.Resolve; fieldErrors period)",
        "parameters": [
          {
            "name": "month",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "format and default not traced (PartnerWorkspaceService.MonthlyReport); presumably Jalali 1405-07 as reports/usage"
          }
        ],
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerWorkspaceMonthlyReportDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/reports/invoices": {
      "get": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Finds API invoices of the partner's businesses by tax id, request UUID or invoice number, with send attempts.",
        "operationId": "PartnerV2_GetReportInvoices_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `partner_not_found` (HTTP 404): the partner is not in «همکاران API» (PartnerWorkspaceService.cs:78, 143-146)\n- `period_invalid` (HTTP 400): period/key/from/to refused (InvoiceReportPeriods.Resolve; fieldErrors period)\n- `validation_failed` (HTTP 400): q empty\n- `business_not_yours` (HTTP 403): businessId not brought by the partner",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "<=64; tax id (22 letters/digits, any brought business), UUID or number (per business); Persian digits accepted"
          },
          {
            "name": "businessId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "default 0 = all brought businesses; another business is 403 business_not_yours"
          }
        ],
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerWorkspaceInvoiceLookupDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/partner/reports/health": {
      "get": {
        "tags": [
          "کارگزاران"
        ],
        "summary": "Connection health: webhook delivery, credentials, result delays, hourly figures, open alerts, static-key users.",
        "operationId": "PartnerV2_GetReportHealth_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid/expired token, or a static key (partner keys are refused)\n- `forbidden` (HTTP 403): a customer token, or a partner token without v2.register (message names v2.register)\n- `partner_not_registered` (HTTP 403): the business is not in «همکاران API» (PartnerOnboardingService.RequirePartner, PartnerOnboardingService.cs:48-56)\n- `partner_suspended` (HTTP 403): partner suspended\n- `capability_disabled` (HTTP 403): the route's capability (hostedOnboarding, credentialHandover) is off\n- `service_unavailable` (HTTP 503): database unreachable (SqlException, EntityException, TimeoutException)\n- `partner_not_found` (HTTP 404): the partner is not in «همکاران API» (PartnerWorkspaceService.cs:78, 143-146)\n- `period_invalid` (HTTP 400): period/key/from/to refused (InvoiceReportPeriods.Resolve; fieldErrors period)",
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PartnerWorkspaceHealthDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/invoices/bulk": {
      "put": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Approves or rejects invoices awaiting the business's reaction in its tax workspace (کارپوشه).",
        "operationId": "TaxWorkspaceV2_BulkInvoicesAsync_put",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nEach operation's period/issuanceDate either both given or both derived from the 22-character TaxId. Requires the delegation permission invoice.sell:manage (sales kinds) or invoice.buy:manage (purchase kinds).\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `unsupported_invoice_action` (HTTP 404): kind not purchase | virtual-purchase | sales | virtual-sales\n- `invalid_bulk_shape` (HTTP 400): both operations and taxIds\n- `invalid_bulk_size` (HTTP 400): 0 or more than TaxWorkspace.ExcelUploadMaxRows (500) operations\n- `tax_workspace_invoice_bulk_action_limit_exceeded` (HTTP 409): more than TaxWorkspace.InvoiceBulkMaxActions (20) executable actions\n- `invoice_context_lookup_limit_exceeded`: too many period/day lookups (status not traced)\n- `(item) invalid_identifier | no_action | invalid_action | invoice_context_not_verified | approve_has_reject_data | invalid_reject_reason | other_description_required | duplicate_identifier | invoice_not_awaiting_reaction | invoice_not_virtual_sale | invoice_virtual_broker_side` (HTTP 200): per item in results[] (status VALIDATION_ERROR, SKIPPED, NOT_ACTIONABLE ...)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "(see nestedTypes.TaxWorkspaceBulkInvoiceRequestDto)": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/TaxWorkspaceBulkInvoiceRequestDto"
                      }
                    ],
                    "description": "kind and either operations or taxIds + action"
                  }
                },
                "required": [
                  "(see nestedTypes.TaxWorkspaceBulkInvoiceRequestDto)"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "processed (each item has its own status/code) — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxWorkspaceBulkResultDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/brokerage-contracts/bulk": {
      "put": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Approves or rejects third-party brokerage contracts awaiting the business's reaction.",
        "operationId": "TaxWorkspaceV2_BulkContractsAsync_put",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nallForCurrentEconomicNumber pages the AWAITING_REACTION contracts (up to ExcelExportMaxRows).\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `tax_workspace_contract_reactions_disabled`: TaxWorkspace.ContractReactionsEnabled off (repository false); status not traced\n- `tax_workspace_contract_permission_missing` (HTTP 403): delegation lacks TaxWorkspace.ContractReactionPermission (contract.brokerage:manage)\n- `invalid_bulk_shape` (HTTP 400): more than one selector\n- `invalid_action` (HTTP 400): allForCurrentEconomicNumber with action not APPROVE/REJECT\n- `economic_number_context_mismatch` (HTTP 403): economicNumber differs from the business's\n- `no_actionable_contracts` (HTTP 409): nothing awaits reaction (all mode)\n- `invalid_bulk_size` (HTTP 400): 0 or more than 500\n- `tax_workspace_contract_bulk_action_limit_exceeded` (HTTP 409): more than TaxWorkspace.ContractBulkMaxActions (20)\n- `(item) contract_not_found | contract_number_ambiguous | contract_context_lookup_failed | duplicate_identifier | invalid_contract_id | invalid_contract_number | contract_not_actionable` (HTTP 200): per item",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "(see nestedTypes.TaxWorkspaceBulkContractRequestDto)": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/TaxWorkspaceBulkContractRequestDto"
                      }
                    ],
                    "description": "exactly one selector: operations, contractBrokerageNumbers, allForCurrentEconomicNumber"
                  }
                },
                "required": [
                  "(see nestedTypes.TaxWorkspaceBulkContractRequestDto)"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "processed — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxWorkspaceBulkResultDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/invoices/{kind}": {
      "get": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "One page of the business's tax-workspace invoice list (sales, purchase or virtual) for one Tehran day.",
        "operationId": "TaxWorkspaceV2_GetInvoicesAsync_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nDelegation permission invoice.buy:view / invoice.sell:view / invoice.virtual.buy:view / invoice.virtual.sell:view. actionAllowed is set on sales and purchase rows. buyerRole is applied locally if the organisation refuses it.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `unsupported_invoice_kind` (HTTP 404): unknown kind",
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "purchase | sales | virtual-purchase | virtual-sales (case-insensitive); else 404 unsupported_invoice_kind"
          },
          {
            "name": "(see nestedTypes.TaxWorkspaceInvoiceFilter)",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/TaxWorkspaceInvoiceFilter"
            },
            "description": "bound [FromUri]: period, issuanceDateFrom, issuanceDateTo required"
          }
        ],
        "responses": {
          "200": {
            "description": "ok; notices may explain a narrowed search — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/invoices/{kind}/virtual-as-broker-client": {
      "get": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "The virtual invoices of one Tehran day in which the business is the principal (آمر), from its sales or purchase list.",
        "operationId": "TaxWorkspaceV2_GetVirtualInvoicesAsBrokerClientAsync_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `unsupported_invoice_kind` (HTTP 404): kind not sales/purchase",
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "sales | purchase only"
          },
          {
            "name": "(see nestedTypes.TaxWorkspaceInvoiceFilter)",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/TaxWorkspaceInvoiceFilter"
            },
            "description": "issuanceDateFrom/To required; pageNumber, pageSize, sellerRole, buyerRole are set by the server"
          }
        ],
        "responses": {
          "200": {
            "description": "ok; a notice when truncated — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/brokerage-contracts": {
      "get": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "One page of the business's third-party brokerage contracts.",
        "operationId": "TaxWorkspaceV2_GetContractsAsync_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nDelegation permission contract.brokerage:view.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)",
        "parameters": [
          {
            "name": "(see nestedTypes.TaxWorkspaceContractFilter)",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/TaxWorkspaceContractFilter"
            },
            "description": "every filter optional; empty = first page of 10"
          }
        ],
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/invoices/{kind}/excel/export": {
      "get": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Exports the invoice list for the filter as an Excel file.",
        "operationId": "TaxWorkspaceV2_ExportInvoicesAsync_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `tax_workspace_excel_invalid_content_type` (HTTP 415): upload not multipart/form-data, or the part's Content-Type is not xlsx/octet-stream\n- `tax_workspace_excel_content_length_required` (HTTP 411): no Content-Length\n- `tax_workspace_excel_file_too_large` (HTTP 413): over ExcelUploadMaxBytes (+1 MiB multipart overhead for the request)\n- `tax_workspace_excel_file_required` (HTTP 400): not exactly one file part named file\n- `tax_workspace_excel_invalid_extension` (HTTP 415): file name not .xlsx\n- `tax_workspace_excel_row_limit_exceeded` (HTTP 413): more rows than ExcelUploadMaxRows\n- `tax_workspace_excel_content_too_large` (HTTP 413): cell content over the limits\n- `tax_workspace_excel_preview_payload_too_large` (HTTP 413): protected preview payload too large\n- `tax_workspace_excel_invalid_package | tax_workspace_excel_invalid_signature | tax_workspace_excel_encrypted_or_invalid | tax_workspace_excel_macro_or_encryption_not_allowed | tax_workspace_excel_formula_not_allowed | tax_workspace_excel_data_sheet_missing | tax_workspace_excel_header_missing | tax_workspace_excel_duplicate_header | tax_workspace_excel_unexpected_header | tax_workspace_excel_header_too_long | tax_workspace_excel_too_many_columns | tax_workspace_excel_uncompressed_limit_exceeded | tax_workspace_excel_zip_entry_limit_exceeded | tax_workspace_excel_zip_entry_name_too_long | invalid_excel_row`: file content refused (TaxWorkspaceExcelService.cs; statuses not traced one by one)\n- `invalid_excel_preview_token` (HTTP 400): malformed token (403 when bound to another actor)\n- `tax_workspace_excel_token_expired` (HTTP 409): preview token expired\n- `tax_workspace_excel_token_context_mismatch` (HTTP 403): token of another business/client/kind\n- `tax_workspace_excel_execution_claim_conflict` (HTTP 409): execution already claimed\n- `tax_workspace_excel_execution_in_progress` (HTTP 409): execution running\n- `tax_workspace_excel_execution_outcome_unknown` (HTTP 409): earlier execution's outcome unknown\n- `tax_workspace_excel_result_expired` (HTTP 409): result past retention\n- `tax_workspace_excel_export_row_limit_exceeded` (HTTP 409): export over ExcelExportMaxRows\n- `tax_workspace_excel_empty` (HTTP 503): generated file empty\n- `tax_workspace_invalid_service_result` (HTTP 503): service answered neither file nor envelope\n- `unsupported_invoice_kind` (HTTP 404): unknown kind\n- `unsupported_invoice_action` (HTTP 404): kind without reactions\n- `tax_workspace_excel_unavailable` (HTTP 503): a file the server made (export, template, result) could not be prepared; try again, then send correlationId to support (1.0.0.209; it was the 415 code before)",
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "as invoices/{kind}"
          },
          {
            "name": "(see nestedTypes.TaxWorkspaceInvoiceFilter)",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/TaxWorkspaceInvoiceFilter"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ok — file",
            "content": {
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "failures — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/invoices/{kind}/excel/template": {
      "get": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Downloads the empty Excel template for invoice reactions of a kind.",
        "operationId": "TaxWorkspaceV2_InvoiceTemplateAsync_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `tax_workspace_excel_invalid_content_type` (HTTP 415): upload not multipart/form-data, or the part's Content-Type is not xlsx/octet-stream\n- `tax_workspace_excel_content_length_required` (HTTP 411): no Content-Length\n- `tax_workspace_excel_file_too_large` (HTTP 413): over ExcelUploadMaxBytes (+1 MiB multipart overhead for the request)\n- `tax_workspace_excel_file_required` (HTTP 400): not exactly one file part named file\n- `tax_workspace_excel_invalid_extension` (HTTP 415): file name not .xlsx\n- `tax_workspace_excel_row_limit_exceeded` (HTTP 413): more rows than ExcelUploadMaxRows\n- `tax_workspace_excel_content_too_large` (HTTP 413): cell content over the limits\n- `tax_workspace_excel_preview_payload_too_large` (HTTP 413): protected preview payload too large\n- `tax_workspace_excel_invalid_package | tax_workspace_excel_invalid_signature | tax_workspace_excel_encrypted_or_invalid | tax_workspace_excel_macro_or_encryption_not_allowed | tax_workspace_excel_formula_not_allowed | tax_workspace_excel_data_sheet_missing | tax_workspace_excel_header_missing | tax_workspace_excel_duplicate_header | tax_workspace_excel_unexpected_header | tax_workspace_excel_header_too_long | tax_workspace_excel_too_many_columns | tax_workspace_excel_uncompressed_limit_exceeded | tax_workspace_excel_zip_entry_limit_exceeded | tax_workspace_excel_zip_entry_name_too_long | invalid_excel_row`: file content refused (TaxWorkspaceExcelService.cs; statuses not traced one by one)\n- `invalid_excel_preview_token` (HTTP 400): malformed token (403 when bound to another actor)\n- `tax_workspace_excel_token_expired` (HTTP 409): preview token expired\n- `tax_workspace_excel_token_context_mismatch` (HTTP 403): token of another business/client/kind\n- `tax_workspace_excel_execution_claim_conflict` (HTTP 409): execution already claimed\n- `tax_workspace_excel_execution_in_progress` (HTTP 409): execution running\n- `tax_workspace_excel_execution_outcome_unknown` (HTTP 409): earlier execution's outcome unknown\n- `tax_workspace_excel_result_expired` (HTTP 409): result past retention\n- `tax_workspace_excel_export_row_limit_exceeded` (HTTP 409): export over ExcelExportMaxRows\n- `tax_workspace_excel_empty` (HTTP 503): generated file empty\n- `tax_workspace_invalid_service_result` (HTTP 503): service answered neither file nor envelope\n- `unsupported_invoice_kind` (HTTP 404): unknown kind\n- `unsupported_invoice_action` (HTTP 404): kind without reactions\n- `tax_workspace_excel_unavailable` (HTTP 503): a file the server made (export, template, result) could not be prepared; try again, then send correlationId to support (1.0.0.209; it was the 415 code before)",
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "a reaction kind (unsupported_invoice_kind / unsupported_invoice_action otherwise)"
          }
        ],
        "responses": {
          "200": {
            "description": "ok — file",
            "content": {
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/invoices/{kind}/excel/preview": {
      "post": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Uploads a filled reaction Excel file and answers a checked preview with a preview token.",
        "operationId": "TaxWorkspaceV2_PreviewInvoicesAsync_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `tax_workspace_excel_invalid_content_type` (HTTP 415): upload not multipart/form-data, or the part's Content-Type is not xlsx/octet-stream\n- `tax_workspace_excel_content_length_required` (HTTP 411): no Content-Length\n- `tax_workspace_excel_file_too_large` (HTTP 413): over ExcelUploadMaxBytes (+1 MiB multipart overhead for the request)\n- `tax_workspace_excel_file_required` (HTTP 400): not exactly one file part named file\n- `tax_workspace_excel_invalid_extension` (HTTP 415): file name not .xlsx\n- `tax_workspace_excel_row_limit_exceeded` (HTTP 413): more rows than ExcelUploadMaxRows\n- `tax_workspace_excel_content_too_large` (HTTP 413): cell content over the limits\n- `tax_workspace_excel_preview_payload_too_large` (HTTP 413): protected preview payload too large\n- `tax_workspace_excel_invalid_package | tax_workspace_excel_invalid_signature | tax_workspace_excel_encrypted_or_invalid | tax_workspace_excel_macro_or_encryption_not_allowed | tax_workspace_excel_formula_not_allowed | tax_workspace_excel_data_sheet_missing | tax_workspace_excel_header_missing | tax_workspace_excel_duplicate_header | tax_workspace_excel_unexpected_header | tax_workspace_excel_header_too_long | tax_workspace_excel_too_many_columns | tax_workspace_excel_uncompressed_limit_exceeded | tax_workspace_excel_zip_entry_limit_exceeded | tax_workspace_excel_zip_entry_name_too_long | invalid_excel_row`: file content refused (TaxWorkspaceExcelService.cs; statuses not traced one by one)\n- `invalid_excel_preview_token` (HTTP 400): malformed token (403 when bound to another actor)\n- `tax_workspace_excel_token_expired` (HTTP 409): preview token expired\n- `tax_workspace_excel_token_context_mismatch` (HTTP 403): token of another business/client/kind\n- `tax_workspace_excel_execution_claim_conflict` (HTTP 409): execution already claimed\n- `tax_workspace_excel_execution_in_progress` (HTTP 409): execution running\n- `tax_workspace_excel_execution_outcome_unknown` (HTTP 409): earlier execution's outcome unknown\n- `tax_workspace_excel_result_expired` (HTTP 409): result past retention\n- `tax_workspace_excel_export_row_limit_exceeded` (HTTP 409): export over ExcelExportMaxRows\n- `tax_workspace_excel_empty` (HTTP 503): generated file empty\n- `tax_workspace_invalid_service_result` (HTTP 503): service answered neither file nor envelope\n- `unsupported_invoice_kind` (HTTP 404): unknown kind\n- `unsupported_invoice_action` (HTTP 404): kind without reactions\n- `tax_workspace_excel_unavailable` (HTTP 503): a file the server made (export, template, result) could not be prepared; try again, then send correlationId to support (1.0.0.209; it was the 415 code before)",
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "reaction kind"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "description": "binary .xlsx in the one part named file (Content-Type xlsx or application/octet-stream); Content-Length header required"
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxWorkspaceExcelPreviewDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/invoices/{kind}/excel/execute": {
      "post": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Executes the reactions of a previewed Excel file.",
        "operationId": "TaxWorkspaceV2_ExecuteInvoiceExcelAsync_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `tax_workspace_excel_invalid_content_type` (HTTP 415): upload not multipart/form-data, or the part's Content-Type is not xlsx/octet-stream\n- `tax_workspace_excel_content_length_required` (HTTP 411): no Content-Length\n- `tax_workspace_excel_file_too_large` (HTTP 413): over ExcelUploadMaxBytes (+1 MiB multipart overhead for the request)\n- `tax_workspace_excel_file_required` (HTTP 400): not exactly one file part named file\n- `tax_workspace_excel_invalid_extension` (HTTP 415): file name not .xlsx\n- `tax_workspace_excel_row_limit_exceeded` (HTTP 413): more rows than ExcelUploadMaxRows\n- `tax_workspace_excel_content_too_large` (HTTP 413): cell content over the limits\n- `tax_workspace_excel_preview_payload_too_large` (HTTP 413): protected preview payload too large\n- `tax_workspace_excel_invalid_package | tax_workspace_excel_invalid_signature | tax_workspace_excel_encrypted_or_invalid | tax_workspace_excel_macro_or_encryption_not_allowed | tax_workspace_excel_formula_not_allowed | tax_workspace_excel_data_sheet_missing | tax_workspace_excel_header_missing | tax_workspace_excel_duplicate_header | tax_workspace_excel_unexpected_header | tax_workspace_excel_header_too_long | tax_workspace_excel_too_many_columns | tax_workspace_excel_uncompressed_limit_exceeded | tax_workspace_excel_zip_entry_limit_exceeded | tax_workspace_excel_zip_entry_name_too_long | invalid_excel_row`: file content refused (TaxWorkspaceExcelService.cs; statuses not traced one by one)\n- `invalid_excel_preview_token` (HTTP 400): malformed token (403 when bound to another actor)\n- `tax_workspace_excel_token_expired` (HTTP 409): preview token expired\n- `tax_workspace_excel_token_context_mismatch` (HTTP 403): token of another business/client/kind\n- `tax_workspace_excel_execution_claim_conflict` (HTTP 409): execution already claimed\n- `tax_workspace_excel_execution_in_progress` (HTTP 409): execution running\n- `tax_workspace_excel_execution_outcome_unknown` (HTTP 409): earlier execution's outcome unknown\n- `tax_workspace_excel_result_expired` (HTTP 409): result past retention\n- `tax_workspace_excel_export_row_limit_exceeded` (HTTP 409): export over ExcelExportMaxRows\n- `tax_workspace_excel_empty` (HTTP 503): generated file empty\n- `tax_workspace_invalid_service_result` (HTTP 503): service answered neither file nor envelope\n- `unsupported_invoice_kind` (HTTP 404): unknown kind\n- `unsupported_invoice_action` (HTTP 404): kind without reactions\n- `tax_workspace_excel_unavailable` (HTTP 503): a file the server made (export, template, result) could not be prepared; try again, then send correlationId to support (1.0.0.209; it was the 415 code before)",
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "same kind as the preview"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "previewToken": {
                    "type": "string",
                    "description": "from the preview answer, valid 15 minutes, bound to the same API client"
                  }
                },
                "required": [
                  "previewToken"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "executed; resultToken downloads the result file — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxWorkspaceExcelExecuteResultDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/brokerage-contracts/excel/export": {
      "get": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Exports the contract list for the filter as an Excel file.",
        "operationId": "TaxWorkspaceV2_ExportContractsAsync_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `tax_workspace_excel_invalid_content_type` (HTTP 415): upload not multipart/form-data, or the part's Content-Type is not xlsx/octet-stream\n- `tax_workspace_excel_content_length_required` (HTTP 411): no Content-Length\n- `tax_workspace_excel_file_too_large` (HTTP 413): over ExcelUploadMaxBytes (+1 MiB multipart overhead for the request)\n- `tax_workspace_excel_file_required` (HTTP 400): not exactly one file part named file\n- `tax_workspace_excel_invalid_extension` (HTTP 415): file name not .xlsx\n- `tax_workspace_excel_row_limit_exceeded` (HTTP 413): more rows than ExcelUploadMaxRows\n- `tax_workspace_excel_content_too_large` (HTTP 413): cell content over the limits\n- `tax_workspace_excel_preview_payload_too_large` (HTTP 413): protected preview payload too large\n- `tax_workspace_excel_invalid_package | tax_workspace_excel_invalid_signature | tax_workspace_excel_encrypted_or_invalid | tax_workspace_excel_macro_or_encryption_not_allowed | tax_workspace_excel_formula_not_allowed | tax_workspace_excel_data_sheet_missing | tax_workspace_excel_header_missing | tax_workspace_excel_duplicate_header | tax_workspace_excel_unexpected_header | tax_workspace_excel_header_too_long | tax_workspace_excel_too_many_columns | tax_workspace_excel_uncompressed_limit_exceeded | tax_workspace_excel_zip_entry_limit_exceeded | tax_workspace_excel_zip_entry_name_too_long | invalid_excel_row`: file content refused (TaxWorkspaceExcelService.cs; statuses not traced one by one)\n- `invalid_excel_preview_token` (HTTP 400): malformed token (403 when bound to another actor)\n- `tax_workspace_excel_token_expired` (HTTP 409): preview token expired\n- `tax_workspace_excel_token_context_mismatch` (HTTP 403): token of another business/client/kind\n- `tax_workspace_excel_execution_claim_conflict` (HTTP 409): execution already claimed\n- `tax_workspace_excel_execution_in_progress` (HTTP 409): execution running\n- `tax_workspace_excel_execution_outcome_unknown` (HTTP 409): earlier execution's outcome unknown\n- `tax_workspace_excel_result_expired` (HTTP 409): result past retention\n- `tax_workspace_excel_export_row_limit_exceeded` (HTTP 409): export over ExcelExportMaxRows\n- `tax_workspace_excel_empty` (HTTP 503): generated file empty\n- `tax_workspace_invalid_service_result` (HTTP 503): service answered neither file nor envelope\n- `unsupported_invoice_kind` (HTTP 404): unknown kind\n- `unsupported_invoice_action` (HTTP 404): kind without reactions\n- `tax_workspace_excel_unavailable` (HTTP 503): a file the server made (export, template, result) could not be prepared; try again, then send correlationId to support (1.0.0.209; it was the 415 code before)",
        "parameters": [
          {
            "name": "(see nestedTypes.TaxWorkspaceContractFilter)",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/TaxWorkspaceContractFilter"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ok — file",
            "content": {
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/brokerage-contracts/excel/template": {
      "get": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Downloads the empty Excel template for contract reactions.",
        "operationId": "TaxWorkspaceV2_ContractTemplateAsync_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `tax_workspace_excel_invalid_content_type` (HTTP 415): upload not multipart/form-data, or the part's Content-Type is not xlsx/octet-stream\n- `tax_workspace_excel_content_length_required` (HTTP 411): no Content-Length\n- `tax_workspace_excel_file_too_large` (HTTP 413): over ExcelUploadMaxBytes (+1 MiB multipart overhead for the request)\n- `tax_workspace_excel_file_required` (HTTP 400): not exactly one file part named file\n- `tax_workspace_excel_invalid_extension` (HTTP 415): file name not .xlsx\n- `tax_workspace_excel_row_limit_exceeded` (HTTP 413): more rows than ExcelUploadMaxRows\n- `tax_workspace_excel_content_too_large` (HTTP 413): cell content over the limits\n- `tax_workspace_excel_preview_payload_too_large` (HTTP 413): protected preview payload too large\n- `tax_workspace_excel_invalid_package | tax_workspace_excel_invalid_signature | tax_workspace_excel_encrypted_or_invalid | tax_workspace_excel_macro_or_encryption_not_allowed | tax_workspace_excel_formula_not_allowed | tax_workspace_excel_data_sheet_missing | tax_workspace_excel_header_missing | tax_workspace_excel_duplicate_header | tax_workspace_excel_unexpected_header | tax_workspace_excel_header_too_long | tax_workspace_excel_too_many_columns | tax_workspace_excel_uncompressed_limit_exceeded | tax_workspace_excel_zip_entry_limit_exceeded | tax_workspace_excel_zip_entry_name_too_long | invalid_excel_row`: file content refused (TaxWorkspaceExcelService.cs; statuses not traced one by one)\n- `invalid_excel_preview_token` (HTTP 400): malformed token (403 when bound to another actor)\n- `tax_workspace_excel_token_expired` (HTTP 409): preview token expired\n- `tax_workspace_excel_token_context_mismatch` (HTTP 403): token of another business/client/kind\n- `tax_workspace_excel_execution_claim_conflict` (HTTP 409): execution already claimed\n- `tax_workspace_excel_execution_in_progress` (HTTP 409): execution running\n- `tax_workspace_excel_execution_outcome_unknown` (HTTP 409): earlier execution's outcome unknown\n- `tax_workspace_excel_result_expired` (HTTP 409): result past retention\n- `tax_workspace_excel_export_row_limit_exceeded` (HTTP 409): export over ExcelExportMaxRows\n- `tax_workspace_excel_empty` (HTTP 503): generated file empty\n- `tax_workspace_invalid_service_result` (HTTP 503): service answered neither file nor envelope\n- `unsupported_invoice_kind` (HTTP 404): unknown kind\n- `unsupported_invoice_action` (HTTP 404): kind without reactions\n- `tax_workspace_excel_unavailable` (HTTP 503): a file the server made (export, template, result) could not be prepared; try again, then send correlationId to support (1.0.0.209; it was the 415 code before)",
        "responses": {
          "200": {
            "description": "ok — file",
            "content": {
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/brokerage-contracts/excel/preview": {
      "post": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Uploads a filled contract-reaction Excel file and answers a checked preview.",
        "operationId": "TaxWorkspaceV2_PreviewContractsAsync_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nContract reactions must be enabled (tax_workspace_contract_reactions_disabled).\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `tax_workspace_excel_invalid_content_type` (HTTP 415): upload not multipart/form-data, or the part's Content-Type is not xlsx/octet-stream\n- `tax_workspace_excel_content_length_required` (HTTP 411): no Content-Length\n- `tax_workspace_excel_file_too_large` (HTTP 413): over ExcelUploadMaxBytes (+1 MiB multipart overhead for the request)\n- `tax_workspace_excel_file_required` (HTTP 400): not exactly one file part named file\n- `tax_workspace_excel_invalid_extension` (HTTP 415): file name not .xlsx\n- `tax_workspace_excel_row_limit_exceeded` (HTTP 413): more rows than ExcelUploadMaxRows\n- `tax_workspace_excel_content_too_large` (HTTP 413): cell content over the limits\n- `tax_workspace_excel_preview_payload_too_large` (HTTP 413): protected preview payload too large\n- `tax_workspace_excel_invalid_package | tax_workspace_excel_invalid_signature | tax_workspace_excel_encrypted_or_invalid | tax_workspace_excel_macro_or_encryption_not_allowed | tax_workspace_excel_formula_not_allowed | tax_workspace_excel_data_sheet_missing | tax_workspace_excel_header_missing | tax_workspace_excel_duplicate_header | tax_workspace_excel_unexpected_header | tax_workspace_excel_header_too_long | tax_workspace_excel_too_many_columns | tax_workspace_excel_uncompressed_limit_exceeded | tax_workspace_excel_zip_entry_limit_exceeded | tax_workspace_excel_zip_entry_name_too_long | invalid_excel_row`: file content refused (TaxWorkspaceExcelService.cs; statuses not traced one by one)\n- `invalid_excel_preview_token` (HTTP 400): malformed token (403 when bound to another actor)\n- `tax_workspace_excel_token_expired` (HTTP 409): preview token expired\n- `tax_workspace_excel_token_context_mismatch` (HTTP 403): token of another business/client/kind\n- `tax_workspace_excel_execution_claim_conflict` (HTTP 409): execution already claimed\n- `tax_workspace_excel_execution_in_progress` (HTTP 409): execution running\n- `tax_workspace_excel_execution_outcome_unknown` (HTTP 409): earlier execution's outcome unknown\n- `tax_workspace_excel_result_expired` (HTTP 409): result past retention\n- `tax_workspace_excel_export_row_limit_exceeded` (HTTP 409): export over ExcelExportMaxRows\n- `tax_workspace_excel_empty` (HTTP 503): generated file empty\n- `tax_workspace_invalid_service_result` (HTTP 503): service answered neither file nor envelope\n- `unsupported_invoice_kind` (HTTP 404): unknown kind\n- `unsupported_invoice_action` (HTTP 404): kind without reactions\n- `tax_workspace_excel_unavailable` (HTTP 503): a file the server made (export, template, result) could not be prepared; try again, then send correlationId to support (1.0.0.209; it was the 415 code before)",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "description": "binary .xlsx, as the invoice preview"
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxWorkspaceExcelPreviewDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/brokerage-contracts/excel/execute": {
      "post": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Executes the reactions of a previewed contract Excel file.",
        "operationId": "TaxWorkspaceV2_ExecuteContractExcelAsync_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `tax_workspace_excel_invalid_content_type` (HTTP 415): upload not multipart/form-data, or the part's Content-Type is not xlsx/octet-stream\n- `tax_workspace_excel_content_length_required` (HTTP 411): no Content-Length\n- `tax_workspace_excel_file_too_large` (HTTP 413): over ExcelUploadMaxBytes (+1 MiB multipart overhead for the request)\n- `tax_workspace_excel_file_required` (HTTP 400): not exactly one file part named file\n- `tax_workspace_excel_invalid_extension` (HTTP 415): file name not .xlsx\n- `tax_workspace_excel_row_limit_exceeded` (HTTP 413): more rows than ExcelUploadMaxRows\n- `tax_workspace_excel_content_too_large` (HTTP 413): cell content over the limits\n- `tax_workspace_excel_preview_payload_too_large` (HTTP 413): protected preview payload too large\n- `tax_workspace_excel_invalid_package | tax_workspace_excel_invalid_signature | tax_workspace_excel_encrypted_or_invalid | tax_workspace_excel_macro_or_encryption_not_allowed | tax_workspace_excel_formula_not_allowed | tax_workspace_excel_data_sheet_missing | tax_workspace_excel_header_missing | tax_workspace_excel_duplicate_header | tax_workspace_excel_unexpected_header | tax_workspace_excel_header_too_long | tax_workspace_excel_too_many_columns | tax_workspace_excel_uncompressed_limit_exceeded | tax_workspace_excel_zip_entry_limit_exceeded | tax_workspace_excel_zip_entry_name_too_long | invalid_excel_row`: file content refused (TaxWorkspaceExcelService.cs; statuses not traced one by one)\n- `invalid_excel_preview_token` (HTTP 400): malformed token (403 when bound to another actor)\n- `tax_workspace_excel_token_expired` (HTTP 409): preview token expired\n- `tax_workspace_excel_token_context_mismatch` (HTTP 403): token of another business/client/kind\n- `tax_workspace_excel_execution_claim_conflict` (HTTP 409): execution already claimed\n- `tax_workspace_excel_execution_in_progress` (HTTP 409): execution running\n- `tax_workspace_excel_execution_outcome_unknown` (HTTP 409): earlier execution's outcome unknown\n- `tax_workspace_excel_result_expired` (HTTP 409): result past retention\n- `tax_workspace_excel_export_row_limit_exceeded` (HTTP 409): export over ExcelExportMaxRows\n- `tax_workspace_excel_empty` (HTTP 503): generated file empty\n- `tax_workspace_invalid_service_result` (HTTP 503): service answered neither file nor envelope\n- `unsupported_invoice_kind` (HTTP 404): unknown kind\n- `unsupported_invoice_action` (HTTP 404): kind without reactions\n- `tax_workspace_excel_unavailable` (HTTP 503): a file the server made (export, template, result) could not be prepared; try again, then send correlationId to support (1.0.0.209; it was the 415 code before)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "previewToken": {
                    "type": "string"
                  }
                },
                "required": [
                  "previewToken"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "executed — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxWorkspaceExcelExecuteResultDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/excel/result": {
      "post": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Downloads the result file of an executed Excel batch.",
        "operationId": "TaxWorkspaceV2_DownloadExcelResultAsync_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nA POST that returns a file.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `tax_workspace_excel_invalid_content_type` (HTTP 415): upload not multipart/form-data, or the part's Content-Type is not xlsx/octet-stream\n- `tax_workspace_excel_content_length_required` (HTTP 411): no Content-Length\n- `tax_workspace_excel_file_too_large` (HTTP 413): over ExcelUploadMaxBytes (+1 MiB multipart overhead for the request)\n- `tax_workspace_excel_file_required` (HTTP 400): not exactly one file part named file\n- `tax_workspace_excel_invalid_extension` (HTTP 415): file name not .xlsx\n- `tax_workspace_excel_row_limit_exceeded` (HTTP 413): more rows than ExcelUploadMaxRows\n- `tax_workspace_excel_content_too_large` (HTTP 413): cell content over the limits\n- `tax_workspace_excel_preview_payload_too_large` (HTTP 413): protected preview payload too large\n- `tax_workspace_excel_invalid_package | tax_workspace_excel_invalid_signature | tax_workspace_excel_encrypted_or_invalid | tax_workspace_excel_macro_or_encryption_not_allowed | tax_workspace_excel_formula_not_allowed | tax_workspace_excel_data_sheet_missing | tax_workspace_excel_header_missing | tax_workspace_excel_duplicate_header | tax_workspace_excel_unexpected_header | tax_workspace_excel_header_too_long | tax_workspace_excel_too_many_columns | tax_workspace_excel_uncompressed_limit_exceeded | tax_workspace_excel_zip_entry_limit_exceeded | tax_workspace_excel_zip_entry_name_too_long | invalid_excel_row`: file content refused (TaxWorkspaceExcelService.cs; statuses not traced one by one)\n- `invalid_excel_preview_token` (HTTP 400): malformed token (403 when bound to another actor)\n- `tax_workspace_excel_token_expired` (HTTP 409): preview token expired\n- `tax_workspace_excel_token_context_mismatch` (HTTP 403): token of another business/client/kind\n- `tax_workspace_excel_execution_claim_conflict` (HTTP 409): execution already claimed\n- `tax_workspace_excel_execution_in_progress` (HTTP 409): execution running\n- `tax_workspace_excel_execution_outcome_unknown` (HTTP 409): earlier execution's outcome unknown\n- `tax_workspace_excel_result_expired` (HTTP 409): result past retention\n- `tax_workspace_excel_export_row_limit_exceeded` (HTTP 409): export over ExcelExportMaxRows\n- `tax_workspace_excel_empty` (HTTP 503): generated file empty\n- `tax_workspace_invalid_service_result` (HTTP 503): service answered neither file nor envelope\n- `unsupported_invoice_kind` (HTTP 404): unknown kind\n- `unsupported_invoice_action` (HTTP 404): kind without reactions\n- `tax_workspace_excel_unavailable` (HTTP 503): a file the server made (export, template, result) could not be prepared; try again, then send correlationId to support (1.0.0.209; it was the 415 code before)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "resultToken": {
                    "type": "string",
                    "description": "from the execute answer"
                  }
                },
                "required": [
                  "resultToken"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "ok — file",
            "content": {
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/delegation": {
      "get": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Reads the business's tax-workspace delegation (کارپوشه) as a connected system needs it.",
        "operationId": "TaxWorkspaceRegistrationV2_GetDelegationAsync_get",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.read`.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)",
        "responses": {
          "200": {
            "description": "ok — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxWorkspaceApiDelegationDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/delegation/otp": {
      "post": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Asks the tax organisation to send the owner's mobile a code for the delegation.",
        "operationId": "TaxWorkspaceRegistrationV2_RequestOtpAsync_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nPermissions requested are the registration set (RegistrationDelegationPermissions).\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `invalid_validity` (HTTP 400): validityDurationDays outside 1..365\n- `invalid_otp` (HTTP 400): code malformed\n- `pending_otp_not_found` (HTTP 409): no code was requested or it expired\n- `otp_operation_in_progress` (HTTP 409): another OTP operation running\n- `otp_operation_concurrency` (HTTP 409): concurrent OTP change\n- `otp_operation_superseded` (HTTP 409): a newer code request replaced this one\n- `active_otp_economic_number_change` (HTTP 409): economic code changed while a code is pending\n- `invalid_otp_response` (HTTP 502): organisation answer unreadable\n- `invalid_delegation_response` (HTTP 502): organisation delegation answer unreadable\n- `otp_request_outcome_unknown | otp_verification_outcome_unknown | otp_request_interrupted | otp_verification_interrupted`: interrupted exchange (statuses not traced)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "validityDurationDays": {
                    "type": "integer",
                    "description": "1..365, default 365"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "code sent (otpPending, maskedMobile, otpLength, otpExpiresAt) — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxWorkspaceApiDelegationDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/delegation/verify": {
      "post": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Verifies the owner's code and stores the delegation.",
        "operationId": "TaxWorkspaceRegistrationV2_VerifyOtpAsync_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `invalid_validity` (HTTP 400): validityDurationDays outside 1..365\n- `invalid_otp` (HTTP 400): code malformed\n- `pending_otp_not_found` (HTTP 409): no code was requested or it expired\n- `otp_operation_in_progress` (HTTP 409): another OTP operation running\n- `otp_operation_concurrency` (HTTP 409): concurrent OTP change\n- `otp_operation_superseded` (HTTP 409): a newer code request replaced this one\n- `active_otp_economic_number_change` (HTTP 409): economic code changed while a code is pending\n- `invalid_otp_response` (HTTP 502): organisation answer unreadable\n- `invalid_delegation_response` (HTTP 502): organisation delegation answer unreadable\n- `otp_request_outcome_unknown | otp_verification_outcome_unknown | otp_request_interrupted | otp_verification_interrupted`: interrupted exchange (statuses not traced)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "otp": {
                    "type": "string",
                    "description": "digits (Persian digits normalised)"
                  }
                },
                "required": [
                  "otp"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "verified — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxWorkspaceApiDelegationDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/memory-unique-id": {
      "post": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Issues a new fiscal memory id through the delegation and saves it on the business.",
        "operationId": "TaxWorkspaceRegistrationV2_AddMemoryUniqueIdAsync_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.invoice.send`.\n\nNot idempotent: each call asks the organisation for a new id.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `tax_workspace_memory_unique_id_disabled` (HTTP 503): memory-unique-id services off\n- `tax_workspace_memory_permission_missing`: delegation lacks memory-unique-id:manage (status not traced)\n- `tax_workspace_memory_operation_in_progress` (HTTP 409): another memory operation running\n- `invalid_memory_unique_id` (HTTP 400): organisation returned an unusable id",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "default 'شناسه دریافت‌شده با API v2'; bounded to 100"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "issued — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxWorkspaceMemoryUniqueIdResultDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/onboarding/otp": {
      "post": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Partner: asks the organisation to send the code to a not-yet-registered taxpayer's mobile.",
        "operationId": "TaxWorkspaceRegistrationV2_RequestOnboardingOtpAsync_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `invalid_validity` (HTTP 400): validityDurationDays outside 1..365\n- `invalid_otp` (HTTP 400): code malformed\n- `pending_otp_not_found` (HTTP 409): no code was requested or it expired\n- `otp_operation_in_progress` (HTTP 409): another OTP operation running\n- `otp_operation_concurrency` (HTTP 409): concurrent OTP change\n- `otp_operation_superseded` (HTTP 409): a newer code request replaced this one\n- `active_otp_economic_number_change` (HTTP 409): economic code changed while a code is pending\n- `invalid_otp_response` (HTTP 502): organisation answer unreadable\n- `invalid_delegation_response` (HTTP 502): organisation delegation answer unreadable\n- `otp_request_outcome_unknown | otp_verification_outcome_unknown | otp_request_interrupted | otp_verification_interrupted`: interrupted exchange (statuses not traced)\n- `partner_suspended` (HTTP 403): registered partner suspended (PartnerAccess.Refusal; unregistered partners pass)\n- `capability_disabled` (HTTP 403): otpOnboarding off for the registered partner\n- `rate_limited` (HTTP 429): 60 code requests per partner client per hour (envelope status \"429\")",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "economicCode": {
                    "type": "string",
                    "description": "11 or 14 digits"
                  },
                  "validityDurationDays": {
                    "type": "integer",
                    "description": "1..365, default 365"
                  },
                  "otp": {
                    "type": "string",
                    "description": "not used here"
                  }
                },
                "required": [
                  "economicCode"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "code sent — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxWorkspaceApiDelegationDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/onboarding/verify": {
      "post": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Partner: verifies the taxpayer's code (the owner's consent), valid 30 minutes for issuing a memory id.",
        "operationId": "TaxWorkspaceRegistrationV2_VerifyOnboardingOtpAsync_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `invalid_validity` (HTTP 400): validityDurationDays outside 1..365\n- `invalid_otp` (HTTP 400): code malformed\n- `pending_otp_not_found` (HTTP 409): no code was requested or it expired\n- `otp_operation_in_progress` (HTTP 409): another OTP operation running\n- `otp_operation_concurrency` (HTTP 409): concurrent OTP change\n- `otp_operation_superseded` (HTTP 409): a newer code request replaced this one\n- `active_otp_economic_number_change` (HTTP 409): economic code changed while a code is pending\n- `invalid_otp_response` (HTTP 502): organisation answer unreadable\n- `invalid_delegation_response` (HTTP 502): organisation delegation answer unreadable\n- `otp_request_outcome_unknown | otp_verification_outcome_unknown | otp_request_interrupted | otp_verification_interrupted`: interrupted exchange (statuses not traced)\n- `partner_suspended` (HTTP 403): registered partner suspended (PartnerAccess.Refusal; unregistered partners pass)\n- `capability_disabled` (HTTP 403): otpOnboarding off for the registered partner",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "economicCode": {
                    "type": "string",
                    "description": "11 or 14 digits"
                  },
                  "otp": {
                    "type": "string",
                    "description": "digits"
                  }
                },
                "required": [
                  "economicCode",
                  "otp"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "verified — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxWorkspaceApiDelegationDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-workspace/onboarding/memory-unique-id": {
      "post": {
        "tags": [
          "کارپوشه مالیاتی"
        ],
        "summary": "Partner: issues a fiscal memory id for a taxpayer whose code this partner verified; the id is only answered (register it with POST /api/register).",
        "operationId": "TaxWorkspaceRegistrationV2_IssueOnboardingMemoryUniqueIdAsync_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.register`. Partner (broker) credential.\n\nError codes:\n- `validation_failed` (HTTP 400): ModelState invalid (query/body binding) or the backend's filter/field validation; message joins the reasons\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): missing scope, or a token of the wrong kind; errors[].message names the cause\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule: a customer JWT is stopped by the IP gate (result/code body); a static key outside the rule answers this code in the envelope\n- `tax_workspace_disabled` (HTTP 503): TaxWorkspace.Enabled off (repository Web.config: false)\n- `service_not_configured` (HTTP 503): trusted-company or secret-protector configuration incomplete\n- `request_cancelled` (HTTP 408): cancelled / timed out\n- `tax_workspace_internal_error` (HTTP 500): unexpected exception\n- `invalid_api_client_context` (HTTP 401): no company or client identity\n- `company_not_available` (HTTP 403): business inactive\n- `economic_number_invalid` (HTTP 409): business economic code not 11/14 digits\n- `permission_denied` (HTTP 403): internal permission missing (for example a read actor reacting)\n- `tax_workspace_reauthorization_required` (HTTP 409): no usable delegation (expired, revoked, unreadable): ask a new one\n- `delegation_permission_missing` (HTTP 403): the delegation lacks the service's permission\n- `tax_workspace_permission_missing`: the organisation answered ACCESS_DENIED: prepended to the organisation's errors, HTTP status of the upstream answer\n- `profile_concurrency` (HTTP 409): concurrent change of the workspace profile\n- `tax_workspace_mutation_in_progress` (HTTP 409): another reaction or OTP operation is running\n- `tax_workspace_mutation_recheck_required` (HTTP 409): an earlier reaction's outcome must be re-read first\n- `tax_workspace_mutation_outcome_unknown` (HTTP 409): earlier reaction outcome unknown\n- `tax_workspace_identity_changed` (HTTP 409): the business's economic code changed during the operation\n- `economic_number_reconciliation_required` (HTTP 409): economic code change pending\n- `economic_number_change_in_progress` (HTTP 409): economic code change running\n- `(organisation codes)`: upstream refusal: envelope status = the organisation's status (or INVALID_RESPONSE), errors = the organisation's [{code,message}], fieldErrors passed through; HTTP = upstream 4xx/5xx, 401 becomes 502, a non-error status becomes 502 (FromUpstream, TaxWorkspaceApplicationService.cs:5225-5249)\n- `upstream_timeout | upstream_transport_error | upstream_invalid_response | upstream_invalid_data | upstream_empty_response | upstream_response_too_large | upstream_server_error | upstream_unavailable | upstream_unauthorized | upstream_nonce_invalid | certificate_signing_failed`: transport, nonce, signing or answer-format failures (TrustedCompanyApiClient / TaxWorkspaceApplicationService; statuses not traced one by one)\n- `tax_workspace_memory_unique_id_disabled` (HTTP 503): memory-unique-id services off\n- `tax_workspace_memory_permission_missing`: delegation lacks memory-unique-id:manage (status not traced)\n- `tax_workspace_memory_operation_in_progress` (HTTP 409): another memory operation running\n- `invalid_memory_unique_id` (HTTP 400): organisation returned an unusable id\n- `partner_suspended` (HTTP 403): registered partner suspended (PartnerAccess.Refusal; unregistered partners pass)\n- `capability_disabled` (HTTP 403): otpOnboarding off for the registered partner\n- `onboarding_owner_check_required` (HTTP 409): no successful verify by this partner client for this economic code in the last 30 minutes",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "economicCode": {
                    "type": "string",
                    "description": "11 or 14 digits; the same as verified"
                  }
                },
                "required": [
                  "economicCode"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "issued (companyTokenId null, created false) — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxWorkspaceMemoryUniqueIdResultDto"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/tax-file-inquiry": {
      "post": {
        "tags": [
          "استعلام پرونده مالیاتی"
        ],
        "summary": "Asks the tax organisation which tax files it holds for a national code, national id, foreign national code or economic code (paid value-added service).",
        "operationId": "TaxFileInquiryV2_InquireAsync_post",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Scope: `v2.lookup.read`.\n\nNew in API v2 1.0.0.195. Refusals (service off, wallet, busy) happen before the organisation is asked and cost nothing. correlationId in the envelope is the inquiry id as 32 hex digits.\n\nError codes:\n- `unauthorized` (HTTP 401): no/invalid token\n- `forbidden` (HTTP 403): wrong kind or scope\n- `IP_NOT_ALLOWED` (HTTP 403): IP rule (auth.ErrorCode passed through)\n- `validation_failed` (HTTP 400): identifier not a valid shape\n- `tax_file_inquiry_not_active` (HTTP 403): the business's «استعلام پرونده مالیاتی خریدار» service is off\n- `tax_file_inquiry_wallet_insufficient` (HTTP 402): wallet balance too low\n- `tax_file_inquiry_busy` (HTTP 429): the business's previous inquiry is still running (30 s wait)\n- `tax_file_lookup_unavailable` (HTTP 503): tax workspace off or not configured\n- `organization_timeout` (HTTP 504): organisation did not answer in time\n- `organization_unavailable` (HTTP 502): organisation error\n- `request_cancelled` (HTTP 408): client disconnected\n- `tax_file_inquiry_internal_error` (HTTP 500): unexpected",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "identifier": {
                    "type": "string",
                    "description": "national code (10 digits), national id (11), foreign national code (12) or economic code (11 or 14); Persian digits read; personal data, body only, never logged"
                  },
                  "token": {
                    "type": "string",
                    "description": "agency token beside a static Customer key; unused with an access token"
                  }
                },
                "required": [
                  "identifier"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "answered (found or not); one fee charged from the business's wallet — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TaxFileInquiryV2Answer"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "validation_failed — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                }
              }
            }
          },
          "402": {
            "description": "wallet cannot pay — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                }
              }
            }
          },
          "403": {
            "description": "forbidden, IP_NOT_ALLOWED or service not active — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                }
              }
            }
          },
          "408": {
            "description": "request cancelled — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "another inquiry of the business still running (status TOO_MANY_REQUESTS) — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "unexpected — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                }
              }
            }
          },
          "502": {
            "description": "organisation unavailable — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "tax-file lookup unavailable here — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                }
              }
            }
          },
          "504": {
            "description": "organisation timeout — envelope family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxWorkspaceEnvelope"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Access token from POST /api/auth/v2/token (client_credentials), valid 60 minutes."
      },
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api-v2.asatsp.ir/api/auth/v2/token",
            "scopes": {
              "v2.register": "partner credentials only (PartnerDefault): POST /api/register, every /api/v2/partner/* route, /api/v2/tax-workspace/onboarding/*",
              "v2.invoice.send": "customer: register and send invoices (send, the simple-model routes, sendInvoice), editInvoice and simple/editInvoice, exchangeAnnouncement, registerPayment, tax-workspace reactions (bulk, Excel preview/execute), delegation/otp, delegation/verify, memory-unique-id",
              "v2.invoice.cancel": "customer: cancelInvoice only",
              "v2.invoice.read": "customer: inquiryInternalId(s), inquiryNo(s), inquiryTaxId(s), inquiryExchangeAnnouncement, inquiryPayment, tax-workspace lists, Excel export/template/result, GET delegation",
              "v2.lookup.read": "customer: GET /api/Currency, GET /api/InvoiceItemUnit(/codes), GET /api/v2/stuffid/{code}, POST /api/v2/tax-file-inquiry"
            }
          }
        }
      }
    },
    "schemas": {
      "InvoiceApiRequestData": {
        "type": "object",
        "properties": {
          "internalId": {
            "type": "string",
            "description": "max 255, unique within the request and among the business's active invoices; numeric values are also stored as LogInvoiceId"
          },
          "send": {
            "type": "boolean",
            "description": "null = the business's API v2 auto-send setting; must not be true with proforma"
          },
          "fiscalId": {
            "type": "string",
            "description": "exactly 6 letters/digits; chooses the fiscal memory. Absent: the default memory of the environment; for a correction, cancellation or return (ins 2-4) of a registered reference, the reference's memory when it is of the requested environment (1.0.0.209)"
          },
          "sandBox": {
            "type": "boolean",
            "description": "true = sandbox fiscal memory; default production"
          },
          "proforma": {
            "type": "boolean",
            "description": "true registers a proforma (no fiscal memory, never sent, ins=1 only, no irtaxid)"
          },
          "description": {
            "type": "string",
            "description": "max 1000"
          },
          "returnRows": {
            "type": "string",
            "description": "returns (ins=4) only: remaining (default; Body = rows left after the return, V7.9) or returned (Body = returned rows; then irtaxid may name any invoice of the chain); max 20"
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceDto"
              }
            ],
            "description": "the official invoice JSON"
          },
          "fiscalMemoryId": {
            "type": "integer",
            "description": "legacy internal CompanyTokenId; must agree with fiscalId when both are sent"
          }
        },
        "required": [
          "internalId",
          "data"
        ]
      },
      "InvoiceDto": {
        "type": "object",
        "properties": {
          "Header": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HeaderDto"
              }
            ],
            "description": "capital H (SDK property name)"
          },
          "Body": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BodyItemDto"
            },
            "description": "required with at least one row unless Header.ins=3 (cancellation: optional, dropped under V7.9 with a warning) Conditionally required."
          },
          "Payments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentItemDto"
            },
            "description": "rows whose fields are all empty are ignored; outside the pattern for 11 (and for cancellations)"
          },
          "Extension": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExtensionItemDto"
            },
            "description": "the SDK type has no members"
          }
        },
        "required": [
          "Header"
        ]
      },
      "HeaderDto": {
        "type": "object",
        "properties": {
          "taxid": {
            "type": "string",
            "description": "C# string; generated by the server; a client value is not mapped into the save request"
          },
          "indatim": {
            "type": "integer",
            "description": "C# long (non-nullable); issue time, Unix milliseconds (up to 10 digits is read as seconds everywhere since 1.0.0.209), > 0, <= 13 digits"
          },
          "ins": {
            "type": "integer",
            "description": "C# int (non-nullable); subject 1 original, 2 correction, 3 cancellation, 4 return"
          },
          "indati2m": {
            "type": "integer",
            "description": "C# long?; Article 9 registration time, Unix milliseconds only; required with insr=1, refused without it; not before indatim, not in the future; a value of 10 digits or fewer (seconds) is refused on indati2m with a message saying so (1.0.0.209) Conditionally required."
          },
          "inty": {
            "type": "integer",
            "description": "C# int?; type 1 or 2; optional only for a cancellation when V7.9 is on for the business Conditionally required."
          },
          "ft": {
            "type": "integer",
            "description": "C# int?; flight type; V7.9 matrix Required in type1/pattern6, outside other patterns (checked only under strict V7.9) Conditionally required."
          },
          "inno": {
            "type": "string",
            "description": "internal serial, max 10, ^[A-Za-z0-9]+$"
          },
          "irtaxid": {
            "type": "string",
            "description": "reference TaxId, 22 letters/digits; required when ins != 1; must be absent for a proforma Conditionally required."
          },
          "scln": {
            "type": "string",
            "description": "customs licence number (<=14 digits), type 1 patterns 1-2 only; a value breaking the V7.9 format is dropped (InvoicePatternFieldPolicy)"
          },
          "setm": {
            "type": "integer",
            "description": "C# int?; settlement 1 cash, 2 credit, 3 both; required when the V7.9 rule set keeps it in the pattern (type 1) except a V7.9 cancellation; outside the pattern for type 2 Conditionally required."
          },
          "tins": {
            "type": "string",
            "description": "seller economic code, 11-14 digits; must equal the authenticated business's economic code"
          },
          "cap": {
            "type": "integer",
            "description": "C# long?; cash amount, 18 integer digits, >= 0; required when setm=3; cap + insp <= tbill (== tbill for pattern 11 with setm=3) Conditionally required."
          },
          "bid": {
            "type": "string",
            "description": "buyer national id/code, 5-14 digits; type-1 original with a buyer requirement needs tinb or bid Conditionally required."
          },
          "insp": {
            "type": "integer",
            "description": "C# long?; credit amount; required when setm=3 Conditionally required."
          },
          "tvop": {
            "type": "integer",
            "description": "C# long?; VAT share of the payment, >= 0"
          },
          "bpc": {
            "type": "string",
            "description": "buyer postal code, exactly 10 digits"
          },
          "tax17": {
            "type": "integer",
            "description": "C# long?; article-17 tax, >= 0; outside pattern 11"
          },
          "inp": {
            "type": "integer",
            "description": "C# int?; pattern; type 1: 1,2,3,4,5,6,7,8,9,11,13,14; type 2: 1,3,9,13; optional only for a V7.9 cancellation Conditionally required."
          },
          "scc": {
            "type": "string",
            "description": "seller customs office code (5 digits), type 1 patterns 1, 2, 7"
          },
          "billid": {
            "type": "string",
            "description": "max 19; required for inp=5 ins=1 under strict V7.9 Conditionally required."
          },
          "tprdis": {
            "type": "integer",
            "description": "C# long?; must equal the sum of Body prdis; not checked for ins=3; optional for inp=7; outside pattern 11 Conditionally required."
          },
          "tdis": {
            "type": "integer",
            "description": "C# long?; = sum(dis); same exceptions as tprdis Conditionally required."
          },
          "tadis": {
            "type": "integer",
            "description": "C# long?; = sum(adis); optional for inp=7; required for pattern 11 Conditionally required."
          },
          "tvam": {
            "type": "integer",
            "description": "C# long?; = sum(vam); required unless ins=3 Conditionally required."
          },
          "todam": {
            "type": "integer",
            "description": "C# long?; = sum(odam + olam); outside pattern 11 Conditionally required."
          },
          "tbill": {
            "type": "integer",
            "description": "C# long?; = sum(tsstam); required unless ins=3 Conditionally required."
          },
          "tob": {
            "type": "integer",
            "description": "C# int?; buyer type 1 natural, 2 legal, 3 civil partnership, 4 foreign; required for ins=1 when InvoiceBuyerRequirement.IsRequired(inty, inp) (type 1 except patterns 7 and 11); tob=2 requires tinb Conditionally required."
          },
          "tinb": {
            "type": "string",
            "description": "buyer economic code, 11-14 digits; see bid and tob Conditionally required."
          },
          "sbc": {
            "type": "string",
            "description": "seller branch code, exactly 4 digits"
          },
          "bbc": {
            "type": "string",
            "description": "buyer branch code, exactly 4 digits"
          },
          "bpn": {
            "type": "string",
            "description": "buyer passport (<=9); V7.9 matrix: conditional in patterns 2 and 6, optional in 7 Conditionally required."
          },
          "crn": {
            "type": "string",
            "description": "contract number, max 12; required when inp=4 Conditionally required."
          },
          "cdcn": {
            "type": "string",
            "description": "customs declaration (cottage) number, pattern 7, <= 14 digits (others ignored)"
          },
          "cdcd": {
            "type": "integer",
            "description": "C# int?; cottage date as Unix day, pattern 7"
          },
          "tonw": {
            "type": "number",
            "description": "C# decimal?; total net weight (patterns 7, 8); removed when outside the pattern"
          },
          "torv": {
            "type": "integer",
            "description": "C# long?; total rial value, pattern 7 (matrix Required) Conditionally required."
          },
          "tocv": {
            "type": "number",
            "description": "C# decimal?; total currency value, pattern 7 (matrix Required) Conditionally required."
          },
          "tinc": {
            "type": "string",
            "description": "agency economic code, pattern 6"
          },
          "lno": {
            "type": "string",
            "description": "bill of lading number, pattern 8 (matrix Required) Conditionally required."
          },
          "lrno": {
            "type": "string",
            "description": "reference bill of lading, pattern 8"
          },
          "ocu": {
            "type": "string",
            "description": "origin country code (max 3), pattern 8; checked against the V7.9 coding Conditionally required."
          },
          "oci": {
            "type": "string",
            "description": "origin city code (max 5), pattern 8; required for Iran (033) Conditionally required."
          },
          "dco": {
            "type": "string",
            "description": "destination country, pattern 8 Conditionally required."
          },
          "dci": {
            "type": "string",
            "description": "destination city, pattern 8 Conditionally required."
          },
          "tid": {
            "type": "string",
            "description": "sender id, pattern 8 Conditionally required."
          },
          "rid": {
            "type": "string",
            "description": "receiver id, pattern 8 Conditionally required."
          },
          "lt": {
            "type": "integer",
            "description": "C# byte?; transport type 1 road, 2 rail, 3 air, 4 sea, pattern 8 Conditionally required."
          },
          "cno": {
            "type": "string",
            "description": "fleet number, pattern 8 Conditionally required."
          },
          "did": {
            "type": "string",
            "description": "road driver id, pattern 8 Conditionally required."
          },
          "sg": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShippingGoodDto"
            },
            "description": "shipped goods, pattern 8 Conditionally required."
          },
          "asn": {
            "type": "string",
            "description": "exchange sale announcement number, 1-30 digits; required for pattern 11 when ins != 3 Conditionally required."
          },
          "asd": {
            "type": "integer",
            "description": "C# int?; announcement date as Unix day > 0, not after the Tehran day of indatim; required for pattern 11 when ins != 3 Conditionally required."
          },
          "In": {
            "type": "string",
            "description": "capital I (SDK name; input is case-insensitive); insurance policy id, pattern 13 (matrix Required) Conditionally required."
          },
          "an": {
            "type": "string",
            "description": "insurance addendum id, pattern 13"
          },
          "insr": {
            "type": "integer",
            "description": "C# int?; send rule, only 1 (Article 9 late invoice); needs the Article 9 feature for the business"
          },
          "nti1": {
            "type": "string",
            "description": "note 1, max 30"
          },
          "nti2": {
            "type": "string",
            "description": "note 2, max 30"
          }
        },
        "required": [
          "indatim",
          "ins",
          "inno",
          "tins"
        ]
      },
      "BodyItemDto": {
        "type": "object",
        "properties": {
          "sstid": {
            "type": "string",
            "description": "goods/service id, exactly 13 digits"
          },
          "sstt": {
            "type": "string",
            "description": "description, max 400"
          },
          "mu": {
            "type": "string",
            "description": "official unit code, 1-8 digits, must exist (GET /api/InvoiceItemUnit/codes); required for pattern 11 Conditionally required."
          },
          "am": {
            "type": "number",
            "description": "C# decimal?; quantity > 0, 18 integer / 8 decimal digits; must be 1 in patterns 6 and 8 under strict V7.9"
          },
          "fee": {
            "type": "number",
            "description": "C# decimal?; unit price, integer (18/0), >= 0; required except patterns 2 and 11 Conditionally required."
          },
          "cfee": {
            "type": "number",
            "description": "C# decimal?; currency amount (14 integer / 4 decimal digits); required when any currency field (cfee, cut, exr, sscv, cpr) is present, except pattern 7 (optional) and 11 (outside) Conditionally required."
          },
          "cut": {
            "type": "string",
            "description": "currency code, max 3; with the currency fields Conditionally required."
          },
          "exr": {
            "type": "number",
            "description": "C# long? in the SDK, but up to 18 integer / 8 decimal digits are accepted and read exactly from the raw body; with the currency fields Conditionally required."
          },
          "prdis": {
            "type": "integer",
            "description": "C# long?; amount before discount; required except pattern 7 and pattern-11 issues Conditionally required."
          },
          "dis": {
            "type": "integer",
            "description": "C# long?; discount, default 0"
          },
          "adis": {
            "type": "integer",
            "description": "C# long?; amount after discount = prdis - dis; required (> 0, the announcement value) for pattern 11 Conditionally required."
          },
          "vra": {
            "type": "number",
            "description": "C# decimal?; VAT rate 0..100, 3 integer / 2 decimal digits; must be 0 in pattern 11"
          },
          "vam": {
            "type": "integer",
            "description": "C# long?; VAT amount; must be 0 in pattern 11"
          },
          "odt": {
            "type": "string",
            "description": "other tax subject, max 255"
          },
          "odr": {
            "type": "number",
            "description": "C# decimal?; other tax rate, 5/2"
          },
          "odam": {
            "type": "integer",
            "description": "C# long?; other tax amount"
          },
          "olt": {
            "type": "string",
            "description": "other legal levy subject, max 255"
          },
          "olr": {
            "type": "number",
            "description": "C# decimal?; rate, 5/2"
          },
          "olam": {
            "type": "integer",
            "description": "C# long?; amount"
          },
          "consfee": {
            "type": "integer",
            "description": "C# long?; making fee, required for pattern 3 Conditionally required."
          },
          "spro": {
            "type": "integer",
            "description": "C# long?; seller profit, required for pattern 3 Conditionally required."
          },
          "bros": {
            "type": "integer",
            "description": "C# long?; commission, required for pattern 3 Conditionally required."
          },
          "tcpbs": {
            "type": "integer",
            "description": "C# long?; consfee + spro + bros, required for pattern 3 Conditionally required."
          },
          "cop": {
            "type": "integer",
            "description": "C# long?; cash share of payment; removed silently for type 2 when outside the pattern"
          },
          "bsrn": {
            "type": "string",
            "description": "third-party contract number, exactly 12 digits, only where InvoiceIdentifierValidator.ShouldSerializeThirdPartyContractNumber(inp, ins)"
          },
          "vop": {
            "type": "integer",
            "description": "C# long?; VAT share of payment; as cop"
          },
          "tsstam": {
            "type": "integer",
            "description": "C# long?; total = adis + vam + odam + olam"
          },
          "nw": {
            "type": "number",
            "description": "C# decimal?; net weight 15/8, required for pattern 7 Conditionally required."
          },
          "ssrv": {
            "type": "integer",
            "description": "C# long?; rial value, required for pattern 7 Conditionally required."
          },
          "sscv": {
            "type": "number",
            "description": "C# decimal?; currency value 14/4, required for pattern 7 Conditionally required."
          },
          "cui": {
            "type": "number",
            "description": "C# decimal?; carat; pattern 3, and pattern 11 (> 0, <= 1000, 2 decimals; 0 treated as absent)"
          },
          "hs": {
            "type": "string",
            "description": "SDK field; not checked by the validator, not in the V7.9 matrix"
          },
          "cpr": {
            "type": "number",
            "description": "C# decimal?; currency purchase rate 18/8, required for pattern 2 Conditionally required."
          },
          "sovat": {
            "type": "integer",
            "description": "C# long?; VAT base of a currency sale, required for pattern 2 Conditionally required."
          },
          "vba": {
            "type": "number",
            "description": "C# decimal?; VAT base, pattern 9 (V7.9 matrix conditional) Conditionally required."
          }
        },
        "required": [
          "sstid",
          "am",
          "vra",
          "vam",
          "tsstam"
        ]
      },
      "PaymentItemDto": {
        "type": "object",
        "properties": {
          "iinn": {
            "type": "string",
            "description": "switch number, exactly 9 digits"
          },
          "acn": {
            "type": "string",
            "description": "acceptor number, exactly 14 digits; required when pmt=4 (POS) Conditionally required."
          },
          "trmn": {
            "type": "string",
            "description": "terminal number, exactly 8 digits; required when pmt=4 Conditionally required."
          },
          "trn": {
            "type": "string",
            "description": "trace/reference number; the code checks exactly 14 digits (OptionalDigits exactLength=true, InvoiceV2JsonValidator.cs:850)"
          },
          "pcn": {
            "type": "string",
            "description": "payer card number, exactly 16 digits; required when pmt=4 Conditionally required."
          },
          "pid": {
            "type": "string",
            "description": "payer id; the code checks exactly 12 digits (exactLength=true, :851)"
          },
          "vatpid": {
            "type": "string",
            "description": "SDK field, not checked"
          },
          "vatbid": {
            "type": "string",
            "description": "SDK field, not checked"
          },
          "pdt": {
            "type": "integer",
            "description": "C# long?; payment time, Unix ms (up to 10 digits is read as seconds); each non-empty row"
          },
          "pmt": {
            "type": "integer",
            "description": "C# int?; method 1..8 (1 cheque, 2 barter, 3 cash, 4 POS, 5 internet, 6 card, 7 transfer, 8 other per InvoicePaymentTaxRegistrationPolicy names)"
          },
          "pv": {
            "type": "integer",
            "description": "C# long?; amount, <= tbill; the rows' sum <= tbill"
          }
        },
        "required": [
          "pdt",
          "pmt",
          "pv"
        ]
      },
      "ExtensionItemDto": {
        "type": "object",
        "properties": {}
      },
      "ShippingGoodDto": {
        "type": "object",
        "properties": {
          "sgid": {
            "type": "string",
            "description": "shipped goods id (13 digits), pattern 8 Conditionally required."
          },
          "sgt": {
            "type": "string",
            "description": "description (<= 400), pattern 8 Conditionally required."
          }
        }
      },
      "ClassicInvoiceData": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string",
            "description": "agency token (the first non-empty one is used when the root token is empty)"
          },
          "internalId": {
            "type": "string",
            "description": "max 255, unique"
          },
          "no": {
            "type": "string",
            "description": "invoice number (Header.inno), max 10, ^[A-Za-z0-9]+$"
          },
          "dateTime": {
            "type": "string",
            "description": "issue time: Unix (<= 13 digits, used as given), yyyyMMddHHmmss (Tehran), or a date text the backend reads (Jalali, then DateTime.TryParse); empty = now"
          },
          "isArticle9": {
            "type": "boolean",
            "description": "Article 9 late invoice (insr=1)"
          },
          "invoiceRegistrationDateTime": {
            "type": "integer",
            "description": "C# long?; Unix ms; with isArticle9 (indati2m) Conditionally required."
          },
          "description": {
            "type": "string"
          },
          "invoiceSubject": {
            "type": "integer",
            "description": "ClassicInvoiceSubject 1 original (default), 2 correction, 3 cancellation, 4 return"
          },
          "invoiceIssue": {
            "type": "integer",
            "description": "legacy alias of invoiceSubject (used when invoiceSubject is absent)"
          },
          "sourceInternalId": {
            "type": "string",
            "description": "reference for subjects 2-4 (or sourceTaxId); the reference must have a TaxId Conditionally required."
          },
          "sourceTaxId": {
            "type": "string",
            "description": "reference TaxId for subjects 2-4; wins over sourceInternalId Conditionally required."
          },
          "settlement": {
            "type": "integer",
            "description": "ClassicSettlementType 1 cash (default), 2 credit, 3 cash/credit"
          },
          "payment": {
            "type": "number",
            "description": "C# decimal?; cash share, required >= 0 when settlement=3 (floored, capped at the total) Conditionally required."
          },
          "buyer": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ClassicBuyerData"
              }
            ],
            "description": "required on routes whose type/pattern needs a buyer; kept when given on the others Conditionally required."
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ClassicInvoiceItem"
            },
            "description": "at least one (every subject); one only for patterns 11 and 14"
          },
          "payments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ClassicPaymentData"
            },
            "description": "outside pattern 11"
          },
          "send": {
            "type": "boolean",
            "description": "null = auto-send setting"
          },
          "fiscalId": {
            "type": "string",
            "description": "6 characters; fiscal memory choice. Absent on invoiceSubject 2-4: the reference's memory when it is of the requested environment (1.0.0.209)"
          },
          "sandBox": {
            "type": "boolean"
          },
          "proforma": {
            "type": "boolean",
            "description": "register as proforma"
          },
          "contractCode": {
            "type": "string",
            "description": "exactly 12 digits, required for template 4; outside 11 Conditionally required."
          },
          "billNo": {
            "type": "string",
            "description": "1-19 digits, required for template 5; outside 11 Conditionally required."
          },
          "cottageNo": {
            "type": "string",
            "description": "template 7, 1-14 digits; required with cottageDate"
          },
          "cottageDate": {
            "type": "string",
            "description": "template 7: yyyyMMdd, yyyyMMddHHmmss, Unix or a date text"
          },
          "saleAnnNo": {
            "type": "string",
            "description": "template 11: 1-30 digits Conditionally required."
          },
          "saleAnnDate": {
            "type": "string",
            "description": "template 11: yyyyMMdd, yyyyMMddHHmmss, Unix s/ms or a date text; not after dateTime Conditionally required."
          },
          "insPolicyNo": {
            "type": "string",
            "description": "template 13: 9-12 digits Conditionally required."
          },
          "extInsPolicyNo": {
            "type": "string",
            "description": "template 13: 9-12 digits"
          },
          "declarationNo": {
            "type": "string",
            "description": "type 1, templates 1-2: 1-14 digits (scln)"
          },
          "officeCode": {
            "type": "string",
            "description": "type 1, templates 1, 2, 7: exactly 5 digits (scc)"
          },
          "flightInfo": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ClassicFlightInfoData"
              }
            ],
            "description": "required for template 6 Conditionally required."
          },
          "shipmentInfo": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ClassicShipmentInfoData"
              }
            ],
            "description": "required for template 8 Conditionally required."
          },
          "tax17": {
            "type": "number",
            "description": "C# decimal?; article-17 tax (floored); outside 11"
          },
          "fiscalMemoryId": {
            "type": "integer",
            "description": "legacy CompanyTokenId"
          }
        },
        "required": [
          "internalId",
          "no",
          "items"
        ]
      },
      "ClassicBuyerData": {
        "type": "object",
        "properties": {
          "type": {
            "type": "integer",
            "description": "ClassicBuyerType 1 natural (default), 2 legal, 3 civil partnership, 4 foreign"
          },
          "nationalCode": {
            "type": "string",
            "description": "5-14 digits; nationalCode or economicCode (or a passport) required Conditionally required."
          },
          "economicCode": {
            "type": "string",
            "description": "11-14 digits; required for type 2 Conditionally required."
          },
          "zipCode": {
            "type": "string",
            "description": "exactly 10 digits; not sent for template 7"
          },
          "name": {
            "type": "string"
          },
          "mobile": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "branchCode": {
            "type": "integer",
            "description": "padded to 4 digits (bbc)"
          },
          "passportNumber": {
            "type": "string",
            "description": "only type 4 in template 2 (currency sale), <= 9 Latin letters/digits"
          }
        }
      },
      "ClassicInvoiceItem": {
        "type": "object",
        "properties": {
          "no": {
            "type": "string",
            "description": "not read by the code traced"
          },
          "internalId": {
            "type": "string",
            "description": "the business's own goods code, max 254; fills a missing stuffId from the business's goods (with a warning)"
          },
          "stuffId": {
            "type": "string",
            "description": "exactly 13 digits (unless filled from internalId)"
          },
          "description": {
            "type": "string",
            "description": "sstt, truncated to 400"
          },
          "qty": {
            "type": "number",
            "description": "> 0"
          },
          "unit": {
            "type": "string",
            "description": "official unit code or unit name (legacy: internal UnitId, with a warning); required except template 2 Conditionally required."
          },
          "unitPrice": {
            "type": "number",
            "description": ">= 0; required except template 11 (there amountAfterDiscount or unitPrice); not sent as fee in templates 2 and 11 Conditionally required."
          },
          "discount": {
            "type": "number",
            "description": ">= 0, <= qty*unitPrice; outside 11"
          },
          "amountAfterDiscount": {
            "type": "number",
            "description": "template 11 only: integer rials > 0, the announcement's deal value Conditionally required."
          },
          "vatRate": {
            "type": "number",
            "description": "0..100; 0 in template 11"
          },
          "otherTaxDescription": {
            "type": "string",
            "description": "odt"
          },
          "otherTaxRate": {
            "type": "number",
            "description": "odr; outside 11"
          },
          "govTaxDescription": {
            "type": "string",
            "description": "olt"
          },
          "govTaxRate": {
            "type": "number",
            "description": "olr; outside 11"
          },
          "wage": {
            "type": "number",
            "description": ">= 0, required for template 3 Conditionally required."
          },
          "profit": {
            "type": "number",
            "description": ">= 0, required for template 3 Conditionally required."
          },
          "commission": {
            "type": "number",
            "description": ">= 0, required for template 3 Conditionally required."
          },
          "carat": {
            "type": "number",
            "description": "cui (template 3; template 11 with the 11 limits)"
          },
          "contractNo": {
            "type": "number",
            "description": "C# decimal?; third-party contract number (bsrn), 12 digits where the rule applies; outside 11"
          },
          "currency": {
            "type": "string",
            "description": "legacy alias of currencyCode"
          },
          "currencyCode": {
            "type": "string",
            "description": "max 3; required for templates 2 and 7 Conditionally required."
          },
          "amountCurrency": {
            "type": "number",
            "description": "cfee (template 2 falls back to qty, 7 to currencyValue)"
          },
          "currencyRate": {
            "type": "number",
            "description": "> 0 for templates 2 and 7; sent as exr floored Conditionally required."
          },
          "currencyValue": {
            "type": "number",
            "description": "> 0 for template 7 (sscv) Conditionally required."
          },
          "currencyPurchaseRate": {
            "type": "number",
            "description": "template 2: > 0 and < currencyRate (cpr) Conditionally required."
          },
          "vatBaseAmount": {
            "type": "number",
            "description": "template 2: required >= 0 (sovat); template 9: optional >= 0 (vba) Conditionally required."
          },
          "netWeight": {
            "type": "number",
            "description": "template 7: > 0 (nw) Conditionally required."
          }
        },
        "required": [
          "stuffId",
          "qty",
          "vatRate"
        ]
      },
      "ClassicPaymentData": {
        "type": "object",
        "properties": {
          "type": {
            "type": "integer",
            "description": "pmt 1..8; default 1 on the simple invoice routes; required on registerPayment Conditionally required."
          },
          "dateTime": {
            "type": "string",
            "description": "as ClassicInvoiceData.dateTime; default the invoice time; required on registerPayment Conditionally required."
          },
          "price": {
            "type": "number",
            "description": "floored (pv); registerPayment: > 0, <= 18 digits Conditionally required."
          },
          "traceNo": {
            "type": "string",
            "description": "trn"
          },
          "cardNo": {
            "type": "string",
            "description": "pcn"
          },
          "payerNationalCode": {
            "type": "string",
            "description": "pid"
          },
          "switchNumber": {
            "type": "string",
            "description": "iinn"
          },
          "acquirerNumber": {
            "type": "string",
            "description": "acn"
          },
          "terminalNumber": {
            "type": "string",
            "description": "trmn"
          },
          "description": {
            "type": "string",
            "description": "stored only"
          }
        }
      },
      "ClassicFlightInfoData": {
        "type": "object",
        "properties": {
          "buyerMethod": {
            "type": "integer",
            "description": "1 national id, 2 foreign (comprehensive) code, 3 passport; derived from the filled field when absent; must resolve to 1..3"
          },
          "economicCode": {
            "type": "string",
            "description": "11-14 digits (tinb)"
          },
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          },
          "flightType": {
            "type": "integer",
            "description": "1 domestic, 2 foreign (ft)"
          },
          "nationalId": {
            "type": "string",
            "description": "10 digits; required for method 1 Conditionally required."
          },
          "foreignId": {
            "type": "string",
            "description": "12 digits; required for method 2 Conditionally required."
          },
          "passportNumber": {
            "type": "string",
            "description": "<= 9; required for method 3, foreign flights only (bpn) Conditionally required."
          },
          "agentEconomicCode": {
            "type": "string",
            "description": "11-14 digits (tinc)"
          },
          "agentName": {
            "type": "string"
          }
        },
        "required": [
          "flightType"
        ]
      },
      "ClassicShipmentInfoData": {
        "type": "object",
        "properties": {
          "blNumber": {
            "type": "string",
            "description": "1-18 digits (lno)"
          },
          "refBlNumber": {
            "type": "string",
            "description": "1-18 digits (lrno)"
          },
          "originCountry": {
            "type": "string",
            "description": "V7.9 country code (ocu)"
          },
          "originProvince": {
            "type": "string",
            "description": "stored only"
          },
          "originCity": {
            "type": "string",
            "description": "V7.9 city code; required for Iran 033 (oci) Conditionally required."
          },
          "destinationCountry": {
            "type": "string",
            "description": "(dco)"
          },
          "destinationProvince": {
            "type": "string"
          },
          "destinationCity": {
            "type": "string",
            "description": "(dci) Conditionally required."
          },
          "senderName": {
            "type": "string"
          },
          "senderLastName": {
            "type": "string"
          },
          "senderEconomicCode": {
            "type": "string",
            "description": "10, 11 or 12 digits (tid)"
          },
          "receiverName": {
            "type": "string"
          },
          "receiverLastName": {
            "type": "string"
          },
          "receiverEconomicCode": {
            "type": "string",
            "description": "10, 11 or 12 digits (rid)"
          },
          "driverName": {
            "type": "string"
          },
          "driverLastName": {
            "type": "string"
          },
          "driverIdCode": {
            "type": "string",
            "description": "required when transportType 1 (road); InvoiceIdentifierValidator driver rule (did) Conditionally required."
          },
          "fleetNumber": {
            "type": "string",
            "description": "max 20 (cno)"
          },
          "transportType": {
            "type": "string",
            "description": "1 road, 2 rail, 3 air, 4 sea (lt)"
          },
          "totalWeight": {
            "type": "number",
            "description": "> 0 (tonw)"
          },
          "shippedItems": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ClassicShipmentGoodData"
            },
            "description": "sg"
          }
        },
        "required": [
          "blNumber",
          "originCountry",
          "destinationCountry",
          "senderEconomicCode",
          "receiverEconomicCode",
          "fleetNumber",
          "transportType",
          "totalWeight"
        ]
      },
      "ClassicShipmentGoodData": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "stored only"
          },
          "stuffId": {
            "type": "string",
            "description": "13 digits (sgid)"
          },
          "name": {
            "type": "string",
            "description": "max 400 (sgt)"
          }
        },
        "required": [
          "stuffId",
          "name"
        ]
      },
      "InvoiceApiReturnData": {
        "type": "object",
        "properties": {
          "result": {
            "type": "integer",
            "description": "1, 0, -1, -2"
          },
          "traceId": {
            "type": "string",
            "description": "Guid, new per request (not the X-Correlation-ID)"
          },
          "message": {
            "type": "string",
            "description": "Persian summary; error answers add the number of errors Presence: alwaysNullable."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiValidationError"
            },
            "description": "on batch routes: all member and global errors Presence: omittedWhenNull."
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoiceApiReturnInfo"
            },
            "description": "null in answers built by BuildErrorReturn Presence: alwaysNullable."
          },
          "exchangeAnnouncement": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceExchangeAnnouncementStatusResult"
              }
            ],
            "description": "exchange-announcement routes Presence: omittedWhenNull."
          },
          "edit": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceEditResult"
              }
            ],
            "description": "edit routes Presence: omittedWhenNull."
          }
        }
      },
      "ApiValidationError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "machine code when there is one Presence: omittedWhenNull."
          },
          "path": {
            "type": "string",
            "description": "JSONPath-like: $.data[i].data.Header.inno, $.uuid, route.template, headers.Authorization Presence: omittedWhenNull."
          },
          "field": {
            "type": "string",
            "description": "field name or a backend reason code Presence: omittedWhenNull."
          },
          "ruleVersion": {
            "type": "string",
            "description": "RC_IITP.IS_V7.9 on V7.9 errors Presence: omittedWhenNull."
          },
          "message": {
            "type": "string",
            "description": "Persian Presence: alwaysNullable."
          }
        }
      },
      "InvoiceApiReturnInfo": {
        "type": "object",
        "properties": {
          "asatspId": {
            "type": "integer",
            "description": "C# long?; internal InvoiceId (tracking code) Presence: omittedWhenNull."
          },
          "taxId": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "fiscalMemoryId": {
            "type": "integer",
            "description": "CompanyTokenId Presence: omittedWhenNull."
          },
          "fiscalId": {
            "type": "string",
            "description": "the invoice's fiscal id snapshot Presence: omittedWhenNull."
          },
          "fiscalMemoryTitle": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "sandBox": {
            "type": "boolean",
            "description": "Presence: omittedWhenNull."
          },
          "environment": {
            "type": "string",
            "description": "Production | Sandbox Presence: omittedWhenNull."
          },
          "environmentTitle": {
            "type": "string",
            "description": "Persian title Presence: omittedWhenNull."
          },
          "isDefaultFiscalMemory": {
            "type": "boolean",
            "description": "false on error members"
          },
          "status": {
            "type": "integer",
            "description": "InvoicePhases: 0 AwaitingSend, 1 Pending, 2 Success, 3 hasError, 7 Proforma (4-6 never produced) Presence: omittedWhenNull."
          },
          "error": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "errors of a refused member ('path: message') or the invoice's latest error Presence: omittedWhenNull."
          },
          "latestTaxId": {
            "type": "string",
            "description": "declared, never set Presence: omittedWhenNull."
          },
          "mainTaxId": {
            "type": "string",
            "description": "declared, never set Presence: omittedWhenNull."
          },
          "issue": {
            "type": "integer",
            "description": "InvoiceIssues 1 Main, 2 Edit, 3 Annul, 4 SalesReturn Presence: omittedWhenNull."
          },
          "internalId": {
            "type": "string",
            "description": "echo of the request's id where known Presence: omittedWhenNull."
          },
          "no": {
            "type": "string",
            "description": "inquiryNo: the requested number; proforma: its number Presence: omittedWhenNull."
          },
          "refrenceNumber": {
            "type": "string",
            "description": "spelled so; the organisation's reference number (status 1/2) Presence: omittedWhenNull."
          },
          "json": {
            "description": "status 2 only: the payload sent to the organisation (InvoiceTaxGovLog.SendStringify Payload, parsed) Presence: omittedWhenNull."
          },
          "statusInquery": {
            "type": "string",
            "description": "spelled so; buyer reaction status, e.g. AWAITING_REACTION Presence: omittedWhenNull."
          },
          "article6Status": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "exchangeAnnouncement": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceExchangeAnnouncementSummary"
              }
            ],
            "description": "pattern 11 only Presence: omittedWhenNull."
          },
          "paymentRegistration": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoicePaymentRegistrationInfo"
              }
            ],
            "description": "payment routes only Presence: omittedWhenNull."
          },
          "payments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoicePaymentApiInfo"
            },
            "description": "payment routes only Presence: omittedWhenNull."
          },
          "proforma": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceProformaApiInfo"
              }
            ],
            "description": "status 7 only Presence: omittedWhenNull."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "registration answers only: non-blocking notes (dropped fields, filled stuffId, buyer tax file, unit notes) Presence: omittedWhenNull."
          }
        }
      },
      "InvoiceProformaApiInfo": {
        "type": "object",
        "properties": {
          "validUntil": {
            "type": "string",
            "description": "Jalali day 1405/07/30 Presence: alwaysNullable."
          },
          "state": {
            "type": "string",
            "description": "open | expired | converted Presence: alwaysNullable."
          },
          "stateTitle": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "convertedInvoiceNo": {
            "type": "string",
            "description": "converted only Presence: omittedWhenNull."
          }
        }
      },
      "InvoiceExchangeAnnouncementSummary": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "notRecorded | notConfirmed | confirmed Presence: alwaysNullable."
          },
          "source": {
            "type": "string",
            "description": "manual | orgApi Presence: omittedWhenNull."
          },
          "setBy": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "setAt": {
            "type": "string",
            "description": "Jalali text, Tehran Presence: omittedWhenNull."
          },
          "setAtUtc": {
            "type": "string",
            "description": "DateTime Presence: omittedWhenNull."
          }
        }
      },
      "InvoiceExchangeAnnouncementStatusResult": {
        "type": "object",
        "properties": {
          "invoiceId": {
            "type": "integer"
          },
          "originTaxId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "rootInvoiceId": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "description": "notRecorded | notConfirmed | confirmed Presence: alwaysNullable."
          },
          "source": {
            "type": "string",
            "description": "manual | orgApi Presence: omittedWhenNull."
          },
          "channel": {
            "type": "string",
            "description": "panel | apiV2 | orgApi | script Presence: omittedWhenNull."
          },
          "setByUserId": {
            "type": "integer",
            "description": "Presence: omittedWhenNull."
          },
          "setBy": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "setAtUtc": {
            "type": "string",
            "description": "DateTime Presence: omittedWhenNull."
          },
          "setAt": {
            "type": "string",
            "description": "Jalali text Presence: omittedWhenNull."
          },
          "saleAnnNo": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "saleAnnDate": {
            "type": "string",
            "description": "Jalali text Presence: omittedWhenNull."
          },
          "note": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "version": {
            "type": "string",
            "description": "base64 rowversion; send back as expectedVersion Presence: omittedWhenNull."
          },
          "canChange": {
            "type": "boolean"
          },
          "pendingCorrectionDrafts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoiceExchangeAnnouncementDraft"
            }
          }
        }
      },
      "InvoiceExchangeAnnouncementDraft": {
        "type": "object",
        "properties": {
          "invoiceId": {
            "type": "integer"
          },
          "no": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "hash": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "inFlight": {
            "type": "boolean",
            "description": "true: submitted (phase 2) without result Presence: omittedWhenNull."
          }
        }
      },
      "InvoiceEditResult": {
        "type": "object",
        "properties": {
          "outcome": {
            "type": "string",
            "description": "unchanged | draftUpdated | paymentUpdated | correctionIssued | confirmationRequired Presence: alwaysNullable."
          },
          "previousTaxId": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "taxId": {
            "type": "string",
            "description": "the saved version's TaxId (new for a correction) Presence: omittedWhenNull."
          },
          "referenceTaxId": {
            "type": "string",
            "description": "correctionIssued / confirmationRequired Presence: omittedWhenNull."
          },
          "confirmedBy": {
            "type": "string",
            "description": "confirmCorrection | confirmationToken Presence: omittedWhenNull."
          },
          "reason": {
            "type": "string",
            "description": "FIELDS_CHANGED | SETTLEMENT_CHANGED | CHANGES_BESIDES_PAYMENT Presence: omittedWhenNull."
          },
          "confirmationToken": {
            "type": "string",
            "description": "ec1.<expiresAt>.<invoiceId>.<64 hex> Presence: omittedWhenNull."
          },
          "expiresAt": {
            "type": "integer",
            "description": "Unix ms Presence: omittedWhenNull."
          }
        }
      },
      "InvoicePaymentRegistrationInfo": {
        "type": "object",
        "properties": {
          "eligible": {
            "type": "boolean"
          },
          "rowsLocked": {
            "type": "boolean"
          },
          "code": {
            "type": "string",
            "description": "eligibility code when not eligible Presence: omittedWhenNull."
          },
          "reason": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          }
        }
      },
      "InvoicePaymentApiInfo": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "type": {
            "type": "integer",
            "description": "1..8"
          },
          "dateTime": {
            "type": "string",
            "description": "Tehran 'yyyy/MM/dd HH:mm' (Gregorian digits as stored) Presence: alwaysNullable."
          },
          "timestamp": {
            "type": "integer",
            "description": "Unix ms Presence: omittedWhenNull."
          },
          "price": {
            "type": "number"
          },
          "traceNo": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "terminalNumber": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "cardNo": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "payerNationalCode": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "description": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "locked": {
            "type": "boolean"
          },
          "registration": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoicePaymentRegistrationState"
              }
            ],
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "InvoicePaymentRegistrationState": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "queued | registered | rejected | unknown | notApplicable | failed | sentWithInvoice | notRegistered Presence: alwaysNullable."
          },
          "code": {
            "type": "string",
            "description": "official or MEGAPAY_* error code Presence: omittedWhenNull."
          },
          "message": {
            "type": "string",
            "description": "Presence: omittedWhenNull."
          },
          "registeredAt": {
            "type": "integer",
            "description": "Unix ms Presence: omittedWhenNull."
          },
          "lastAttemptAt": {
            "type": "integer",
            "description": "Unix ms Presence: omittedWhenNull."
          },
          "taxCreateDate": {
            "type": "integer",
            "description": "Presence: omittedWhenNull."
          },
          "registrationId": {
            "type": "integer",
            "description": "Presence: omittedWhenNull."
          },
          "registeredAmount": {
            "type": "integer",
            "description": "paidAmount registered (without VAT share) Presence: omittedWhenNull."
          }
        }
      },
      "V2ClientCredentialsResult": {
        "type": "object",
        "properties": {
          "credential_type": {
            "type": "string",
            "description": "customer | partner Presence: alwaysNullable."
          },
          "client_id": {
            "type": "string",
            "description": "v2-customer-{id} Presence: alwaysNullable."
          },
          "client_secret": {
            "type": "string",
            "description": "only when created or rotated in this answer, else null; shown once Presence: alwaysNullable."
          },
          "service_name": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "allowed_scopes": {
            "type": "string",
            "description": "space separated, sorted Presence: alwaysNullable."
          },
          "token_endpoint": {
            "type": "string",
            "description": "V2Auth:TokenEndpoint, default /api/auth/v2/token (relative) Presence: alwaysNullable."
          },
          "expires_in": {
            "type": "integer",
            "description": "access token lifetime, seconds"
          },
          "created": {
            "type": "boolean"
          },
          "rotated": {
            "type": "boolean"
          },
          "legacy_api_key_sunset_utc": {
            "type": "string",
            "description": "2026-12-01T20:30:00Z by default (the end of 10 Azar 1405, Tehran) Presence: alwaysNullable."
          },
          "active": {
            "type": "boolean",
            "description": "false when the credential is revoked or switched off and takes no token; then client_secret is null and warning says the owner must issue a new one in the panel (1.0.0.199)"
          },
          "warning": {
            "type": "string",
            "description": "secret issued now: \"ClientSecret is shown only once…\"; existing client on client-credentials: \"Client already exists. Send rotate_secret=true…\"; existing client on /api/register: a Persian text naming the panel tab «تنظیمات کسب‌وکار › اتصال API v2»; active false: the Persian withdrawn-credential text Presence: alwaysNullable."
          }
        }
      },
      "RegisterReturnData": {
        "type": "object",
        "properties": {
          "result": {
            "type": "integer",
            "description": "RegisterResult"
          },
          "traceId": {
            "type": "string",
            "description": "Guid"
          },
          "message": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "error": {
            "type": "string",
            "description": "FISCAL_ID_INVALID | FISCAL_ID_INQUIRY_UNAVAILABLE | business_registered_elsewhere | partner refusal code | null Presence: alwaysNullable."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RegisterUserData"
              }
            ],
            "description": "on success (result 1, 2, 3) Presence: alwaysNullable."
          }
        }
      },
      "RegisterUserData": {
        "type": "object",
        "properties": {
          "companyId": {
            "type": "integer",
            "description": "C# long"
          },
          "fiscalId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "fiscalMemoryId": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "sandBox": {
            "type": "boolean",
            "description": "Presence: alwaysNullable."
          },
          "environment": {
            "type": "string",
            "description": "Production | Sandbox Presence: alwaysNullable."
          },
          "environmentTitle": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "economicCode": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "valueAddedNotCalled": {
            "type": "boolean"
          },
          "taxFileState": {
            "type": "string",
            "description": "production only: active | notActive | notFound | unavailable Presence: alwaysNullable."
          },
          "taxFileStatus": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "taxFileStatusTitle": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "taxFileMessage": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "customerApiKey": {
            "type": "string",
            "description": "always null since 1.0.0.107 Presence: alwaysNullable."
          },
          "serviceAuth": {
            "allOf": [
              {
                "$ref": "#/components/schemas/V2ClientCredentialsResult"
              }
            ],
            "description": "the business's customer credentials Presence: alwaysNullable."
          },
          "created": {
            "type": "boolean"
          },
          "updated": {
            "type": "boolean"
          }
        }
      },
      "StuffIdV2Data": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "anonymous type (StuffIdV2Controller.cs:73-82)"
          },
          "description": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "goods or service type text"
          },
          "vatRate": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "taxable": {
            "type": "boolean",
            "description": "مشمول true, معاف false, else from vatRate, else null Presence: alwaysNullable."
          },
          "category": {
            "type": "string"
          },
          "editDate": {
            "type": "string",
            "description": "catalogue date text"
          }
        }
      },
      "IpAccessV2Data": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "anonymous type (ClientAccessV2Controller.cs:85-98)"
          },
          "allowedIps": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "addresses or ranges Presence: alwaysNullable."
          },
          "callerIp": {
            "type": "string",
            "description": "address ASA sees this request from Presence: alwaysNullable."
          },
          "refused": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "[{at: yyyy-MM-ddTHH:mm:ssZ, ip}]"
          }
        }
      },
      "TaxWorkspaceEnvelope": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "OK / organisation status on success; see responseFamilies Presence: alwaysNullable."
          },
          "data": {
            "description": "the endpoint's data type; null on failure Presence: alwaysNullable."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaxWorkspaceErrorDto"
            },
            "description": "empty on success"
          },
          "fieldErrors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaxWorkspaceFieldErrorDto"
            },
            "description": "empty on success"
          },
          "correlationId": {
            "type": "string",
            "description": "same as the X-Correlation-ID header Presence: alwaysNullable."
          },
          "notices": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "how a successful answer was obtained Presence: omittedWhenNull."
          }
        }
      },
      "TaxWorkspaceErrorDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "message": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "TaxWorkspaceFieldErrorDto": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "errorMessage": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "TaxWorkspaceInvoiceFilter": {
        "type": "object",
        "properties": {
          "period": {
            "type": "string",
            "description": "YYYYPP Jalali year + quarter 01-04; >= 140404; not after the current period"
          },
          "issuanceDateFrom": {
            "type": "integer",
            "description": "13-digit epoch ms"
          },
          "issuanceDateTo": {
            "type": "integer",
            "description": "13-digit epoch ms; same Tehran day as from, inside the period"
          },
          "status": {
            "type": "string",
            "description": "REJECTED | APPROVED | SYSTEMIC_APPROVED | IMPOSSIBLE_REACTION | AWAITING_REACTION | NO_NEED_REACTION | CANCELED | SYSTEMIC_REJECTED"
          },
          "pattern": {
            "type": "string",
            "description": "SALE | CURRENCY_SALE | GOLD | CONTRACT | BILL | PLANE_TICKET | EXPORT | LADING | REFINEMENT_AND_DISTRIBUTION | MERCANTILE_EXCHANGE_SALE | INSURANCE_SERVICES | CHAIN | MERCANTILE_EXCHANGE_BUY | IMPORT"
          },
          "contractBrokerageNumber": {
            "type": "string",
            "description": "exactly 12 digits"
          },
          "sellerRole": {
            "type": "string",
            "description": "sales only: NORMAL | BROKER_CLIENT | BROKER"
          },
          "buyerRole": {
            "type": "string",
            "description": "purchase only: NORMAL | BROKER_CLIENT | BROKER"
          },
          "pageNumber": {
            "type": "integer",
            "description": "default 1, >= 1"
          },
          "pageSize": {
            "type": "integer",
            "description": "default 10, 1..10"
          }
        },
        "required": [
          "period",
          "issuanceDateFrom",
          "issuanceDateTo"
        ]
      },
      "TaxWorkspaceContractFilter": {
        "type": "object",
        "properties": {
          "contractBrokerageId": {
            "type": "string",
            "description": "<= 16 digits"
          },
          "contractBrokerageNumber": {
            "type": "string",
            "description": "exactly 12 digits"
          },
          "contractBrokerageInternalNumber": {
            "type": "string",
            "description": "<= 19"
          },
          "brokerClientEconomicNumber": {
            "type": "string",
            "description": "11 or 14 digits"
          },
          "brokerEconomicNumber": {
            "type": "string",
            "description": "11 or 14 digits"
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "repeat the query key; FINAL_REGISTRATION | AWAITING_REACTION | CANCELLED | REJECTED"
          },
          "issueDateFrom": {
            "type": "integer",
            "description": "13-digit epoch ms"
          },
          "issueDateTo": {
            "type": "integer",
            "description": "13-digit epoch ms"
          },
          "createDateFrom": {
            "type": "integer",
            "description": "13-digit epoch ms"
          },
          "createDateTo": {
            "type": "integer",
            "description": "13-digit epoch ms"
          },
          "pageNumber": {
            "type": "integer",
            "description": "default 1"
          },
          "pageSize": {
            "type": "integer",
            "description": "default 10, 1..10"
          }
        }
      },
      "TaxWorkspaceInvoiceDto": {
        "type": "object",
        "properties": {
          "taxId": {
            "type": "string",
            "description": "the organisation's row (string fields as the organisation sends them) Presence: alwaysNullable."
          },
          "parentTaxId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "type": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "pattern": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "subject": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "status": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "referenceTaxId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "totalAmount": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "totalVatAmount": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "issuanceDate": {
            "type": "integer",
            "description": "epoch ms Presence: alwaysNullable."
          },
          "article6Status": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "buyerCallStatus": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "sellerCallStatus": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "isVirtualInvoice": {
            "type": "boolean",
            "description": "Presence: alwaysNullable."
          },
          "sellerName": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "buyerName": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "buyerEconomicNumber": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "buyerRole": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "sellerRole": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "sellerEconomicNumber": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "period": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "createDate": {
            "type": "integer",
            "description": "epoch ms Presence: alwaysNullable."
          },
          "contractBrokerageNumber": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "brokerClientName": {
            "type": "string",
            "description": "virtual lists Presence: alwaysNullable."
          },
          "actionAllowed": {
            "type": "boolean",
            "description": "sales and purchase lists only Presence: alwaysNullable."
          }
        }
      },
      "TaxWorkspaceContractDto": {
        "type": "object",
        "properties": {
          "contractBrokerageId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "issueDate": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "startDate": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "createDate": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "updateDate": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "status": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "subject": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "type": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "contractBrokerageRegistrar": {
            "type": "string",
            "description": "BROKER | BROKER_CLIENT Presence: alwaysNullable."
          },
          "brokerClientEconomicNumber": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "brokerClientName": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "brokerEconomicNumber": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "brokerName": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "amount": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "contractBrokerageInternalNumber": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "contractBrokerageNumber": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "parentContractBrokerageId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "title": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "brokerBranchCode": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "brokerClientBranchCode": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "actionAllowed": {
            "type": "boolean"
          }
        }
      },
      "TaxWorkspaceBulkInvoiceRequestDto": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "description": "purchase | virtual-purchase | sales | virtual-sales"
          },
          "operations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaxWorkspaceBulkInvoiceOperationDto"
            },
            "description": "either operations or taxIds Conditionally required."
          },
          "taxIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "simple form with the root action/rejectReasons/rejectDescription Conditionally required."
          },
          "action": {
            "type": "string",
            "description": "with taxIds: APPROVE | REJECT (empty = skipped) Conditionally required."
          },
          "rejectReasons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "REJECT: NOT_INFORMED | BUYER | SELLER | PRODUCT | AMOUNT | PAYMENT | OTHER Conditionally required."
          },
          "rejectDescription": {
            "type": "string",
            "description": "required with OTHER Conditionally required."
          }
        },
        "required": [
          "kind"
        ]
      },
      "TaxWorkspaceBulkInvoiceOperationDto": {
        "type": "object",
        "properties": {
          "taxId": {
            "type": "string",
            "description": "22 letters/digits"
          },
          "period": {
            "type": "string",
            "description": "both period and issuanceDate, or neither (then derived from the TaxId) Conditionally required."
          },
          "issuanceDate": {
            "type": "integer",
            "description": "epoch ms Conditionally required."
          },
          "action": {
            "type": "string",
            "description": "APPROVE | REJECT | empty (skipped)"
          },
          "rejectReasons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "REJECT only; must be empty for APPROVE Conditionally required."
          },
          "rejectDescription": {
            "type": "string",
            "description": "required with OTHER; must be empty for APPROVE Conditionally required."
          }
        },
        "required": [
          "taxId"
        ]
      },
      "TaxWorkspaceBulkContractRequestDto": {
        "type": "object",
        "properties": {
          "operations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaxWorkspaceBulkContractOperationDto"
            },
            "description": "one selector only Conditionally required."
          },
          "contractBrokerageNumbers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "with the root action Conditionally required."
          },
          "action": {
            "type": "string",
            "description": "APPROVE | REJECT Conditionally required."
          },
          "allForCurrentEconomicNumber": {
            "type": "boolean",
            "description": "react to every contract awaiting the business Conditionally required."
          },
          "economicNumber": {
            "type": "string",
            "description": "optional confirmation of the business's economic number (never selects a business)"
          }
        }
      },
      "TaxWorkspaceBulkContractOperationDto": {
        "type": "object",
        "properties": {
          "contractBrokerageId": {
            "type": "string",
            "description": "id or number Conditionally required."
          },
          "contractBrokerageNumber": {
            "type": "string",
            "description": "12 digits Conditionally required."
          },
          "action": {
            "type": "string",
            "description": "APPROVE | REJECT"
          }
        },
        "required": [
          "action"
        ]
      },
      "TaxWorkspaceBulkResultDto": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "success": {
            "type": "integer"
          },
          "failed": {
            "type": "integer"
          },
          "skipped": {
            "type": "integer"
          },
          "batchCorrelationId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaxWorkspaceBulkItemResultDto"
            }
          }
        }
      },
      "TaxWorkspaceBulkItemResultDto": {
        "type": "object",
        "properties": {
          "identifier": {
            "type": "string",
            "description": "taxId or contract id Presence: alwaysNullable."
          },
          "period": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "issuanceDate": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "action": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "status": {
            "type": "string",
            "description": "for example SUCCESS, VALIDATION_ERROR, SKIPPED, NOT_ACTIONABLE (full list not traced) Presence: alwaysNullable."
          },
          "code": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "message": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "correlationId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "TaxWorkspaceExcelPreviewDto": {
        "type": "object",
        "properties": {
          "previewToken": {
            "type": "string",
            "description": "for excel/execute Presence: alwaysNullable."
          },
          "batchCorrelationId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "expiresAt": {
            "type": "integer",
            "description": "epoch ms"
          },
          "summary": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TaxWorkspaceExcelSummaryDto"
              }
            ],
            "description": "Presence: alwaysNullable."
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaxWorkspaceExcelRowDto"
            },
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "TaxWorkspaceExcelSummaryDto": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "executable": {
            "type": "integer"
          },
          "approve": {
            "type": "integer"
          },
          "reject": {
            "type": "integer"
          },
          "noAction": {
            "type": "integer"
          },
          "invalid": {
            "type": "integer"
          }
        }
      },
      "TaxWorkspaceExcelRowDto": {
        "type": "object",
        "properties": {
          "rowNumber": {
            "type": "integer"
          },
          "identifier": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "period": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "issuanceDate": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "action": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "rejectReasons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Presence: alwaysNullable."
          },
          "rejectDescription": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "values": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "cell values by column"
          },
          "previewStatus": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "previewCode": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "previewMessage": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "processResult": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "processedAt": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "responseCode": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "responseMessage": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "correlationId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "TaxWorkspaceExcelExecuteResultDto": {
        "type": "object",
        "properties": {
          "batchCorrelationId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "resultToken": {
            "type": "string",
            "description": "for excel/result Presence: alwaysNullable."
          },
          "summary": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TaxWorkspaceBulkResultDto"
              }
            ],
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "TaxWorkspaceApiDelegationDto": {
        "type": "object",
        "properties": {
          "economicCode": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "status": {
            "type": "string",
            "description": "NotConnected | PendingOtp | Active | Expired | Revoked | Invalid | Error Presence: alwaysNullable."
          },
          "usable": {
            "type": "boolean"
          },
          "otpPending": {
            "type": "boolean"
          },
          "maskedMobile": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "otpLength": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "otpExpiresAt": {
            "type": "integer",
            "description": "epoch ms, only while pending Presence: alwaysNullable."
          },
          "expiresAt": {
            "type": "integer",
            "description": "delegation expiry, only when usable Presence: alwaysNullable."
          },
          "grantedPermissions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "empty unless usable"
          },
          "memoryUniqueIdAvailable": {
            "type": "boolean"
          },
          "memoryPermissionGranted": {
            "type": "boolean"
          }
        }
      },
      "TaxWorkspaceMemoryUniqueIdResultDto": {
        "type": "object",
        "properties": {
          "memoryUniqueId": {
            "type": "string",
            "description": "the new fiscal memory id Presence: alwaysNullable."
          },
          "message": {
            "type": "string",
            "description": "the organisation's message Presence: alwaysNullable."
          },
          "companyTokenId": {
            "type": "integer",
            "description": "null for the partner onboarding route Presence: alwaysNullable."
          },
          "created": {
            "type": "boolean"
          },
          "environment": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "TaxFileInquiryV2Answer": {
        "type": "object",
        "properties": {
          "identifier": {
            "type": "string",
            "description": "the digits asked Presence: alwaysNullable."
          },
          "queriedBy": {
            "type": "string",
            "description": "nationalId | economicCode Presence: alwaysNullable."
          },
          "found": {
            "type": "boolean"
          },
          "message": {
            "type": "string",
            "description": "null when found Presence: alwaysNullable."
          },
          "taxFiles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaxFileInquiryV2File"
            }
          }
        }
      },
      "TaxFileInquiryV2File": {
        "type": "object",
        "properties": {
          "economicCode": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "nationalId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "brand": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "taxFileStatus": {
            "type": "string",
            "description": "NOT_ALLOCATED | ACTIVE | TEMPORARY_UNAUTHORIZE | PERMANENT_UNAUTHORIZE (organisation values) Presence: alwaysNullable."
          },
          "taxFileStatusTitle": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "active": {
            "type": "boolean"
          },
          "callStatusTitle": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "registrationStatusTitle": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "buyerType": {
            "type": "integer",
            "description": "1..4 as Header.tob; null when unknown Presence: alwaysNullable."
          },
          "buyerTypeTitle": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "warning": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "PartnerSessionCreateRequest": {
        "type": "object",
        "properties": {
          "economicCode": {
            "type": "string",
            "description": "11 or 14 digits; only this business can be registered through the link"
          },
          "nationalId": {
            "type": "string",
            "description": "10, 11 or 12 digits; used without an economic code"
          },
          "businessName": {
            "type": "string",
            "description": "reminder only, <= 200"
          },
          "mobile": {
            "type": "string",
            "description": "09 followed by 9 digits"
          },
          "reference": {
            "type": "string",
            "description": "partner's own id, <= 100 of letters, digits . _ - : / # @"
          },
          "returnUrl": {
            "type": "string",
            "description": "https on an allowed origin; default the partner's"
          },
          "expiresInMinutes": {
            "type": "integer",
            "description": "10..10080; default the partner's (1440)"
          },
          "issueMemoryUniqueId": {
            "type": "boolean",
            "description": "default true"
          },
          "requestCredentials": {
            "type": "boolean",
            "description": "default false; needs credentialHandover"
          },
          "idempotencyKey": {
            "type": "string",
            "description": "8..64 of Latin letters, digits . _ - :"
          }
        }
      },
      "ClassicInvoiceBatchRequest": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string",
            "description": "agency token; when empty the first non-empty data[].token is used"
          },
          "uuid": {
            "type": "string",
            "description": "GUID; unique per business"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ClassicInvoiceData"
            },
            "description": "1..250"
          },
          "checkTypeTwoBuyers": {
            "type": "boolean",
            "description": "multi-invoice request: also ask type-2 buyers' tax files (within five national codes)"
          }
        },
        "required": [
          "uuid",
          "data"
        ]
      },
      "TaxWorkspaceApiOnboardingRequest": {
        "type": "object",
        "properties": {
          "economicCode": {
            "type": "string",
            "description": "11 or 14 digits (Persian digits normalised)"
          },
          "otp": {
            "type": "string",
            "description": "onboarding/verify only Conditionally required."
          },
          "validityDurationDays": {
            "type": "integer",
            "description": "onboarding/otp only: 1..365, default 365"
          }
        },
        "required": [
          "economicCode"
        ]
      },
      "TaxWorkspaceExcelExecuteRequestDto": {
        "type": "object",
        "properties": {
          "previewToken": {
            "type": "string",
            "description": "from the preview answer"
          }
        },
        "required": [
          "previewToken"
        ]
      },
      "PartnerSessionPrefillDto": {
        "type": "object",
        "properties": {
          "economicCode": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "nationalId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "businessName": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "mobile": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "PartnerSessionBusinessDto": {
        "type": "object",
        "properties": {
          "companyId": {
            "type": "integer"
          },
          "economicCode": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "name": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "created": {
            "type": "boolean",
            "description": "false when the taxpayer's existing panel was completed"
          }
        }
      },
      "PartnerSessionMemoryDto": {
        "type": "object",
        "properties": {
          "memoryUniqueId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "issued": {
            "type": "boolean",
            "description": "true: issued in this visit"
          },
          "at": {
            "type": "string",
            "description": "DateTime Presence: alwaysNullable."
          }
        }
      },
      "PartnerSessionErrorDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "message": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "at": {
            "type": "string",
            "description": "DateTime Presence: alwaysNullable."
          }
        }
      },
      "PartnerSessionCredentialsDto": {
        "type": "object",
        "properties": {
          "available": {
            "type": "boolean",
            "description": "owner agreed"
          },
          "claimed": {
            "type": "boolean"
          },
          "clientId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "claimedAt": {
            "type": "string",
            "description": "DateTime Presence: alwaysNullable."
          }
        }
      },
      "PartnerEventDeliveryDto": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "delivery state name (for example pending, delivered, failed, cancelled) Presence: alwaysNullable."
          },
          "attempts": {
            "type": "integer"
          },
          "lastStatusCode": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "deliveredAt": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "nextAttemptAt": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "PartnerProfileDto": {
        "type": "object",
        "properties": {
          "companyId": {
            "type": "integer"
          },
          "displayName": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "status": {
            "type": "string",
            "description": "active | suspended Presence: alwaysNullable."
          },
          "capabilities": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerCapabilitiesDto"
              }
            ],
            "description": "Presence: alwaysNullable."
          },
          "allowedOrigins": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "defaultReturnUrl": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "webhook": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerWebhookProfileDto"
              }
            ],
            "description": "Presence: alwaysNullable."
          },
          "hourlySessionLimit": {
            "type": "integer"
          },
          "sessionLifetimeMinutes": {
            "type": "integer"
          }
        }
      },
      "PartnerCapabilitiesDto": {
        "type": "object",
        "properties": {
          "directRegister": {
            "type": "boolean"
          },
          "otpOnboarding": {
            "type": "boolean"
          },
          "hostedOnboarding": {
            "type": "boolean"
          },
          "credentialHandover": {
            "type": "boolean"
          }
        }
      },
      "PartnerWebhookProfileDto": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "enabled": {
            "type": "boolean"
          },
          "secretConfigured": {
            "type": "boolean"
          }
        }
      },
      "PartnerSessionDto": {
        "type": "object",
        "properties": {
          "sessionId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "status": {
            "type": "string",
            "description": "created | opened | in_progress | business_ready | completed | expired | cancelled Presence: alwaysNullable."
          },
          "statusTitle": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "reference": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "url": {
            "type": "string",
            "description": "only in create / new-link answers Presence: alwaysNullable."
          },
          "createdAt": {
            "type": "string",
            "description": "DateTime"
          },
          "expiresAt": {
            "type": "string",
            "description": "DateTime"
          },
          "prefill": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerSessionPrefillDto"
              }
            ],
            "description": "{economicCode, nationalId, businessName, mobile} Presence: alwaysNullable."
          },
          "issueMemoryUniqueId": {
            "type": "boolean"
          },
          "requestCredentials": {
            "type": "boolean"
          },
          "returnUrl": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "openedAt": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "openCount": {
            "type": "integer"
          },
          "claimedAt": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "businessReadyAt": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "completedAt": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "cancelledAt": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "cancelledBy": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "business": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerSessionBusinessDto"
              }
            ],
            "description": "{companyId, economicCode, name, created} Presence: alwaysNullable."
          },
          "memory": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerSessionMemoryDto"
              }
            ],
            "description": "{memoryUniqueId, issued, at} Presence: alwaysNullable."
          },
          "lastError": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerSessionErrorDto"
              }
            ],
            "description": "{code, message, at} Presence: alwaysNullable."
          },
          "credentials": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerSessionCredentialsDto"
              }
            ],
            "description": "{available, claimed, clientId, claimedAt} Presence: alwaysNullable."
          }
        }
      },
      "PartnerSessionListDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerSessionDto"
            }
          },
          "page": {
            "type": "integer"
          },
          "pageSize": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "PartnerCredentialsDto": {
        "type": "object",
        "properties": {
          "companyId": {
            "type": "integer"
          },
          "clientId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "clientSecret": {
            "type": "string",
            "description": "only when made now Presence: alwaysNullable."
          },
          "secretIssued": {
            "type": "boolean"
          },
          "scopes": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "tokenEndpoint": {
            "type": "string",
            "description": "absolute: https://api-v2.asatsp.ir/api/auth/v2/token Presence: alwaysNullable."
          },
          "apiBaseUrl": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "message": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "PartnerEventDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "evt_..., also the webhook-id header Presence: alwaysNullable."
          },
          "sequence": {
            "type": "integer",
            "description": "pass the last as after"
          },
          "type": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "createdAt": {
            "type": "string"
          },
          "sessionId": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "data": {
            "description": "the webhook body's data Presence: alwaysNullable."
          },
          "delivery": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerEventDeliveryDto"
              }
            ],
            "description": "{status, attempts, lastStatusCode, deliveredAt, nextAttemptAt} Presence: alwaysNullable."
          }
        }
      },
      "PartnerEventListDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerEventDto"
            }
          },
          "nextAfter": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "hasMore": {
            "type": "boolean"
          }
        }
      },
      "PartnerWorkspaceOverviewDto": {
        "type": "object",
        "properties": {
          "readAt": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "readDay": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "readClock": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "period": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceReportPeriodInfo"
              }
            ],
            "description": "Presence: alwaysNullable."
          },
          "businesses": {
            "type": "object",
            "description": "{total, added, active, idle} Presence: alwaysNullable."
          },
          "onboarding": {
            "type": "object",
            "description": "{created, opened, completed, open, expired, cancelled, conversionPercent?, createdToday, completedToday} Presence: alwaysNullable."
          },
          "invoices": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceReportTotals"
              }
            ],
            "description": "Presence: alwaysNullable."
          },
          "statuses": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "InvoiceReportStatus {invoices, amount, key}"
          },
          "acceptancePercent": {
            "type": "number",
            "description": "Presence: alwaysNullable."
          },
          "sandbox": {
            "type": "object",
            "description": "InvoiceReportFigure {invoices, amount} Presence: alwaysNullable."
          },
          "channels": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "InvoiceReportSlice {invoices, amount, key, vat}"
          },
          "days": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "InvoiceReportDay {day, invoices, amount, vat, registered, registeredAmount, inFlight, inFlightAmount, notSent, notSentAmount, errored, erroredAmount}"
          },
          "comparison": {
            "type": "object",
            "description": "{title, fromDay, toDay, isPartial, invoices: InvoiceReportTotals, acceptancePercent?, newBusinesses, completedSignUps} Presence: alwaysNullable."
          },
          "webhook": {
            "type": "object",
            "description": "PartnerWorkspaceWebhookSummaryDto {state, stateTitle, host, last24Hours, last7Days, lastDeliveredAt?, lastError, lastStatusCode?}; windows {events, delivered, failed, pending, feedOnly, successPercent?, averageMs?, p95Ms?} Presence: alwaysNullable."
          },
          "credentials": {
            "type": "object",
            "description": "{clientId, active, scopes, createdAt?, lastUsedAt?, revokedAt?} Presence: alwaysNullable."
          },
          "resultDelay": {
            "type": "object",
            "description": "{waiting, late, thresholdMinutes, oldestSentAt?, businesses} Presence: alwaysNullable."
          },
          "findings": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{code, severity, title, detail, tab}"
          },
          "rejected": {
            "type": "object",
            "description": "{invoices, requests, businesses, lastAt} Presence: alwaysNullable."
          },
          "legacyKeys": {
            "type": "object",
            "description": "{sunsetUtc, lastDay, partnerKeyRefused, businesses: [{companyId, name, calls, lastCallAt, hasCredentials}]} Presence: alwaysNullable."
          }
        }
      },
      "InvoiceReportPeriodInfo": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "description": "[JsonProperty] names Presence: alwaysNullable."
          },
          "key": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "title": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "fromDay": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "toDay": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "days": {
            "type": "integer"
          },
          "elapsedDays": {
            "type": "integer"
          },
          "isOpen": {
            "type": "boolean"
          }
        }
      },
      "InvoiceReportTotals": {
        "type": "object",
        "properties": {
          "invoices": {
            "type": "integer"
          },
          "amount": {
            "type": "number"
          },
          "vat": {
            "type": "number"
          },
          "registered": {
            "type": "integer"
          },
          "registeredAmount": {
            "type": "number"
          },
          "registeredVat": {
            "type": "number"
          },
          "inFlight": {
            "type": "integer"
          },
          "inFlightAmount": {
            "type": "number"
          },
          "needsAction": {
            "type": "integer"
          },
          "needsActionAmount": {
            "type": "number"
          },
          "businesses": {
            "type": "integer"
          },
          "activeDays": {
            "type": "integer"
          }
        }
      },
      "PartnerWorkspaceBusinessListDto": {
        "type": "object",
        "properties": {
          "period": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceReportPeriodInfo"
              }
            ],
            "description": "Presence: alwaysNullable."
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerWorkspaceBusinessDto"
            }
          },
          "page": {
            "type": "integer"
          },
          "pageSize": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "health": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "count per health"
          }
        }
      },
      "PartnerWorkspaceBusinessDto": {
        "type": "object",
        "properties": {
          "companyId": {
            "type": "integer"
          },
          "name": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "economicCode": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "active": {
            "type": "boolean"
          },
          "source": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "sourceTitle": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "connectedAt": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "invoices": {
            "type": "integer"
          },
          "amount": {
            "type": "number"
          },
          "vat": {
            "type": "number"
          },
          "registered": {
            "type": "integer"
          },
          "inFlight": {
            "type": "integer"
          },
          "errored": {
            "type": "integer"
          },
          "notSent": {
            "type": "integer"
          },
          "sandbox": {
            "type": "integer"
          },
          "acceptancePercent": {
            "type": "number",
            "description": "Presence: alwaysNullable."
          },
          "lastDay": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "topError": {
            "type": "object",
            "description": "{code, message, count} Presence: alwaysNullable."
          },
          "health": {
            "type": "string",
            "description": "ok | attention | idle | inactive Presence: alwaysNullable."
          },
          "healthTitle": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "PartnerWorkspaceErrorsDto": {
        "type": "object",
        "properties": {
          "readDay": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "readClock": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "period": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceReportPeriodInfo"
              }
            ],
            "description": "Presence: alwaysNullable."
          },
          "total": {
            "type": "object",
            "description": "{invoices, amount} Presence: alwaysNullable."
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{code, message, origin, invoices, amount, businesses, lastDay, topBusinesses: [{companyId, name, invoices}]}"
          },
          "cancellationTotal": {
            "type": "object",
            "description": "{invoices, amount} Presence: alwaysNullable."
          },
          "cancellationReasons": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "as reasons"
          },
          "truncated": {
            "type": "boolean"
          },
          "days": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{day, registered, errored, errorPercent?}"
          }
        }
      },
      "PartnerWorkspaceRejectionsDto": {
        "type": "object",
        "properties": {
          "readDay": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "readClock": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "period": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceReportPeriodInfo"
              }
            ],
            "description": "Presence: alwaysNullable."
          },
          "total": {
            "type": "object",
            "description": "{invoices, requests, businesses, lastAt} Presence: alwaysNullable."
          },
          "sandbox": {
            "type": "object",
            "description": "same shape Presence: alwaysNullable."
          },
          "duplicates": {
            "type": "object",
            "description": "same shape Presence: alwaysNullable."
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{field, message, invoices, requests, businesses, lastDay, lastClock, topBusinesses}"
          },
          "truncated": {
            "type": "boolean"
          },
          "partial": {
            "type": "boolean"
          },
          "days": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{day, invoices}"
          },
          "recent": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{day, clock, companyId?, businessName, api, apiTitle, traceId, member?, internalId, sandbox, errors: [{field, message}]}"
          }
        }
      },
      "PartnerWorkspaceFunnelDto": {
        "type": "object",
        "properties": {
          "period": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceReportPeriodInfo"
              }
            ],
            "description": "Presence: alwaysNullable."
          },
          "stages": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{key, title, count, percent?, dropped}"
          },
          "figures": {
            "type": "object",
            "description": "as overview.onboarding Presence: alwaysNullable."
          },
          "medianMinutesToComplete": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "medianMinutesToOpen": {
            "type": "integer",
            "description": "Presence: alwaysNullable."
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{code, message, count}"
          },
          "stalled": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "PartnerWorkspaceSessionDto {sessionId, status, statusTitle, stage, stageTitle, reference, businessName, economicCode, mobile, companyId?, createdAt, expiresAt, openedAt?, lastActivityAt?, completedAt?, cancelledBy, lastErrorCode, lastErrorMessage, credentialsRequested, credentialsClaimed}"
          },
          "days": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{day, created, completed}"
          }
        }
      },
      "PartnerWorkspaceUsageDto": {
        "type": "object",
        "properties": {
          "fromMonth": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "toMonth": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "months": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{key, title, isOpen}"
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{companyId, name, economicCode, months: [cell], total: cell}; cell = {invoices, registered, amount}"
          },
          "totals": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "cells"
          }
        }
      },
      "PartnerWorkspaceMonthlyReportDto": {
        "type": "object",
        "properties": {
          "generatedAt": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "generatedDay": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "generatedClock": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "partnerName": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "businessName": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "overview": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerWorkspaceOverviewDto"
              }
            ],
            "description": "Presence: alwaysNullable."
          },
          "funnel": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerWorkspaceFunnelDto"
              }
            ],
            "description": "Presence: alwaysNullable."
          },
          "businesses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerWorkspaceBusinessDto"
            }
          },
          "errors": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerWorkspaceErrorsDto"
              }
            ],
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "PartnerWorkspaceInvoiceLookupDto": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "matchedBy": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{invoiceId, companyId, businessName, number, taxId, uuid, invoiceDay, createdAt, channel, type?, pattern?, subject?, referenceTaxId, status, statusTitle, netPrice, vat, sandbox, latestError, errorCode, attempts: [{sentAt, answeredAt?, success?, referenceNumber, errorCode, error}]}"
          },
          "hint": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          }
        }
      },
      "PartnerWorkspaceHealthDto": {
        "type": "object",
        "properties": {
          "webhook": {
            "type": "object",
            "description": "as overview.webhook Presence: alwaysNullable."
          },
          "webhookUrl": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "webhookEnabled": {
            "type": "boolean"
          },
          "webhookSecretConfigured": {
            "type": "boolean"
          },
          "webhookSecretMask": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "webhookSecretCreatedAt": {
            "type": "string",
            "description": "Presence: alwaysNullable."
          },
          "credentials": {
            "type": "object",
            "description": "as overview.credentials Presence: alwaysNullable."
          },
          "resultDelay": {
            "type": "object",
            "description": "as overview.resultDelay Presence: alwaysNullable."
          },
          "hours": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{at, invoices, errored}"
          },
          "findings": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{code, severity, title, detail, tab}"
          },
          "openAlerts": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "{key, title, detail, severity, openedAt, lastSeenAt, occurrences}"
          },
          "legacyKeys": {
            "type": "object",
            "description": "as overview.legacyKeys Presence: alwaysNullable."
          }
        }
      }
    }
  }
}
