{"openapi":"3.0.3","info":{"title":"ePošťák Connector API","version":"1.5.1","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 the same customerRef-rooted business events; polling remains the reliable reconciliation checkpoint. 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. 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":"Account locked after 5 failed attempts","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. Sending is the default; `delivery=stage` only stores the document. `externalId` and `Idempotency-Key` are unique within the assigned Connector mailbox/customerRef. A replay of the same command returns the original result; 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}]}}}},"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 exact recipient matched the supplied tax identifier.","field":"recipient.taxId","retryable":false,"nextAction":"Verify the recipient identifier and country.","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","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 business event stream for one approved customerRef. customerRef is always at the event root. Persist nextCursor only after committing the returned events locally. The optional native Connector webhook pushes the same event item, while polling remains the reliable reconciliation checkpoint.","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/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.","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."},"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","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","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","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","additionalProperties":true}}}}},"x-epostak-visibility":"advanced","security":[{"integratorBearerAuth":[]}]}},"/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":{"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 subscribes to all seven Connector business events. 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":"The same canonical event item returned by GET /connector/events. 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; no Peppol or transport fields are exposed.","parameters":[{"name":"X-Webhook-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix timestamp included in the signature input."},{"name":"X-Webhook-Signature","in":"header","required":true,"schema":{"type":"string","example":"sha256=ab12..."},"description":"HMAC-SHA256 signature of timestamp + '.' + the exact raw request body."},{"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"]}},{"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/ConnectorBusinessEvent"},"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."}}},"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."}],"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"}}}}}}}},"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 key's allowed scopes. If omitted, the JWT inherits the key's full scope set (or `*` for wildcard keys)."}}},"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","self_billing_invoice","self_billing_credit_note"],"default":"invoice"},"number":{"type":"string","maxLength":255},"precedingDocumentNumber":{"type":"string","maxLength":255},"recipient":{"$ref":"#/components/schemas/ConnectorBusinessRecipientRequest"},"issueDate":{"type":"string","format":"date"},"dueDate":{"type":"string","format":"date"},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"EUR"},"note":{"type":"string","maxLength":5000},"iban":{"type":"string","maxLength":64},"paymentMethod":{"type":"string"},"variableSymbol":{"type":"string"},"buyerReference":{"type":"string"},"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},"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"]},"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},"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."},"response":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ConnectorBusinessInvoiceResponse"}],"description":"Current business response, or null when neither side has sent one."}},"additionalProperties":false},"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"}}},"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"]},"number":{"type":"string","nullable":true},"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."}}}}},"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","minimum":0,"exclusiveMinimum":true},"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"]},"discount":{"type":"number","minimum":0,"maximum":100},"deliveryDate":{"type":"string","format":"date"},"lineType":{"type":"string"},"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}},"additionalProperties":false},"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}}},"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"]}},"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":7,"uniqueItems":true,"description":"Optional event filter. Omit it to subscribe to all seven Connector business event types.","items":{"type":"string","enum":["document.queued","document.delivered","document.received","document.processed","document.needs_attention","document.failed","document.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"}}},"ConnectorWebhookTestEvent":{"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"]},"number":{"type":"string","nullable":true},"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."}}},"test":{"type":"boolean","enum":[true]}}},"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"]},"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"}}},"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"}}}},"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."}