SWITCHGRID

Migration from /enedis/v2 to /v0_1

← Back to
Getting started with API v0.1
 
👉
If you are familiar with our /enedis/v2 API, see this document as a migration guide

Why v0.1 ?

Introducing new DSOs like GRDF is breaking backwards compatibility. Path /enedis/v2/… is replaced by api.switchgrid.tech/v0_1/…
Each version of the API will have its own specification, and guide.
Consents disappear. Other concepts like Ask and Order stay, but Ask are quite heavily modified (lifecycle, properties and creation arguments)

Changes

Old asks have electricityContracts.
New asks have contracts.
 
{
  "contracts": [
    ...
  ],
  "consentDuration": "2 years"
}
Minimal payload for creating an Ask with new contracts field

⚠️ DOCUSEAL is no longer supported as a consentCollectionMedium

New Asks support contracts from different DSOs than Enedis. We are adapting the web form to support these, but not the PDF-based Docuseal one.
 

contracts format changes

  • You can still reference GET /search_contract results by contract uuid.
  • The format for other contracts is now as follows
    • explicit tags holder._tag: NaturalPerson | LegalEntity and _energyType: gas | electricity
    • currently only French contracts are supported, thus the address format is french (with French property names)
      • {
  "_energyType": "gas",
  "deliveryPointId": "2142764108****",
  "holder": {
    "_tag": "NaturalPerson",
    "fullName": "Jean Dupont"
  },
  "address": {
    "rueEtNumero": "8 rue du Moulin",
    "codePostal": "02500",
    "commune": "Buire"
  }
}
      FrenchGasContract
      {
  "_energyType": "electricity",
  "deliveryPointId": "2142764108****",
  "holder": {
    "_tag": "LegalEntity",
    "name": "SCEA Dupont",
    "otherNames": ["La ferme de Jean"]
  },
  "address": {
    "rueEtNumero": "7 rue des Frères",
    "codePostal": "67000",
    "commune": "Strasbourg"
  }
}
      FrenchElectricityContract

Contracts without validation

  • Enedis offers the possiblity of checking against their systems if a contract exists. Other DSOs do not necessarily offer that (like GRDF in France). So we now allow an Ask to be signed even though it’s possible that there is a mistake in the contract (wrong holder name, wrong delivery point id, etc.), as we have no way to check that for GRDF.

prm/pdm/pce are now called deliveryPointId, no matter what type of energy we are talking about

It refers to the internal DSO id for a “Point de Livraison” in France, and possibly in other countries too. Caution, it’s not the same as the meter’s serial number in most cases.

Changes in Ask lifecycle

Possible status values of asks are now the following :
  • CREATED
  • PENDING_ADDRESS_CHECK -> will directly go to PENDING_USER_ACTION or NOT_VALID
  • ADDRESS_CHECK_FAILED -> NOT_VALID
  • NOT_VALID new !
  • PREPARING_CONSENT_COLLECTION
  • PENDING_USER_ACTION
  • ACCEPTED
 
  • NOT_VALID is new, and can reflect a couple of problems.
  • For transitions CREATED → INVALID and CREATED → PENDING_USER_ACTION, webhooks will be triggered.
  • On POST /ask We’ll wait max 3 seconds for one of the above transitions to happen. If they don’t (e.g. when there are many contracts to check), the response will still have status: CREATED. Either poll or use the state transition webhooks to tell your users the Ask is ready.
  • The Ask’s consentCollectionUrl will be available immediately on status CREATED (and will be https://app.switchgrid.tech/c/{askId}). If ask is not ready to be signed yet, this will reflect in a message and an impossibility to submit the form.
 

Backwards compatibililty with previous API /enedis/v2

GET /ask response changes

Fields that are removed :
  • __experimentalAddressChecksResults
  • addressCheckResults ⇒ this is now in the contracts new field.
  • consentIds ⇒ Consent object altogether disappears in favor of revoking an Ask entirely, or Ask individual contracts.
 

Test deliveryPointIds

Like Stripe does it, some special deliveryPointIds can be used to test our API.
There are test deliveryPointIds for every Dso. If these are specified, no real request to the corresponding Dsos will be made. Instead, deterministic behaviours will happen.
Dso
deliveryPointId
type of meter / point / contract
behaviour
GRDF
00000000000001
Residential
Successful flow, with email confirmation sent by Switchgrid. Data is random, but representative.
GRDF
00000000000002
Residential
Successful flow, no need for SMS confirmation because we already have declared an access to that PCE
GRDF
GI0000001
Professional
ㅤ