Advertisement
Not a member of Pastebin yet?
Sign Up,
it unlocks many cool features!
- openapi: '3.0.3'
- info:
- title: Tollar AdSystem API
- version: '1.0.0'
- description: |
- Tollar AdSystem is Tezro bonus and promotion system for merchants.
- ---
- This API is available for merchants of Tezro after registering in Tollar AdSystem using app.
- <b>Summary</b>
- - The system is for merchants, who plans to improve customer conversions and sails using givebacks (bonus) to customers based on their activity (e.g. X funds for product view or share)
- - The API is used as bridge between merchants' system and Tezro AdSystem.
- - Currently API provides two endpoints:
- - `POST /activities` - for sending tracked customer activity to Tezro for future givebacks to customer. Available to use right from client-side (browser or mobile app)
- - `GET /customers/:customer_id` - for retrieving customers current state in Tezro bonus system
- - Detailed description of DTOs and data types are described right in schemas, please expand them to get more info
- <b>Developer notes</b>
- - Currently API Security is under construction and accepts any valid string value (error causes if `PublicApiKey` header is missing`)
- - All endpoints require `PublicApiKey`
- - Private (server-to-server) endpoints will also require `SignedAuthKey` auth header (currently is /customers/ and it's under construction)
- - `POST /activities` endpoint in the production mode will also use extra mechanisms like origin domains and ip adresses whitelisting, browser fingerprinting and rate-limits to reduce system abuse from public and fraudulent access
- - Timestamp header is used to validate actuality of requests and reply MITM attacks
- servers:
- - url: https://dev-openapi.tezro.com/adsystem/mock
- description: Dev mock server
- - url: http://localhost:8080
- description: For local development
- tags:
- - name: Activities
- description: Endpoints realted to creating customer activities
- - name: Customers
- description: Endpoints realted to tracking customers' info
- paths:
- /activities:
- post:
- operationId: addActivity
- summary: Add new activity info
- description: Based on `customer_id` will register new or update existing customer info.
- tags:
- - Activities
- security:
- - PublicApiKey: []
- parameters:
- - $ref: '#/components/parameters/Timestamp'
- requestBody:
- required: true
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/AddActivityPayloadDto'
- responses:
- '400':
- $ref: '#/components/responses/400_bad_request'
- '401':
- $ref: '#/components/responses/401_missing_auth'
- '403':
- $ref: '#/components/responses/403_forbidden'
- '201':
- $ref: '#/components/responses/201_empty_ok'
- /customers/{customer_id}:
- get:
- operationId: getCustomer
- summary: Get customer info
- tags:
- - Customers
- security:
- - PublicApiKey: []
- - SignedAuthKey: []
- parameters:
- - $ref: '#/components/parameters/Timestamp'
- - in: path
- required: true
- name: customer_id
- examples:
- Customer not linked to Tezro:
- value: customer-not-linked-to-tezro
- Customer linked to Tezro:
- value: customer-linked-to-tezro
- schema:
- $ref: '#/components/schemas/CustomerId'
- responses:
- '401':
- $ref: '#/components/responses/401_missing_auth'
- '403':
- $ref: '#/components/responses/403_forbidden'
- '404':
- $ref: '#/components/responses/404_not_found'
- '200':
- description: Customer info
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/CustomerDto'
- examples:
- Customer not linked to Tezro:
- description: Example state of DTO for customer, who not authorized and linked account in Tezro yet
- value:
- customer_id: customer-not-linked-to-tezro
- created_at: 2024-05-14T05:02:34.234Z
- code: 'refer-code-customer-not-linked-to-tezro'
- link_to_app: 'https://tezro.app.link/customer-not-linked-to-tezro'
- balance:
- total_earned_tollars: '10'
- total_earned_in_usd: '0.01'
- today_earned_tollars: '10'
- today_earned_in_usd: '0.01'
- Customer linked to Tezro:
- description: Example state of DTO for customer, who linked account in Tezro
- value:
- customer_id: customer-linked-to-tezro
- created_at: 2024-05-14T05:02:34.234Z
- code: 'refer-code-customer-linked-to-tezro'
- link_to_app: 'https://tezro.app.link/customer-linked-to-tezro'
- balance:
- total_earned_tollars: '100'
- total_earned_in_usd: '0.1'
- today_earned_tollars: '10'
- today_earned_in_usd: '0.01'
- linked_user_id: tezro-user-id
- linked_user_at: 2024-05-14T15:02:34.234Z
- components:
- # Security schemas for current API
- # TODO WIP
- securitySchemes:
- PublicApiKey:
- type: apiKey
- name: KeyId
- in: header
- SignedAuthKey:
- type: apiKey
- name: x-tezro-signature
- in: header
- description: WIP. Calculated for every request. For mock or dev servers may pass `API_INTEGRATE`.
- parameters:
- Timestamp:
- name: timestamp
- in: header
- required: true
- schema:
- $ref: '#/components/schemas/DateTime'
- # DTOs and other data types
- schemas:
- DateTime:
- description: System wide date-time format. Prefer to use UTC time.
- externalDocs:
- url: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6
- type: string
- format: date-time
- example: 2024-05-14T05:02:34.234Z
- CustomerId:
- type: string
- description: "Customer's id"
- example: 'ea077b53-012d-4efe-99b6-2de5a17630dd'
- # Add new activity request payload
- AddActivityPayloadDto:
- type: object
- required:
- - tag
- - customer_id
- - entity_id
- properties:
- tag:
- $ref: '#/components/schemas/ActivityTagEnum'
- customer_id:
- $ref: '#/components/schemas/CustomerId'
- entity_id:
- description: Entity is universal name for this endpoint. Pass here system-wide unique value for entity like product, order, product review and etc.
- type: string
- example: 'some-product-or-order-or-other-entity-id'
- meta:
- description: |
- Any valid JSON object. Tezro stores it and provides you ability to do analytics based on this data
- You are able to pass here extra info about event (e.g. customers' session duration or current page info or product review notes)
- type: object
- example: { key: value }
- # Activity types (enum)
- ActivityTagEnum:
- type: string
- description: Activity tag unique code. List below is to be extended in the future.
- example: 'view_product'
- enum:
- - view_product
- - buy_product
- - share_product
- - favorite_product
- - view_shared_product
- - buy_shared_product
- - leave_review
- # Merchant's
- CustomerDto:
- type: object
- description: Customer info
- required:
- - id
- - created_at
- - code
- - link_to_app
- properties:
- customer_id:
- $ref: '#/components/schemas/CustomerId'
- created_at:
- $ref: '#/components/schemas/DateTime'
- code:
- type: string
- example: sOmEUnIqUeReFeRaLcOdE
- link_to_app:
- type: string
- description: Deeplink. Generate QR code based on this value, so customers are available to navigate to Tezro and get givebacks to their wallet.
- example: https://tezro.app.link/customer-referal-link
- balance:
- $ref: '#/components/schemas/CustomerBalanceDto'
- linked_user_id:
- type: string
- description: Available after authorizing in Tezro app and linking customer account.
- example: 'some-tezro-user-id'
- linked_user_at:
- $ref: '#/components/schemas/DateTime'
- CustomerBalanceDto:
- description: |
- Customer's balance info.<br />
- P.s. Tollar - abstract currency in context of current system.<br />
- P.p.s $ equivalents are recalculated by actual rate on time of request.
- type: object
- properties:
- total_earned_tollars:
- description: All time earned funds.
- type: string
- default: '0'
- example: '1000.00'
- total_earned_in_usd:
- description: $ equivalent of all time earned funds.
- type: string
- default: '0'
- example: '10.00'
- today_earned_tollars:
- description: Earned funds since 00:00:00 (UTC) until current time.
- type: string
- default: '0'
- example: '1000.00'
- today_earned_in_usd:
- description: $ equivalent of earned funds since 00:00:00 (UTC) until current time.
- type: string
- default: '0'
- example: '10.00'
- # Common error response structure
- ErrorResponseDto:
- description: Common error response payload
- type: object
- required:
- - code
- - message
- - description
- properties:
- code:
- description: HTTP status code
- type: number
- example: 400
- message:
- description: ERROR_CODE
- type: string
- example: FORBIDDEN
- description:
- description: More detailed info
- type: string
- example: Entity not found
- # Common responses
- responses:
- 201_empty_ok:
- description: Ok, entity created
- 400_bad_request:
- description: Bad request payload
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/ErrorResponseDto'
- 401_missing_auth:
- description: Required to provide auth credentials
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/ErrorResponseDto'
- 403_forbidden:
- description: You are not allowed to perform this request
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/ErrorResponseDto'
- 404_not_found:
- description: Resource not found
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/ErrorResponseDto'
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement