Authentification

Pour utiliser cette api, vous devez nous contacter à contact@immosquare.com. Après vérification nous vous fournirons une clé et un token pour vous connecter à l'api. Il vous suffira ensuite d'appeler l'api avec vos identifiants et de les envoyer dans le header de la requête REST.

POST /path
Content-Type: application/json
apiKey: xz1232xzd213213er213213dczxcc3loizxzs12dczx
apiToken: xz1287xzdwer213213dczxcas12dczx

GET /path
apiKey: xz1232xzd213213er213213dczxcc3loizxzs12dczx
apiToken: xz1287xzdwer213213dczxcas12dczx

Erreurs

storeimmo utilise des codes conventionnels de réponse HTTP pour indiquer le succès ou l'échec d'une requêtes API.

En général, les codes débutant par 2xx indiquent un succès, les codes débutant par 4xx indiquent une error qui résulte des informations fournies lors de l'appel ( par exemple : un paramètre est manquant,... ), et les codes débutant par 5xx indiquent une erreur interne sur notre serveur.

HTTP Statut	Code Description
200 - OK	Succès de la requête.
400 - Bad Request	Paramètres manquants, mauvais type envoyé,...
401 - Unauthorized	API Key/token invalide
402 - Request Failed	Paramètres ok mais la requête a échoué
404 - Not Found	Cette requête n'existe pas
429 - Too Many Requests	Trop de requête
500, 502, 503, 504 - Server Errors	Erreur interne

Accès à l'api

L'api dispose de 2 niveaux de privilèges.

accès marketplace : reservé aux propriétaires de la marketplace et autorise un acccès total à tous les produits et toutes les informations.
accès fournisseur : autorise la consultation des achats concernant uniqument les produits ratachés à ce fournisseur.

Tous les appels doivent se faire avec l'un des paramètres suivants pour identifier l'utilisateur :

Params	Type d'accès	Description
access_token	fournisseur	provenant de la connexion oauth2
email	marketplace	email utilisé pour la création du compte via l'api
uid	marketplace	id distant utilisé pour la création du compte via l'api

Accès marketplace

Pour obtenir un espace fournisseur sur la marketplace, vous devez :

obtenir vos crédentials d’API (apiKey/apiToken), valable pour toute la marketplace
définir avec immosquare. votre url de reception des différents webhooks

Accès fournisseur

Pour obtenir un espace fournisseur sur la marketplace, vous devez :

obtenir vos crédentials d’API (apiKey/apiToken), valable pour tous les produits de votre compagnie sur la marketplace
définir avec immosquare. votre url de reception des différents webhooks
définir avec immosquare. votre adresse de callback pour le protocole oAuth2 si vous voulez utiliser la connexion automaitque entre la marketplace et votre application.
définir avec immosquare. vos SKU pour les différents produits (le SKU est l’identifiant unique de chacun de vos produits/pricings).

Le principe

La marketplace gère le cycle d’achat sous forme de plans (abonnements mensuels ou annuels) ou de tokens (crédits) ou de checkouts (achat unique).
Chaque client possède un espace où il retrouve l’ensemble de ses services actifs.
Sur un service, le client peut se connecter à l'application partenaire via le protocole oAuth2.
L’application partenaire s’exécute ensuite dans un environnement qui lui est propre.
L’application partenaire peut proposer des services directement liés à des annonces (reçues via l’API) ou alors des services sans forcément un lien avec les annonces.
Une fois la première intégration effectuée, l’application partenaire pourra également fonctionner pour les différentes marketplace développées par immosquare. (apiKey/Token propre à chaque marketplace).

Pour chaque produit, on définit

un product SKU (PARTNER1-PRODUCT1)
et pour chaque Tarif, un pricing SKU (PARTNER1-PRODUCT1-PRICING1). Un produit peut avoir différents tarifs et chaque tarif peut avoir plusieurs options. (La structuration est définie en partenariat avec immosquare.)
Lorsque ces actions sont réalisées, le produit est achetable dans la marketplace.

Connexion avec le protocole OAuth2

