Partner Link

The Partner Link API can be used to easily integrate your site with Cruvee at the web browser level to allow winery owners/staff on your site to “claim” their winery on Cruvee, edit their winery profile on Cruvee, and add/edit their wines on Cruvee. You can then immediately pull this updated information from Cruvee using the query APIs. Using this approach is an alternative to integrating with our (forthcoming) update APIs and is a convenient solution to initiating Own IT updates from your site.

Partner linking is done by redirecting users on your site to Cruvee, telling us what action you want the user to perform. Once the user has completed the action, they will be returned to your site. Furthermore, minor branding is applied to the Cruvee page when in Partner Linking mode to indicate the request is coming from your site and Cruvee’s navigation is hidden to keep the user on track with the intended workflow.

General Workflow

Partner Link Workflow

  1. User visits/signs in to your site.
  2. User initiates action on your site to begin the Partner Link functionality. This can be in the form of a button or link on your site. The button/link must resolve to code on your server. Note that you would already have queries Cruvee’s API to identify the winery or wine to add, edit, or claim.
  3. You build the appropriate Partner Link hyperlink and redirect the user to that link. This hyperlink must be built dynamically on your site at the time the user initiates the process (more details below). In other words, the partner links cannot be static or pre-built.
  4. Cruvee receives redirected user and parses & validates the parameters you included on the Partner Link URL.
  5. If the user does not have an active session on Cruvee (i.e. they’re not signed in to Cruvee), they will be prompted to sign in or sign up for Cruvee. If the user has an account and signs in or has an active session on Cruvee, their account will be checked to see if they have the necessary privileges to perform the action. If the user creates a new account and claims their winery, they will be returned to your site at that time since their account and winery connection needs to be verified (this is an asynchronous process that may include manual steps).
  6. Once the user has signed in and their permissions have been verified, they will be sent to the appropriate page on Cruvee (edit winery, edit wine, add wine, …).
  7. Once the user saves or cancels their work, Cruvee will redirect the user back to your site with an “outcome” parameter (among other parameters).
  8. If the outcome was successful, you can initiate a Cruvee API call from your server to retrieve the updated information. See the Cruvee API documentation for more details on how to search for and read entities from Cruvee.

Partner Link Parameters

First, the base URL of the Partner Link entry point is:

https://cruvee.com/Authentication/PartnerLink

Additional parameters are appended to the entry point URL as query string parameters as described below.

When building a partner link URL, there are several required parameters and one optional parameter. Each of these parameters are described below.

IMPORTANT: parameter names are case-sensitive.

  • action – indicates the target action to be performed. Valid values include “claim”, “edit”, and “addWine”. See details on each action type below for how and when to use each action type.
  • appId – the Application ID provided by Cruvee when you signed up for Cruvee’s API.
  • returnUrl – the URL that Cruvee should use when returning users back to your site. Cruvee will append parameters to this URL (described below).
  • sig – this is a signature or hash that is used by Cruvee to validate your site’s request (described below).
  • timestamp – this is a numerical timestamp from your server when the Partner Link and “sig” were generated. The timestamp value is the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. The Cruvee server will deny your Partner Link request if your timestamp is +/- 10 seconds from the current time on the Cruvee server.
  • userData (optional) – optional parameter that allows you to pass any value you’d like to Cruvee that we will pass back to you when the user completes the action. Maximum length is 50 characters.
  • ynId – the Cruvee YnId for the entity to be claimed, edited, or added to. Cruvee provides YnId values for each entity returned in the search API.

Calculating Signature (“sig”)

The “sig” parameter mentioned above is calculated using the following procedure.

  1. Build a source string by concatenating the values for the following parameters. The parameters must be added in the order specified below and a ‘\n’ (newline) character must be appended to each value. This source-string is ONLY used to calculate the “sig” parameter and must NOT be part of the Partner Link URL.
    1. action – the action from Partner Link built above.
    2. appId – your Application ID.
    3. returnUrl – your return URL.
    4. secret – your Application Secret provided by Cruvee when you signed up for Cruvee’s API. ONLY use for “sig” calculation. NEVER INCLUDE YOUR SECRET ON A URL OR YOUR APP WILL BE DEACTIVATED!
    5. timestamp – timestamp from the Partner Link built above.
    6. userData – userData from Partner Link (if specified).
    7. ynId – ynId from Partner Link built above.
  2. Lower case the entire source string.
  3. Calculate MD5 hash of source string.
  4. Use MD5 hash as the “sig” parameter in your Partner Link.

Cruvee will recalculate the signature when the Partner Link hits our servers and compare our value to the “sig” parameter you provided. If the signatures match, processing of the request will continue. Otherwise the request will be denied and a validation error will be returned.

Example

Let’s assume you want to build a Partner Link to allow a winery owner to claim their winery profile on Cruvee. Your AppId is “4ab99aa7ea8a468985e81dc0f407b024″ and your secret is “9e222c4653de47f4824d72d65f9cb1b8″. The winery’s Cruvee brand YnId is “00100″ and your return URL is “http://localhost:9002/PartnerLinkReturn”.

