**גרסאות API** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=he)

# Organisation invoices

OpenAPI 3.0.3 · API 2.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v2",
    "description": "API"
  }
]
```

Existing local Unisoft invoices of the authenticated organisation; provider-managed billing coverage is declared explicitly.

## פעולות

## GET /organisation/invoices

List the organisation's locally stored Unisoft invoices

`list_organisation_invoices`

Required scope: `invoices:read`, explicitly granted; payment/receipt scopes do not grant access. Reads Unisoft invoices billed to the authenticated organisation, not donation receipts or tax documents. Coverage is PARTIAL: only persisted local factures records of type COM/SOFT are included; Mercury internal_factures and Stripe UK/US/Pennylane billing owned by Unisoft Internal are excluded. An empty result does not prove that the organisation has no invoices. No provider request, sync, reconciliation, portal creation, invoice issuance, fee/tax calculation or debit occurs. COM/PAYGREEN total is normalised to minor EUR units from its audited stored major-unit total. SOFT amountMinor and currency remain null because its producer/unit cannot be verified. settlementStatus is always NOT_REPORTED; neither the PDF nor age proves payment or overdue status. Unknown historical dates/period components and invalid money remain null, never fabricated zero or current dates. The PDF href requires the same invoices:read authentication through REST, and its availability is NOT_CHECKED in JSON. Campaign-restricted keys are refused because billing has no campaign owner. Unknown query parameters and non-empty request bodies are rejected. The shared authentication layer may record API-key usage. Sorts by valid stored BSON datetime descending, then id descending, with absent/invalid dates last. Cursor continuation is bound to organisation and type; concurrent changes do not form a snapshot. An unusable historical UUID returns 409 INVALID_INVOICE_HISTORY instead of silently dropping an invoice or inventing continuation. No invoice lines, donor identities, private snapshots or provider account identifiers are returned.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "invoices:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "description": "Page size, an integer from 1 to 200; default 50.",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "description": "Opaque nextCursor returned by this organisation invoice list with the same type filter.",
  "schema": {
    "type": "string",
    "maxLength": 2048
  }
}
```