La marketplace respecte tous les protocoles ouath2. (https://oauth.net/2/). Les URL de connexion sont :

https://{store-url}/oauth/authorize
https://{store-url}/oauth/token

Après ces calls, vous devriez avoir un oauthToken rattaché à cet utilisateur (qui n’a pas de limite de temps)

Api Endpoints

Services

HTTP Request

GET https://{store-url}/fr/api/v1/services

Query Parameters

Params	Obligatoire	Description
access_token ou email ou id	oui	pour identifier l'utilisateur
product_sku	non	sku du produit

Réponse

{
  "profile": {
    "id": 20870,
    "reference": 1234,
    "profile_id": 21359,
    "agency_id": 1,
    "uid": "481",
    "email": "johndoe@email.com",
    "username": "johndoe",
    "sign_in_count": 0,
    "country": "FR",
    "public_email": "johndoe@email.com",
    "first_name": "Jon",
    "last_name": "Doe",
    "phone": "01 02 03 04 05",
    "phone_sms": "01 02 03 04 05",
    "phone_office": null,
    "phone_visibility": 1,
    "picture_url": "https://samples-photos.com/woman.jpeg",
    "website": "http://johndoe.com",
    "spoken_languages": "fr,en",
    "facebook_url": "",
    "twitter_url": "",
    "linkedin_url": "",
    "pinterest_url": "",
    "google_plus_url": "",
    "instagram_url": "",
    "youtube_url": "",
    "color1": "#a48a77",
    "color2": "#b0b0b0",
    "color1_print": "4745 C",
    "color2_print": "7505 C",
    "company_name": "John Doe Real Estate",
    "company_email": "johndoe-realestate@email.com",
    "company_logo_url": "",
    "corporate_account": 1,
    "presentation_text": {
      "fr": "Agence immobilière",
      "en": "",
      "es": ""
    },
    "bio": {
      "fr": "Depuis 1993, John Doe Real Estate vous propose le plus large choix d'appartements et de villas...",
      "en": "",
      "es": ""
    },
    "baseline": {
      "fr": "Tout l'immobilier depuis 1993",
      "en": "",
      "es": ""
    },
    "billing_address": {
      "address1": "01 Boulevard de Cimiez",
      "address2": "",
      "city": "Nice",
      "country": "FR",
      "province": "06",
      "zipcode": "06000"
    },
    "shipping_address": {
      "same_as_billing": 1,
      "address1": "01 Boulevard de Cimiez",
      "address2": "",
      "city": "Nice",
      "country": "FR",
      "province": "06",
      "zipcode": "06000"
    },
    "created_at": "2020-06-02T16:32:53.000-04:00",
    "updated_at": "2017-06-08T10:48:28.000-04:00",
    "uids": [
      {
        "uid": "481",
        "provider": "immosquareeu"
      }
    ]
  },
  "authorizations": {
    "plans": [
      {
        "id": 457,
        "pricing_sku": "IMMO-SI-PREMIUM",
        "product_sku": "IMMO-SI",
        "status": "active",
        "name": "Illimité",
        "validity_date_start": "2017-06-13T10:39:47.000-04:00",
        "validity_date_end": "2018-06-13T10:39:47.000-04:00",
        "mode": "plan_year",
        "extras": []
      },
      {
        "id": 414,
        "pricing_sku": "IMMO-PZ-PLAN",
        "product_sku": "IMMO-PZ",
        "status": "active",
        "name": "Affichette Vitrine",
        "validity_date_start": "2017-06-02T16:55:31.000-04:00",
        "validity_date_end": "2018-06-02T16:55:31.000-04:00",
        "mode": "plan_month",
        "extras": []
      }
    ],
    "tokens": [
      {
        "id": 1177,
        "pricing_sku": "PIXIS-PX-TOKENS",
        "product_sku": "PIXIS-PX",
        "status": "active",
        "name": "Service de retouche photo",
        "validity_date_start": "2020-10-16T09:14:22.000-04:00",
        "tokens": 6,
        "updated": false,
        "validity_date_end": "2021-10-16T09:14:20.000-04:00",
        "extras": []
      },
      {
        "id": 2333,
        "pricing_sku": "PIXIS-PX-TOKENS",
        "product_sku": "PIXIS-PX",
        "status": "active",
        "name": "Service de retouche photo",
        "validity_date_start": "2021-05-16T09:14:22.000-04:00",
        "tokens": 12,
        "updated": false,
        "validity_date_end": "2022-05-16T09:14:20.000-04:00",
        "extras": []
      }
    ]
  }
}

Débit de token

Si L'utilisateur achète plusieurs fois des tokens chaque achat va correspondre à une entrée authorization. Donc pour connaître le nombre de tokens disponibles pour un utilisateur sur un produit il faut sommer les tokens des authorizations actives. Dans l'exemple précédant l'utilisateur possède donc 18 tokens sur le produit ayant le product_sku PIXIS-PX (6 provenant de l'achat #1177 et 12 provenant de l'achat #2333)

Dans le call suivant, vous devez spécifier quelle authorization vous voulez débiter.

Si l'authorization spécifiée dans le call dispose de plus de token que le nombre de token à débiter, aucun problème le débit va s'opérer.
Si le nombre de token à débiter est supérieur au nombre de tokens de l' authorization spécifiée, mais que l'ensemble des authorizations (somme des tokens) permet le débit, le débit va s'opérer en retirant premièrerement les tokens de l'authorization spécifiée, puis retira les tokens restant des autres authorizations en respectant l'ordre d'achat

HTTP Request

POST https://{store-url}/fr/api/v1/services/debit/{authorizationId}/{quantityToDebit}

Query Parameters

Params	Obligatoire	Description
authorizationId	oui	id de l' authorization à débiter
quantityToDebit	oui	nombre de tokens à débiter

Réponse

{
  "status": "ok"
}

Webhooks

Il exite plusieurs webhooks sur la marketplace qui vous avertiront sur l'url de votre choix lors que certaines actions sont effectuées

authorization.create

Ce webhook se lance à chaque fois q'une authorisation est créée, c'est à dire à chaque nouvel achat d'un produit ou lors d'un renouvellement.

Pour produit de type abonnement chaque authorization correspond à une période (date de début, date de fin). Lors d'un renouvellement (mensuel ou annuel), l'authorization courante est désactivée et une nouvele authorization est créée avec la nouvelle période. Donc lors d'un renouvellement, vous allez recevoir 2 appels : un authorization.disable, puis par la suite un deuxieme authorization.create

{
  "webhook": "authorization.create",
  "store": {
    "id": 24,
    "slug": "marketplace-xx"
  },
  "client": {
    "id": 20870,
    "uid": "311830",
    "email": "johndoe@email.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "data": {
    "id": 72705,
    "pricing_sku": "CCI-PLAN-0",
    "product_sku": "CCI-PART",
    "status": "active",
    "name": "Abonnement pour Cocoon-Immo",
    "validity_date_start": "2023-02-28",
    "validity_date_end": "2026-02-28",
    "inactive_date": null,
    "mode": "plan_year",
    "extras": []
  }
}

authorization.disable

Ce webhook se lance à chaque fois q'une authorisation est désactivée.

{
  "webhook": "authorization.disable",
  "store": {
    "id": 24,
    "slug": "marketplace-xx"
  },
  "client": {
    "id": 20870,
    "uid": "311830",
    "email": "johndoe@email.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "data": {
    "id": 72705,
    "pricing_sku": "CCI-PLAN-0",
    "product_sku": "CCI-PART",
    "status": "active",
    "name": "Abonnement pour Cocoon-Immo",
    "validity_date_start": "2023-02-28",
    "validity_date_end": "2026-02-28",
    "inactive_date": null,
    "mode": "plan_year",
    "extras": []
  }
}

tokens.debit

Ce webhook se lance à chaque fois q'un débit est effectué.

{
  "webhook": "tokens.debit",
  "store": {
    "id": 24,
    "slug": "marketplace-xx"
  },
  "client": {
    "id": 20870,
    "uid": "311830",
    "email": "johndoe@email.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "data": {
    "id": 164,
    "pricing_sku": "PIXIS-PX-TOKENS",
    "product_sku": "PIXIS-PX",
    "status": "active",
    "name": "Service de retouche photo",
    "validity_date_start": "2022-09-12",
    "validity_date_end": "2023-09-12",
    "inactive_date": null,
    "mode": "tokens",
    "tokens": 0,
    "extras": []
  }
}