· last year · May 15, 2024, 03:20 AM
1openapi: '3.0.3'
2info:
3 title: Tollar AdSystem API
4 version: '1.0.0'
5 description: |
6 Tollar AdSystem is Tezro promotion system for merchants.
7 ---
8 This API is available for merchants of Tezro after registering in Tollar AdSystem using app.
9
10servers:
11 - url: https://dev-openapi.tezro.com/adsystem/mock
12 description: Dev mock server
13 - url: http://localhost:8080
14 description: For local development
15
16tags:
17 - name: Activities
18 description: Endpoints realted to creating customer activities
19 - name: Customers
20 description: Endpoints realted to tracking customers' info
21
22paths:
23 /activities:
24 post:
25 operationId: addActivity
26 summary: Add new activity info
27 description: Based on `customer_id` will register new or update existing customer info.
28 tags:
29 - Activities
30 security:
31 - PublicApiKey: []
32 parameters:
33 - $ref: '#/components/parameters/Timestamp'
34 requestBody:
35 required: true
36 content:
37 application/json:
38 schema:
39 $ref: '#/components/schemas/AddActivityPayloadDto'
40 responses:
41 '400':
42 $ref: '#/components/responses/400_bad_request'
43 '401':
44 $ref: '#/components/responses/401_missing_auth'
45 '403':
46 $ref: '#/components/responses/403_forbidden'
47 '201':
48 $ref: '#/components/responses/201_empty_ok'
49
50 /customers/{customer_id}:
51 get:
52 operationId: getCustomer
53 summary: Get customer info
54 tags:
55 - Customers
56 security:
57 - PublicApiKey: []
58 - SignedAuthKey: []
59 parameters:
60 - $ref: '#/components/parameters/Timestamp'
61 - in: path
62 required: true
63 name: customer_id
64 examples:
65 Customer not linked to Tezro:
66 value: customer-not-linked-to-tezro
67 Customer linked to Tezro:
68 value: customer-linked-to-tezro
69 schema:
70 $ref: '#/components/schemas/CustomerId'
71 responses:
72 '401':
73 $ref: '#/components/responses/401_missing_auth'
74 '403':
75 $ref: '#/components/responses/403_forbidden'
76 '404':
77 $ref: '#/components/responses/404_not_found'
78 '200':
79 description: Customer info
80 content:
81 application/json:
82 schema:
83 $ref: '#/components/schemas/CustomerDto'
84 examples:
85 Customer not linked to Tezro:
86 value:
87 customer_id: customer-not-linked-to-tezro
88 created_at: 2024-05-14T05:02:34.234Z
89 code: 'refer-code-customer-not-linked-to-tezro'
90 link_to_app: 'https://tezro.app.link/customer-not-linked-to-tezro'
91 balance:
92 total_earned_tollars: '10'
93 total_earned_in_usd: '0.01'
94 today_earned_tollars: '10'
95 today_earned_in_usd: '0.01'
96 Customer linked to Tezro:
97 value:
98 customer_id: customer-linked-to-tezro
99 created_at: 2024-05-14T05:02:34.234Z
100 code: 'refer-code-customer-linked-to-tezro'
101 link_to_app: 'https://tezro.app.link/customer-linked-to-tezro'
102 balance:
103 total_earned_tollars: '100'
104 total_earned_in_usd: '0.1'
105 today_earned_tollars: '10'
106 today_earned_in_usd: '0.01'
107 linked_user_id: tezro-user-id
108 linked_user_at: 2024-05-14T15:02:34.234Z
109
110components:
111 # Security schemas for current API
112 # TODO WIP
113 securitySchemes:
114 PublicApiKey:
115 type: apiKey
116 name: KeyId
117 in: header
118 SignedAuthKey:
119 type: apiKey
120 name: x-tezro-signature
121 in: header
122 description: WIP. Calculated for every request. For mock or dev servers may pass `API_INTEGRATE`.
123
124 parameters:
125 Timestamp:
126 name: timestamp
127 in: header
128 required: true
129 schema:
130 $ref: '#/components/schemas/DateTime'
131
132 # DTOs and other data types
133 schemas:
134 DateTime:
135 description: System wide date-time format. Prefer to use UTC time.
136 externalDocs:
137 url: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6
138 type: string
139 format: date-time
140 example: 2024-05-14T05:02:34.234Z
141 CustomerId:
142 type: string
143 description: "Customer's id"
144 example: 'ea077b53-012d-4efe-99b6-2de5a17630dd'
145
146 # Add new activity request payload
147 AddActivityPayloadDto:
148 type: object
149 required:
150 - tag
151 - customer_id
152 - entity_id
153 properties:
154 tag:
155 $ref: '#/components/schemas/ActivityTagEnum'
156 customer_id:
157 $ref: '#/components/schemas/CustomerId'
158 entity_id:
159 type: string
160 example: 'some-product-or-order-or-other-entity-id'
161 meta:
162 description: Any valid JSON object
163 type: object
164 example: { key: value }
165
166 # Activity types (enum)
167 ActivityTagEnum:
168 type: string
169 description: Activity tag unique code. List below is to be extended in the future.
170 example: 'view_product'
171 enum:
172 - view_product
173 - buy_product
174 - share_product
175 - favorite_product
176 - view_shared_product
177 - buy_shared_product
178 - leave_review
179
180 # Merchant's
181 CustomerDto:
182 type: object
183 description: Customer info
184 required:
185 - id
186 - created_at
187 - code
188 - link_to_app
189 properties:
190 customer_id:
191 $ref: '#/components/schemas/CustomerId'
192 created_at:
193 $ref: '#/components/schemas/DateTime'
194 code:
195 type: string
196 example: sOmEUnIqUeReFeRaLcOdE
197 link_to_app:
198 type: string
199 example: https://tezro.app.link/customer-referal-link
200 balance:
201 $ref: '#/components/schemas/CustomerBalanceDto'
202 linked_user_id:
203 type: string
204 description: Available after authorizing in Tezro app and linking customer account.
205 example: 'some-tezro-user-id'
206 linked_user_at:
207 $ref: '#/components/schemas/DateTime'
208
209 CustomerBalanceDto:
210 description: |
211 Customer's balance info.<br />
212 P.s. Tollar - abstract currency in context of current system.<br />
213 P.p.s $ equivalents are recalculated by actual rate on time of request.
214 type: object
215 properties:
216 total_earned_tollars:
217 description: All time earned funds.
218 type: string
219 default: '0'
220 example: '1000.00'
221 total_earned_in_usd:
222 description: $ equivalent of all time earned funds.
223 type: string
224 default: '0'
225 example: '10.00'
226 today_earned_tollars:
227 description: Earned funds since 00:00:00 (UTC) until current time.
228 type: string
229 default: '0'
230 example: '1000.00'
231 today_earned_in_usd:
232 description: $ equivalent of earned funds since 00:00:00 (UTC) until current time.
233 type: string
234 default: '0'
235 example: '10.00'
236
237 # Common error response structure
238 ErrorResponseDto:
239 description: Common error response payload
240 type: object
241 required:
242 - code
243 - message
244 - description
245 properties:
246 code:
247 description: HTTP status code
248 type: number
249 example: 400
250 message:
251 description: ERROR_CODE
252 type: string
253 example: FORBIDDEN
254 description:
255 description: More detailed info
256 type: string
257 example: Entity not found
258
259 # Common responses
260 responses:
261 201_empty_ok:
262 description: Ok, entity created
263
264 400_bad_request:
265 description: Bad request payload
266 content:
267 application/json:
268 schema:
269 $ref: '#/components/schemas/ErrorResponseDto'
270
271 401_missing_auth:
272 description: Required to provide auth credentials
273 content:
274 application/json:
275 schema:
276 $ref: '#/components/schemas/ErrorResponseDto'
277
278 403_forbidden:
279 description: You are not allowed to perform this request
280 content:
281 application/json:
282 schema:
283 $ref: '#/components/schemas/ErrorResponseDto'
284
285 404_not_found:
286 description: Resource not found
287 content:
288 application/json:
289 schema:
290 $ref: '#/components/schemas/ErrorResponseDto'