```json
{
  "name": "type",
  "in": "query",
  "description": "Optional exact stored kind COM or SOFT. Omit to include both covered local kinds.",
  "schema": {
    "type": "string",
    "enum": [
      "COM",
      "SOFT"
    ]
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A page of local invoices with explicitly partial coverage.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceListResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_LIMIT, INVALID_CURSOR, INVALID_INVOICE_TYPE, INVALID_QUERY_PARAMETER, UNEXPECTED_QUERY_PARAMETERS or UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, disabled organisation or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_INVOICE_HISTORY: a stored invoice identity prevents safe pagination.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. No financial operation was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "invoices:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /organisation/invoices/{id}

Read one locally stored Unisoft invoice

`get_organisation_invoice`

Required scope: `invoices:read`, explicitly granted; payment/receipt scopes do not grant access. Reads Unisoft invoices billed to the authenticated organisation, not donation receipts or tax documents. Coverage is PARTIAL: only persisted local factures records of type COM/SOFT are included; Mercury internal_factures and Stripe UK/US/Pennylane billing owned by Unisoft Internal are excluded. An empty result does not prove that the organisation has no invoices. No provider request, sync, reconciliation, portal creation, invoice issuance, fee/tax calculation or debit occurs. COM/PAYGREEN total is normalised to minor EUR units from its audited stored major-unit total. SOFT amountMinor and currency remain null because its producer/unit cannot be verified. settlementStatus is always NOT_REPORTED; neither the PDF nor age proves payment or overdue status. Unknown historical dates/period components and invalid money remain null, never fabricated zero or current dates. The PDF href requires the same invoices:read authentication through REST, and its availability is NOT_CHECKED in JSON. Campaign-restricted keys are refused because billing has no campaign owner. Unknown query parameters and non-empty request bodies are rejected. The shared authentication layer may record API-key usage. Accepts only the local invoice UUID. Missing, deleted, unknown-kind and foreign-organisation invoices return the same 404. A provider customer reference cannot authorise an invoice. JSON never returns a provider URL, secret or reusable payment method.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "invoices:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Local Unisoft invoice UUID returned by this list. No external customer or provider invoice reference.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "One local invoice with coverage and an authenticated REST PDF path.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_LIMIT, INVALID_CURSOR, INVALID_INVOICE_TYPE, INVALID_QUERY_PARAMETER, UNEXPECTED_QUERY_PARAMETERS or UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, disabled organisation or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: invoice absent, deleted, uncovered or owned by another organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. No financial operation was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "invoices:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /organisation/invoices/{id}/pdf

Download the organisation's existing local invoice PDF

`download_organisation_invoice_pdf`

Required scope: `invoices:read`, explicitly granted; payment/receipt scopes do not grant access. Reads Unisoft invoices billed to the authenticated organisation, not donation receipts or tax documents. Coverage is PARTIAL: only persisted local factures records of type COM/SOFT are included; Mercury internal_factures and Stripe UK/US/Pennylane billing owned by Unisoft Internal are excluded. An empty result does not prove that the organisation has no invoices. No provider request, sync, reconciliation, portal creation, invoice issuance, fee/tax calculation or debit occurs. COM/PAYGREEN total is normalised to minor EUR units from its audited stored major-unit total. SOFT amountMinor and currency remain null because its producer/unit cannot be verified. settlementStatus is always NOT_REPORTED; neither the PDF nor age proves payment or overdue status. Unknown historical dates/period components and invalid money remain null, never fabricated zero or current dates. The PDF href requires the same invoices:read authentication through REST, and its availability is NOT_CHECKED in JSON. Campaign-restricted keys are refused because billing has no campaign owner. Unknown query parameters and non-empty request bodies are rejected. The shared authentication layer may record API-key usage. The server first checks the invoice's current organisation ownership and covered type, then reads exactly FACTURE_DIR/<UUID>. URLs, client paths, redirects, symlinks and hardlinks are never followed. Only an existing regular PDF beginning %PDF- and at most 20971520 bytes is returned as an attachment; no document is generated or repaired. 409 DOCUMENT_UNAVAILABLE means absent or ineligible file; 503 DOCUMENT_STORAGE_UNAVAILABLE means the private storage is unavailable. Ask an Unisoft administrator to restore the existing document/storage; do not retry issuance or payment.

MCP returns the actual private file as an embedded resource with MIME type and base64 blob, plus filename, byteLength and the SHA-256 of the decoded bytes. Use the host file capability to save or attach those bytes under the returned filename and verify size and SHA-256. The unisoft URI identifies this response only; it is not a public URL or a reusable download handle. Do not paste the blob into chat text, publicly upload a financial document or invent a sharing URL. The current authenticated REST owner rechecks organisation, permissions and every required source or export proof on each call. REST keeps its binary response. A file proves only that these bytes were retrieved, not payment settlement, document legal validity or delivery to a recipient.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "invoices:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Local Unisoft invoice UUID returned by this list. No external customer or provider invoice reference.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Existing PDF attachment, maximum 20 MiB, private and no-store.",
  "content": {
    "application/pdf": {
      "schema": {
        "type": "string",
        "format": "binary"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_LIMIT, INVALID_CURSOR, INVALID_INVOICE_TYPE, INVALID_QUERY_PARAMETER, UNEXPECTED_QUERY_PARAMETERS or UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, disabled organisation or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: invoice absent, deleted, uncovered or owned by another organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "DOCUMENT_UNAVAILABLE: existing file missing, ineligible, oversized or not a PDF. No generation is attempted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. No financial operation was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "DOCUMENT_STORAGE_UNAVAILABLE: private invoice storage is not accessible. Restore storage through the invoice owner.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "invoices:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-mcp-file": {
    "mimeType": "application/pdf",
    "maxBytes": 20971520
  }
}
```

## סכמות

