Submit a job

curl --request POST \
  --url https://api.home.datanumia.com/api/v2/contracts-jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file

import requests

url = "https://api.home.datanumia.com/api/v2/contracts-jobs"

files = { "file": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.home.datanumia.com/api/v2/contracts-jobs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.home.datanumia.com/api/v2/contracts-jobs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.home.datanumia.com/api/v2/contracts-jobs"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.home.datanumia.com/api/v2/contracts-jobs")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.home.datanumia.com/api/v2/contracts-jobs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "_links": {
    "self": {
      "href": "https://<DATANUMIA_ROOT_URL>/contracts-jobs/{job-id}"
    }
  }
}

{
  "errorCode": "<string>",
  "errorDescription": "<string>"
}

This response has no body data.

This response has no body data.

bulk mode contracts

Submit a job

Allows you to submit an archive containing sites’ contracts (see details in “Body” section).

Once the archive is sent, it is decompressed and each file it contains is processed. No order is guaranteed for the file processing order nor the order of processing of requests within a file.

Contracts processing for a given pod is atomic within a file meaning that validation rules described in the corresponding unitary operations are evaluated before inserting the contracts for a given pod.

Since the processing is asynchronous (archive storage, then processing to avoid blocking the API), this endoint returns a URL to access the job status through a details report. For the same reason, errors are not returned via an HTTP code but via this report.

POST

contracts-jobs

Submit a job

curl --request POST \
  --url https://api.home.datanumia.com/api/v2/contracts-jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file

import requests

url = "https://api.home.datanumia.com/api/v2/contracts-jobs"

files = { "file": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.home.datanumia.com/api/v2/contracts-jobs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.home.datanumia.com/api/v2/contracts-jobs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.home.datanumia.com/api/v2/contracts-jobs"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.home.datanumia.com/api/v2/contracts-jobs")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.home.datanumia.com/api/v2/contracts-jobs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "_links": {
    "self": {
      "href": "https://<DATANUMIA_ROOT_URL>/contracts-jobs/{job-id}"
    }
  }
}

{
  "errorCode": "<string>",
  "errorDescription": "<string>"
}

This response has no body data.

This response has no body data.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

multipart/form-data

Only the .tar.gz archive format is valid. The archive must contain between 1 and 10 JSON files and its size cannot exceed 5 MB. Each JSON file can contain up to 10 000 contracts.

Expected object formats are :

{
  "type": "object",
  "properties": {
    "contracts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "siteId": {
            "type": "string",
            "description": "Site identifier provided by Datanumia",
            "example": "site-3000"
          },
          "podId": {
            "type": "string",
            "description":"Identifier of the point of delivery",
            "example":"pdl-38"
          },
          "fluid": {
            "type": "string",
            "description": "Type of energy covered by the contract: electricity or gas",
            "enum": ["elec","gas"]
          },
          "ts": {
            "type": "string",
            "description": "Effective date of the contract, whether it is a new contract or an amendment to a previously submitted contract. \n\rThe supported format is as defined by RFC 3339, section 5.6 restricted to : full-date'T'partial-time'Z'",
            "example":"2021-07-21T22:00:00Z"
          },
          "generationTs": {
            "type": "string",
            "description":"Date used to historize contracts for a given ts. \n\r The supported format is as defined by RFC 3339, section 5.6 restricted to : full-date'T'partial-time'Z'",
            "example": "2022-05-17T14:28:37Z"
          },
          "supplyContractParameters": {
            "type": "object",
            "description": "Parameters and values describing the contract. This list may vary depending on Marketer's configuration",
            "example" : "{ \"TARIFF\": \"ELEC_PE_VERT\",
          \"TARIFF_OPTION\": \"HPHC\",
          \"SUBSCRIBED_POWER\": \"9\",
          \"MILLESIME\": \"2\"
                }"
          },
          "tariffCalendar": {
            "type": "array",
            "description": "Distributor calendar associated to the client's site. Specific to electricity contracts.",
            "items": {
              "type":"object",
              "properties" : {
                "periods":{
                  "type": "array",
                  "description": "Period for which the calendar is defined : \n\r - If tariffCalendar contains more than one object, then a period must be defined for each. \n\r - Periods defined within tariffCalendar must cover a full year without overlap \n\r - The beginDate must precede the endDate ",
                  "items": [
                    {
                      "type": "object",
                      "properties": {
                        "beginDate": {
                          "type": "string",
                          "description": "Start date of the period. This date is included.\n\r The supported format is as defined by RFC 3339 : --MM:DD",
                          "example": "--01-01"
                        },
                        "endDate": {
                          "type": "string",
                          "description": "End date of the period. This date is included.\n\r The supported format is as defined by RFC 3339 : --MM:DD",
                          "example": "--12-31"
                        }
                      },
                      "required": [
                        "beginDate",
                        "endDate"
                      ]
                    }
                  ]
                },
                "timeRangeByLabels": {
                  "type": "array",
                  "description": "Defines the period of activity for a list of labels",
                  "items": {
                    "type": "object",
                    "properties": {
                      "label": {
                        "type": "string",
                        "description": "Label name (= Dial name). By convention, value is \"cadran1\" ",
                        "example": "cadran1",
                      },
                      "ranges": {
                        "type": "array",
                        "description": "Time ranges during which the label is active",
                        "items": {
                          "type": "object",
                          "properties": {
                            "begin": {
                              "type": "string",
                              "description": "Begin time in HH:mm:ss format",
                              "example": "00:00:00"
                            },
                            "end": {
                              "type": "string",
                              "description": "End time in HH:mm:ss format",
                              "example": "06:00:00"
                            }
                          },
                          "required": [
                            "begin",
                            "end"
                          ]
                        }
                      }
                    },
                    "required": [
                      "label",
                      "ranges"
                    ]
                  }
                }
              },
              "required": [
                "timeRangeByLabels"
              ]
            }
          }
        },
        "required": [
          "siteId",
          "podId",
          "fluid",
          "ts",
          "generationTs",
          "supplyContractParameters"
        ]
      }
    }
  }
}