First let’s append all of the basic parameters to the base URL (with parameter names in bold).

https://cruvee.com/Authentication/PartnerLink?action=claim&appId=4ab99aa7ea8a468985e81dc0f407b024&returnUrl=http%3A%2F%2Flocalhost%3A9002%2FPartnerLinkReturn&timestamp=1267126989246&ynId=ynbid%3A000101

Next we need to calculate the “sig” parameter value and append it to the URL.

To calculate the signature parameter we need to build the signature source string as described above. Here is the source string for our example. Note that a ‘\n’ (newline) character is appended to each parameter value, including the last value.


claim\n
4ab99aa7ea8a468985e81dc0f407b024\n

http://localhost:9002/PartnerLinkReturn\n

9e222c4653de47f4824d72d65f9cb1b8\n
1267126989246\n
ynbid:000101\n

Next lower-case the source string and calculate the MD5 checksum. The result is “7b9d4a704605f62804ae46fbaaff3872″. This is your signature (“sig”) and what should be included in your Partner Link. The final Partner Link becomes:

https://cruvee.com/Authentication/PartnerLink?action=claim&appId=4ab99aa7ea8a468985e81dc0f407b024&returnUrl=http%3A%2F%2Flocalhost%3A9002%2FPartnerLinkReturn&timestamp=1267126989246&ynId=ynbid%3A000101&sig=7b9d4a704605f62804ae46fbaaff3872

The user can now be redirected to this URL.

Partner Link Replies

When Cruvee returns users back to your site using the “returnUrl” value in the Partner Link, we will append several parameters that you can inspect to react accordingly on your site.

  • action – the action you specified on the Partner Link.
  • appId – the appId you specified on the Partner Link.
  • outcome – the outcome of the user’s action on Cruvee. Valid outcome values include:
    • save – user saved entity (winery, wine, …)
    • cancel – user canceled action within Cruvee.
    • validationError – there was a validation error. See “error” parameter value(s).
    • wineryClaimed – winery was successfully claimed (or has already been claimed) by user.
    • newAccountPendingVerification – a new account was created by the user on Cruvee and is pending verification
  • timestamp – the timestamp from the Cruvee server when the return URL was constructed.
  • error – there will be zero or more “error” parameters indicating any errors that occurred. Used with the validationError outcome.
  • sig – Cruvee calculated signature that you can use to verify that the reply indeed came from Cruvee (i.e. to protect your reply entry point).
  • userData – the optional userData value that you passed on the Partner Link.
  • ynId – the YnId you specified on your Partner Link.

The “sig” parameter is built using the same approach that you used for the Partner Link but with the following source string parameters of: action, appId, outcome, secret, timestamp, userData (if specified), and ynId. See instructions above for how to build and calculate “sig”.

Claim Winery Action

The claim winery action (“claim”) is used to either verify that a user has claimed a winery brand in Cruvee or to initiate the claiming process. If the user has already claimed the winery, the Partner Link outcome will be “wineryClaimed”. If, however, the user has not claimed the winery and goes through the process of creating an account and claiming the winery, the outcome will be “newAccountPendingVerification”. Since new Cruvee accounts and new winery connections must be verified and approved by an asynchronous process (verification email and possible manual approval), you will have to retry sending users to edit their winery and wine data after they initially sign up. The amount of time to retry is difficult to predict since it depends on how long it takes the user to open their Cruvee account verification email and confirm their email address.

Edit Winery Profile Action

Use the “edit” action with a winery brand YnId to initiate a winery edit process. Once the user authenticates, they will be sent to the winery profile edit page on Cruvee where the user can updated their profile, upload digital media, edit location information, and more.

Edit Wine Action

Use the “edit” action with a wine YnId to initiate a wine edit process. Once the user authenticates, they will be sent to the wine edit page on Cruvee where the user can edit the wine, add SKUs, upload digital media, and more.

Add Wine Action

Use the “addWine” action along with winery brand YnId to initiate the add wine process. Once the user authenticates, they will be sent to the add wine page on Cruvee for the specified brand.

Important Things To Keep In Mind

  • Ensure that the clocks on your server(s) are synchronized using NTP or Windows Time Service to avoid your Partner Links being falsely rejected for stale or out-of-range timestamps.
  • Keep your API Secret (provided by Cruvee when you sign up for the API), well, secret. Never include your secret on URL as a parameter. The secret is only included in the source string when calculating the signature/hash.
  • You are encouraged to verify the signature returned by Cruvee in the Partner Link reply to ensure that replies are coming from Cruvee and not an impostor. If you’re using session based validation this may not be strictly necessary but it can provide an additional layer of security.
  • Use the “userData” parameter if you need a user or session specific value passed through the Partner Link process.

Comments are closed.