Starting the sandbox: the shortest way to a first response
Most integrations fail not on technology but on time to the first success. Anyone needing three weeks until a test document is signed loses backing in the team and with management. Our goal for the developer hub is therefore simple: a developer should get from registration to a first successful request within an afternoon. The sandbox is the place for that, a test environment where you can try flows without triggering real transactions.
Begin with the prerequisites. You need access to the developer hub, sandbox credentials, a way to send HTTP requests and a simple test document. A one-page PDF suffices. The exact steps for registration, access methods and current endpoints are in the developer hub documentation, and we deliberately do not describe them in detail here so this article does not age when details change.
A smart first step is a connection test: a simple request that only checks whether your credentials are valid and the environment responds. That sounds banal and saves hours of troubleshooting later because you separate authentication and network problems from business problems. Note response times and the structure of responses, since your own code will have to process them. Many teams save time by trying the first calls in an API client before writing code.
Also store configuration and secrets cleanly from the start. Credentials belong neither in source code nor in chat messages but in a secrets manager or at least in environment variables. Separate sandbox and production access strictly and name configurations so mix-ups are unlikely. That is standard hygiene but especially important with signature data because it concerns confidential contracts. Guidance on secure configuration is available from the BSI.
A word on expectations: the sandbox mirrors the behaviour of the production environment but is not identical in every detail. Individual procedures, such as identifications or steps requiring a partner, behave differently in tests or are simplified. That is normal and intended, because real identifications in test environments would be neither sensible nor compliant with data protection. Plan a separate acceptance test before going live. What exactly is possible in the sandbox is in the documentation.
The first envelope: from document to invitation
At the centre of every integration stands the signing transaction, which we call an envelope in daily talk: a container bundling documents, signers, order, level and settings. The first envelope should be as simple as possible: one document, one signer, simple (SES) or advanced signature (AES), no special rules. The goal is not feature scope but a transaction that runs through so you understand the interplay.
Conceptually creation consists of four steps. First, create the transaction and pass your own reference so you can find it later. Second, add the document and define where to sign. Third, register the signers with name, contact route and role. Fourth, start the transaction, whereupon the invitation is sent. Exact calls, fields and response formats are in the API reference. Stick to it instead of guessing from other vendors' examples.
After the start we recommend running through the transaction as the signer. Open the invitation, read the texts, click through the steps and sign. This change of view is underrated: developers often know only the API side and are surprised how the flow feels to users. Note oddities such as unclear texts, too many clicks or error messages. These observations feed your design later, especially when you embed the flow in your interface.
Then look at the result: which information do you receive at the end? The signed document, details of the process, times, where applicable evidence. Check where you retrieve this data, how long it stays available and in which format. Decide where your system stores the signed document and check that the checksum matches the original you handed over. That shows early whether your storage meets requirements.
Once the first envelope runs, extend step by step: several signers, order, reminders, deadlines, templates. Always extend only one thing at a time and test it before adding the next. That way you know where an error lies. Whoever builds in five functions simultaneously searches in five directions when problems arise. How flows can later be embedded without a media break is described in white-label signature API without context switching.
Connecting webhooks: your system learns what happens
Without a return channel your integration is blind. After the envelope starts, your system does not know whether the signer opened, signed or declined. Webhooks close this gap by letting the signing flow report state changes actively to an endpoint in your application. The sandbox is good for practising because errors stay without consequences.
To start you need a reachable endpoint. In local development that is the first practical hurdle because your machine is not reachable from the internet. Tools that temporarily expose local ports, or a simple test server in the cloud, solve that. Make sure to use such access only for tests and switch it off afterwards. Register the endpoint per documentation and then trigger events by running the test transactions.
The first endpoint should only receive and log: verify the message, write it to a table or file and answer with a success code. Nothing more. Look closely at the payload: which fields does it contain, what do event types look like, how are times formatted, which references come back? This knowledge is the basis of your state model. Only then build logic, with idempotency, state machine and retries, as we describe in webhook state management for e-signature events.
Test failure cases as well. What happens when your endpoint returns an error code? Is the message retried? How does your system react to duplicate delivery? What happens if you process events in another order? The sandbox is the right place to provoke such situations deliberately. Whoever meets them first in production meets them under pressure. Create a small set of test cases and run it again after every larger change.
Do not forget authenticity. Your endpoint should verify that messages really come from the signing flow, as the documentation describes. That belongs in the code from the start, not in a later hardening phase, because an endpoint accepting everything unchecked is a gateway. Work in the sandbox as you will in production so the transition brings no surprises.
Preparing the QES path: what else needs clarifying
The qualified electronic signature (QES) differs from SES and AES not in the basic structure of your integration but in the parties involved. Sign2x is not a qualified trust service provider, and for QES we work with partner QTSPs such as Sign8. For your preparation that means: besides technical connection, organisational and contractual questions must be clarified, and they often take more time than the code. Start early.
First the business question: for which document types do you really need QES? AES vs QES via API helps with classification. Then the procedure question: which identification procedures should your users use, and which are practical for your target group? Then the contract question: which agreements are needed with Sign2x and the partner, and how are responsibilities and data flows regulated? And finally the operations question: who supports users when identification fails?
Technically three things change. First, the level is set in transaction creation, and the flow contains additional steps. Second, new events are added, especially around identification, and your state model should map them. Third, duration grows: identification and certificate creation take time, and users interrupt. Your interface should support waiting states, reminders and resumption. Whether and in which form a QES run is possible in the sandbox, discuss with us, because real identifications in test environments are not sensible.
Legally, QES is not permissible or needed for every transaction. Check with your legal counsel whether a form requiring QES is prescribed for your transaction and whether electronic form is permitted at all. The basics of the signature levels are in the eIDAS Regulation. For business with an AML link, identification requirements are added, which we classify in AML-ready signature API for ISVs.
A pilot with real users is indispensable for QES. Choose a small group, such as internal staff or friendly customers, and accompany them. Observe where they hesitate, where they drop out and which questions they ask. From these observations come better texts, better hints and sometimes a different order. Allow several weeks and do not expect the first version to be perfect. On hosting, Sign2x answers with operation on the Open Sovereign Cloud (OSC) from T-Systems, under European law, which you can record in your documentation.
Typical stumbling blocks and how to avoid them
From supporting development teams we know recurring stumbling blocks. The first is document change after start: a document is altered after the transaction has begun and the checksum no longer matches. Solution: finalise documents before starting and store the checksum. The second is missing reference: without your own identifier in the transaction you cannot assign webhooks. Solution: always pass your reference, in multi-tenant systems together with the tenant identifier.
The third stumbling block is polling instead of webhooks: out of habit teams query states regularly instead of receiving events. That works in tests and breaks at volume. Solution: plan webhooks from the start, a reconciliation as a safety net suffices. The fourth is missing idempotency: duplicate delivery leads to duplicate follow-ups. Solution: store the event ID, enforce uniqueness, write state and history in one transaction.
The fifth stumbling block is mixing sandbox and production. Credentials get confused, test transactions land in real systems or vice versa. Solution: separate configurations, clear naming, safeguards preventing production in test environments. The sixth is underestimated user guidance: the technology runs but users do not understand the flow. Solution: test texts, explain steps, provide help, for example via the help centre.
The seventh stumbling block concerns expectations on performance and availability. Anyone measuring response times in the sandbox and deriving production values is mistaken. Test environments have different load profiles. Plan load tests for your own use case in agreement with us and do not rely on blanket figures. We quote none because without your context they carry no meaning. If you plan high volumes, bulk signature API for enterprises helps.
Finally a suggested plan for the first two weeks. Week one: set up the sandbox, connection test, first envelope, run through as signer, webhook endpoint with logging. Week two: state model, idempotency, first interface integration, failure cases, hand over to the business team for testing. After that decide whether and when to tackle QES and bulk scenarios. If you need support along the way, use the documentation in the developer hub, the articles in the Sign2x blog, examples under use cases or ask us via contact. The Sign2x quiz also offers a first assessment.
Start the sandbox in the developer hub
Further reading: silent tech: signature inside ERP surfaces and DORA Article 30 and the signature audit trail. Legal background on data processing in the GDPR.
Frequently asked questions
How fast do I get to a first signature in the sandbox?
With valid credentials and a test document often within an afternoon. The exact steps are in the developer hub documentation.
Do I need webhooks for the first test?
Not for the first run, but for a real integration. Practise them early in the sandbox, with logging, idempotency and failure cases.
Can I fully test QES in the sandbox?
Real identifications are not sensible in test environments. Which parts of the QES path can be tested we discuss with you. Sign2x is not a QTSP, QES runs through a partner such as Sign8.
Which signature levels does Sign2x support?
SES, AES and QES. Start with the simplest level your transaction legally supports and extend later.
Where is Sign2x hosted?
On the Open Sovereign Cloud (OSC) from T-Systems, a European operation under European law.
