Vendor registration via social networks

Instructions for Vendor registration via social networks

What the add-on does

The add-on links user creation through a social network to the creation of a vendor company. It uses providers from the standard social authentication add-on, hybrid_auth. It also provides registration, sign-in, password change and recovery operations for external applications, and extends the company API with the ms_companies entity.

Social sign-in on the storefront and API registration are separate flows. When a social provider creates a new user, the add-on assigns an active company status and the vendor user type. API registration instead takes account of the marketplace settings for vendor applications and two-step approval.

Where to find the add-on

• In the Vendor registration via social networks add-on card, the General tab contains the API entity ms_companies section with three settings.
• The Information tab contains the “API Method Extension” and “Registration and authorization users by API” reference sections. The Instruction tab displays this manual.
• Social providers and their storefront availability are configured in the standard social authentication add-on, not through these three settings.
• Related administration screens include vendor profile fields, product filters, the vendor list and vendor cards, and vendor administrator accounts. Use them to map fields and verify a created company.
• On the storefront, the entry point is the sign-in form with social provider buttons.

Before configuring the add-on

Social sign-in requires a configured provider in hybrid_auth. The add-on displays only active providers from the supplied list; it does not add its own social network list or OAuth credential settings. Verify that the selected provider supplies enough information to create the user and company, including an email address.

For API registration, check the general vendor settings that allow vendor applications (apply_for_vendor) and enable two-step vendor approval (allow_approve_vendors_in_two_steps). Without permission to apply, API registration returns access denied. With two-step approval, this add-on does not automatically activate the new company.

Extended scenarios depend on the project environment. Performer search uses the active ms_tasks_and_services add-on. Detailed company responses query the ms_task_or_service service marker, while registration and sign-in query Rocket.Chat integration fields. These dependencies are not declared in this add-on’s addon.xml. Before connecting an external application, the integrator should verify the related extensions and data; the code does not establish that these operations work on a clean CS-Cart installation without them.

Configure the fields and filter

All three settings on the General tab are dropdown lists. They select existing profile fields and filters rather than creating new ones.

1. Check that vendor profile fields exist for the performer flag and personal information. The dropdowns list vendor profile field descriptions; fields belonging to another profile type may not appear.
2. Select the matching fields in Become a performer and About me.
3. If the application searches performers by rate, select the corresponding Rate per hour filter.
4. Save the add-on settings. Populate the fields for a test vendor and check the detailed API response.

A blank option means no mapping: the corresponding API alias will not be linked to a profile field, and a blank rate filter will not restrict results by amount. Selecting fields does not populate vendor data. An empty about_me value is not copied into the selected field, so clearing that field through this shorthand parameter is not supported by the mapping code.

How social registration works

1. The visitor opens the storefront sign-in form and selects an available social provider.
2. The visitor authenticates with the provider and returns to the site.
3. When creating a new user, the add-on creates a company. If no company name is supplied, it uses the email address.
4. The company is assigned active status and the account is linked to it as a vendor. During the subsequent OAuth profile update, the associated user is marked as the primary vendor administrator.

This behaviour applies to user creation through social authentication. The add-on does not provide a separate bulk conversion flow for existing customers. Test a new social account and repeat sign-in separately. The button template sets the return address to the storefront home page; it does not specify an automatic redirect to the vendor panel.

Registration, sign-in and passwords through the API

The operations below use the storefront /index.php endpoint and a dispatch parameter. They are not routes under /api/ms_companies. Use HTTPS and POST with form parameters: the controller reads request parameters but does not parse an arbitrary JSON body itself. Configure credentials through the client’s protected HTTP Basic Auth settings, not in the URL.

Registration with an existing user email redirects to authorization rather than creating another vendor. The client must handle the redirect and repeat sign-in at the trusted site address. If the company name matching the email already exists but the user does not, the response reports “Company exists”.

The Information tab describes registration without a password and delivery of a password by email. Account creation and notifications in that scenario are delegated to CS-Cart: verify the resulting account and email on your particular build. Supplying an email address alone is not proof of completed registration.

Registration and sign-in also return rocket_chat_user_id and rocket_chat_auth_token read from the company. These values may be empty; their presence in the response does not mean a new Rocket.Chat user has been created. Store returned keys in the application’s protected storage.

Inspect the JSON status field, not just the HTTP status. These operations output JSON with their own status; the controller does not explicitly set the matching HTTP status. Error responses include error_message.

Company data through ms_companies

