{"openapi":"3.0.3","info":{"title":"ePošťák Connector API","version":"1.12.0","description":"Focused machine contract for the recommended managed ERP integration. ePošťák approves the integrator and Peppol companies; the integrator configures stable customerRef values in the dashboard. Use an official SDK or follow the raw HTTP lifecycle token → documents → events/webhook → acknowledge local import or respond to the counterparty. A native integrator-wide webhook can push customerRef-rooted document events and explicitly selected customer lifecycle signals; polling remains the reliable document reconciliation checkpoint. Operations marked x-epostak-availability: private-preview are available only to explicitly allowlisted DEV integrators and return an opaque 404 elsewhere; their presence in this contract does not imply production availability. Existing Enterprise API and SAPI integrations remain supported and do not have to migrate to Connector.","contact":{"email":"info@epostak.sk","url":"https://epostak.sk"}},"servers":[{"url":"https://dev.epostak.sk/api/v1","description":"Sandbox/test"},{"url":"https://epostak.sk/api/v1","description":"Production (separate approved go-live)"}],"tags":[{"name":"Connector","description":"Recommended managed ERP surface: create and list business documents through /connector/documents, read document detail, follow eligible send/cancel links for staged documents, acknowledge local ERP processing, and poll business events. Recipient resolution, electronic format, and delivery stay managed by ePošťák."},{"name":"Connector — Advanced","description":"Optional Connector tools for ERP source mapping and technical support or audit evidence. These operations are not alternative starting flows."},{"name":"Auth","description":"API key introspection and rotation"}],"externalDocs":{"description":"Connector integration guide","url":"https://epostak.sk/api/docs/connector"},"paths":{"/auth/token":{"post":{"tags":["Auth"],"summary":"Mint a JWT access token (OAuth 2.0 client_credentials)","description":"Exchange the assigned client_id and a compatible sk_int_* client_secret for a short-lived Bearer JWT. Existing supported integrator credentials do not need to be replaced just to adopt Connector. client_id is the displayed key ID or prefix; it is not the secret. Set api_interface to connector and request only the Connector scopes needed by your integration.","operationId":"authToken","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JwtTokenRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/JwtTokenRequest"}}}},"responses":{"200":{"description":"Access token + refresh token issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JwtTokenResponse"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"description":"Invalid grant_type or malformed body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeppolErrorResponse"}}}},"401":{"description":"Invalid client credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeppolErrorResponse"}}}},"403":{"description":"Requested scope(s) not allowed by key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeppolErrorResponse"}}}},"423":{"description":"Invalid credential attempts throttled after 5 failures; valid credentials remain usable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeppolErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeppolErrorResponse"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}}}}},"/connector/documents":{"post":{"tags":["Connector"],"summary":"Send a business document","description":"Recommended Connector entry point. Send ordinary business JSON and identify the recipient with a company ID, tax ID, or VAT ID. ePošťák verifies the exact recipient and capability, then uses the managed delivery pipeline. `delivery=send` is an explicit instruction from a `documents:send` scope holder and proceeds to physical dispatch regardless of `autoSendEnabled`, which governs only automated policy-driven sources. `state=queued` after `delivery=send` means asynchronous dispatch was accepted; without send/cancel links it is not a staged document waiting for manual action. Only `delivery=stage` stores a new command and returns send/cancel links. `externalId` and `Idempotency-Key` are unique within the assigned Connector mailbox/customerRef. A replay of the same command returns the original result, including a historical staged state without automatically sending it; reusing either identifier with different content returns 409. When both are supplied they must identify the same business command.","operationId":"connectorCreateDocument","x-epostak-required-scopes":["documents:send"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Stable retry key scoped to the assigned Connector mailbox/customerRef. Reusing it with the same command is safe; different content returns 409 IDEMPOTENCY_CONFLICT."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessDocumentRequest"},"example":{"customerRef":"erp-acme","externalId":"invoice-2026-0042","type":"invoice","number":"2026-0042","recipient":{"country":"SK","taxId":"2120123456"},"issueDate":"2026-07-14","dueDate":"2026-07-28","currency":"EUR","lines":[{"description":"Monthly licence","quantity":1,"unitPrice":100,"vatRate":23}],"orderReference":"PO-2026-0042"}}}},"responses":{"200":{"description":"Idempotent replay of the same document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessDocument"},"example":{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","externalId":"invoice-2026-0042","direction":"outbound","type":"invoice","number":"2026-0042","state":"queued","replayed":true,"currency":"EUR","amounts":{"withoutTax":100,"tax":23,"total":123,"due":123},"createdAt":"2026-07-14T10:00:00.000Z","updatedAt":"2026-07-14T10:00:00.000Z","links":{"self":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111?customerRef=erp-acme","evidence":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/evidence?customerRef=erp-acme"}}}}},"201":{"description":"Document accepted into the managed flow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessDocument"},"example":{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","externalId":"invoice-2026-0042","direction":"outbound","type":"invoice","number":"2026-0042","state":"queued","replayed":false,"currency":"EUR","amounts":{"withoutTax":100,"tax":23,"total":123,"due":123},"createdAt":"2026-07-14T10:00:00.000Z","updatedAt":"2026-07-14T10:00:00.000Z","links":{"self":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111?customerRef=erp-acme","evidence":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/evidence?customerRef=erp-acme"}}}}},"400":{"description":"Malformed JSON; returns a correlated DOCUMENT_INVALID business error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"401":{"description":"Missing, expired, or invalid Connector access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"CUSTOMER_NOT_READY, IDEMPOTENCY_CONFLICT, or RECIPIENT_AMBIGUOUS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"},"example":{"error":{"code":"IDEMPOTENCY_CONFLICT","message":"Idempotency-Key was already used with different document content.","retryable":false,"nextAction":"Use the original payload or a new business command identifier.","requestId":"req_connector_01J2YQ4R"}}}}},"413":{"description":"Request body exceeds the limit; returns a correlated DOCUMENT_INVALID business error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"422":{"description":"Invalid document or recipient not found/not reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"},"example":{"error":{"code":"RECIPIENT_NOT_FOUND","message":"No receiving endpoint was found for this company.","field":"recipient.taxId","retryable":false,"nextAction":"Check the company identifier or ask the recipient which identifier it uses.","requestId":"req_connector_01J2YQ4S"}}}}},"429":{"description":"Connector rate limit exceeded. Retry only after the advertised delay.","headers":{"Retry-After":{"description":"Whole seconds to wait before retrying.","schema":{"type":"integer","minimum":1},"example":30}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"},"example":{"error":{"code":"DELIVERY_TEMPORARILY_UNAVAILABLE","message":"Too many Connector requests.","retryable":true,"nextAction":"Retry after the Retry-After delay.","requestId":"req_connector_01J2YQ4T"}}}}},"503":{"description":"Recipient verification or delivery temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"},"example":{"error":{"code":"RECIPIENT_LOOKUP_UNAVAILABLE","message":"Recipient verification is temporarily unavailable.","retryable":true,"nextAction":"Retry the same command with the same Idempotency-Key.","requestId":"req_connector_01J2YQ4U"}}}}}},"security":[{"integratorBearerAuth":[]}],"x-epostak-visibility":"recommended"},"get":{"tags":["Connector"],"summary":"List business documents","description":"Returns business-only documents for one approved customer. Tenant scope and the consent floor are applied before data is read.","operationId":"connectorListDocuments","x-epostak-required-scopes":["documents:read"],"parameters":[{"name":"customerRef","in":"query","required":true,"schema":{"type":"string"}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["inbound","outbound"]}},{"name":"state","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ConnectorBusinessState"}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["invoice","credit_note","debit_note","prepayment_invoice","correction","self_billing_invoice","self_billing_credit_note"]}},{"name":"createdAfter","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Cursor-paged business document list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessDocumentList"},"example":{"documents":[{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","externalId":"invoice-2026-0042","direction":"outbound","type":"invoice","number":"2026-0042","state":"queued","replayed":false,"currency":"EUR","amounts":{"withoutTax":100,"tax":23,"total":123,"due":123},"createdAt":"2026-07-14T10:00:00.000Z","updatedAt":"2026-07-14T10:00:00.000Z","links":{"self":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111?customerRef=erp-acme","evidence":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/evidence?customerRef=erp-acme"}}],"nextCursor":null,"hasMore":false}}}},"409":{"description":"Customer not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"422":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}}},"security":[{"integratorBearerAuth":[]}],"x-epostak-visibility":"recommended"}},"/connector/documents/{documentId}":{"get":{"tags":["Connector"],"summary":"Get Connector document or lifecycle","description":"Backward-compatible dual contract. Calling an established Invoice documentId without customerRef returns the original ERP lifecycle shape and preserves that documentId and its links. Supplying customerRef, or addressing a canonical Connector run ID, returns the canonical business document. include=technical remains available for the lifecycle projection. Visibility is limited to documents created after consent.","operationId":"connectorGetDocumentLifecycle","x-epostak-required-scopes":["documents:read"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customerRef","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Your stable ERP reference configured for the approved company. Send it exactly once."},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["technical"]},"description":"Requests the established technical lifecycle projection."}],"responses":{"200":{"description":"Established lifecycle detail or canonical business document, selected as described above","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","externalId":"invoice-2026-0042","direction":"outbound","type":"invoice","number":"2026-0042","state":"sending","replayed":false,"currency":"EUR","amounts":{"withoutTax":100,"tax":23,"total":123,"due":123},"createdAt":"2026-07-14T10:00:00.000Z","updatedAt":"2026-07-14T10:01:00.000Z","links":{"self":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111?customerRef=erp-acme","evidence":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/evidence?customerRef=erp-acme"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-visibility":"recommended","security":[{"integratorBearerAuth":[]}]}},"/connector/documents/{documentId}/send":{"post":{"tags":["Connector"],"summary":"Send a staged document","description":"Sends a document created with delivery=stage. Call this operation only when the create or detail response contains links.send. The request has no body. Replays are safe: a completed send returns 200; an in-flight send returns 202 with state=sending for polling through document detail or events.","operationId":"connectorSendStagedDocument","x-epostak-required-scopes":["documents:send"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Document ID from the create response, document list, or events."},{"name":"customerRef","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Your stable ERP reference configured for the approved company. Send it exactly once."}],"responses":{"200":{"description":"Send accepted or safe replay of a completed send","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessDocument"},"example":{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","externalId":"invoice-2026-0042","direction":"outbound","type":"invoice","number":"2026-0042","state":"queued","replayed":false,"currency":"EUR","amounts":{"withoutTax":100,"tax":23,"total":123,"due":123},"createdAt":"2026-07-14T10:00:00.000Z","updatedAt":"2026-07-14T10:01:00.000Z","links":{"self":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111?customerRef=erp-acme","evidence":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/evidence?customerRef=erp-acme"}}}}},"202":{"description":"Send is in flight; response state is sending and can be polled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessDocument"},"example":{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","externalId":"invoice-2026-0042","direction":"outbound","type":"invoice","number":"2026-0042","state":"sending","replayed":false,"currency":"EUR","amounts":{"withoutTax":100,"tax":23,"total":123,"due":123},"createdAt":"2026-07-14T10:00:00.000Z","updatedAt":"2026-07-14T10:01:00.000Z","links":{"self":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111?customerRef=erp-acme","evidence":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/evidence?customerRef=erp-acme"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Opaque not found: the document is unavailable or customerRef is blank, repeated, or mismatched","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Customer is not ready to send","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"422":{"description":"Document is not eligible for this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"503":{"description":"Delivery is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}}},"security":[{"integratorBearerAuth":[]}],"x-epostak-visibility":"recommended"}},"/connector/documents/{documentId}/cancel":{"post":{"tags":["Connector"],"summary":"Cancel a staged document","description":"Cancels a staged document before sending starts. Call this operation only when the create or detail response contains links.cancel. The request has no body and repeated cancellation is idempotent.","operationId":"connectorCancelStagedDocument","x-epostak-required-scopes":["documents:send"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Document ID from the create response, document list, or events."},{"name":"customerRef","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Your stable ERP reference configured for the approved company. Send it exactly once."}],"responses":{"200":{"description":"Document cancelled or safe replay of an earlier cancellation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessDocument"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Opaque not found: the document is unavailable or customerRef is blank, repeated, or mismatched","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Document is not eligible for cancellation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"503":{"description":"Cancellation is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}}},"security":[{"integratorBearerAuth":[]}],"x-epostak-visibility":"recommended"}},"/connector/documents/{documentId}/acknowledge":{"post":{"tags":["Connector"],"summary":"Acknowledge local ERP processing","description":"Idempotently records that the ERP processed an inbound document. This is local state only and does not emit a recipient response or change transport state.","operationId":"connectorAcknowledgeDocument","x-epostak-required-scopes":["documents:write"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customerRef","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Your stable ERP reference configured for the approved company. Send it exactly once."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reference"],"properties":{"reference":{"type":"string","maxLength":255}},"additionalProperties":false},"example":{"reference":"ERP-IMPORT-88421"}}}},"responses":{"200":{"description":"Processing recorded or already recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorAcknowledgeResponse"},"example":{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","state":"processed","processedAt":"2026-07-14T10:05:00.000Z","reference":"ERP-IMPORT-88421","idempotent":false}}}},"404":{"description":"Document not found in the permitted customer scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Acknowledgement body exceeds 64 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"},"example":{"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds the 64 KiB limit.","retryable":false,"nextAction":"Send only the local ERP processing reference.","requestId":"req_connector_01J2YQ5B"}}}}},"422":{"description":"Document cannot be acknowledged or request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}}},"security":[{"integratorBearerAuth":[]}],"x-epostak-visibility":"recommended"}},"/connector/events":{"get":{"tags":["Connector"],"summary":"Connector events","description":"Canonical polling-first document event stream for one approved customerRef. customerRef is always at the event root. Persist nextCursor only after committing the returned events locally. Operational connection, intake, mapping, review, and ERP-delivery events use the separate feature-gated /connector/operations/events stream, so this released response contract remains unchanged.","operationId":"connectorListEvents","x-epostak-required-scopes":["documents:read"],"x-epostak-canonical-response-schema":"#/components/schemas/ConnectorBusinessEventsResponse","parameters":[{"name":"customerRef","in":"query","required":true,"schema":{"type":"string"},"description":"Your stable ERP reference configured in the integrator dashboard for a company already approved by ePošťák."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous response."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessEventsResponse"},"example":{"events":[{"id":"evt_01JZ...","customerRef":"erp-acme","documentId":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","type":"document.received","state":"received","occurredAt":"2026-07-15T09:15:00.000Z","data":{"direction":"inbound","type":"invoice","number":"2026-0088","response":null}}],"nextCursor":"eyJ0cyI6IjIwMjYtMDctMTVUMDk6MTU6MDAuMDAwWiIsImlkIjoiZXZ0XzAxSloifQ","hasMore":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API plan required or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"integratorBearerAuth":[]}],"x-epostak-visibility":"recommended"}},"/connector/intakes":{"post":{"tags":["Connector"],"summary":"Accept an ERP export for asynchronous Peppol processing","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nFeature-gated, channel-neutral intake shared by direct API, portal, SFTP, email and Bridge adapters. The source artifact and intake record are stored durably before HTTP 202 is returned. A normal non-UBL source pins the exact active Mapping Spec revision at acceptance; recognized Peppol Billing or Self-Billing UBL can use validated passthrough without a profile. When Epostak-Connection has an explicitly started learning session, the server instead classifies the intake as onboarding_sample, forces stage, accepts only the bounded sample set and never invokes Autopilot or Peppol. Requested send remains stage-only until the selected structured or eligible digital-PDF profile is certified and auto-send is explicitly enabled. Scans and images require human review.","operationId":"connectorCreateIntake","x-epostak-required-scopes":["documents:send","firms:manage"],"parameters":[{"name":"Epostak-Customer-Ref","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Integrator-owned routing reference for an approved company. Required when Epostak-Connection is omitted. It is never read from the source document or AI output."},{"name":"Epostak-Connection","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Trusted connection binding that derives the company, outbound profile and delivery policy. Required when Epostak-Customer-Ref is omitted. If both selectors are sent, they must resolve to the same company."},{"name":"Epostak-Mapping-Profile","in":"header","required":false,"schema":{"type":"string","minLength":2,"maxLength":120,"pattern":"^[a-z0-9][a-z0-9._-]{1,119}$"},"description":"Mapping profile key. An active revision is required for production non-UBL intake. A server-started connection learning session may use its bound draft profile without granting runtime or send authority."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Stable replay key. Reuse with identical bytes and metadata returns the existing intake; reuse with different input returns 409."},{"name":"Epostak-Delivery","in":"header","required":false,"schema":{"type":"string","enum":["stage","send"],"default":"stage"},"description":"Requested delivery. send is honored only when the exact pinned structured profile revision has document-type auto-send permission."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}},"application/xml":{"schema":{"type":"string","format":"binary"}},"text/xml":{"schema":{"type":"string","format":"binary"}},"application/ubl+xml":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}},"multipart/form-data":{"schema":{"type":"object","required":["document"],"properties":{"document":{"type":"string","format":"binary","description":"One PDF, JPEG, PNG or WebP file. OCR inputs always require review."}},"additionalProperties":false}}}},"responses":{"202":{"description":"Artifact and intake accepted durably, or an exact idempotent replay resolved to the existing intake","headers":{"Location":{"required":true,"schema":{"type":"string"},"description":"Relative URL of the accepted intake."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorIntakeResponse"}}}},"400":{"description":"Malformed source or multipart request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden, insufficient scope or customerRef is not approved for the integrator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Universal intake feature is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency-Key was reused with different content or metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"411":{"description":"Content-Length is required for bounded multipart parsing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Production structured input exceeds 10 MiB, an onboarding structured sample exceeds 2 MiB, or OCR input exceeds 20 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Unsupported or MIME-spoofed source content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Metadata, mapping profile or source structure is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-visibility":"experimental","security":[{"integratorBearerAuth":[]}],"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/intakes/{intakeId}":{"get":{"tags":["Connector"],"summary":"Get asynchronous intake status","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nReturns the tenant-isolated status of one accepted intake, including its pinned profile revision, review requirement, effective delivery and safe failure code. Raw source or extracted accounting values are never returned.","operationId":"connectorGetIntake","x-epostak-required-scopes":["documents:send","firms:manage"],"parameters":[{"name":"intakeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current intake state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorIntakeResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden or insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Intake was not found or the feature is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-visibility":"experimental","security":[{"integratorBearerAuth":[]}],"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/mapper":{"post":{"tags":["Connector — Advanced"],"summary":"Advanced: Connector Mapper","description":"Advanced mapping input for ERPs that cannot emit the recommended business JSON directly. The default execute=preview returns the established launch checklist plus canonical document, submission, and mapping fields. Existing clients may continue to use execute=stage or execute=send with confirmed=true; new integrations should prefer submitting the returned business document to POST /connector/documents. Omitting mappingRevision preserves the established Mapper behavior exactly. Mapping Spec v2 is an explicit opt-in: shadow keeps the established mapping authoritative and returns a value-free comparison whose candidate evaluation has no side effects, while apply requires the exact approved active revision and fails closed when that revision cannot produce a valid canonical document. The established execute setting still controls whether the authoritative result is previewed, staged or sent.","operationId":"connectorMapper","x-epostak-required-scopes":["documents:send","firms:manage"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"templateKey":{"type":"string","description":"Saved mapping template key from Connector Mapper Studio."},"sourceType":{"type":"string","enum":["json","csv","xml","pdf_text","text"],"default":"json"},"sourceText":{"type":"string","description":"Raw CSV, XML, PDF text or plain ERP export."},"sourceJson":{"type":"object","additionalProperties":true,"description":"Raw ERP JSON export when sourceType=json."},"customerRef":{"type":"string","description":"Optional override for the Connector Mailbox customerRef stored in the template defaults."},"mappingRevision":{"$ref":"#/components/schemas/ConnectorMapperRevisionSelector"},"execute":{"type":"string","enum":["preview","stage","send"],"default":"preview","description":"Established execution mode. Preview is recommended for new integrations; stage and send remain supported for compatibility."},"confirmed":{"type":"boolean","description":"Required for send and for uncertain mapping confirmations."},"confirmAll":{"type":"boolean","description":"Compatibility alias for confirmed."},"fieldMap":{"type":"object","additionalProperties":true,"description":"Optional per-call field map override."},"defaults":{"type":"object","additionalProperties":true,"description":"Optional per-call default values such as currency or customerRef."}},"additionalProperties":true},"example":{"templateKey":"pohoda-csv-v1","sourceType":"csv","execute":"preview","sourceText":"Doklad,DIC,Partner,Popis,Pocet,CenaBezDph,Sadzba\\nFA-2026-001,2120123456,Odberatel s.r.o.,Servis,1,100,23"}}}},"responses":{"200":{"description":"Mapping preview or ready launch checklist, with canonical document fields added without removing the established response fields","content":{"application/json":{"schema":{"type":"object","properties":{"mappingRevision":{"$ref":"#/components/schemas/ConnectorMapperRevisionMetadata"},"shadow":{"$ref":"#/components/schemas/ConnectorMapperShadowMetadata"}},"additionalProperties":true},"example":{"customerRef":"erp-acme","externalId":"invoice-2026-0042","type":"invoice","number":"2026-0042","recipient":{"country":"SK","taxId":"2120123456"},"currency":"EUR","lines":[{"description":"Servis","quantity":1,"unitPrice":100,"vatRate":23}]}}}},"201":{"description":"Mapped payload was staged or sent through Connector Autopilot","content":{"application/json":{"schema":{"type":"object","properties":{"mappingRevision":{"$ref":"#/components/schemas/ConnectorMapperRevisionMetadata"},"shadow":{"$ref":"#/components/schemas/ConnectorMapperShadowMetadata"}},"additionalProperties":true}}}},"404":{"description":"Mapping template was not found for the integrator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Requested send was not performed, for example Autopilot returned a replayed staged run","content":{"application/json":{"schema":{"type":"object","properties":{"mappingRevision":{"$ref":"#/components/schemas/ConnectorMapperRevisionMetadata"},"shadow":{"$ref":"#/components/schemas/ConnectorMapperShadowMetadata"}},"additionalProperties":true}}}},"413":{"description":"Request body is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Required mapping fields are missing or confirmations are required","content":{"application/json":{"schema":{"type":"object","properties":{"mappingRevision":{"$ref":"#/components/schemas/ConnectorMapperRevisionMetadata"}},"additionalProperties":true}}}}},"x-epostak-visibility":"advanced","security":[{"integratorBearerAuth":[]}]}},"/connector/mapper/ocr":{"post":{"tags":["Connector — Advanced"],"summary":"Advanced: map a PDF or image with OCR","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nFeature-gated OCR preview for an explicitly selected approved Mapping Spec v2 revision. External provider processing must be explicitly approved for the environment. The upload is size-bounded, MIME-sniffed and malware-scanned before one OCR extraction. OCR never stages or sends directly in this version: review the returned canonical draft and submit the confirmed document through the normal Connector flow. Uploading the binary again starts a new extraction. This endpoint does not alter the established /connector/mapper JSON contract.","operationId":"connectorMapperOcr","x-epostak-required-scopes":["documents:send","firms:manage"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["document","templateKey","revisionId","customerRef"],"properties":{"document":{"type":"string","format":"binary","description":"PDF, JPEG, PNG or WebP document, at most 20 MB."},"templateKey":{"type":"string","maxLength":120,"description":"OCR Mapper profile key."},"revisionId":{"type":"string","format":"uuid","description":"Exact approved active Mapping Spec v2 revision."},"customerRef":{"type":"string","maxLength":128,"description":"Request-authoritative Connector customer routing reference."},"execute":{"type":"string","enum":["preview"],"default":"preview"},"confirmed":{"type":"string","enum":["false"],"default":"false","description":"OCR requires a separate human review; direct confirmation is not accepted."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OCR mapping preview or idempotent execution result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Malformed multipart request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden or insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"OCR feature, mapping profile or revision is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"411":{"description":"Content-Length is required so the multipart limit can be enforced before parsing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Multipart body or document exceeds the limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Unsupported or spoofed document content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unsafe, unextractable or invalid mapped document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"OCR rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Malware scanner, OCR provider or delivery dependency is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-visibility":"experimental","security":[{"integratorBearerAuth":[]}],"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/documents/{documentId}/ubl":{"get":{"tags":["Connector — Advanced"],"summary":"Advanced: original UBL document","description":"Advanced technical endpoint for downloading the original UBL/XML for ERP import or archiving. Use /connector/documents/{documentId} for the normal business document state.","operationId":"connectorGetDocumentUbl","x-epostak-required-scopes":["documents:read"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customerRef","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Your stable ERP reference configured for the approved company. Send it exactly once."}],"responses":{"200":{"description":"UBL/XML document","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-visibility":"advanced","security":[{"integratorBearerAuth":[]}]}},"/connector/documents/{documentId}/evidence":{"get":{"tags":["Connector — Advanced"],"summary":"Advanced: technical document evidence","description":"Advanced support and audit view with structured technical evidence. The normal ERP flow should use the business state from document detail.","operationId":"connectorGetDocumentEvidence","x-epostak-required-scopes":["documents:read"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customerRef","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Your stable ERP reference configured for the approved company. Send it exactly once."}],"responses":{"200":{"description":"Structured evidence","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-visibility":"advanced","security":[{"integratorBearerAuth":[]}]}},"/connector/documents/{documentId}/support-packet":{"get":{"tags":["Connector — Advanced"],"summary":"Advanced: support packet","description":"Advanced evidence manifest for support, audit, and disputes. It contains no internal storage paths and is not required in the normal send/list/events flow.","operationId":"connectorGetDocumentSupportPacket","x-epostak-required-scopes":["documents:read"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"customerRef","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Your stable ERP reference configured for the approved company. Send it exactly once."}],"responses":{"200":{"description":"Support packet manifest","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-visibility":"advanced","security":[{"integratorBearerAuth":[]}]}},"/connector/documents/{documentId}/respond":{"post":{"tags":["Connector"],"summary":"Send an invoice business response","description":"Sends a business response for an inbound invoice to the counterparty. This is different from acknowledge: acknowledge records the local ERP import only, while respond sends a Peppol Invoice Response behind this business-language contract. The integrator does not call the internal ePošťák Box or an Enterprise endpoint. The strict JSON body is limited to 32 KB and note to 500 characters. Repeating an already stored identical status is a safe idempotent replay.","operationId":"connectorRespondToDocument","security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["documents:write"],"x-epostak-visibility":"recommended","parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Inbound invoice ID."},{"name":"customerRef","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Your stable ERP reference configured for the approved company. Send it exactly once."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorInvoiceResponseRequest"},"example":{"status":"under_query","note":"Please add the purchase order number."}}}},"responses":{"200":{"description":"Response sent, or a safe replay of an already stored identical status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorInvoiceResponseResult"},"example":{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","response":{"status":"under_query","direction":"sent","delivery":"sent","respondedAt":"2026-07-15T10:05:00.000Z"},"idempotent":false}}}},"202":{"description":"Response accepted and queued for delivery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorInvoiceResponseResult"},"example":{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","response":{"status":"accepted","direction":"sent","delivery":"queued","respondedAt":"2026-07-15T10:05:00.000Z"},"idempotent":false}}}},"400":{"description":"Connector business error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"401":{"description":"Connector business error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"403":{"description":"Connector business error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"404":{"description":"Connector business error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"409":{"description":"Connector business error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"413":{"description":"Request body exceeds 32 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"422":{"description":"Connector business error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"429":{"description":"Connector business error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}},"503":{"description":"Connector business error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBusinessErrorResponse"}}}}}}},"/connector/webhook":{"get":{"tags":["Connector"],"summary":"Get the integrator webhook","description":"Returns the single Connector webhook configuration for this integrator. No X-Firm-Id is used. webhook is null until configured.","operationId":"connectorGetWebhook","security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["webhooks:read"],"x-epostak-visibility":"recommended","responses":{"200":{"description":"Current configuration or webhook=null.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["webhook"],"properties":{"webhook":{"type":"object","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConnectorWebhook"}]}}},"examples":{"configured":{"value":{"webhook":{"id":"wh_01JZ...","url":"https://erp.example.com/epostak/events","events":["document.received","document.delivered","document.failed"],"active":true,"failedAttempts":0,"createdAt":"2026-07-15T09:00:00.000Z","updatedAt":"2026-07-15T09:10:00.000Z"}}},"notConfigured":{"value":{"webhook":null}}}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Connector"],"summary":"Create or update the integrator webhook","description":"Configures one global webhook for the integrator. The JSON body is limited to 32 KB. Omitting events preserves the backward-compatible default of the seven document events; customer lifecycle events require explicit opt-in. Creation returns the HMAC secret once; an update keeps the existing secret. No X-Firm-Id is used.","operationId":"connectorPutWebhook","security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["webhooks:write"],"x-epostak-visibility":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorWebhookUpsertRequest"},"example":{"url":"https://erp.example.com/epostak/events","events":["document.received","document.delivered","document.failed"]}}}},"callbacks":{"connectorEvent":{"{$request.body#/url}":{"post":{"summary":"Connector business event push","description":"Document events use the same canonical item returned by GET /connector/events. Opt-in customer lifecycle events are webhook-only account signals. Verify HMAC-SHA256 over timestamp + '.' + the exact raw body, deduplicate by X-Webhook-Event-Id, and return a 2xx response only after durable acceptance. Return 503 for transient receiver failures: network errors and 408, 425, 429, 502, 503, and 504 are delivered through 10 total attempts (1 initial attempt plus 9 retries); 500 is terminal. customerRef identifies the approved company; migration codes, Peppol transport fields, and user identities are never exposed.","parameters":[{"name":"X-Webhook-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix timestamp in seconds included in the signature input."},{"name":"X-Webhook-Signature","in":"header","required":true,"schema":{"type":"string","example":"sha256=ab12..."},"description":"Wire format: sha256=<64 lowercase hex characters>. Compute HMAC-SHA256 over timestamp + '.' + the exact raw request body using the returned secret unchanged as UTF-8 text, never hex-decoded. Test deliveries use the same current subscription secret as live deliveries."},{"name":"X-Webhook-Event-Id","in":"header","required":true,"schema":{"type":"string"},"description":"Stable event deduplication key, unchanged across delivery retries."},{"name":"X-Webhook-Id","in":"header","required":true,"schema":{"type":"string"},"description":"Identifier of this webhook delivery record."},{"name":"X-Webhook-Event","in":"header","required":true,"schema":{"type":"string","enum":["document.queued","document.delivered","document.received","document.processed","document.needs_attention","document.failed","document.cancelled","customer.active","customer.integration_detachment_scheduled","customer.integration_detachment_cancelled","customer.integration_detached","customer.provider_change_requested","customer.provider_change_cancelled","customer.provider_changed","customer.deactivated","connection.created","connection.updated","connection.disabled","connection.credential_rotated","connection.test_passed","connection.test_failed","connection.learning_started","connection.learning_stopped","connection.adapter_quarantined","intake.received","intake.sample_received","intake.scanning","intake.ocr_extracted","intake.transforming","intake.validating","intake.needs_review","intake.staged","intake.sending","intake.sent","intake.delivered","intake.malware_rejected","intake.mapping_failed","intake.validation_failed","intake.retry_later","intake.failed_internal","intake.cancelled","intake.sampled","intake.learning_corpus_updated","intake.learning_candidate_created","mapping.profile_created","mapping.candidate_created","mapping.revision_approved","mapping.revision_activated","mapping.revision_rolled_back","mapping.technical_certified","mapping.probation_reset","mapping.automation_enabled","mapping.pdf_probation_started","mapping.pdf_probation_ready","mapping.pdf_automation_enabled","mapping.pdf_suspended","review.opened","review.claimed","review.released","review.resolved","review.cancelled","delivery.received","delivery.transforming","delivery.validating","delivery.needs_review","delivery.staged","delivery.ready","delivery.delivering","delivery.delivered","delivery.acknowledged","delivery.retry_later","delivery.failed","delivery.cancelled"]}},{"name":"X-Webhook-Attempt","in":"header","required":true,"schema":{"type":"integer","minimum":1}},{"name":"X-Webhook-Max-Attempts","in":"header","required":true,"schema":{"type":"integer","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorWebhookCallbackEvent"},"example":{"id":"evt_01JZ...","customerRef":"erp-acme","documentId":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","type":"document.received","state":"received","occurredAt":"2026-07-15T09:15:00.000Z","data":{"direction":"inbound","type":"invoice","number":"2026-0088","response":null}}}}},"responses":{"200":{"description":"Event accepted."},"204":{"description":"Event accepted with no response body."}}}}}},"responses":{"200":{"description":"Webhook updated; the existing signing secret remains active.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["webhook"],"properties":{"webhook":{"$ref":"#/components/schemas/ConnectorWebhook"}}},"example":{"webhook":{"id":"wh_01JZ...","url":"https://erp.example.com/epostak/events","events":["document.received","document.delivered","document.failed"],"active":true,"failedAttempts":0,"createdAt":"2026-07-15T09:00:00.000Z","updatedAt":"2026-07-15T09:10:00.000Z"}}}}},"201":{"description":"Webhook created. Store the signing secret now; it is shown only once.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["webhook","secret"],"properties":{"webhook":{"$ref":"#/components/schemas/ConnectorWebhook"},"secret":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[a-f0-9]{64}$","readOnly":true}}},"example":{"webhook":{"id":"wh_01JZ...","url":"https://erp.example.com/epostak/events","events":["document.received","document.delivered","document.failed"],"active":true,"failedAttempts":0,"createdAt":"2026-07-15T09:00:00.000Z","updatedAt":"2026-07-15T09:10:00.000Z"},"secret":"7c4a8d09ca3762af61e59520943dc26494f8941b7a8331369f7f16f2e19f6c21"}}}},"400":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request body exceeds 32 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Connector"],"summary":"Delete the integrator webhook","description":"Stops new push deliveries and removes the Connector webhook. Polling through GET /connector/events remains available for reconciliation. No X-Firm-Id is used.","operationId":"connectorDeleteWebhook","security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["webhooks:write"],"x-epostak-visibility":"recommended","responses":{"204":{"description":"Webhook deleted."},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/connector/webhook/rotate-secret":{"post":{"tags":["Connector"],"summary":"Rotate the webhook signing secret","description":"Replaces the HMAC signing secret and returns the new secret once. No X-Firm-Id is used.","operationId":"connectorRotateWebhookSecret","security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["webhooks:write"],"x-epostak-visibility":"recommended","responses":{"200":{"description":"New signing secret, shown once.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","secret","message"],"properties":{"id":{"type":"string","description":"Connector webhook identifier."},"secret":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[a-f0-9]{64}$","readOnly":true},"message":{"type":"string","description":"Reminder that the one-time secret must be stored now."}}},"example":{"id":"wh_01JZ...","secret":"7c4a8d09ca3762af61e59520943dc26494f8941b7a8331369f7f16f2e19f6c21","message":"Save this secret now. It will not be shown again."}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/connector/webhook/test":{"post":{"tags":["Connector"],"summary":"Queue a signed test event","description":"Queues one signed test event for an approved customerRef. The event has the same canonical business shape as polling and production pushes, plus test=true. No X-Firm-Id is used.","operationId":"connectorTestWebhook","security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["webhooks:write"],"x-epostak-visibility":"recommended","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["customerRef"],"properties":{"customerRef":{"type":"string","minLength":1,"description":"Integrator-configured reference for an approved company."},"event":{"type":"string","enum":["document.queued","document.delivered","document.received","document.processed","document.needs_attention","document.failed","document.cancelled","customer.active","customer.integration_detachment_scheduled","customer.integration_detachment_cancelled","customer.integration_detached","customer.provider_change_requested","customer.provider_change_cancelled","customer.provider_changed","customer.deactivated"],"description":"Optional business event; defaults to document.queued."},"scenario":{"type":"string","enum":["success","deduplication","retry_503","rate_limit_429","terminal_422","timeout","signature"],"description":"Optional deterministic receiver scenario."}}},"example":{"customerRef":"erp-acme"}}}},"responses":{"202":{"description":"Test delivery queued.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["deliveryId","status","event"],"properties":{"deliveryId":{"type":"string"},"status":{"type":"string","enum":["queued"]},"event":{"$ref":"#/components/schemas/ConnectorWebhookTestEvent"}}},"example":{"deliveryId":"whd_01JZ...","status":"queued","event":{"id":"evt_01JZ...","customerRef":"erp-acme","documentId":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","type":"document.received","state":"received","occurredAt":"2026-07-15T09:15:00.000Z","data":{"direction":"inbound","type":"invoice","number":"2026-0088","response":null},"test":true}}}}},"400":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/connector/webhook/deliveries":{"get":{"tags":["Connector"],"summary":"List webhook delivery history","description":"Cursor-paged push delivery diagnostics across the integrator's customerRef values. Use GET /connector/events as the business reconciliation checkpoint. No X-Firm-Id is used.","operationId":"connectorListWebhookDeliveries","security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["webhooks:read"],"x-epostak-visibility":"recommended","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous response."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["PENDING","SUCCESS","FAILED","RETRYING"]},"description":"Optional delivery-status filter."},{"name":"customerRef","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Exact approved customerRef."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["document.queued","document.delivered","document.received","document.processed","document.needs_attention","document.failed","document.cancelled","customer.active","customer.integration_detachment_scheduled","customer.integration_detachment_cancelled","customer.integration_detached","customer.provider_change_requested","customer.provider_change_cancelled","customer.provider_changed","customer.deactivated"]}},{"name":"test","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"The from/to range may not exceed 90 days."}],"responses":{"200":{"description":"Webhook delivery history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorWebhookDeliveries"},"example":{"deliveries":[{"id":"whd_01JZ...","webhookId":"wh_01JZ...","eventId":"evt_01JZ...","customerRef":"erp-acme","type":"document.received","status":"SUCCESS","attempts":1,"responseStatus":204,"responseTimeMs":83,"lastAttemptAt":"2026-07-15T09:16:00.000Z","nextRetryAt":null,"createdAt":"2026-07-15T09:15:59.000Z"}],"nextCursor":"eyJpZCI6IndoZF8wMUpaLi4uIn0","hasMore":false}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/connector/webhook/deliveries/{deliveryId}":{"get":{"tags":["Connector"],"summary":"Inspect one webhook delivery","description":"Returns the authorized business event, exact signed request body when available, safe endpoint origin/path, diagnosis and every real delivery execution. Historical rows never fabricate missing attempts.","operationId":"connectorGetWebhookDelivery","security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["webhooks:read"],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Authorized delivery evidence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorWebhookDeliveryDetail"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/connector/webhook/deliveries/{deliveryId}/replay":{"post":{"tags":["Connector"],"summary":"Replay the exact Connector event","description":"Durably creates a new delivery while preserving the original event ID, customerRef, business payload and exact raw request body. A successful real delivery requires explicit confirmation so the receiver can deduplicate the unchanged event ID.","operationId":"connectorReplayWebhookDelivery","security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["webhooks:write"],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"confirmSuccessfulReplay":{"type":"boolean","default":false}}},"example":{}}}},"responses":{"200":{"description":"Idempotent repeat of an accepted replay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorWebhookReplayResult"}}}},"202":{"description":"Replay durably accepted; pending publication recovery remains automatic.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorWebhookReplayResult"}}}},"400":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/connector/webhook/test-suite":{"post":{"tags":["Connector"],"summary":"Run receiver diagnostics","description":"Runs selected scenarios through the real signing, authorization, queue, endpoint-safety and delivery path with three test attempts at 0, 5 and 30 seconds. Test failures never affect the production circuit breaker.","operationId":"connectorRunWebhookTestSuite","security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["webhooks:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorWebhookTestSuiteRequest"},"example":{"customerRef":"erp-acme","event":"document.received","scenarios":["success","deduplication","retry_503","rate_limit_429","terminal_422","timeout","signature"]}}}},"responses":{"200":{"description":"Idempotent repeat of the same run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorWebhookTestSuiteAccepted"}}}},"202":{"description":"Diagnostic run durably accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorWebhookTestSuiteAccepted"}}}},"400":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/connector/webhook/test-suite/{testRunId}":{"get":{"tags":["Connector"],"summary":"Read receiver diagnostic progress","description":"Returns scenario progress. Replay identity intentionally pauses with REPLAY_TEST_DELIVERY after its first success; replay the supplied delivery through the normal replay endpoint. The suite proves stable event ID/body and signed-request acceptance, but cannot observe the receiver's internal deduplication or HMAC calculation.","operationId":"connectorGetWebhookTestSuite","security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["webhooks:read"],"parameters":[{"name":"testRunId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Diagnostic run progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorWebhookTestSuiteStatus"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/connector/connections":{"get":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["firms:manage"],"x-epostak-visibility":"experimental","summary":"List Connector connections","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nLists tenant-isolated adapter bindings. Credentials and channel secrets are never returned.","operationId":"connectorListConnections","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","testing","active","needs_attention","disabled"]}}],"responses":{"200":{"description":"Connection list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorConnectionList"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"},"post":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["firms:manage"],"x-epostak-visibility":"experimental","summary":"Create a Connector connection","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nBinds one approved company and Connector mailbox to a channel. Company identity comes only from customerRef during this authenticated setup; uploaded files and AI output cannot change it. New connections start in draft, staged delivery, and integrator-owned review. Managed Exceptions is not currently available.","operationId":"connectorCreateConnection","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorConnectionCreate"}}}},"responses":{"201":{"description":"Connection state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorConnectionEnvelope"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/connections/{connectionId}":{"get":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["firms:manage"],"x-epostak-visibility":"experimental","summary":"Get a Connector connection","operationId":"connectorGetConnection","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Connection state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorConnectionEnvelope"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live."},"patch":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["firms:manage"],"x-epostak-visibility":"experimental","summary":"Update a Connector connection","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nUpdates configuration additively. Any readiness-affecting change returns the connection to draft so it must be tested again. Review ownership can remain integrator-owned only; preserved historical non-integrator ownership cannot be changed through this API.","operationId":"connectorPatchConnection","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorConnectionPatch"}}}},"responses":{"200":{"description":"Connection state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorConnectionEnvelope"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/connections/{connectionId}/disable":{"post":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["firms:manage"],"x-epostak-visibility":"experimental","summary":"Disable a Connector connection","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nIdempotently disables the binding and revokes its connection credential and Bridge device tokens.","operationId":"connectorDisableConnection","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Connection state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorConnectionEnvelope"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/connections/{connectionId}/credentials/rotate":{"post":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["firms:manage"],"x-epostak-visibility":"experimental","summary":"Rotate a connection credential","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nRotates an SFTP password or unguessable email intake address and returns the new value once. Rotation returns the connection to draft until it passes its channel test again.","operationId":"connectorRotateConnectionCredential","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Credential rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorConnectionCredentialResult"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/connections/{connectionId}/test":{"post":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["firms:manage"],"x-epostak-visibility":"experimental","summary":"Test a Connector connection","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nChecks the channel without sending a Peppol document. Transport and mapping readiness are returned separately so a working Bridge, SFTP, API, email or portal connection can start bounded sample collection before a mapping revision is active.","operationId":"connectorTestConnection","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Connection test completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorConnectionTestResult"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/connections/{connectionId}/learning/start":{"post":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["firms:manage"],"x-epostak-visibility":"experimental","summary":"Start bounded outbound sample collection","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nStarts or returns the active learning session for a transport-tested outbound connection with a bound mapping profile. While the session is collecting, every intake through this connection is forced to onboarding_sample and stage; no document can reach Autopilot or Peppol. The session accepts 3–10 unique samples and expires automatically.","operationId":"connectorStartConnectionLearning","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorLearningSessionStart"}}}},"responses":{"200":{"description":"The already active session was returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorLearningSessionEnvelope"}}}},"201":{"description":"Sample collection started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorLearningSessionEnvelope"}}}},"400":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/connections/{connectionId}/learning/stop":{"post":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["firms:manage"],"x-epostak-visibility":"experimental","summary":"Stop outbound sample collection","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nCloses the active learning session without deleting accepted samples. Later connection intakes return to the normal pinned-revision rules.","operationId":"connectorStopConnectionLearning","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Sample collection stopped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorLearningSessionEnvelope"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/connections/{connectionId}/bridge-devices":{"get":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["firms:manage"],"x-epostak-visibility":"experimental","summary":"List Bridge devices","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nLists token-free device state for one Bridge connection.","operationId":"connectorListBridgeDevices","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Bridge device list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBridgeDeviceList"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"},"post":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["firms:manage"],"x-epostak-visibility":"experimental","summary":"Create a Bridge pairing","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nCreates one short-lived pairing code for the connection. Revoke the existing live device before replacing it.","operationId":"connectorCreateBridgeDevice","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBridgeDeviceCreate"}}}},"responses":{"201":{"description":"Pairing created; store or enter the code now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBridgeDeviceCreateResult"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/connections/{connectionId}/bridge-devices/{deviceId}/revoke":{"post":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["firms:manage"],"x-epostak-visibility":"experimental","summary":"Revoke a Bridge device","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nImmediately revokes the device token while preserving its audit record.","operationId":"connectorRevokeBridgeDevice","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Bridge device revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBridgeDeviceEnvelope"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/documents/{documentId}/export":{"post":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-visibility":"experimental","summary":"Create a pinned ERP export","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nCreates an idempotent asynchronous export for an inbound Peppol invoice. The active inbound mapping revision and connection policy are pinned when the job is accepted. The endpoint is hidden unless the server-side inbound mapping capability is enabled for the approved DEV integrator.","operationId":"connectorCreateDocumentExport","x-epostak-required-scopes":["documents:read"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Inbound Peppol invoice ID."},{"name":"Epostak-Connection","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"Trusted inbound or bidirectional connection that selects the company, mapping profile, and delivery policy."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255}},{"name":"Epostak-Customer-Ref","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Optional compatibility assertion. When present, it must match the company bound to Epostak-Connection."}],"responses":{"202":{"description":"Pinned ERP delivery state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorDeliveryEnvelope"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/deliveries/{deliveryJobId}":{"get":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-visibility":"experimental","summary":"Get an ERP delivery","operationId":"connectorGetDelivery","x-epostak-required-scopes":["documents:read"],"parameters":[{"name":"deliveryJobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Pinned ERP delivery state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorDeliveryEnvelope"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live."}},"/connector/deliveries/{deliveryJobId}/artifact":{"get":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-visibility":"experimental","summary":"Download a generated ERP artifact","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nReturns the immutable artifact generated by the exact revision pinned on the delivery job. Its Content-Type and filename describe the configured ERP format.","operationId":"connectorDownloadDeliveryArtifact","x-epostak-required-scopes":["documents:read"],"parameters":[{"name":"deliveryJobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Immutable ERP artifact.","headers":{"Content-Disposition":{"schema":{"type":"string"},"description":"Attachment filename selected by the pinned profile."},"X-Content-Type-Options":{"schema":{"type":"string","enum":["nosniff"]}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/deliveries/{deliveryJobId}/acknowledge":{"post":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-visibility":"experimental","summary":"Acknowledge an ERP import","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nRecords durable ERP acceptance. Identical retries are idempotent; a different reference conflicts. Acknowledged staged imports advance the probation counter of the pinned inbound profile revision.","operationId":"connectorAcknowledgeDelivery","x-epostak-required-scopes":["documents:write"],"parameters":[{"name":"deliveryJobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorDeliveryAcknowledgment"}}}},"responses":{"200":{"description":"Pinned ERP delivery state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorDeliveryEnvelope"}}}},"400":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/deliveries/{deliveryJobId}/release":{"post":{"tags":["Connector"],"security":[{"integratorBearerAuth":[]}],"x-epostak-visibility":"experimental","summary":"Release a staged ERP delivery","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nExplicitly releases a reviewed staged artifact to the configured inbound ERP adapter. The pinned mapping revision and generated artifact remain unchanged. Identical retries after release are idempotent; expectedUpdatedAt prevents acting on a stale staged view.","operationId":"connectorReleaseDelivery","x-epostak-required-scopes":["documents:write"],"parameters":[{"name":"deliveryJobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorDeliveryRelease"}}}},"responses":{"200":{"description":"Pinned ERP delivery state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorDeliveryEnvelope"}}}},"400":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}},"/connector/operations/events":{"get":{"tags":["Connector"],"summary":"List Connector operational events","description":"Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.\n\nFeature-gated polling stream for connection, intake, mapping, review, and ERP-delivery lifecycle events. It has an independent exact cursor and does not change the released document event stream. Persist nextCursor only after committing the returned events locally.","operationId":"connectorListOperationalEvents","security":[{"integratorBearerAuth":[]}],"x-epostak-required-scopes":["documents:read"],"x-epostak-visibility":"experimental","parameters":[{"name":"customerRef","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Your stable ERP reference configured for the approved company."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Opaque cursor returned by this operational stream. Do not reuse a document-events cursor."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"Operational lifecycle page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorOperationalEventsResponse"}}}},"400":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Request rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-epostak-availability":"private-preview","x-epostak-preview-environment":"dev"}}},"components":{"schemas":{"JwtTokenRequest":{"type":"object","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string","description":"The client_id displayed with the assigned integrator credential; it is separate from the sk_int_* secret."},"client_secret":{"type":"string","description":"The full compatible sk_int_* integrator secret. Keep it server-side."},"scope":{"type":"string","description":"Optional space-separated subset of the credential's effective allowed scopes. Omitting it returns that allowed set. Unknown names and known but ungranted scopes are rejected."},"api_interface":{"type":"string","enum":["connector"],"description":"Optional interface selector. Send `connector` for Connector integrations. Omitting it preserves the legacy enterprise_api default on /api/v1/auth/token."}}},"JwtTokenResponse":{"type":"object","required":["access_token","token_type","expires_in","refresh_token","scope"],"properties":{"access_token":{"type":"string","description":"Short-lived JWT (RS256, 15 min TTL). Use as `Authorization: Bearer <token>` on all `/api/v1/*` endpoints."},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"integer","example":900},"refresh_token":{"type":"string","description":"Refresh token (30 day TTL). Single-use — rotated on each `/auth/renew` call."},"scope":{"type":"string","example":"documents:send documents:read"}}},"PeppolErrorResponse":{"type":"object","description":"Error envelope used by the JWT auth endpoints (`/auth/token`, `/auth/renew`, `/auth/revoke`) and any `/sapi/v1/*` endpoint. Different from `ErrorResponse` — designed for Peppol Access Point error semantics with retry hints.","required":["error"],"properties":{"error":{"type":"object","required":["category","code","message","retryable","correlation_id"],"properties":{"category":{"type":"string","enum":["AUTH","VALIDATION","PROCESSING","TEMPORARY","PERMANENT"]},"code":{"type":"string","example":"SAPI-AUTH-001","description":"Stable machine-readable code (e.g. `SAPI-AUTH-001` invalid creds, `SAPI-AUTH-008` scope denied, `SAPI-AUTH-099` internal)."},"message":{"type":"string","example":"Invalid client credentials"},"retryable":{"type":"boolean","description":"True for 5xx/429 — caller may retry with backoff."},"correlation_id":{"type":"string","format":"uuid"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"issue":{"type":"string"},"value":{"type":"string"}}}}}}}},"ConnectorBusinessDocumentRequest":{"type":"object","required":["customerRef","externalId","number","recipient","lines"],"properties":{"customerRef":{"type":"string","maxLength":255,"description":"Your stable ERP reference configured in the integrator dashboard for a company already approved by ePošťák. It is not a company-discovery or provisioning identifier."},"externalId":{"type":"string","maxLength":255},"delivery":{"type":"string","enum":["send","stage"],"default":"send"},"type":{"type":"string","enum":["invoice","credit_note","debit_note","prepayment_invoice","correction","self_billing_invoice","self_billing_credit_note"],"default":"invoice"},"number":{"type":"string","maxLength":255},"precedingDocumentNumber":{"type":"string","description":"Original invoice number. Required for credit_note, self_billing_credit_note, correction (384) and debit_note (383).","maxLength":255},"recipient":{"$ref":"#/components/schemas/ConnectorBusinessRecipientRequest"},"issueDate":{"type":"string","format":"date"},"dueDate":{"type":"string","format":"date"},"taxPointDate":{"type":"string","format":"date","description":"VAT tax point date (BT-7). Kept separate from the actual delivery date."},"deliveryDate":{"type":"string","format":"date","description":"Actual delivery date for the whole document (BT-72)."},"documentDiscountPercent":{"type":"number","minimum":0,"maximum":100,"description":"Document-level discount percentage represented as a Peppol BG-20 allowance. This is additional to any lines[].discount."},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"EUR"},"note":{"type":"string","maxLength":5000},"iban":{"type":"string","maxLength":64},"paymentMethod":{"type":"string"},"paymentTerms":{"type":"string","maxLength":500,"description":"Peppol BT-20 textual payment terms."},"variableSymbol":{"type":"string"},"buyerReference":{"type":"string","description":"Peppol BT-10 internal buyer routing reference, up to 100 characters. A document must contain buyerReference or orderReference.","minLength":1,"maxLength":100,"pattern":"\\S"},"orderReference":{"type":"string","description":"Peppol BT-13 purchase-order reference, up to 100 characters. A document must contain orderReference or buyerReference.","minLength":1,"maxLength":100,"pattern":"\\S"},"prepaidAmount":{"type":"number","minimum":0},"prepayments":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/ConnectorBusinessPrepayment"}},"lines":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#/components/schemas/ConnectorBusinessLine"}},"attachments":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/ConnectorBusinessAttachment"}}},"additionalProperties":false,"anyOf":[{"required":["buyerReference"]},{"required":["orderReference"]}]},"ConnectorBusinessDocument":{"type":"object","required":["id","customerRef","direction","type","state","response"],"properties":{"id":{"type":"string","format":"uuid"},"customerRef":{"type":"string"},"externalId":{"type":"string","nullable":true},"direction":{"type":"string","enum":["inbound","outbound"]},"type":{"type":"string","enum":["invoice","credit_note","self_billing_invoice","self_billing_credit_note"],"description":"Backward-compatible billing family. Debit notes (383) and prepayment invoices (386) use invoice; businessType carries their exact subtype."},"number":{"type":"string","nullable":true},"state":{"$ref":"#/components/schemas/ConnectorBusinessState"},"replayed":{"type":"boolean"},"currency":{"type":"string","nullable":true},"amounts":{"type":"object","properties":{"withoutTax":{"type":"number","nullable":true},"tax":{"type":"number","nullable":true},"total":{"type":"number","nullable":true},"due":{"type":"number","nullable":true}},"additionalProperties":false},"sender":{"$ref":"#/components/schemas/ConnectorBusinessParty"},"recipient":{"$ref":"#/components/schemas/ConnectorBusinessParty"},"issueDate":{"type":"string","format":"date","nullable":true},"dueDate":{"type":"string","format":"date","nullable":true},"taxPointDate":{"type":"string","format":"date","nullable":true,"description":"VAT tax point date (Peppol BT-7), when different from the issue date."},"deliveryDate":{"type":"string","format":"date","nullable":true,"description":"Document-level actual delivery date (Peppol BT-72)."},"documentDiscountPercent":{"type":"number","minimum":0,"maximum":100,"nullable":true,"description":"Document-level percentage discount applied proportionally across VAT categories."},"processedAt":{"type":"string","format":"date-time","nullable":true},"processedReference":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true},"links":{"type":"object","properties":{"self":{"type":"string"},"evidence":{"type":"string"},"acknowledge":{"type":"string"},"send":{"type":"string","description":"Present only when the staged document can be sent."},"cancel":{"type":"string","description":"Present only when the staged document can be cancelled before sending starts."}},"additionalProperties":false,"description":"Action links are capability-driven. send and cancel are present only while a staged document is eligible for those actions; acknowledge is present only for an unprocessed inbound document."},"businessType":{"type":"string","x-extensible-enum":["debit_note","prepayment_invoice","correction"],"description":"Exact business subtype for UBL 383, 384 or 386. Present only for these subtypes. The existing type/documentType/docType field retains invoice for compatibility; use businessType when present, otherwise the existing family field."},"lines":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#/components/schemas/ConnectorBusinessLine"}},"delivery":{"type":"string","enum":["send","stage"],"default":"send"},"attachments":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/ConnectorBusinessAttachment"}},"precedingDocumentNumber":{"type":"string","description":"Original invoice number. Required for credit_note, self_billing_credit_note, correction (384) and debit_note (383).","maxLength":255},"note":{"type":"string","maxLength":5000},"iban":{"type":"string","maxLength":64},"paymentMethod":{"type":"string"},"variableSymbol":{"type":"string"},"buyerReference":{"type":"string","description":"Peppol BT-10 internal buyer routing reference, up to 100 characters. A document must contain buyerReference or orderReference."},"paymentTerms":{"type":"string","maxLength":500,"description":"Peppol BT-20 textual payment terms."},"orderReference":{"type":"string","description":"Peppol BT-13 purchase-order reference, up to 100 characters. A document must contain orderReference or buyerReference."},"prepaidAmount":{"type":"number","minimum":0},"prepayments":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/ConnectorBusinessPrepayment"}},"response":{"type":"object","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConnectorBusinessInvoiceResponse"}],"description":"Current business response, or null when neither side has sent one."}},"additionalProperties":false,"description":"Business document. List and detail include persisted submission content (lines, attachments including content, payment details and prepayments) when available. Historical documents without a submission payload may omit these fields. Content reflects the normalized accepted document, not a byte-for-byte copy of the POST request."},"ConnectorBusinessErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable","requestId"],"properties":{"code":{"type":"string","enum":["CUSTOMER_NOT_READY","RECIPIENT_NOT_FOUND","RECIPIENT_AMBIGUOUS","RECIPIENT_NOT_REACHABLE","RECIPIENT_LOOKUP_UNAVAILABLE","DOCUMENT_INVALID","IDEMPOTENCY_CONFLICT","DELIVERY_TEMPORARILY_UNAVAILABLE","PAYLOAD_TOO_LARGE"]},"message":{"type":"string"},"field":{"type":"string"},"retryable":{"type":"boolean"},"nextAction":{"type":"string"},"requestId":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","description":"Correlation ID echoed in the X-Request-Id response header. Invalid incoming IDs are replaced."}},"additionalProperties":false}},"additionalProperties":false},"ErrorResponse":{"type":"object","description":"Standard error envelope for `/api/v1/*` endpoints (excluding `/auth/token|renew|revoke` which use `PeppolErrorResponse`, and `/oauth/token` which uses RFC 6749 `OAuthErrorResponse`). The `requestId` echoes the `X-Request-Id` response header — quote it in support tickets.","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Branch on this value, not only on HTTP status. Known codes:\n- VALIDATION_ERROR (422) - JSON, XML shape, or required field validation failed; fix the payload and retry.\n- UBL_VALIDATION_ERROR (422) - Peppol/CEN schematron rejection; inspect details[].rule such as BR-CO-26.\n- UNPROCESSABLE_ENTITY (422) - business rule rejection.\n- IDEMPOTENCY_KEY_MISMATCH (422) - the same Idempotency-Key was reused with a different canonicalized body.\n- IDEMPOTENCY_IN_FLIGHT (409) - the same idempotency key is still processing; wait and poll status.\n- CONNECTOR_LEGACY_IDEMPOTENCY_OWNER_UNPROVEN (409) - a pre-deploy Connector send cannot yet prove the historical key owner; if retryable=true wait 30 seconds and retry the exact same key/body, never change the key; if retryable=false do not resubmit and contact support.\n- AUTOPILOT_REPLAY_MISMATCH (409) - the command changed or a historical direct reference is reserved in another/unproven ownership namespace; no timed retry, reconcile first.\n- CONNECTOR_OUTBOX_REFERENCE_RESERVED (409) - a historical outbox item without proven integrator ownership already reserves the ERP reference; reconcile first.\n- NOT_FOUND (404).\n- FORBIDDEN (403) - plan, scope, or ownership denied.\n- CONFLICT (409) - duplicate or unique-constraint collision.\n- BAD_REQUEST (400) - malformed body or parameters.\n- INVALID_PARAM (400).\n- PAYLOAD_TOO_LARGE (413).\n- RATE_LIMITED (429) - respect Retry-After when present.\n- VALIDATION_SERVICE_UNAVAILABLE (503) - retry with backoff.\n- IDEMPOTENCY_STORE_UNAVAILABLE (503) - retry the same payload with the same Idempotency-Key.\n- SEND_FAILED (502) - Peppol AP dispatch failed, retryable when the same payload and key are used.\n- SERVICE_UNAVAILABLE (503) - upstream dependency unavailable.\n- INTERNAL_ERROR (500).\nBusiness error catalog:\n- participant_not_found (422) - retryable=false; fix_hint=change or verify the receiver Peppol ID.\n- receiver_unsupported_document_type (422) - retryable=false; fix_hint=change document type/profile or receiver capability.\n- validation_failed (422) - retryable=false; fix_hint=fix the UBL/JSON payload using details/rule.\n- temporary_transport_error (502/503) - retryable=true; fix_hint=retry with backoff and the same Idempotency-Key.\n- delivery_dead_lettered (409) - retryable=false; fix_hint=inspect events/support-packet, then retry manually or contact support.\n- duplicate_idempotency_key (422) - retryable=false; fix_hint=send the original body or use a new key for changed payload.","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"receiverPeppolId is required"},"requestId":{"type":"string","format":"uuid","description":"Mirror of the `X-Request-Id` response header — for tracing."},"details":{"description":"Optional structured details (e.g., Zod error array, Peppol schematron rule IDs)"},"conflictTarget":{"type":"string","description":"On 409 from a unique-constraint collision: comma-joined target columns (e.g. `firm_id,idempotency_key`)."}}}}},"ConnectorBusinessState":{"type":"string","enum":["queued","sending","delivered","received","processed","needs_attention","failed","cancelled"]},"ConnectorBusinessDocumentList":{"type":"object","required":["documents","nextCursor","hasMore"],"properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorBusinessDocument"}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}},"additionalProperties":false},"ConnectorAcknowledgeResponse":{"type":"object","required":["id","customerRef","state","processedAt","reference","idempotent"],"properties":{"id":{"type":"string","format":"uuid"},"customerRef":{"type":"string"},"state":{"type":"string","enum":["processed"]},"processedAt":{"type":"string","format":"date-time"},"reference":{"type":"string"},"idempotent":{"type":"boolean"}},"additionalProperties":false},"ConnectorBusinessEventsResponse":{"type":"object","additionalProperties":false,"required":["events","nextCursor","hasMore"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorBusinessEvent"}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}},"ConnectorIntakeResponse":{"type":"object","required":["ok","intakeId","replayed","status","purpose","source","routing","delivery","reviewRequired","documentType","failureCode","documentId","outboxId","learning","createdAt","updatedAt"],"properties":{"ok":{"type":"boolean","enum":[true]},"intakeId":{"type":"string","format":"uuid"},"replayed":{"type":"boolean","description":"True when this response resolved an exact Idempotency-Key replay."},"status":{"type":"string","enum":["received","scanning","transforming","validating","needs_review","sampled","staged","sending","sent","delivered","malware_rejected","mapping_failed","validation_failed","retry_later","failed_internal","cancelled"]},"purpose":{"type":"string","enum":["production","onboarding_sample"],"description":"Server-owned processing purpose. onboarding_sample can be selected only by an active connection learning session and can never be sent."},"source":{"type":"object","required":["kind","mimeType"],"properties":{"kind":{"type":"string","enum":["json","xml","csv","ubl","pdf","image"]},"mimeType":{"type":"string"}},"additionalProperties":false},"routing":{"type":"object","required":["customerRef","connectionId","profileId","revisionId"],"properties":{"customerRef":{"type":"string"},"connectionId":{"type":"string","format":"uuid","nullable":true,"description":"Connection binding pinned at acceptance, or null for the legacy customerRef path."},"profileId":{"type":"string","format":"uuid","nullable":true},"revisionId":{"type":"string","format":"uuid","nullable":true,"description":"Exact immutable mapping revision pinned for production, or null for validated UBL passthrough and onboarding samples."}},"additionalProperties":false},"delivery":{"type":"object","required":["requested","effective"],"properties":{"requested":{"type":"string","enum":["stage","send"]},"effective":{"type":"string","enum":["stage","send"]}},"additionalProperties":false},"reviewRequired":{"type":"boolean"},"documentType":{"type":"string","nullable":true,"enum":["invoice","credit_note","self_billing_invoice","self_billing_credit_note"],"description":"Backward-compatible billing family; 383/384/386 use invoice with businessType carrying the exact subtype."},"failureCode":{"type":"string","nullable":true},"documentId":{"type":"string","format":"uuid","nullable":true},"outboxId":{"type":"string","format":"uuid","nullable":true},"learning":{"type":"object","nullable":true,"required":["sessionId","sampleId"],"properties":{"sessionId":{"type":"string","format":"uuid"},"sampleId":{"type":"string","format":"uuid","nullable":true,"description":"Mapper corpus sample after analysis, or null while the intake is still being processed."}},"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"businessType":{"type":"string","x-extensible-enum":["debit_note","prepayment_invoice","correction"],"description":"Exact business subtype for UBL 383, 384 or 386. Present only for these subtypes. The existing type/documentType/docType field retains invoice for compatibility; use businessType when present, otherwise the existing family field."}},"additionalProperties":false},"ConnectorMapperRevisionSelector":{"type":"object","description":"Explicit Mapping Spec v2 opt-in. templateKey is required when this selector is present. fieldMap, defaults and saveTemplate cannot be combined with it. Omitting the selector uses the established Mapper path without reading revision state.","required":["id","mode"],"properties":{"id":{"type":"string","format":"uuid","description":"Exact immutable mapping revision UUID."},"mode":{"type":"string","enum":["shadow","apply"],"description":"shadow keeps the established Mapper result authoritative and evaluates the selected candidate without side effects; the established execute setting still applies to the authoritative result. apply uses only the exact approved revision that is currently active for the template and fails closed on mapping or canonical validation errors."}},"additionalProperties":false},"ConnectorMapperRevisionMetadata":{"type":"object","description":"Identity and evaluation metadata returned only when mappingRevision was supplied. Hashes and fingerprints do not expose mapped source values.","required":["id","mode","revisionNumber","specVersion","state","contentHash","evaluationFingerprint","routing"],"properties":{"id":{"type":"string","format":"uuid"},"mode":{"type":"string","enum":["shadow","apply"]},"revisionNumber":{"type":"integer","minimum":1},"specVersion":{"type":"integer","minimum":1,"description":"Stored mapping specification version. Successful v2 evaluation requires version 2; an incompatible selected revision can still report its version in failure metadata."},"state":{"type":"string","enum":["candidate","approved"]},"contentHash":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"SHA-256 of the immutable mapping specification."},"evaluationFingerprint":{"type":"string","nullable":true,"pattern":"^[a-f0-9]{64}$","description":"Value-free fingerprint of this revision evaluation, or null when no candidate evaluation was possible."},"routing":{"type":"object","required":["customerRefOrigin"],"properties":{"customerRefOrigin":{"type":"string","enum":["request","missing","request_invalid","not_evaluated"],"description":"Whether the request-scoped customerRef was present, missing, invalid, or could not be evaluated. Mapping revisions never provide routing authority."}},"additionalProperties":false}},"additionalProperties":false},"ConnectorMapperShadowMetadata":{"type":"object","description":"Shadow-only diagnostics. The established Mapper output remains authoritative; candidate evaluation and comparison never stage or send a document.","required":["status"],"properties":{"status":{"type":"string","enum":["compared","candidate_failed","candidate_invalid","not_comparable"]},"reason":{"type":"string","enum":["legacy_raw_ubl","legacy_document_unavailable"]},"evaluationFingerprint":{"type":"string","nullable":true,"pattern":"^[a-f0-9]{64}$"},"issues":{"type":"array","description":"Safe machine-readable issue codes; source excerpts and values are never included.","items":{"type":"object","required":["code","severity"],"properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["error","warning","blocking"]}},"additionalProperties":true}},"comparison":{"$ref":"#/components/schemas/ConnectorMapperShadowComparison"}},"additionalProperties":false},"ConnectorConnectionList":{"type":"object","additionalProperties":false,"required":["connections"],"properties":{"connections":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorConnection"}}}},"ConnectorConnectionCreate":{"type":"object","additionalProperties":false,"required":["customerRef","name","channel"],"properties":{"customerRef":{"type":"string","minLength":1,"maxLength":128},"channel":{"type":"string","enum":["api","portal","email","sftp","bridge"]},"name":{"type":"string","minLength":1,"maxLength":120},"direction":{"type":"string","enum":["outbound","inbound","bidirectional"],"default":"outbound"},"outboundProfileId":{"type":"string","format":"uuid","nullable":true},"inboundProfileId":{"type":"string","format":"uuid","nullable":true},"reviewOwner":{"type":"string","enum":["integrator"],"default":"integrator","description":"Integrator review is the only writable ownership mode. Firm and ePostak queues are reserved for a future additive release."},"managedExceptionsEnabled":{"type":"boolean","enum":[false],"default":false,"description":"Reserved compatibility field. Managed Exceptions is not currently available and true is rejected."},"outboundDeliveryMode":{"type":"string","enum":["stage","auto"],"default":"stage"},"inboundDeliveryMode":{"type":"string","enum":["stage","auto"],"default":"stage"},"channelConfig":{"$ref":"#/components/schemas/ConnectorConnectionChannelConfigInput"}}},"ConnectorConnectionEnvelope":{"type":"object","additionalProperties":false,"required":["connection"],"properties":{"connection":{"$ref":"#/components/schemas/ConnectorConnection"}}},"ConnectorConnectionPatch":{"type":"object","minProperties":1,"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"direction":{"type":"string","enum":["outbound","inbound","bidirectional"],"default":"outbound"},"outboundProfileId":{"type":"string","format":"uuid","nullable":true},"inboundProfileId":{"type":"string","format":"uuid","nullable":true},"reviewOwner":{"type":"string","enum":["integrator"],"default":"integrator","description":"Integrator review is the only writable ownership mode. Firm and ePostak queues are reserved for a future additive release."},"managedExceptionsEnabled":{"type":"boolean","enum":[false],"default":false,"description":"Reserved compatibility field. Managed Exceptions is not currently available and true is rejected."},"outboundDeliveryMode":{"type":"string","enum":["stage","auto"],"default":"stage"},"inboundDeliveryMode":{"type":"string","enum":["stage","auto"],"default":"stage"},"channelConfig":{"$ref":"#/components/schemas/ConnectorConnectionChannelConfigInput"}}},"ConnectorConnectionCredentialResult":{"type":"object","additionalProperties":false,"required":["connection","credential"],"properties":{"connection":{"$ref":"#/components/schemas/ConnectorConnection"},"credential":{"type":"string","readOnly":true,"description":"One-time SFTP password or unguessable email intake address. Store it now; the API never returns it again and persists only a verifier or hash."}}},"ConnectorConnectionTestResult":{"type":"object","additionalProperties":false,"required":["connection","test"],"properties":{"connection":{"$ref":"#/components/schemas/ConnectorConnection"},"test":{"type":"object","additionalProperties":false,"required":["passed","code","transport","mapping","capabilities"],"properties":{"passed":{"type":"boolean"},"code":{"type":"string","nullable":true},"transport":{"type":"object","additionalProperties":false,"required":["passed","code"],"properties":{"passed":{"type":"boolean"},"code":{"type":"string","nullable":true}},"description":"Authoritative channel test. A connection can pass transport before its mapping profile is active."},"mapping":{"type":"object","additionalProperties":false,"required":["ready","code"],"properties":{"ready":{"type":"boolean"},"code":{"type":"string","nullable":true}},"description":"Separate mapping readiness. It never changes the transport result or grants send permission."},"capabilities":{"type":"object","additionalProperties":false,"required":["structuredOutbound","ublPassthrough","inboundMapping"],"properties":{"structuredOutbound":{"type":"boolean"},"ublPassthrough":{"type":"boolean"},"inboundMapping":{"type":"boolean"}}}}}}},"ConnectorLearningSessionStart":{"type":"object","additionalProperties":false,"properties":{"durationMinutes":{"type":"integer","minimum":15,"maximum":1440,"default":60},"sampleLimit":{"type":"integer","minimum":3,"maximum":10,"default":10}}},"ConnectorLearningSessionEnvelope":{"type":"object","additionalProperties":false,"required":["learning"],"properties":{"learning":{"$ref":"#/components/schemas/ConnectorLearningSession"}}},"ConnectorBridgeDeviceList":{"type":"object","additionalProperties":false,"required":["devices"],"properties":{"devices":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorBridgeDevice"}}}},"ConnectorBridgeDeviceCreate":{"type":"object","additionalProperties":false,"required":["name","platform"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"platform":{"type":"string","enum":["windows","macos"]}}},"ConnectorBridgeDeviceCreateResult":{"type":"object","additionalProperties":false,"required":["device","pairingCode"],"properties":{"device":{"$ref":"#/components/schemas/ConnectorBridgeDevice"},"pairingCode":{"type":"string","readOnly":true,"description":"One-time 15-minute pairing code. The server stores only its SHA-256 hash and never returns the code again."}}},"ConnectorBridgeDeviceEnvelope":{"type":"object","additionalProperties":false,"required":["device"],"properties":{"device":{"$ref":"#/components/schemas/ConnectorBridgeDevice"}}},"ConnectorDeliveryEnvelope":{"type":"object","additionalProperties":false,"required":["delivery"],"properties":{"delivery":{"$ref":"#/components/schemas/ConnectorDeliveryJob"}}},"ConnectorDeliveryAcknowledgment":{"type":"object","additionalProperties":false,"properties":{"reference":{"type":"string","minLength":1,"maxLength":255,"description":"Optional stable reference of the ERP import operation."}}},"ConnectorDeliveryRelease":{"type":"object","additionalProperties":false,"required":["expectedUpdatedAt"],"properties":{"expectedUpdatedAt":{"type":"string","format":"date-time","description":"The updatedAt value returned when the staged delivery was reviewed."}}},"ConnectorBusinessRecipientRequest":{"type":"object","required":["country"],"properties":{"country":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"ISO country code that determines how the ordinary identifier is interpreted."},"name":{"type":"string","maxLength":255},"companyId":{"type":"string","maxLength":255,"description":"Company registration number for this country. Do not put a tax or VAT identifier in this field."},"taxId":{"type":"string","maxLength":255,"description":"Local tax identifier for this country. Do not put a company registration or VAT identifier in this field."},"vatId":{"type":"string","maxLength":255,"description":"VAT identifier for this country. Do not put a company registration or local tax identifier in this field."},"networkId":{"type":"string","maxLength":255,"description":"Optional expert override. The identifier is still verified before use."},"address":{"type":"object","properties":{"street":{"type":"string"},"city":{"type":"string"},"postalCode":{"type":"string","maxLength":32}},"additionalProperties":false}},"anyOf":[{"required":["companyId"]},{"required":["taxId"]},{"required":["vatId"]},{"required":["networkId"]}],"additionalProperties":false},"ConnectorBusinessPrepayment":{"type":"object","required":["amountWithVat"],"properties":{"advanceInvoiceRef":{"type":"string"},"taxDocumentRef":{"type":"string"},"settlementDate":{"type":"string","format":"date"},"amountWithoutVat":{"type":"number","minimum":0},"vatAmount":{"type":"number","minimum":0},"amountWithVat":{"type":"number","minimum":0},"vatRate":{"type":"number","minimum":0,"maximum":100},"taxTreatment":{"type":"string","enum":["standard","zero_rated","reverse_charge","exempt","intra_community_supply","export","out_of_scope"]}},"additionalProperties":false},"ConnectorBusinessLine":{"type":"object","required":["description","quantity","unitPrice","vatRate"],"properties":{"description":{"type":"string","maxLength":1000},"quantity":{"type":"number","description":"Positive for standard lines; negative for lineType=advance_deduction. Zero is never allowed."},"unit":{"type":"string","maxLength":16},"unitPrice":{"type":"number","minimum":0},"vatRate":{"type":"number","minimum":0,"maximum":100},"taxTreatment":{"type":"string","enum":["standard","zero_rated","reverse_charge","exempt","intra_community_supply","export","out_of_scope"]},"taxExemptionReasonCode":{"type":"string","maxLength":255,"description":"Peppol BT-121 VAT exemption reason code from the current CEF VATEX list. The code must match taxTreatment and is allowed only for exempt or non-taxable values."},"taxExemptionReason":{"type":"string","maxLength":1000,"description":"Peppol BT-120 human-readable VAT exemption reason. Allowed only for exempt or non-taxable taxTreatment values."},"discount":{"type":"number","minimum":0,"maximum":100},"deliveryDate":{"type":"string","format":"date"},"lineType":{"type":"string","description":"advance_deduction requires a negative quantity and advanceInvoiceReference."},"advanceInvoiceReference":{"type":"string"},"customsTariffCode":{"type":"string"},"commodityClassificationCode":{"type":"string"},"commodityClassificationListId":{"type":"string"},"reverseChargeParagraphLetter":{"type":"string"},"controlStatementType":{"type":"string"},"controlStatementQuantity":{"type":"number","minimum":0},"controlStatementUnit":{"type":"string"}},"additionalProperties":false},"ConnectorBusinessAttachment":{"type":"object","required":["fileName","mimeType","content"],"properties":{"fileName":{"type":"string","maxLength":255},"mimeType":{"type":"string","maxLength":255},"content":{"type":"string","format":"byte"},"description":{"type":"string","maxLength":1000}},"additionalProperties":false},"ConnectorBusinessParty":{"type":"object","properties":{"name":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"companyId":{"type":"string","nullable":true},"taxId":{"type":"string","nullable":true},"vatId":{"type":"string","nullable":true},"resolution":{"type":"string","enum":["verified"],"nullable":true},"networkId":{"type":"string"},"address":{"type":"object","additionalProperties":false,"properties":{"street":{"type":"string"},"city":{"type":"string"},"postalCode":{"type":"string"}}}},"additionalProperties":false},"ConnectorBusinessEvent":{"type":"object","additionalProperties":false,"required":["id","customerRef","documentId","type","state","occurredAt","data"],"properties":{"id":{"type":"string"},"customerRef":{"type":"string","minLength":1,"description":"Integrator-configured reference for the approved company that owns this event."},"documentId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["document.queued","document.delivered","document.received","document.processed","document.needs_attention","document.failed","document.cancelled"],"example":"document.delivered"},"state":{"$ref":"#/components/schemas/ConnectorBusinessState"},"occurredAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":false,"required":["direction","type","number","response"],"properties":{"customerRef":{"type":"string","deprecated":true,"description":"Compatibility alias for existing Connector clients. New clients must route on root customerRef."},"direction":{"type":"string","enum":["outbound","inbound"]},"type":{"type":"string","enum":["invoice","credit_note","self_billing_invoice","self_billing_credit_note"],"description":"Backward-compatible billing family. Debit notes (383) and prepayment invoices (386) use invoice; businessType carries their exact subtype."},"number":{"type":"string","nullable":true},"process_id":{"type":"string","nullable":true,"description":"Canonical bare Peppol process URN."},"response":{"type":"object","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConnectorBusinessInvoiceResponse"}],"description":"Current business response, or null when neither side has sent one. acknowledge does not populate this field."},"businessType":{"type":"string","x-extensible-enum":["debit_note","prepayment_invoice","correction"],"description":"Exact business subtype for UBL 383, 384 or 386. Present only for these subtypes. The existing type/documentType/docType field retains invoice for compatibility; use businessType when present, otherwise the existing family field."}}}}},"ConnectorMapperShadowComparison":{"type":"object","description":"Value-free semantic comparison between the authoritative established Mapper output and the selected v2 revision.","required":["matches","criticalMismatch","legacyFingerprint","candidateFingerprint","differences","truncated"],"properties":{"matches":{"type":"boolean"},"criticalMismatch":{"type":"boolean"},"legacyFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"candidateFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"differences":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorMapperShadowDifference"}},"truncated":{"type":"boolean"}},"additionalProperties":false},"ConnectorConnection":{"type":"object","additionalProperties":false,"required":["id","customerRef","name","channel","direction","status","profiles","review","delivery","channelConfig","credential","test","disabledAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"customerRef":{"type":"string","maxLength":128},"name":{"type":"string","minLength":1,"maxLength":120},"channel":{"type":"string","enum":["api","portal","email","sftp","bridge"]},"direction":{"type":"string","enum":["outbound","inbound","bidirectional"],"default":"outbound"},"status":{"type":"string","enum":["draft","testing","active","needs_attention","disabled"]},"profiles":{"type":"object","additionalProperties":false,"required":["outbound","inbound"],"properties":{"outbound":{"type":"object","nullable":true,"additionalProperties":false,"required":["id","key","sourceType","runtimeMode","activeRevisionId"],"properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"sourceType":{"type":"string","enum":["auto","json","csv","xml","ocr","pdf_text","text"]},"runtimeMode":{"type":"string","enum":["off","shadow","active"]},"activeRevisionId":{"type":"string","format":"uuid","nullable":true}}},"inbound":{"type":"object","nullable":true,"additionalProperties":false,"required":["id","key","sourceType","runtimeMode","activeRevisionId"],"properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"sourceType":{"type":"string","enum":["auto","json","csv","xml","ocr","pdf_text","text"]},"runtimeMode":{"type":"string","enum":["off","shadow","active"]},"activeRevisionId":{"type":"string","format":"uuid","nullable":true}}}}},"review":{"type":"object","additionalProperties":false,"required":["owner","managedExceptionsEnabled"],"properties":{"owner":{"type":"string","enum":["firm","integrator","epostak"],"description":"Stored owner. Non-integrator values can appear only on preserved historical connections and are not writable through this API."},"managedExceptionsEnabled":{"type":"boolean","description":"Stored compatibility state. A historical true value is preserved but cannot be enabled through this API."}}},"delivery":{"type":"object","additionalProperties":false,"required":["outbound","inbound"],"properties":{"outbound":{"type":"string","enum":["stage","auto"],"default":"stage"},"inbound":{"type":"string","enum":["stage","auto"],"default":"stage"}}},"channelConfig":{"$ref":"#/components/schemas/ConnectorConnectionChannelConfig"},"credential":{"type":"object","additionalProperties":false,"required":["configured","prefix","version"],"properties":{"configured":{"type":"boolean"},"prefix":{"type":"string","nullable":true},"version":{"type":"integer","minimum":0}}},"test":{"type":"object","additionalProperties":false,"required":["status","code","testedAt"],"properties":{"status":{"type":"string","enum":["not_run","passed","failed"]},"code":{"type":"string","nullable":true},"testedAt":{"type":"string","format":"date-time","nullable":true}}},"disabledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ConnectorConnectionChannelConfigInput":{"type":"object","additionalProperties":false,"properties":{"allowedSenders":{"type":"array","maxItems":50,"uniqueItems":true,"items":{"type":"string","format":"email","maxLength":254},"description":"Exact sender allowlist for an email connection. Required before the connection test can pass."},"deliveryRecipients":{"type":"array","maxItems":50,"uniqueItems":true,"items":{"type":"string","format":"email","maxLength":254},"description":"Exact ERP mailbox recipients for inbound delivery over an email connection. Required before an inbound or bidirectional email connection can pass its test."}}},"ConnectorLearningSession":{"type":"object","additionalProperties":false,"required":["id","connectionId","profileId","state","sampleLimit","sampleCount","expiresAt","closedAt","createdAt","updatedAt","replayed"],"properties":{"id":{"type":"string","format":"uuid"},"connectionId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["collecting","closed","expired"]},"sampleLimit":{"type":"integer","minimum":3,"maximum":10},"sampleCount":{"type":"integer","minimum":0,"maximum":10},"expiresAt":{"type":"string","format":"date-time"},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"replayed":{"type":"boolean","description":"True when start returned the already active learning session."}}},"ConnectorBridgeDevice":{"type":"object","additionalProperties":false,"required":["id","connectionId","name","platform","status","protocolVersion","appVersion","credential","capabilities","pairingExpiresAt","lastHeartbeatAt","revokedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"connectionId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":120},"platform":{"type":"string","enum":["windows","macos"]},"status":{"type":"string","enum":["pairing","active","paused","revoked"]},"protocolVersion":{"type":"string","enum":["1.0"]},"appVersion":{"type":"string","nullable":true},"credential":{"type":"object","additionalProperties":false,"required":["configured","prefix","version"],"properties":{"configured":{"type":"boolean"},"prefix":{"type":"string","nullable":true},"version":{"type":"integer","minimum":0}}},"capabilities":{"type":"object","additionalProperties":true},"pairingExpiresAt":{"type":"string","format":"date-time","nullable":true},"lastHeartbeatAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ConnectorDeliveryJob":{"type":"object","additionalProperties":false,"required":["id","connectionId","documentId","profileId","revisionId","format","mimeType","fileName","deliveryMode","status","failureCode","replayed","artifact","deliveredAt","acknowledgedAt","acknowledgmentRef","createdAt","updatedAt","links"],"properties":{"id":{"type":"string","format":"uuid"},"connectionId":{"type":"string","format":"uuid"},"documentId":{"type":"string","format":"uuid"},"profileId":{"type":"string","format":"uuid","nullable":true},"revisionId":{"type":"string","format":"uuid","nullable":true},"format":{"type":"string","enum":["json","xml","csv","ubl"]},"mimeType":{"type":"string","maxLength":120},"fileName":{"type":"string","maxLength":255},"deliveryMode":{"type":"string","enum":["stage","auto"]},"status":{"type":"string","enum":["received","transforming","validating","needs_review","staged","ready","delivering","delivered","retry_later","failed","cancelled"]},"failureCode":{"type":"string","nullable":true,"maxLength":80},"replayed":{"type":"boolean","description":"True when this response is an idempotent replay of an existing export, staged release, or acknowledgment."},"artifact":{"type":"object","additionalProperties":false,"required":["available","href"],"properties":{"available":{"type":"boolean"},"href":{"type":"string","nullable":true}}},"deliveredAt":{"type":"string","format":"date-time","nullable":true},"acknowledgedAt":{"type":"string","format":"date-time","nullable":true},"acknowledgmentRef":{"type":"string","nullable":true,"maxLength":255},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"ConnectorBusinessInvoiceResponse":{"type":"object","additionalProperties":false,"required":["status","direction","reason","respondedAt"],"properties":{"status":{"type":"string","enum":["received","in_process","under_query","conditionally_accepted","rejected","accepted","paid"]},"direction":{"type":"string","enum":["sent","received"]},"reason":{"type":"string","maxLength":500,"nullable":true,"description":"Sanitized reason supplied with the business response, when available."},"respondedAt":{"type":"string","format":"date-time","nullable":true}}},"ConnectorMapperShadowDifference":{"type":"object","description":"One value-free semantic difference. Only SHA-256 fingerprints are exposed, never source or mapped values.","required":["path","severity","kind","legacyFingerprint","candidateFingerprint"],"properties":{"path":{"type":"string"},"severity":{"type":"string","enum":["critical","warning"]},"kind":{"type":"string","enum":["added","removed","changed","type_changed"]},"legacyFingerprint":{"type":"string","nullable":true,"pattern":"^[a-f0-9]{64}$"},"candidateFingerprint":{"type":"string","nullable":true,"pattern":"^[a-f0-9]{64}$"}},"additionalProperties":false},"ConnectorConnectionChannelConfig":{"type":"object","additionalProperties":false,"properties":{"allowedSenders":{"type":"array","items":{"type":"string","format":"email"}},"deliveryRecipients":{"type":"array","items":{"type":"string","format":"email"}},"domain":{"type":"string","nullable":true},"username":{"type":"string","nullable":true},"host":{"type":"string","nullable":true},"port":{"type":"integer","minimum":1,"maximum":65535},"directories":{"type":"object","additionalProperties":false,"required":["outbox","inbox","status"],"properties":{"outbox":{"type":"string","enum":["/outbox"]},"inbox":{"type":"string","enum":["/inbox"]},"status":{"type":"string","enum":["/status"]}}}}},"ConnectorCustomerLifecycleEvent":{"type":"object","additionalProperties":false,"required":["id","customerRef","type","occurredAt","data"],"properties":{"id":{"type":"string","format":"uuid","description":"Stable lifecycle event id used for deduplication."},"customerRef":{"type":"string","minLength":1,"description":"Integrator-configured reference for the affected company."},"type":{"type":"string","enum":["customer.active","customer.integration_detachment_scheduled","customer.integration_detachment_cancelled","customer.integration_detached","customer.provider_change_requested","customer.provider_change_cancelled","customer.provider_changed","customer.deactivated"]},"occurredAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":false,"required":["customerRef","status","reason","initiatedBy","effectiveAt"],"properties":{"customerRef":{"type":"string","deprecated":true,"description":"Compatibility alias. Route lifecycle events on root customerRef."},"status":{"type":"string","enum":["active","integration_detachment_scheduled","provider_change_pending","inactive"]},"reason":{"type":"string","enum":["activation_completed","integration_detachment_scheduled","integration_detachment_cancelled","authorization_revoked","integrator_detached","provider_change_requested","provider_change_cancelled","provider_changed","contract_terminated","service_terminated"]},"initiatedBy":{"type":"string","enum":["customer","integrator","provider","system"],"description":"Actor category only. No individual user identity is disclosed."},"effectiveAt":{"type":"string","format":"date-time"},"payerMode":{"type":"string","nullable":true,"enum":["firm_billed","integrator_billed",null],"description":"Billing owner snapshot when it is relevant to the transition."},"relationshipMode":{"type":"string","enum":["technical_delegation","managed_service"]},"apiWillDeactivate":{"type":"boolean","description":"Whether API paid by the integrator ends at effectiveAt."}}}},"example":{"id":"69f08e56-fb60-5b39-a6d0-b6154966f273","customerRef":"erp-acme","type":"customer.provider_change_requested","occurredAt":"2026-07-15T09:20:00.000Z","data":{"customerRef":"erp-acme","status":"provider_change_pending","reason":"provider_change_requested","initiatedBy":"customer","effectiveAt":"2026-07-15T09:20:00.000Z"}}},"ConnectorOperationalEvent":{"type":"object","additionalProperties":false,"required":["id","customerRef","type","state","occurredAt","data"],"properties":{"id":{"type":"string","format":"uuid","description":"Stable lifecycle event id used for deduplication."},"customerRef":{"type":"string","minLength":1,"description":"Integrator-configured reference for the company bound to the source connection."},"type":{"type":"string","enum":["connection.created","connection.updated","connection.disabled","connection.credential_rotated","connection.test_passed","connection.test_failed","connection.learning_started","connection.learning_stopped","connection.adapter_quarantined","intake.received","intake.sample_received","intake.scanning","intake.ocr_extracted","intake.transforming","intake.validating","intake.needs_review","intake.staged","intake.sending","intake.sent","intake.delivered","intake.malware_rejected","intake.mapping_failed","intake.validation_failed","intake.retry_later","intake.failed_internal","intake.cancelled","intake.sampled","intake.learning_corpus_updated","intake.learning_candidate_created","mapping.profile_created","mapping.candidate_created","mapping.revision_approved","mapping.revision_activated","mapping.revision_rolled_back","mapping.technical_certified","mapping.probation_reset","mapping.automation_enabled","mapping.pdf_probation_started","mapping.pdf_probation_ready","mapping.pdf_automation_enabled","mapping.pdf_suspended","review.opened","review.claimed","review.released","review.resolved","review.cancelled","delivery.received","delivery.transforming","delivery.validating","delivery.needs_review","delivery.staged","delivery.ready","delivery.delivering","delivery.delivered","delivery.acknowledged","delivery.retry_later","delivery.failed","delivery.cancelled"]},"state":{"type":"string","pattern":"^[a-z0-9_]+$"},"occurredAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":false,"required":["customerRef","resource","details"],"properties":{"customerRef":{"type":"string","deprecated":true,"description":"Compatibility alias. Route events on root customerRef."},"resource":{"type":"object","additionalProperties":false,"required":["type","id","connectionId"],"properties":{"type":{"type":"string","enum":["connection","intake","mapping","review","delivery"]},"id":{"type":"string","format":"uuid"},"connectionId":{"type":"string","format":"uuid","nullable":true}}},"details":{"type":"object","additionalProperties":true,"description":"Bounded, value-free diagnostic codes and hashes. Raw accounting content, secrets, actor identities, and mapped values are never included."}}}}},"ConnectorOperationalEventsResponse":{"type":"object","additionalProperties":false,"required":["events","nextCursor","hasMore"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorOperationalEvent"}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}},"ConnectorWebhookEvent":{"oneOf":[{"$ref":"#/components/schemas/ConnectorBusinessEvent"},{"$ref":"#/components/schemas/ConnectorCustomerLifecycleEvent"}]},"ConnectorWebhookCallbackEvent":{"oneOf":[{"$ref":"#/components/schemas/ConnectorBusinessEvent"},{"$ref":"#/components/schemas/ConnectorCustomerLifecycleEvent"},{"$ref":"#/components/schemas/ConnectorOperationalEvent"}]},"ConnectorWebhook":{"type":"object","additionalProperties":false,"required":["id","url","events","active","failedAttempts","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["document.queued","document.delivered","document.received","document.processed","document.needs_attention","document.failed","document.cancelled","customer.active","customer.integration_detachment_scheduled","customer.integration_detachment_cancelled","customer.integration_detached","customer.provider_change_requested","customer.provider_change_cancelled","customer.provider_changed","customer.deactivated"]}},"operationalEvents":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["connection.created","connection.updated","connection.disabled","connection.credential_rotated","connection.test_passed","connection.test_failed","connection.learning_started","connection.learning_stopped","connection.adapter_quarantined","intake.received","intake.sample_received","intake.scanning","intake.ocr_extracted","intake.transforming","intake.validating","intake.needs_review","intake.staged","intake.sending","intake.sent","intake.delivered","intake.malware_rejected","intake.mapping_failed","intake.validation_failed","intake.retry_later","intake.failed_internal","intake.cancelled","intake.sampled","intake.learning_corpus_updated","intake.learning_candidate_created","mapping.profile_created","mapping.candidate_created","mapping.revision_approved","mapping.revision_activated","mapping.revision_rolled_back","mapping.technical_certified","mapping.probation_reset","mapping.automation_enabled","mapping.pdf_probation_started","mapping.pdf_probation_ready","mapping.pdf_automation_enabled","mapping.pdf_suspended","review.opened","review.claimed","review.released","review.resolved","review.cancelled","delivery.received","delivery.transforming","delivery.validating","delivery.needs_review","delivery.staged","delivery.ready","delivery.delivering","delivery.delivered","delivery.acknowledged","delivery.retry_later","delivery.failed","delivery.cancelled"]},"description":"Feature-gated operational lifecycle subscriptions. Omitted when none are selected."},"active":{"type":"boolean"},"failedAttempts":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ConnectorWebhookUpsertRequest":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public HTTPS receiver URL."},"events":{"type":"array","minItems":1,"maxItems":15,"uniqueItems":true,"description":"Optional document and customer lifecycle filter. Omit both event fields to subscribe only to the backward-compatible document default (document.queued, document.delivered, document.received, document.processed, document.needs_attention, document.failed, document.cancelled). Customer lifecycle events require explicit opt-in.","items":{"type":"string","enum":["document.queued","document.delivered","document.received","document.processed","document.needs_attention","document.failed","document.cancelled","customer.active","customer.integration_detachment_scheduled","customer.integration_detachment_cancelled","customer.integration_detached","customer.provider_change_requested","customer.provider_change_cancelled","customer.provider_changed","customer.deactivated"]}},"operationalEvents":{"type":"array","minItems":1,"maxItems":58,"uniqueItems":true,"description":"Optional feature-gated connection, intake, mapping, review, and ERP-delivery lifecycle subscriptions.","items":{"type":"string","enum":["connection.created","connection.updated","connection.disabled","connection.credential_rotated","connection.test_passed","connection.test_failed","connection.learning_started","connection.learning_stopped","connection.adapter_quarantined","intake.received","intake.sample_received","intake.scanning","intake.ocr_extracted","intake.transforming","intake.validating","intake.needs_review","intake.staged","intake.sending","intake.sent","intake.delivered","intake.malware_rejected","intake.mapping_failed","intake.validation_failed","intake.retry_later","intake.failed_internal","intake.cancelled","intake.sampled","intake.learning_corpus_updated","intake.learning_candidate_created","mapping.profile_created","mapping.candidate_created","mapping.revision_approved","mapping.revision_activated","mapping.revision_rolled_back","mapping.technical_certified","mapping.probation_reset","mapping.automation_enabled","mapping.pdf_probation_started","mapping.pdf_probation_ready","mapping.pdf_automation_enabled","mapping.pdf_suspended","review.opened","review.claimed","review.released","review.resolved","review.cancelled","delivery.received","delivery.transforming","delivery.validating","delivery.needs_review","delivery.staged","delivery.ready","delivery.delivering","delivery.delivered","delivery.acknowledged","delivery.retry_later","delivery.failed","delivery.cancelled"]}}}},"ConnectorInvoiceResponseRequest":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["received","in_process","under_query","conditionally_accepted","rejected","accepted","paid"]},"note":{"type":"string","maxLength":500,"description":"Optional explanation sent to the counterparty."}}},"ConnectorInvoiceResponseResult":{"type":"object","additionalProperties":false,"required":["id","customerRef","response","idempotent"],"properties":{"id":{"type":"string","format":"uuid"},"customerRef":{"type":"string","minLength":1},"response":{"type":"object","additionalProperties":false,"required":["status","direction","delivery","respondedAt"],"properties":{"status":{"type":"string","enum":["received","in_process","under_query","conditionally_accepted","rejected","accepted","paid"]},"direction":{"type":"string","enum":["sent"]},"delivery":{"type":"string","enum":["sent","queued"]},"respondedAt":{"type":"string","format":"date-time"}}},"idempotent":{"type":"boolean"}}},"ConnectorDocumentWebhookTestEvent":{"type":"object","additionalProperties":false,"required":["id","customerRef","documentId","type","state","occurredAt","data","test"],"properties":{"id":{"type":"string"},"customerRef":{"type":"string","minLength":1,"description":"Integrator-configured reference for the approved company that owns this event."},"documentId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["document.queued","document.delivered","document.received","document.processed","document.needs_attention","document.failed","document.cancelled"],"example":"document.delivered"},"state":{"$ref":"#/components/schemas/ConnectorBusinessState"},"occurredAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":false,"required":["direction","type","number","response"],"properties":{"customerRef":{"type":"string","deprecated":true,"description":"Compatibility alias for existing Connector clients. New clients must route on root customerRef."},"direction":{"type":"string","enum":["outbound","inbound"]},"type":{"type":"string","enum":["invoice","credit_note","self_billing_invoice","self_billing_credit_note"],"description":"Backward-compatible billing family. Debit notes (383) and prepayment invoices (386) use invoice; businessType carries their exact subtype."},"number":{"type":"string","nullable":true},"process_id":{"type":"string","nullable":true,"description":"Canonical bare Peppol process URN."},"response":{"type":"object","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConnectorBusinessInvoiceResponse"}],"description":"Current business response, or null when neither side has sent one. acknowledge does not populate this field."},"businessType":{"type":"string","x-extensible-enum":["debit_note","prepayment_invoice","correction"],"description":"Exact business subtype for UBL 383, 384 or 386. Present only for these subtypes. The existing type/documentType/docType field retains invoice for compatibility; use businessType when present, otherwise the existing family field."}}},"test":{"type":"boolean","enum":[true]},"testRunId":{"type":"string","format":"uuid"},"testScenario":{"type":"string"}}},"ConnectorCustomerWebhookTestEvent":{"type":"object","additionalProperties":false,"required":["id","customerRef","type","occurredAt","data","test"],"properties":{"id":{"type":"string","format":"uuid","description":"Stable lifecycle event id used for deduplication."},"customerRef":{"type":"string","minLength":1,"description":"Integrator-configured reference for the affected company."},"type":{"type":"string","enum":["customer.active","customer.integration_detachment_scheduled","customer.integration_detachment_cancelled","customer.integration_detached","customer.provider_change_requested","customer.provider_change_cancelled","customer.provider_changed","customer.deactivated"]},"occurredAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":false,"required":["customerRef","status","reason","initiatedBy","effectiveAt"],"properties":{"customerRef":{"type":"string","deprecated":true,"description":"Compatibility alias. Route lifecycle events on root customerRef."},"status":{"type":"string","enum":["active","integration_detachment_scheduled","provider_change_pending","inactive"]},"reason":{"type":"string","enum":["activation_completed","integration_detachment_scheduled","integration_detachment_cancelled","authorization_revoked","integrator_detached","provider_change_requested","provider_change_cancelled","provider_changed","contract_terminated","service_terminated"]},"initiatedBy":{"type":"string","enum":["customer","integrator","provider","system"],"description":"Actor category only. No individual user identity is disclosed."},"effectiveAt":{"type":"string","format":"date-time"},"payerMode":{"type":"string","nullable":true,"enum":["firm_billed","integrator_billed",null],"description":"Billing owner snapshot when it is relevant to the transition."},"relationshipMode":{"type":"string","enum":["technical_delegation","managed_service"]},"apiWillDeactivate":{"type":"boolean","description":"Whether API paid by the integrator ends at effectiveAt."}}},"test":{"type":"boolean","enum":[true]},"testRunId":{"type":"string","format":"uuid"},"testScenario":{"type":"string"}},"example":{"id":"69f08e56-fb60-5b39-a6d0-b6154966f273","customerRef":"erp-acme","type":"customer.provider_change_requested","occurredAt":"2026-07-15T09:20:00.000Z","data":{"customerRef":"erp-acme","status":"provider_change_pending","reason":"provider_change_requested","initiatedBy":"customer","effectiveAt":"2026-07-15T09:20:00.000Z"}}},"ConnectorWebhookTestEvent":{"oneOf":[{"$ref":"#/components/schemas/ConnectorDocumentWebhookTestEvent"},{"$ref":"#/components/schemas/ConnectorCustomerWebhookTestEvent"}]},"ConnectorWebhookDelivery":{"type":"object","additionalProperties":false,"required":["id","webhookId","eventId","customerRef","type","status","attempts","responseStatus","responseTimeMs","lastAttemptAt","nextRetryAt","createdAt"],"properties":{"id":{"type":"string"},"webhookId":{"type":"string"},"eventId":{"type":"string","nullable":true},"customerRef":{"type":"string","nullable":true,"description":"Integrator-configured reference for the approved company."},"type":{"type":"string","enum":["document.queued","document.delivered","document.received","document.processed","document.needs_attention","document.failed","document.cancelled","customer.active","customer.integration_detachment_scheduled","customer.integration_detachment_cancelled","customer.integration_detached","customer.provider_change_requested","customer.provider_change_cancelled","customer.provider_changed","customer.deactivated"]},"status":{"type":"string","enum":["PENDING","SUCCESS","FAILED","RETRYING"]},"attempts":{"type":"integer","minimum":0},"responseStatus":{"type":"integer","nullable":true},"responseTimeMs":{"type":"integer","minimum":0,"nullable":true},"lastAttemptAt":{"type":"string","format":"date-time","nullable":true},"nextRetryAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"documentId":{"type":"string","nullable":true},"test":{"type":"boolean"},"testScenario":{"type":"string","nullable":true},"diagnosisCode":{"type":"string","nullable":true,"enum":["RECEIVER_AUTH_REJECTED","RECEIVER_URL_NOT_FOUND","RECEIVER_PAYLOAD_REJECTED","RECEIVER_RATE_LIMITED","RECEIVER_UNAVAILABLE","RECEIVER_TIMEOUT","RECEIVER_NETWORK_ERROR","ENDPOINT_BLOCKED","AUTHORIZATION_CHANGED","RETRIES_EXHAUSTED","QUEUE_PUBLICATION_FAILED","UNKNOWN_DELIVERY_ERROR",null]},"nextAction":{"type":"string","nullable":true},"replayedFromId":{"type":"string","format":"uuid","nullable":true},"canReplay":{"type":"boolean"},"attemptHistoryComplete":{"type":"boolean","description":"False for historical or degraded rows; missing attempts are never fabricated."},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"ConnectorWebhookDeliveries":{"type":"object","additionalProperties":false,"required":["deliveries","nextCursor","hasMore"],"properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorWebhookDelivery"}},"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}},"ConnectorWebhookDeliveryAttempt":{"type":"object","additionalProperties":false,"required":["id","number","outcome","startedAt","retryable"],"properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer","minimum":1},"outcome":{"type":"string","enum":["STARTED","SUCCESS","RETRY_SCHEDULED","TERMINAL_FAILURE","AUTHORIZATION_CANCELLED"]},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"durationMs":{"type":"integer","minimum":0,"nullable":true},"endpoint":{"type":"string","format":"uri","nullable":true,"description":"Origin and path only; userinfo and query are omitted."},"requestTimestamp":{"type":"string","nullable":true},"requestBodySha256":{"type":"string","nullable":true,"pattern":"^[0-9a-f]{64}$"},"responseStatus":{"type":"integer","nullable":true},"responseContentType":{"type":"string","nullable":true},"responseBody":{"type":"string","nullable":true,"maxLength":2048},"responseBodySha256":{"type":"string","nullable":true,"pattern":"^[0-9a-f]{64}$"},"responseBodyTruncated":{"type":"boolean"},"retryable":{"type":"boolean","nullable":true},"retryAfterMs":{"type":"integer","nullable":true},"nextRetryAt":{"type":"string","format":"date-time","nullable":true},"diagnosisCode":{"type":"string","nullable":true},"errorMessage":{"type":"string","nullable":true}}},"ConnectorWebhookDeliveryDetail":{"type":"object","additionalProperties":false,"required":["delivery","payload","rawBody","rawBodySha256","attemptHistoryComplete","endpoint","signature","attempts"],"properties":{"delivery":{"$ref":"#/components/schemas/ConnectorWebhookDelivery"},"payload":{"$ref":"#/components/schemas/ConnectorWebhookEvent"},"rawBody":{"type":"string","nullable":true,"description":"Exact byte sequence signed and sent. Null for older evidence."},"rawBodySha256":{"type":"string","nullable":true,"pattern":"^[0-9a-f]{64}$"},"attemptHistoryComplete":{"type":"boolean"},"endpoint":{"type":"string","format":"uri","nullable":true},"signature":{"type":"object","additionalProperties":false,"required":["algorithm","signedValue","signaturePersisted"],"properties":{"algorithm":{"type":"string","enum":["HMAC-SHA256"]},"signedValue":{"type":"string","enum":["{X-Webhook-Timestamp}.{rawBody}"]},"signaturePersisted":{"type":"boolean","enum":[false]}}},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorWebhookDeliveryAttempt"}}}},"ConnectorWebhookReplayResult":{"type":"object","additionalProperties":false,"required":["accepted","deduplicated","replayedFrom","deliveryId","webhookId","eventId","status","links"],"properties":{"accepted":{"type":"boolean","enum":[true]},"deduplicated":{"type":"boolean"},"replayedFrom":{"type":"string","format":"uuid"},"deliveryId":{"type":"string","format":"uuid"},"webhookId":{"type":"string"},"eventId":{"type":"string","nullable":true,"description":"Unchanged from the source delivery."},"status":{"type":"string","enum":["PENDING","RETRYING","SUCCESS","FAILED"]},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"ConnectorWebhookTestSuiteRequest":{"type":"object","additionalProperties":false,"required":["customerRef"],"properties":{"customerRef":{"type":"string","minLength":1,"maxLength":100},"event":{"type":"string","enum":["document.queued","document.delivered","document.received","document.processed","document.needs_attention","document.failed","document.cancelled","customer.active","customer.integration_detachment_scheduled","customer.integration_detachment_cancelled","customer.integration_detached","customer.provider_change_requested","customer.provider_change_cancelled","customer.provider_changed","customer.deactivated"],"default":"document.queued"},"scenarios":{"type":"array","minItems":1,"maxItems":7,"uniqueItems":true,"items":{"type":"string","enum":["success","deduplication","retry_503","rate_limit_429","terminal_422","timeout","signature"]},"default":["success","deduplication","retry_503","rate_limit_429","terminal_422","timeout","signature"]}}},"ConnectorWebhookTestSuiteAccepted":{"type":"object","additionalProperties":false,"required":["testRunId","status","deduplicated","deliveryIds","expiresAt","links"],"properties":{"testRunId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["RUNNING"]},"deduplicated":{"type":"boolean"},"deliveryIds":{"type":"array","items":{"type":"string","format":"uuid"}},"expiresAt":{"type":"string","format":"date-time"},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"ConnectorWebhookTestSuiteStatus":{"type":"object","additionalProperties":false,"required":["testRunId","event","scenarios","status","createdAt","expiresAt","links"],"properties":{"testRunId":{"type":"string","format":"uuid"},"event":{"type":"string","enum":["document.queued","document.delivered","document.received","document.processed","document.needs_attention","document.failed","document.cancelled","customer.active","customer.integration_detachment_scheduled","customer.integration_detachment_cancelled","customer.integration_detached","customer.provider_change_requested","customer.provider_change_cancelled","customer.provider_changed","customer.deactivated"]},"status":{"type":"string","enum":["RUNNING","ACTION_REQUIRED","COMPLETED","FAILED","EXPIRED"]},"scenarios":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["scenario","complete","passed","failureReason","actionRequired","replayDeliveryId","deliveries"],"properties":{"scenario":{"type":"string","enum":["success","deduplication","retry_503","rate_limit_429","terminal_422","timeout","signature"]},"complete":{"type":"boolean"},"passed":{"type":"boolean","nullable":true},"failureReason":{"type":"string","nullable":true},"actionRequired":{"type":"string","enum":["REPLAY_TEST_DELIVERY"],"nullable":true},"replayDeliveryId":{"type":"string","format":"uuid","nullable":true},"deliveries":{"type":"array","items":{"type":"object"}}}}},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"links":{"type":"object","additionalProperties":{"type":"string"}}}}},"headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the rate-limit window resets","schema":{"type":"integer"}}},"securitySchemes":{"integratorBearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Short-lived JWT minted from an assigned compatible sk_int_* integrator credential. On Connector operations, the integrator-configured customerRef selects an approved company and X-Firm-Id is not used. Existing Enterprise API and SAPI credential flows remain supported by their respective contracts."}}},"security":[{"integratorBearerAuth":[]}],"x-epostak-advanced-openapi":"https://epostak.sk/api/openapi.enterprise.json","x-epostak-sdk":{"recommended":true,"languages":["TypeScript","Python","PHP",".NET","Java","Ruby"],"url":"https://github.com/staniduris/epostak-sdk#connector-erpintegrator-flow"},"x-epostak-compatibility":"Connector is additive. Existing supported Enterprise API and SAPI endpoints and credentials remain available.","x-epostak-private-preview":{"status":"private-preview","environment":"dev","access":"explicit-integrator-allowlist","unavailableBehavior":"opaque-404","productionAvailable":false}}