|
1
|
--- |
|
2
|
title: "ProcureNet Quickstart: Run Your First Orchestration Call" |
|
3
|
sidebarTitle: "Quickstart" |
|
4
|
description: "Start a WCS-scored procurement session, connect to the real-time stream, and advance your first state machine transition in under 10 minutes." |
|
5
|
--- |
|
6
|
|
|
7
|
This guide walks you through the fastest path to a working ProcureNet integration. You'll obtain your API key, start a scored orchestration session, connect to the session's real-time stream, and fire your first state transition — all with TypeScript examples you can run directly against the API. By the end, you'll have a live session flowing through ProcureNet's v7 orchestration pipeline. |
|
8
|
|
|
9
|
<Steps> |
|
10
|
|
|
11
|
<Step title="Obtain your API key"> |
|
12
|
ProcureNet uses separate credentials for different parts of the API. For session orchestration you need a **JWT token** (covered in [Authentication](/authentication)), but to call wallet and payment endpoints you'll need a **mod key**. |
|
13
|
|
|
14
|
Request your API key from the ProcureNet dashboard or your account team. Once issued, you'll use it as the `x-perplexity-mod-key` header on all wallet and payment requests. |
|
15
|
|
|
16
|
Store your key in an environment variable and never hard-code it in client-side code: |
|
17
|
|
|
18
|
```typescript |
|
19
|
// .env |
|
20
|
PROCURENET_MOD_KEY=your_mod_key_here |
|
21
|
PROCURENET_JWT=your_jwt_token_here |
|
22
|
PROCURENET_BASE_URL=https://api.procurenet.io |
|
23
|
``` |
|
24
|
|
|
25
|
<Warning> |
|
26
|
Never expose your `x-perplexity-mod-key` or JWT in browser-side JavaScript or public repositories. These credentials carry full API access for their respective scopes. |
|
27
|
</Warning> |
|
28
|
</Step> |
|
29
|
|
|
30
|
<Step title="Start an orchestration session"> |
|
31
|
Call `POST /api/v7/orchestrate` to create a session. Pass identity hints for the buyer — the more signals you provide, the higher the Wallet Confidence Score (WCS) and the richer the session capabilities you'll unlock. |
|
32
|
|
|
33
|
The `hints` object accepts any combination of `customerId`, `email`, `phone`, and `deviceId`. Each contributes to the WCS score: |
|
34
|
- `customerId` — 100 points |
|
35
|
- `email` — 40 points |
|
36
|
- `phone` — 40 points |
|
37
|
- `deviceId` — 20 points (max total: 200) |
|
38
|
|
|
39
|
```typescript |
|
40
|
const response = await fetch( |
|
41
|
`${process.env.PROCURENET_BASE_URL}/api/v7/orchestrate`, |
|
42
|
{ |
|
43
|
method: "POST", |
|
44
|
headers: { |
|
45
|
"Content-Type": "application/json", |
|
46
|
}, |
|
47
|
body: JSON.stringify({ |
|
48
|
amount: 1250.00, |
|
49
|
currency: "USD", |
|
50
|
hints: { |
|
51
|
customerId: "cust_01HXYZ9ABC", |
|
52
|
email: "buyer@example.com", |
|
53
|
phone: "+14155552671", |
|
54
|
deviceId: "dev_fingerprint_abc123", |
|
55
|
}, |
|
56
|
}), |
|
57
|
} |
|
58
|
); |
|
59
|
|
|
60
|
const session = await response.json(); |
|
61
|
console.log(session); |
|
62
|
``` |
|
63
|
|
|
64
|
A successful response returns the session identifier, the calculated WCS score, the resolved mode, and the transport type to use for your real-time connection: |
|
65
|
|
|
66
|
```json |
|
67
|
{ |
|
68
|
"session_id": "sess_01JKAB3MXPQ7RVTZWN5", |
|
69
|
"wcs_score": 200, |
|
70
|
"mode": "resolved", |
|
71
|
"transport": "sse" |
|
72
|
} |
|
73
|
``` |
|
74
|
|
|
75
|
Use the `mode` and `transport` fields together to decide how to connect in the next step. |
|
76
|
|
|
77
|
<Tip> |
|
78
|
A `wcs_score` of 200 means all four identity hints were present and valid. A score ≥ 100 puts the session in `resolved` mode and unlocks prefill data retrieval via `GET /api/v7/sessions/{id}/prefill`. |
|
79
|
</Tip> |
|
80
|
</Step> |
|
81
|
|
|
82
|
<Step title="Connect to the session stream"> |
|
83
|
ProcureNet pushes real-time session events over either SSE or WebSocket depending on the `transport` value in your orchestration response. Open the appropriate connection immediately after starting the session. |
|
84
|
|
|
85
|
<Tabs> |
|
86
|
<Tab title="SSE (resolved sessions)"> |
|
87
|
Use SSE when `transport` is `"sse"` — this applies to all sessions with a WCS score ≥ 100. |
|
88
|
|
|
89
|
```typescript |
|
90
|
// Connect to SSE stream for resolved sessions |
|
91
|
const sessionId = session.session_id; |
|
92
|
const streamUrl = `${process.env.PROCURENET_BASE_URL}/api/v7/sessions/${sessionId}/stream`; |
|
93
|
|
|
94
|
const eventSource = new EventSource(streamUrl, { |
|
95
|
// Pass auth via query param or use a server-side proxy |
|
96
|
// that adds the Authorization header |
|
97
|
withCredentials: true, |
|
98
|
}); |
|
99
|
|
|
100
|
eventSource.onmessage = (event) => { |
|
101
|
const data = JSON.parse(event.data); |
|
102
|
console.log("Session event:", data); |
|
103
|
}; |
|
104
|
|
|
105
|
eventSource.onerror = (error) => { |
|
106
|
console.error("SSE connection error:", error); |
|
107
|
eventSource.close(); |
|
108
|
}; |
|
109
|
``` |
|
110
|
</Tab> |
|
111
|
<Tab title="WebSocket (partial / anonymous sessions)"> |
|
112
|
Use WebSocket when `transport` is `"websocket"` — this applies to sessions with a WCS score below 100. |
|
113
|
|
|
114
|
```typescript |
|
115
|
// Connect to WebSocket stream for partial or anonymous sessions |
|
116
|
const sessionId = session.session_id; |
|
117
|
const wsUrl = `wss://api.procurenet.io/api/v7/sessions/${sessionId}/ws`; |
|
118
|
|
|
119
|
const ws = new WebSocket(wsUrl); |
|
120
|
|
|
121
|
ws.onopen = () => { |
|
122
|
// Authenticate the WebSocket connection on open |
|
123
|
ws.send( |
|
124
|
JSON.stringify({ |
|
125
|
type: "auth", |
|
126
|
token: process.env.PROCURENET_JWT, |
|
127
|
}) |
|
128
|
); |
|
129
|
}; |
|
130
|
|
|
131
|
ws.onmessage = (event) => { |
|
132
|
const data = JSON.parse(event.data); |
|
133
|
console.log("Session event:", data); |
|
134
|
}; |
|
135
|
|
|
136
|
ws.onerror = (error) => { |
|
137
|
console.error("WebSocket error:", error); |
|
138
|
}; |
|
139
|
``` |
|
140
|
</Tab> |
|
141
|
</Tabs> |
|
142
|
|
|
143
|
<Info> |
|
144
|
Keep your stream connection open for the lifetime of the session. ProcureNet emits state transition events, escrow status updates, and procurement intelligence results over this channel in real time. |
|
145
|
</Info> |
|
146
|
</Step> |
|
147
|
|
|
148
|
<Step title="Advance the session state"> |
|
149
|
Sessions move through a state machine. Call `POST /api/v7/sessions/{id}/transition` with the target state to advance the session. ProcureNet validates the transition against the current state and rejects illegal moves with a deterministic error code. |
|
150
|
|
|
151
|
```typescript |
|
152
|
const sessionId = session.session_id; |
|
153
|
|
|
154
|
const transitionResponse = await fetch( |
|
155
|
`${process.env.PROCURENET_BASE_URL}/api/v7/sessions/${sessionId}/transition`, |
|
156
|
{ |
|
157
|
method: "POST", |
|
158
|
headers: { |
|
159
|
"Content-Type": "application/json", |
|
160
|
Authorization: `Bearer ${process.env.PROCURENET_JWT}`, |
|
161
|
}, |
|
162
|
body: JSON.stringify({ |
|
163
|
target_state: "awaiting_payment", |
|
164
|
}), |
|
165
|
} |
|
166
|
); |
|
167
|
|
|
168
|
if (!transitionResponse.ok) { |
|
169
|
const error = await transitionResponse.json(); |
|
170
|
console.error("Transition rejected:", error); |
|
171
|
} else { |
|
172
|
const result = await transitionResponse.json(); |
|
173
|
console.log("New session state:", result.state); |
|
174
|
} |
|
175
|
``` |
|
176
|
|
|
177
|
After a successful transition, ProcureNet emits a transition event on your stream connection. Your stream handler receives the new state so your UI can update without polling. |
|
178
|
|
|
179
|
<Tip> |
|
180
|
For high-value transactions, call `POST /api/v7/sessions/{id}/escrow-accept` before the final transition to satisfy ProcureNet's legal compliance requirement. The escrow endpoint writes an immutable audit trail entry that unlocks the payment transition. |
|
181
|
</Tip> |
|
182
|
</Step> |
|
183
|
|
|
184
|
</Steps> |
|
185
|
|
|
186
|
## Deprecated Endpoint Notice |
|
187
|
|
|
188
|
<Warning> |
|
189
|
**`POST /api/payments/route` is deprecated** and will be removed in a future release. Migrate to the v7 pipeline: |
|
190
|
|
|
191
|
1. Call `POST /api/v7/orchestrate` to start a WCS-scored session. |
|
192
|
2. Call `POST /api/v7/sessions/{id}/funding-method` to set the payment method on the session. |
|
193
|
|
|
194
|
The old `/api/payments/route` endpoint does not support WCS scoring, transport selection, or the v7 state machine. Any new integration should use the v7 endpoints exclusively. |
|
195
|
</Warning> |
|
196
|
|
|
197
|
## Next Steps |
|
198
|
|
|
199
|
<CardGroup cols={2}> |
|
200
|
<Card title="Authentication" icon="lock" href="/authentication"> |
|
201
|
Understand all four credential types and when to use each one. |
|
202
|
</Card> |
|
203
|
<Card title="Prefill Data" icon="fill" href="/api/sessions-prefill"> |
|
204
|
Retrieve pre-populated buyer fields for resolved sessions (WCS ≥ 100). |
|
205
|
</Card> |
|
206
|
<Card title="USDC Payments" icon="circle-dollar-to-slot" href="/guides/field-evaluation-payments"> |
|
207
|
Pay field evaluators on-chain when offline evaluations sync. |
|
208
|
</Card> |
|
209
|
<Card title="Webhooks" icon="webhook" href="/guides/webhooks"> |
|
210
|
Handle Procurement Express callbacks with HMAC signature verification. |
|
211
|
</Card> |
|
212
|
</CardGroup> |