Requests to /api/ms_companies require an API-enabled account with the appropriate CS-Cart permissions. Administrative operations use vendor viewing and management permissions; customer API access declares separate view_ms_companies and manage_ms_companies privileges. Receiving a key alone does not grant access to every operation.

• GET /api/ms_companies returns a company list in mscompanies and search parameters in params. Use items_per_page and page for pagination.
• GET /api/ms_companies/{company_id} returns one company, its logos, a profile_link, and categories derived from active service products. Nonempty mapped profile values appear inside fields.
• GET /api/ms_companies?get_current=Y selects the company associated with the current API account. The user must have a company association: without one, the code may return a list instead of the user’s own company.

The entity is also intended for viewing other vendors. Updates have a separate ownership check: an account associated with a company is not intended to modify another company.

POST /api/ms_companies creates a company when vendor management permissions are available. The required fields are company and email. Use create_vendor_admin=Y or is_create_vendor_admin=Y to request administrator creation, and notify_vendor_admin=Y to request a notification during that creation. If the administrator email is already in use, the company may still be created while the response contains a message explaining that its administrator was not created. Check both records.

PUT /api/ms_companies/{company_id} updates company data. For the mapped fields, use executor with Y or N, and a nonempty about_me value. Example body without credentials:

{
  "status": "A",
  "executor": "Y",
  "about_me": "Store configuration consulting"
}

Explicitly supply status when updating a company. If it is omitted or is not a valid CS-Cart vendor status, the add-on substitutes active status. The example deliberately uses A for an active company; supply the intended valid status for other companies.

The profile_picture parameter accepts a Base64 image Data URI with an allowed extension. Successful processing replaces the company’s theme logo. Supplying an empty parameter removes the existing image; omit the parameter when the image must remain unchanged. Keep the original logo before replacing it and verify the storefront afterwards: a response containing company_id does not confirm that the image was processed successfully.

Performer search and rate filtering

Add get_performers=Y to a list request. This mode requires an active ms_tasks_and_services add-on and its performer lookup function. Otherwise, the code falls back to a regular company list; that result must not be treated as a filtered performer list.

GET /api/ms_companies?get_performers=Y&min_rate=100&max_rate=2000&currency=RUB

• min_rate is the lower rate boundary; it defaults to 0.
• max_rate is the upper boundary. When a range filter is applied and this boundary is omitted or 0, the highest rate among active companies is used.
• currency is the range currency; the store’s primary currency is used when omitted.
• A range is applied only when a Rate per hour filter is selected and at least one boundary is nonzero. Omitting both boundaries adds no rate restriction.
• category_id, cid, or parent_cid selects the category, in that order of priority. Otherwise, the service category from the related add-on is used, or 0 if none is configured.

How to check the result

1. Use a separate test social account with no existing store user. Check that the storefront shows only active provider buttons, then complete sign-in.
2. Find the created vendor in the administration panel. Check its name, email, active status, company association and administrator role. Sign in again and verify that the same account is used.
3. For the API flow, register another test email. Compare the actual company status with the two-step approval setting and check both the JSON response and emails.
4. Sign in with the password, save the new API key, and request the current company using get_current=Y. Compare its identifier with the vendor card.
5. Populate Become a performer and About me, then check fields.executor and fields.about_me in the detailed response. Update them through the API and read the company again.
6. If performer search is used, compare a regular list with get_performers=Y, then test the category and range against vendors with known rates.
7. On a test account, verify password change, sign-in with the new password, and recovery email delivery. If the application changes pictures, separately inspect the storefront logo.

Troubleshooting

• Missing social buttons: check provider status and configuration, and whether the current theme uses the standard hybrid_auth block.
• Registration access denied: check permission to apply as a vendor. For a denial on /api/ms_companies, separately check API access and account privileges.
• “Email is empty” or missing email/password: check the Basic Auth fields and whether the web server passes authentication through. During password change, “Email is empty” can also mean a missing new password or Basic Auth password field.
• Wrong password or unknown user: check the email and password; an API key cannot replace the password for sign-in. Update the application’s stored key after a new authorization.
• Missing executor/about_me: check field mapping, populated values, and that the request retrieves an individual company rather than a list.
• Filtering has no effect: check the related add-on, selected rate filter, actual rates, and service category.
• Creation/update failure or an SQL error instead of JSON: review the error and server log with the integrator, especially the Rocket.Chat data and tasks/services extension. Do not treat registration as successful until both the company and user have been verified.

API login using a computed email hash is no longer supported. Use the current password for authorize; completing social login on the storefront does not replace password verification in this operation.