{
  "type": "object",
  "properties": {
    "contracts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "personCustomerId": {
            "type": "string",
            "description": "Person identifier provided by the Marketer",
            "example": "bp-3000"
          },
          "siteCustomerId": {
            "type": "string",
            "description": "Site identifier provided by the Marketer",
            "example": "site-3000"
          },
          "podId": {
            "type": "string",
            "description":"Identifier of the point of delivery",
            "example":"pdl-38"
          },
          "fluid": {
            "type": "string",
            "description": "Type of energy covered by the contract: electricity or gas",
            "enum": ["elec","gas"]
          },
          "ts": {
            "type": "string",
            "description": "Effective date of the contract, whether it is a new contract or an amendment to a previously submitted contract. \n\rThe supported format is as defined by RFC 3339, section 5.6 restricted to : full-date'T'partial-time'Z'",
            "example":"2021-07-21T22:00:00Z"
          },
          "generationTs": {
            "type": "string",
            "description":"Date used to historize contracts for a given ts. \n\r The supported format is as defined by RFC 3339, section 5.6 restricted to : full-date'T'partial-time'Z'",
            "example": "2022-05-17T14:28:37Z"
          },
          "supplyContractParameters": {
            "type": "object",
            "description": "Parameters and values describing the contract. This list may vary depending on Marketer's configuration",
            "example" : "\"supplyContractParameters\": { \"TARIFF\": \"ELEC_PE_VERT\",
          \"TARIFF_OPTION\": \"HPHC\",
          \"SUBSCRIBED_POWER\": \"9\",
          \"MILLESIME\": \"2\"
                }\""
          },
          "tariffCalendar": {
            "type": "array",
            "description": "Distributor calendar associated to the client's site. Specific to electricity contracts.",
            "items": {
              "type":"object",
              "properties" : {
                "periods":{
                  "type": "array",
                  "description": "Period for which the calendar is defined : \n\r - If tariffCalendar contains more than one object, then a period must be defined for each. \n\r - Periods defined within tariffCalendar must cover a full year without overlap \n\r - The beginDate must precede the endDate ",
                  "items": [
                    {
                      "type": "object",
                      "properties": {
                        "beginDate": {
                          "type": "string",
                          "description": "Start date of the period. This date is included.\n\r The supported format is as defined by RFC 3339 : --MM:DD",
                          "example": "--01-01"
                        },
                        "endDate": {
                          "type": "string",
                          "description": "End date of the period. This date is included.\n\r The supported format is as defined by RFC 3339 : --MM:DD",
                          "example": "--12-31"
                        }
                      },
                      "required": [
                        "beginDate",
                        "endDate"
                      ]
                    }
                  ]
                },
                "timeRangeByLabels": {
                  "type": "array",
                  "description": "Defines the period of activity for a list of labels",
                  "items": {
                    "type": "object",
                    "properties": {
                      "label": {
                        "type": "string",
                        "description": "Label name (= Dial name). By convention, value is \"cadran1\" ",
                        "example": "cadran1",
                      },
                      "ranges": {
                        "type": "array",
                        "description": "Time ranges during which the label is active",
                        "items": {
                          "type": "object",
                          "properties": {
                            "begin": {
                              "type": "string",
                              "description": "Begin time in HH:mm:ss format",
                              "example": "00:00:00"
                            },
                            "end": {
                              "type": "string",
                              "description": "End time in HH:mm:ss format",
                              "example": "06:00:00"
                            }
                          },
                          "required": [
                            "begin",
                            "end"
                          ]
                        }
                      }
                    },
                    "required": [
                      "label",
                      "ranges"
                    ]
                  }
                }
              },
              "required": [
                "timeRangeByLabels"
              ]
            }
          }
        },
        "required": [
          "siteCustomerId",
          "personCustomerId",
          "podId",
          "fluid",
          "ts",
          "generationTs",
          "supplyContractParameters"
        ]
      }
    }
  }
}

file

A .tar.gz archive containing the The json files to be processed.

Response

Returns a job tracking URL "GET /indexes-collect-jobs/{job-id}" to access a detailed execution report.

Return a job id that can be used to track the job execution status

_links

object

Show child attributes

Energy Consumption

part-budget-api

Contracts lifecycle

Indexes Collect lifecycle

Indexes lifecycle

Person, Site and Service Offer lifecycle

Tariffs lifecycle

Control-scenario-api-v2

tariff-heading-api

Forecast consumption lifecycle

Similar home gas comparisons lifecycle

Similar home elec comparisons lifecycle

Targets lifecycle

Comparison lifecycle

Energy disaggregation

weather lifecycle

Challenges Lifecycle

Submit a job

Authorizations

Body

Response