Preview. This API is not stable yet: field names, values and routes may change without notice until version 1.0.0. Watch the version number above and expect breaking changes.

Read access to the documents (invoices and credit notes) Konformy transmits or receives for your Stripe account, through its PDP (Plateforme de Dématérialisation Partenaire, the registered platform of the French e-invoicing reform). **Authentication**: every call carries `Authorization: Bearer `. Keys are created from the Konformy app in your Stripe dashboard (API tab). A `kfy_live_…` key reads live data, a `kfy_test_…` key reads test data. Keys are shown once at creation and can be revoked at any time. **Pagination**: list endpoints return `data`, `has_more` and `next_cursor`. Pass `next_cursor` as `starting_after` to fetch the next page. Pages hold up to 100 items. **Rate limits**: 300 requests per minute per key, 60 per minute on document downloads. Over the quota, the API answers `429` with a `Retry-After` header. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. **Errors**: `{"error": {"code": "…", "message": "…"}}`. Codes are stable identifiers meant for programs; messages are technical English for humans.

States of an issued document (click to expand)

state is the one value to branch on; routing says which table applies.

Routing einvoicing: French business buyer, deposited at the PDP, delivered to the buyer's platform, regulatory data forwarded to the tax authority.

state	Meaning
`pending`	Not deposited yet: a few seconds after finalisation, or held (no subscription, company not yet verified by the PDP)
`awaiting_payment`	Deposited, in flight or accepted by the buyer, not paid yet
`paid`	Payment declared (`fr:212`)
`refused`	Refused by the buyer (`fr:210`)
`rejected_by_network`	Rejected by the network before the tax authority took it (`fr:213`)
`ppf_accepted_undelivered`	Tax authority holds the regulatory data, the buyer could not be reached (no receiving platform, or PDP error)
`ppf_refused_delivered`	Tax authority refused the regulatory data, the buyer got the document
`ppf_refused_undelivered`	Tax authority refused the regulatory data, the buyer did not get it
`not_transmitted`	Konformy could not deposit it (missing data, lost PDP connection, connected account), or a 0 € invoice the merchant chose not to transmit
`cancelled`	Voided in Stripe before any deposit

Routing ereporting: consumer or foreign buyer, a sale taxed under a foreign VAT (French buyer included), or a French business buyer absent from the e-invoicing directory: the sale is declared to the tax authority, no document is delivered.

state	Meaning
`pending`	Queued for the next declaration run
`declared`	Declared to the tax authority (`transmitted_at`)
`not_transmitted`	Konformy could not declare it (data it could not map, or refused by the PDP); nothing will be retried as is
`cancelled`	Voided in Stripe before any declaration

Received documents: state is the treatment your team gave the document in the app: new, approved, refused, paid, disputed.

Which file to send your customer for a Stripe sale (click to expand)

For a Stripe invoice in_…, call GET /api/v1/documents/issued?stripe_id=in_…, then:

Answer	Send
`routing` = `ereporting`	The Stripe PDF: the sale is declared to the tax authority, no e-invoice exists (consumer, foreign buyer, sale taxed under a foreign VAT, or buyer absent from the directory)
`routing` = `einvoicing` and `documents.factur_x` = `available`	The Factur-X from `GET /api/v1/documents/issued/{id}/file`: the e-invoice as deposited at the PDP
`routing` = `einvoicing` and `documents.factur_x` = `unavailable`	Nothing yet: still processing, blocked, rejected or not yet deposited. `state` says which: `pending` on its way, `not_transmitted` blocked before the deposit (the app says what to fix; a 0 € invoice left out by the merchant's option reads the same and never gets a Factur-X), `cancelled` voided in Stripe before any deposit
Empty list	The Stripe PDF: Konformy did not handle this invoice (transmission paused, customer not tagged when transmission is limited to tagged customers, invoice finalized before the installation)