```json
{
  "components": {
    "schemas": {
      "OrganisationInvoiceListResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "meta",
          "coverage"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrganisationInvoice"
            }
          },
          "coverage": {
            "$ref": "#/components/schemas/OrganisationInvoiceCoverage"
          },
          "meta": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "nextCursor",
              "hasMore",
              "count"
            ],
            "properties": {
              "nextCursor": {
                "type": "string",
                "nullable": true,
                "description": "Opaque cursor bound to this organisation and type filter. Reuse unchanged with the same type; null when the page has no continuation."
              },
              "hasMore": {
                "type": "boolean"
              },
              "count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 200
              }
            }
          }
        }
      },
      "OrganisationInvoice": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "type",
          "number",
          "issuedAt",
          "period",
          "amountMinor",
          "currency",
          "settlementStatus",
          "pdf"
        ],
        "description": "Allowlisted local Unisoft billing document. This is an invoice billed to the organisation, separate from donation receipts and tax documents.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Local Unisoft invoice UUID. Provider invoice IDs and customer references are not accepted."
          },
          "type": {
            "type": "string",
            "enum": [
              "COM",
              "SOFT"
            ],
            "description": "Stored invoice kind: COM for commissions, SOFT for software. SOFT's issuing owner and amount unit have not been verified in this checkout."
          },
          "number": {
            "type": "string",
            "nullable": true,
            "description": "COM/PAYGREEN printed number KHC- followed by the stored positive integer num. Null when this printed-number convention cannot be verified."
          },
          "issuedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Stored BSON datetime normalised to UTC, years 0000 to 9999. Missing, invalid and unsupported historical date types remain null. No current date is substituted."
          },
          "period": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "year",
              "month"
            ],
            "description": "Stored invoicing period, without a timezone or inferred boundaries. Each invalid or absent component is null; historical month 0 is not repaired.",
            "properties": {
              "year": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9999,
                "nullable": true
              },
              "month": {
                "type": "integer",
                "minimum": 1,
                "maximum": 12,
                "nullable": true
              }
            }
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "nullable": true,
            "description": "COM/PAYGREEN total converted exactly from the owner's stored major-unit total into minor units: 12.34 EUR becomes 1234. Null for SOFT, unverified producer/currency, missing, malformed, fractional-cent or unsafe totals. Null never means zero. No fee or tax is recalculated."
          },
          "currency": {
            "type": "string",
            "enum": [
              "eur"
            ],
            "nullable": true,
            "description": "EUR is fixed by the audited COM/PAYGREEN PDF template. Null for SOFT or incompatible stored currency. No current organisation currency is substituted."
          },
          "settlementStatus": {
            "type": "string",
            "enum": [
              "NOT_REPORTED"
            ],
            "description": "The local invoice owner supplies no verified settlement state. File presence, invoice number and age do not imply paid, unpaid, overdue, captured or settled."
          },
          "pdf": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "href",
              "availability"
            ],
            "description": "Authenticated REST download of the existing PDF. JSON metadata does not check file existence. No public or provider URL is exposed.",
            "properties": {
              "href": {
                "type": "string",
                "description": "Relative API path under /integrations/v2/organisation/invoices. Use the same API environment and invoices:read credentials; it is not a public link."
              },
              "availability": {
                "type": "string",
                "enum": [
                  "NOT_CHECKED"
                ]
              }
            }
          }
        }
      },
      "OrganisationInvoiceCoverage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source",
          "complete",
          "limitations"
        ],
        "description": "Explicitly partial coverage: only the local factures owner is readable; provider-managed billing is not included.",
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "LOCAL_FACTURES"
            ]
          },
          "complete": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "PROVIDER_INVOICES_NOT_INCLUDED",
                "SETTLEMENT_NOT_REPORTED",
                "SOFT_AMOUNT_UNIT_UNVERIFIED"
              ]
            }
          }
        }
      },
      "OrganisationInvoiceError": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      },
      "OrganisationInvoiceResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "coverage"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/OrganisationInvoice"
          },
          "coverage": {
            "$ref": "#/components/schemas/OrganisationInvoiceCoverage"
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
