**Versions de l’API** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=fr)

# Factures de l’organisation

OpenAPI 3.0.3 · API 2.0.0

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

Factures Unisoft locales existantes de l’organisation authentifiée ; la couverture de la facturation gérée par les prestataires est précisée explicitement.

## Opérations

## GET /organisation/invoices

Lister les factures Unisoft locales de l’organisation

`list_organisation_invoices`

Autorisation requise : `invoices:read`, attribuée explicitement ; les droits sur les paiements et reçus ne donnent aucun accès. Consulte les factures Unisoft adressées à l’organisation authentifiée, distinctes des reçus de dons et des documents fiscaux. La couverture est PARTIELLE : seuls les enregistrements locaux persistés factures de type COM/SOFT sont inclus ; internal_factures Mercury et la facturation Stripe UK/US/Pennylane portée par Unisoft Internal sont exclus. Un résultat vide ne prouve pas que l’organisation n’a aucune facture. Aucun appel au prestataire, synchronisation, rapprochement, création de portail, émission de facture, calcul de frais ou de taxe, ni débit n’est effectué. Le total COM/PAYGREEN est normalisé en unités mineures EUR depuis son total en unités majeures audité. Les champs amountMinor et currency de SOFT restent null car son producteur et son unité ne peuvent pas être vérifiés. settlementStatus vaut toujours NOT_REPORTED ; ni le PDF ni son ancienneté ne prouvent un paiement ou un retard. Les dates historiques, composantes de période et montants inconnus restent null, sans zéro ni date courante fabriqués. Le href du PDF exige la même authentification invoices:read via REST ; sa disponibilité JSON vaut NOT_CHECKED. Les clés limitées à des collectes sont refusées, car la facturation n’appartient à aucune collecte. Les paramètres de requête inconnus et les corps de requête non vides sont refusés. La couche d’authentification partagée peut enregistrer l’usage de la clé API. Tri par datetime BSON enregistré valide décroissant, puis id décroissant ; les dates absentes ou invalides arrivent en dernier. Le curseur est lié à l’organisation et au filtre type ; les changements concurrents ne constituent pas un instantané. Un UUID historique inexploitable renvoie 409 INVALID_INVOICE_HISTORY au lieu d’ignorer une facture ou d’inventer une continuation. Aucune ligne de facture, identité de donateur, copie privée ni identifiant de compte prestataire n’est renvoyé.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "limit",
  "in": "query",
  "description": "Taille de page entière entre 1 et 200 ; valeur par défaut 50.",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "description": "Curseur nextCursor opaque renvoyé par cette liste de factures de l’organisation avec le même filtre type.",
  "schema": {
    "type": "string",
    "maxLength": 2048
  }
}
```

```json
{
  "name": "type",
  "in": "query",
  "description": "Type enregistré exact facultatif COM ou SOFT. Omettez-le pour inclure les deux types locaux couverts.",
  "schema": {
    "type": "string",
    "enum": [
      "COM",
      "SOFT"
    ]
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page de factures locales avec une couverture explicitement partielle.",
  "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 ou UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, organisation désactivée ou CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_INVOICE_HISTORY : l’identité enregistrée d’une facture empêche une pagination sûre.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Aucune opération financière n’a été tentée.",
  "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}

Consulter une facture Unisoft locale

`get_organisation_invoice`

Autorisation requise : `invoices:read`, attribuée explicitement ; les droits sur les paiements et reçus ne donnent aucun accès. Consulte les factures Unisoft adressées à l’organisation authentifiée, distinctes des reçus de dons et des documents fiscaux. La couverture est PARTIELLE : seuls les enregistrements locaux persistés factures de type COM/SOFT sont inclus ; internal_factures Mercury et la facturation Stripe UK/US/Pennylane portée par Unisoft Internal sont exclus. Un résultat vide ne prouve pas que l’organisation n’a aucune facture. Aucun appel au prestataire, synchronisation, rapprochement, création de portail, émission de facture, calcul de frais ou de taxe, ni débit n’est effectué. Le total COM/PAYGREEN est normalisé en unités mineures EUR depuis son total en unités majeures audité. Les champs amountMinor et currency de SOFT restent null car son producteur et son unité ne peuvent pas être vérifiés. settlementStatus vaut toujours NOT_REPORTED ; ni le PDF ni son ancienneté ne prouvent un paiement ou un retard. Les dates historiques, composantes de période et montants inconnus restent null, sans zéro ni date courante fabriqués. Le href du PDF exige la même authentification invoices:read via REST ; sa disponibilité JSON vaut NOT_CHECKED. Les clés limitées à des collectes sont refusées, car la facturation n’appartient à aucune collecte. Les paramètres de requête inconnus et les corps de requête non vides sont refusés. La couche d’authentification partagée peut enregistrer l’usage de la clé API. Accepte uniquement l’UUID de la facture locale. Les factures absentes, supprimées, de type inconnu et d’une autre organisation renvoient le même 404. Une référence client de prestataire ne peut pas autoriser l’accès à une facture. Le JSON ne renvoie jamais d’URL de prestataire, de secret ni de moyen de paiement réutilisable.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID local de la facture Unisoft renvoyé par cette liste. Aucune référence client externe ni référence de facture prestataire.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Facture locale avec sa couverture et un chemin de téléchargement REST authentifié du PDF.",
  "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 ou UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, organisation désactivée ou CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND : facture absente, supprimée, hors couverture ou appartenant à une autre organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Aucune opération financière n’a été tentée.",
  "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

Télécharger le PDF local existant d’une facture de l’organisation

`download_organisation_invoice_pdf`

Autorisation requise : `invoices:read`, attribuée explicitement ; les droits sur les paiements et reçus ne donnent aucun accès. Consulte les factures Unisoft adressées à l’organisation authentifiée, distinctes des reçus de dons et des documents fiscaux. La couverture est PARTIELLE : seuls les enregistrements locaux persistés factures de type COM/SOFT sont inclus ; internal_factures Mercury et la facturation Stripe UK/US/Pennylane portée par Unisoft Internal sont exclus. Un résultat vide ne prouve pas que l’organisation n’a aucune facture. Aucun appel au prestataire, synchronisation, rapprochement, création de portail, émission de facture, calcul de frais ou de taxe, ni débit n’est effectué. Le total COM/PAYGREEN est normalisé en unités mineures EUR depuis son total en unités majeures audité. Les champs amountMinor et currency de SOFT restent null car son producteur et son unité ne peuvent pas être vérifiés. settlementStatus vaut toujours NOT_REPORTED ; ni le PDF ni son ancienneté ne prouvent un paiement ou un retard. Les dates historiques, composantes de période et montants inconnus restent null, sans zéro ni date courante fabriqués. Le href du PDF exige la même authentification invoices:read via REST ; sa disponibilité JSON vaut NOT_CHECKED. Les clés limitées à des collectes sont refusées, car la facturation n’appartient à aucune collecte. Les paramètres de requête inconnus et les corps de requête non vides sont refusés. La couche d’authentification partagée peut enregistrer l’usage de la clé API. Le serveur vérifie d’abord l’organisation propriétaire et le type couvert de la facture actuelle, puis lit exactement FACTURE_DIR/<UUID>. Les URL, chemins client, redirections, liens symboliques et liens physiques ne sont jamais suivis. Seul un fichier PDF ordinaire existant commençant par %PDF- et pesant au plus 20971520 octets est renvoyé en pièce jointe ; aucun document n’est généré ni réparé. 409 DOCUMENT_UNAVAILABLE signale un fichier absent ou inéligible ; 503 DOCUMENT_STORAGE_UNAVAILABLE signale un stockage privé indisponible. Demandez à un administrateur Unisoft de restaurer le document ou le stockage existant ; ne relancez ni émission ni paiement.

Le MCP renvoie le fichier privé réel dans une ressource embarquée avec son type MIME et son blob base64, ainsi que filename, byteLength et le SHA-256 des octets décodés. Utiliser la capacité fichiers de l’hôte pour enregistrer ou joindre ces octets sous le nom renvoyé et vérifier leur taille et leur SHA-256. L’URI unisoft identifie uniquement cette réponse. Elle ne constitue ni une URL publique ni une référence de téléchargement réutilisable. Fournir le fichier au destinataire autorisé, sans recopier le blob dans le texte du chat, publier un document financier ou inventer une URL de partage. Le propriétaire REST authentifié recontrôle l’organisation, les permissions et toutes les sources ou preuves d’export requises à chaque appel. REST conserve sa réponse binaire. Le fichier prouve uniquement la récupération de ces octets. Il ne prouve ni règlement bancaire, ni validité juridique du document, ni remise à un destinataire.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID local de la facture Unisoft renvoyé par cette liste. Aucune référence client externe ni référence de facture prestataire.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Pièce jointe PDF existante, privée, sans cache (no-store), de 20 MiB au maximum.",
  "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 ou UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, organisation désactivée ou CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND : facture absente, supprimée, hors couverture ou appartenant à une autre organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "DOCUMENT_UNAVAILABLE : fichier existant absent, inéligible, trop volumineux ou non PDF. Aucune génération n’est tentée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Aucune opération financière n’a été tentée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrganisationInvoiceError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "DOCUMENT_STORAGE_UNAVAILABLE : le stockage privé des factures est inaccessible. Faites restaurer le stockage par le propriétaire des factures.",
  "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
  }
}
```

## Schémas

```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": "Curseur opaque lié à cette organisation et au filtre type. Réutilisez-le sans modification avec le même type ; null indique l’absence de page suivante."
              },
              "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": "Document local de facturation Unisoft en liste blanche. Il s’agit d’une facture adressée à l’organisation, distincte des reçus de dons et des documents fiscaux.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID local de la facture Unisoft. Les identifiants de facture du prestataire et les références client ne sont pas acceptés."
          },
          "type": {
            "type": "string",
            "enum": [
              "COM",
              "SOFT"
            ],
            "description": "Type de facture enregistré : COM pour les commissions, SOFT pour le logiciel. Le propriétaire émetteur et l’unité du montant SOFT n’ont pas pu être vérifiés dans ce checkout."
          },
          "number": {
            "type": "string",
            "nullable": true,
            "description": "Numéro imprimé COM/PAYGREEN : KHC- suivi de l’entier positif num enregistré. Vaut null lorsque cette convention de numérotation imprimée ne peut pas être vérifiée."
          },
          "issuedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "datetime BSON enregistré, normalisé en UTC, pour les années 0000 à 9999. Les dates historiques absentes, invalides ou de type non pris en charge restent null. La date courante ne les remplace jamais."
          },
          "period": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "year",
              "month"
            ],
            "description": "Période de facturation enregistrée, sans fuseau horaire ni bornes déduites. Chaque composante absente ou invalide vaut null ; le mois historique 0 n’est pas corrigé.",
            "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": "Total COM/PAYGREEN converti exactement des unités majeures enregistrées par son propriétaire vers les unités mineures : 12.34 EUR devient 1234. Vaut null pour SOFT, un producteur ou une devise non vérifiés, ou un total absent, mal formé, inférieur à la précision du centime ou hors des bornes sûres. null ne signifie jamais zéro. Aucun frais ni taxe n’est recalculé."
          },
          "currency": {
            "type": "string",
            "enum": [
              "eur"
            ],
            "nullable": true,
            "description": "EUR est fixé par le modèle PDF COM/PAYGREEN audité. Vaut null pour SOFT ou une devise enregistrée incompatible. La devise actuelle de l’organisation ne remplace aucune donnée."
          },
          "settlementStatus": {
            "type": "string",
            "enum": [
              "NOT_REPORTED"
            ],
            "description": "Le propriétaire des factures locales ne fournit aucun état de règlement vérifié. La présence du fichier, le numéro de facture et son ancienneté ne permettent de conclure ni au paiement, ni à un impayé, ni à un retard, ni à une capture, ni à un règlement bancaire."
          },
          "pdf": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "href",
              "availability"
            ],
            "description": "Téléchargement REST authentifié du PDF existant. Les métadonnées JSON ne vérifient pas la présence du fichier. Aucune URL publique ni de prestataire n’est exposée.",
            "properties": {
              "href": {
                "type": "string",
                "description": "Chemin API relatif sous /integrations/v2/organisation/invoices. Utilisez le même environnement API et des identifiants autorisés pour invoices:read ; ce lien n’est pas public."
              },
              "availability": {
                "type": "string",
                "enum": [
                  "NOT_CHECKED"
                ]
              }
            }
          }
        }
      },
      "OrganisationInvoiceCoverage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source",
          "complete",
          "limitations"
        ],
        "description": "Couverture explicitement partielle : seul le propriétaire local factures est lisible ; la facturation gérée par des prestataires n’est pas incluse.",
        "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"
      }
    }
  }
}
```
