How to Write a B2B Portal Specification: Structure and Essential Sections
Contents
A good technical specification does not describe buttons and colors. It describes how the business works now, how it should work after launch, and by what rules. Without this, contractors estimate different things, quotes differ by multiples, and after launch disputes arise over "was this included in the project or not."
Technical Specification Structure
1. Goals and metrics
What should change and how to measure it: share of orders placed through the portal, order processing time, number of manual edits, manager workload. With current and target values.
2. Participants and roles
Dealers and their employees, managers, head of sales, accounting, warehouse, administrator. For each role: what they see, what they can do, and what they approve.
3. Scenarios
Step by step, from the user's perspective:
- a dealer places an order by SKU, from Excel, or by reordering;
- a dealer receives documents and a statement of account;
- a dealer submits a claim;
- a manager approves an over-limit order;
- an administrator connects a new dealer.
A scenario describes not only the happy path, but also error cases: out of stock, limit exceeded, price changed.
4. Business rules
- pricing: price types, discounts, promotions, manual prices;
- credit limits and behavior when exceeded;
- inventory reserves: when they are placed and when they are released;
- order multiples and units of measure;
- approvals: which orders, by whom, and within what timeframe.
5. Data map
| Object | Source | Service line | Frequency | What to do on error |
|---|---|---|---|---|
| Products | 1C | to the portal | when changed | retry, notification |
| Prices | 1C | to the portal | when changed | retry, block old prices |
| Orders | portal | to 1C and Bitrix24 | immediately | queue, retry |
| ... |
6. Integration requirements
Duplicate protection, queuing, retries, audit log, monitoring, daily reconciliation, behavior when the accounting system is unavailable.
7. Non-functional requirements
Response time, concurrent users, availability, backups, security, mobile support, data retention.
8. Acceptance
Test database, test scenarios, launch success criteria, pilot group composition, pilot timeline.
9. Support and development
Incident response time, data exchange monitoring, customization process, handover of code and access credentials.
Common Mistakes in Technical Specifications
- describing screens instead of scenarios;
- the phrase "prices are taken from 1C" without describing the rules;
- no section on errors and data exchange failures;
- no acceptance criteria;
- "two-way sync with 1C" without details on what exactly and how often;
- accounting system configuration and customizations are not specified;
- no support requirements.
What to Include with the Technical Specification
- 1C configuration name and version, or MoySklad plan;
- list of accounting system customizations;
- export of products and price types;
- examples of real orders from email and messaging apps;
- sample invoices for different clients;
- description of sales pipelines in Bitrix24, if CRM is involved.
Frequently asked questions
Can you start without a technical specification?
You can start with an audit and scoping, which will produce a technical specification. Starting development without documented rules is risky.
How long does it take to prepare a technical specification?
Usually two to six weeks, depending on process complexity and the availability of people on the company side.
Who should approve the technical specification?
The sales process owner, accounting, the person in charge of the accounting system, and the executive who accepts the project.
Do you need a technical specification for an off-the-shelf solution?
Yes, at least in an abbreviated form: it shows what customizations will be needed.
