Archive

Fiscal archive restitution: the exact transmitted bytes of your e-invoicing documents, their SHA-256 manifest, their audit trail, and the export that packages all three.

Afficher l'état de l'archive fiscale de cette organisation

GET /api/v1/archive

Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.

Ce que l'archive fiscale fait pour cette organisation. state vaut vault (le coffre ArchiveVault payant : chaque octet transmis écrit dans un bucket verrouillé, soumis à une durée de conservation), france_capture (la capture des transmissions françaises, indépendante du coffre) ou none ; entitled indique si le plan actuel inclut le coffre, et plans_with_vault nomme les plans qui l'incluent, pour une organisation qui ne l'a pas encore. vault_status (provisioning, active, retained, error) décrit un coffre en cours de mise en service ou de clôture.

Le reste est ce qu'un vérificateur demande : region — où les octets résident physiquement ; retention_days — la durée de conservation que le bucket de stockage impose lui-même, ce qui empêche toute modification ou suppression d'un objet archivé avant son échéance ; locked ; object_count ; et last_proven_at / integrity_state (never, running, passed, failed, inconclusive, ou not_applicable pour une organisation qui n'archive rien) issus de la re-vérification périodique de toutes les empreintes stockées par la plateforme.

quota_bytes et used_bytes sont MESURÉS, jamais imposés : dépasser le quota ne supprime rien. (#980)

Réponses

Exemple de requête

curl -X GET "https://kworia.com/api/v1/archive" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json"

Lister les objets archivés (index du manifeste)

GET /api/v1/archive/documents

Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.

L'index paginé du manifeste de l'archive, du plus récemment archivé au plus ancien.

Chaque ligne est un OBJET archivé, pas un document. Une seule facture en produit normalement plusieurs — le corps de la requête envoyée au prestataire de facturation électronique, la réponse reçue, le XML UBL, le PDF, chaque pièce jointe, les événements webhook et les preuves de transmission — et chacun porte son propre id, son propre object_kind et sa propre empreinte sha256. Cette empreinte est celle des octets exacts que renvoie GET /api/v1/archive/documents/{id}/download : le destinataire peut la recalculer et prouver que l'archive n'a pas altéré ce qui a été transmis.

Filtres : number et counterparty (partiels, insensibles à la casse), issued_from / issued_until (date d'émission du document), amount_min / amount_max, direction (outbound, inbound), kind (request_body, response_body, ubl_xml, pdf, attachment, webhook_event, received_document_json, status_snapshot, evidence), plus per_page (1–200, 25 par défaut) et page.

Les montants sont des chaînes, jamais des flottants — un index qui arrondirait un total est un index qu'un vérificateur peut réfuter. L'adresse de stockage (bucket, compte de stockage, clé d'objet) est volontairement absente ici ; le manifest.csv de l'export la porte pour le vérificateur qui en a besoin. (#980)

Paramètres

Réponses

Exemple de requête

curl -X GET "https://kworia.com/api/v1/archive/documents" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json"

Télécharger un objet archivé, octet pour octet

GET /api/v1/archive/documents/{id}/download

Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.

Les octets archivés d'un objet, restitués exactement tels qu'ils ont été conservés — rien n'est régénéré, ré-encodé ni re-signé. Content-Type reprend le content_type de la ligne du manifeste et Content-Length sa taille size_bytes, de sorte que la réponse peut être hachée et comparée au sha256 de la ligne. {id} est l'id d'une ligne renvoyée par GET /api/v1/archive/documents.

404 pour un identifiant absent de l'archive de votre organisation — la même réponse que pour un identifiant qui n'existe pas, afin qu'un identifiant ne puisse pas être testé. 503, jamais 404, lorsque l'archive ne peut pas restituer des octets que le manifeste annonce : il s'agit d'un incident d'intégrité et non d'une page manquante, le contrôle d'intégrité de la plateforme est alerté, et répondre « introuvable » le dissimulerait.

Chaque téléchargement réussi est ajouté à la chaîne d'audit de l'organisation, avec l'utilisateur et la surface concernés. (#980)

Paramètres

Réponses

Exemple de requête

curl -X GET "https://kworia.com/api/v1/archive/documents/{id}/download" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json"

Commander un export de l'archive (ZIP)

POST /api/v1/archive/exports

Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.

Commande un ZIP contenant les objets archivés, leur manifeste, la piste d'audit et les échanges réseau. 202, et non 201 : la construction est asynchrone (file d'attente d'archivage), donc ce qui existe au retour est l'ordre de travail (status: pending) et pas encore l'artefact — interrogez GET /api/v1/archive/exports/{id} et récupérez-le lorsque download_url n'est plus nul.

Un corps vide signifie l'archive entière. Sinon, les huit mêmes clauses que GET /api/v1/archive/documents le restreignent (number, counterparty, issued_from, issued_until, amount_min, amount_max, direction, kind) ; il n'y a pas de pagination, car un export parcourt l'ensemble des résultats. L'ensemble est figé à l'instant de la commande : les documents archivés pendant la construction n'y sont pas ajoutés en silence.

Un seul export est construit à la fois par organisation. Une seconde demande alors qu'un export est en attente ou en cours est refusée avec un 409, tout comme une demande dont les filtres ne correspondent à rien. Un ZIP contient également un nombre borné d'objets — 72 000 par défaut, déduit de ce qu'une construction peut tenir en mémoire et achever dans son budget de temps — et une demande qui le dépasse est refusée par le même 409, plutôt qu'acceptée puis mise en échec une heure plus tard ; restreignez-la avec issued_from/issued_until, un exercice par export. L'artefact terminé expire — sept jours par défaut — puis est supprimé du disque opérationnel : une copie de dix ans de contreparties et de montants ne doit pas rester indéfiniment hors du coffre verrouillé.

Nécessite la permission archive.export (et un jeton d'API portant la portée archive.export). Contrairement à toute autre écriture de cette API, ce point de terminaison reste accessible à une organisation ARCHIVÉE : il ne modifie aucun enregistrement de gestion, et une organisation archivée est précisément celle qui a le plus besoin qu'on lui restitue ses documents fiscaux. (#980)

Corps de la requête

Réponses

Exemple de requête

curl -X POST "https://kworia.com/api/v1/archive/exports" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "string",
    "counterparty": "string",
    "issued_from": "string",
    "issued_until": "string",
    "amount_min": 1,
    "amount_max": 1,
    "direction": "string",
    "kind": "string"
}'

Afficher un export et où le récupérer

GET /api/v1/archive/exports/{id}

Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.

L'état d'un ordre de travail : status (pending, building, completed, failed, expired), object_count — ce que la construction a réellement empaqueté — et, séparément, missing_object_count, car fondre un manque dans le total ferait passer une restitution partielle pour une restitution complète. Également file_size_bytes, manifest_sha256, les filters de la commande et expires_at.

Dès qu'il y a quelque chose à récupérer, download_url pointe vers GET /api/v1/archive/exports/{id}/download — authentifié par le même jeton Bearer que toutes les autres opérations ici. Ce n'est pas le lien signé destiné au navigateur que porte l'e-mail de notification : celui-ci est protégé par la session, et un jeton Bearer présenté à cette adresse produit une redirection vers la page de connexion. Tant qu'il n'y a rien à récupérer, download_url est nul.

Le ZIP contient, conformément au §3.8 de la spécification : objects/<clé d'objet> — les octets archivés eux-mêmes ; manifest.json et manifest.csv — un enregistrement par objet avec son SHA-256, son bucket, son compte de stockage, sa région, sa taille et present_in_export ; audit-trail.json et audit-trail.csv — la chaîne d'empreintes en ajout seul de l'organisation, exportée ENTIÈREMENT même pour un export filtré, car une chaîne ne se vérifie que de bout en bout ; transmissions.json et transmissions.csv — chaque échange avec le réseau de facturation électronique ou l'administration fiscale, rattaché à la piste d'audit par l'identifiant de document et incluant les transmissions du e-reporting français qui n'appartiennent à aucun document unique ; et un README bilingue FR/EN expliquant au destinataire comment recalculer lui-même les empreintes.

404 pour un identifiant hors de votre organisation. (#980)

Paramètres

Réponses

Exemple de requête

curl -X GET "https://kworia.com/api/v1/archive/exports/{id}" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json"

Télécharger un export terminé (ZIP)

GET /api/v1/archive/exports/{id}/download

Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.

Le ZIP lui-même — l'adresse vers laquelle pointe download_url — authentifié par le même jeton Bearer que toutes les autres opérations ici, raison pour laquelle il ne porte aucune signature.

404 pour un identifiant hors de votre organisation et pour un export qui n'est pas prêt (une seule réponse pour « pas le vôtre », « aucun export » et « pas terminé »). 410 une fois expires_at dépassé : l'artefact a été volontairement supprimé du disque opérationnel, et la suite consiste à en commander un autre — ce qu'un « introuvable » ne vous dirait pas. 503 si la ligne est terminée mais que l'artefact n'est pas sur le disque ; le contrôle d'intégrité de la plateforme est alerté.

Chaque téléchargement réussi est ajouté à la chaîne d'audit de l'organisation, avec l'utilisateur concerné et la porte utilisée — la restitution fait elle-même partie des preuves qu'un vérificateur peut se voir présenter. (#980)

Paramètres

Réponses

Exemple de requête

curl -X GET "https://kworia.com/api/v1/archive/exports/{id}/download" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json"