Operator APIs — How They Work
This page should give you a general introduction how the operator interfaces of PRISMA work and how the general setup is done.
TL;DR Pick a primary channel (SOAP, AS2, SFTP/FTPS or e-mail), configure a fallback — it is mandatory — send us endpoints plus credentials or certificates, validate on TEST, then we schedule PROD. S/MIME keys must be RSA. Production passwords must not contain spaces.
Transport channels
Pick one primary channel. You do not need a backend — e-mail or SFTP alone is a valid setup.
| Channel | Synchronous | As primary | As fallback |
|---|---|---|---|
| SOAP over HTTPS | yes | yes | — |
| AS2 | no | yes | — |
| SFTP / FTPS | — | yes | yes |
| E-Mail (S/MIME) | — | yes | yes |
Fallback
A fallback is mandatory, if AS2 or SOAP is chosen. If your backend is unreachable, we deliver through it.
| Encrypted with S/MIME using the public key you supplied, sent to your fallback address | |
| File (SFTP/FTPS) | SOAP envelope stripped, written to the directory configured for that interface |
| Filename | yyyyMMdd-HHmmss-SSS |
Keep your fallback address in sync with your technical contacts.
What to send us
Endpoint and environment
- Interface(s) and target environment
- Complete TEST and PROD endpoint URLs, and which version is deployed at each
- Confirmation that the endpoint is reachable from PRISMA
- IP allowlisting, firewall rules, VPN or proxy requirements
- For SOAP: SOAP version, expected content type, expected HTTP status codes
- Fallback configuration (mandatory)
Per channel and interface
| Channel | Required |
|---|---|
| SOAP | Endpoint URLs, credentials (below) |
| AS2 | AS2 id, endpoint URL, certificates (below) |
| SFTP / FTPS | Server address, port, username, password / server certificate |
| Recipient address, public key for S/MIME encryption |
Certificates
AS2 uses two separate certificates. They are not interchangeable.
| Purpose | Required | |
|---|---|---|
| S/MIME certificate | Signing and encryption at message level | always |
| SSL certificate | TLS at transport level | only if your backend uses TLS |
- S/MIME public keys must be RSA. ECC is not supported.
- SSL certificates are expected in PEM format (
.pem,.crt,.cer). - Certificate replacements are scheduled: we agree a switch date with you and activate the new certificate on that date.
Credentials
Only SOAP needs credentials. AS2 authenticates with certificates alone. One pair for Basic Authentication and one for Web Service authentication, per direction, preferably with the following naming conventions:
<TSONAME>_2_PRISMA_HTTP
PRISMA_2_<TSONAME>_HTTP
<TSONAME>_2_PRISMA_WS
PRISMA_2_<TSONAME>_WS
- Share passwords through a secure exchange or a one-time link. Never in plain e-mail.
- If a password is no longer available unhashed, create a new pair.
- Production passwords must not contain spaces.
Environments
| TEST | Configure and validate here first |
| PROD | Scheduled only after TEST is validated |
Versioning
- Several minor versions run in parallel. You choose the one you implement.
- Removing data on outgoing interfaced means a new major version and a 12-month adaptation period.
- Changes (e.g. urgent bug fixes, security fixes etc.) to a version you already run live are agreed with you bilaterally.
- Breaking changes after a TEST rollout are announced by e-mail to the TSO User Group plus a market message on TEST.
Getting connected
Configure and validate the connection on TEST before scheduling any production migration.
- Tell us the interface(s), target version, environment, planned activation or migration date, and the technical contact or team carrying out the change.
- We configure TEST.
- You validate on TEST.
- We schedule PROD.