{"openapi":"3.1.0","info":{"title":"Let’s Peppol Proxy API","description":"Proxy registry and document-transport endpoints.\n\n`/sapi/document/**` accepts KYC JWTs carrying a `uid`: normally a user's\nAuthorization Code + PKCE token forwarded by App, or App's client-credentials\ntoken for background synchronization. `/sapi/registry/**` is service-only and\nrequires the `service` scope. `/api/stats/**` is public. Local-control APIs are\nintentionally omitted from this OpenAPI document.\n\nJWTs are verified against KYC JWKS and checked for expiry, configured issuer,\nand audience `letspeppol-api`. The optional `X-Acting-User-Authorization`\nheader carries an end-user token only when an APP service token performs an\noperation that still needs user identity; it never replaces the primary bearer\ntoken.\n\nError bodies use either `{ \"errorCode\": \"...\", \"message\": \"...\" }` or\n`{ \"message\": \"...\" }`. Access-point outages can return 503 with Retry-After;\nduplicate or conflicting operations return 409.\n","contact":{"name":"Let’s Peppol"},"version":"v1"},"servers":[{"url":"/proxy","description":"Proxy API through the public reverse proxy"}],"tags":[{"name":"Proxy Statistics","description":"Public aggregate proxy usage counters; no company or document data is returned."},{"name":"Proxy Documents","description":"Service-facing document transport endpoints for polling, submitting, updating, and acknowledging UBL documents through the proxy."},{"name":"Proxy Registry","description":"Service-facing endpoints for managing a company's proxy registration and access-point level app links."}],"paths":{"/sapi/registry/unregister":{"put":{"tags":["Proxy Registry"],"summary":"Unregister company from access point","description":"Disables the proxy registration for the given company while preserving the stored record.","operationId":"unregister","parameters":[{"name":"peppolId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RegistryDto"}}}}},"security":[{"serviceAuth":["service"]}]}},"/sapi/registry/settings":{"get":{"tags":["Proxy Registry"],"summary":"Get company Peppol settings","description":"Reads the receiving flag, fetching it from the provider when unknown, and checks the current receiving SMP for send-only companies.","operationId":"getSettings","parameters":[{"name":"peppolId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PeppolSettings"}}}}},"security":[{"serviceAuth":["service"]}]},"put":{"tags":["Proxy Registry"],"summary":"Update company Peppol settings","description":"Changes receiving settings without deleting the company or its document history. Omitted fields are unchanged.","operationId":"updateSettings","parameters":[{"name":"peppolId","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeppolSettings"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PeppolSettings"}}}}},"security":[{"serviceAuth":["service"]}]}},"/sapi/registry/reject":{"put":{"tags":["Proxy Registry"],"summary":"Reject app link","description":"Revokes or rejects an app identity that should no longer act on behalf of the given company.","operationId":"reject","parameters":[{"name":"peppolId","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppLinkRequest"}}},"required":true},"responses":{"200":{"description":"OK"}},"security":[{"serviceAuth":["service"]}]}},"/sapi/registry/allow":{"put":{"tags":["Proxy Registry"],"summary":"Allow app link","description":"Approves an app identity so it can act on behalf of the given company through the proxy.","operationId":"allow","parameters":[{"name":"peppolId","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppLinkRequest"}}},"required":true},"responses":{"200":{"description":"OK"}},"security":[{"serviceAuth":["service"]}]}},"/sapi/document/{id}":{"get":{"tags":["Proxy Documents"],"summary":"Get proxy document by id","description":"Loads a single document visible to the authenticated company context.","operationId":"getById","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/UblDocumentDto"}}}}},"security":[{"serviceAuth":["service"]},{"oauth2":["openid"]}]},"put":{"tags":["Proxy Documents"],"summary":"Update outbound proxy document","description":"Replaces the contents or metadata of an outbound document that has not completed sending yet.","operationId":"update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Acting-User-Authorization","in":"header","required":false,"schema":{"type":"string"}},{"name":"noArchive","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UblDocumentDto"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/UblDocumentDto"}}}}},"security":[{"serviceAuth":["service"]},{"oauth2":["openid"]}]},"delete":{"tags":["Proxy Documents"],"summary":"Cancel outbound proxy document","description":"Cancels an outbound document that should no longer be sent through the proxy.","operationId":"delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"noArchive","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK"}},"security":[{"serviceAuth":["service"]},{"oauth2":["openid"]}]}},"/sapi/document/{id}/reschedule":{"put":{"tags":["Proxy Documents"],"summary":"Schedule or resend outbound document","description":"Queues an outbound document for sending immediately or at a later scheduled time.","operationId":"reschedule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Acting-User-Authorization","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UblDocumentDto"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/UblDocumentDto"}}}}},"security":[{"serviceAuth":["service"]},{"oauth2":["openid"]}]}},"/sapi/document/{id}/downloaded":{"put":{"tags":["Proxy Documents"],"summary":"Acknowledge one downloaded document","description":"Marks a single inbound document as downloaded by the authenticated user or linked app.","operationId":"downloaded","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"noArchive","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK"}},"security":[{"serviceAuth":["service"]},{"oauth2":["openid"]}]}},"/sapi/document/downloaded":{"put":{"tags":["Proxy Documents"],"summary":"Acknowledge multiple downloaded documents","description":"Marks a batch of inbound documents as downloaded by the authenticated user or linked app.","operationId":"downloadedBatch","parameters":[{"name":"noArchive","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"string","format":"uuid"}}}},"required":true},"responses":{"200":{"description":"OK"}},"security":[{"serviceAuth":["service"]},{"oauth2":["openid"]}]}},"/sapi/registry":{"get":{"tags":["Proxy Registry"],"summary":"Get registry state","description":"Returns the current proxy registration state for the given company.","operationId":"getById_1","parameters":[{"name":"peppolId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RegistryDto"}}}}},"security":[{"serviceAuth":["service"]}]},"post":{"tags":["Proxy Registry"],"summary":"Register company on access point","description":"Creates or updates proxy registration for the given company using the configured access point.","operationId":"register","parameters":[{"name":"peppolId","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrationRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RegistryDto"}}}}},"security":[{"serviceAuth":["service"]}]},"delete":{"tags":["Proxy Registry"],"summary":"Delete registry record","description":"Removes the stored proxy registry entry for the given company.","operationId":"delete_1","parameters":[{"name":"peppolId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}},"security":[{"serviceAuth":["service"]}]}},"/sapi/document":{"get":{"tags":["Proxy Documents"],"summary":"Poll new inbound documents","description":"Returns newly available inbound documents for the authenticated user or linked app context.","operationId":"getAllNew","parameters":[{"name":"size","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":100}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UblDocumentDto"}}}}}},"security":[{"serviceAuth":["service"]},{"oauth2":["openid"]}]},"post":{"tags":["Proxy Documents"],"summary":"Create outbound proxy document","description":"Stores a new outbound UBL document for later transmission through the configured access point.","operationId":"createToSend","parameters":[{"name":"X-Acting-User-Authorization","in":"header","required":false,"schema":{"type":"string"}},{"name":"noArchive","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UblDocumentDto"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/UblDocumentDto"}}}}},"security":[{"serviceAuth":["service"]},{"oauth2":["openid"]}]}},"/sapi/document/status":{"post":{"tags":["Proxy Documents"],"summary":"Fetch document status updates","description":"Returns the latest known status for the provided proxy document identifiers.","operationId":"getStatusUpdates","requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"string","format":"uuid"}}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UblDocumentDto"}}}}}},"security":[{"serviceAuth":["service"]},{"oauth2":["openid"]}]}},"/sapi/registry/registration-status":{"get":{"tags":["Proxy Registry"],"summary":"Get registration state and default access point","description":"Includes the configured access point for new registrations, even when the company has never registered.","operationId":"getRegistrationStatus","parameters":[{"name":"peppolId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RegistryDto"}}}}},"security":[{"serviceAuth":["service"]}]}},"/sapi/registry/receiving-availability":{"get":{"tags":["Proxy Registry"],"summary":"Check the current receiving SMP","description":"Uses Recommand to look up a Peppol identifier without requiring a local registration. Reserved for trusted backend services.","operationId":"getReceivingAvailability","parameters":[{"name":"peppolId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PeppolSettings"}}}}},"security":[{"serviceAuth":["service"]}]}},"/sapi/document/{id}/details":{"get":{"tags":["Proxy Documents"],"summary":"Get proxy document details","description":"Returns transport and UBL-derived details for one document visible to the authenticated company or linked app.","operationId":"getDetails","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DocumentDetailsDto"}}}}},"security":[{"serviceAuth":["service"]},{"oauth2":["openid"]}]}},"/api/stats":{"get":{"tags":["Proxy Statistics"],"summary":"Get proxy usage statistics","description":"Returns the number of registry entries using a configured access point.","operationId":"getStats","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ProxyStatsDto"}}}}}}}},"components":{"schemas":{"RegistryDto":{"type":"object","properties":{"peppolId":{"type":"string"},"peppolActive":{"type":"boolean"},"accessPoint":{"type":"string"},"defaultAccessPoint":{"type":"string"}}},"PeppolSettings":{"type":"object","properties":{"receiveDocuments":{"type":"boolean"},"receivingSmpUrl":{"type":"string"}}},"AppLinkRequest":{"type":"object","properties":{"uid":{"type":"string","format":"uuid"}}},"UblDocumentDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["INCOMING","OUTGOING"]},"type":{"type":"string","enum":["INVOICE","CREDIT_NOTE","SELF_BILLING_INVOICE","SELF_BILLING_CREDIT_NOTE"]},"ownerPeppolId":{"type":"string"},"partnerPeppolId":{"type":"string"},"createdOn":{"type":"string","format":"date-time"},"scheduledOn":{"type":"string","format":"date-time"},"processedOn":{"type":"string","format":"date-time"},"processedStatus":{"type":"string"},"ubl":{"type":"string"}}},"RegistrationRequest":{"type":"object","properties":{"name":{"type":"string"},"language":{"type":"string"},"country":{"type":"string"},"address":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"vatNumber":{"type":"string"},"signedContract":{"type":"string","format":"byte"}}},"DocumentDetailsDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ownerPeppolId":{"type":"string"},"partnerPeppolId":{"type":"string"},"accessPoint":{"type":"string"},"accessPointId":{"type":"string"},"processedOn":{"type":"string","format":"date-time"},"processedStatus":{"type":"string"},"partnerPeppolAccessPoint":{"type":"string"},"partnerPeppolMessageId":{"type":"string"},"partnerPeppolMessageOn":{"type":"string","format":"date-time"}}},"ProxyStatsDto":{"type":"object","properties":{"activeCompanies":{"type":"integer","format":"int64"}}}},"securitySchemes":{"oauth2":{"type":"oauth2","description":"KYC browser Authorization Code flow. PKCE (S256) is mandatory.","flows":{"authorizationCode":{"authorizationUrl":"/kyc/auth/oauth2/authorize","tokenUrl":"/kyc/auth/oauth2/token","scopes":{"openid":"OpenID Connect sign-in"}}}},"serviceAuth":{"type":"oauth2","description":"Trusted backend client-credentials flow for registry and background document traffic.","flows":{"clientCredentials":{"tokenUrl":"/kyc/auth/oauth2/token","scopes":{"service":"Service-to-service API access"}}}},"bearerAuth":{"type":"http","description":"Manual JWT entry for diagnostics; normal callers obtain it through OAuth2.","scheme":"bearer","bearerFormat":"JWT"}}}}