Authentification Codes HTTP 💚 Succès (2xx) 🚫 Erreurs client (4xx) 🔧 Erreurs serveur (5xx) Accès à l'api Accès marketplace Accès fournisseur Api Endpoints Services Débit de token Webhooks authorization.create authorization.disable tokens.debit
Mode d'affichage
Automatique
Mode d'affichage
Clair
Sombre
Automatique

Authentification

Prérequis :
  • Pour utiliser cette API, vous devez nous contacter Ă  contact@immosquare.com. Après vĂ©rification, nous vous fournirons apiKey et apiToken Ă  inclure dans les headers de vos requĂŞtes.
# POST
POST /path
Content-Type: application/json
apiKey: xz1232xzd213213er213213dczxcc3loizxzs12dczx
apiToken: xz1287xzdwer213213dczxcas12dczx

# GET
GET /path
apiKey: xz1232xzd213213er213213dczxcc3loizxzs12dczx
apiToken: xz1287xzdwer213213dczxcas12dczx

Codes HTTP

Nous utilisons des codes conventionnels de réponse HTTP pour indiquer le succès ou l'échec des requêtes.

💚 Succès (2xx)

HTTP Statut Description
200 - OK Succès de la requête

đźš« Erreurs client (4xx)

HTTP Statut Description
400 - Bad Request Paramètres manquants ou invalides
401 - Unauthorized API Key/token invalide
402 - Request Failed RequĂŞte valide mais Ă©chec du traitement
404 - Not Found Endpoint inexistant
429 - Too Many Requests Quota de requêtes dépassé

🔧 Erreurs serveur (5xx)

HTTP Statut Description
500, 502, 503, 504 - Server Errors Erreur technique 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": []
  }
}
© immosquare 2013-2025 - Mentions légales