> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datanumia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contracts

Energy supply contracts are used to associate a site with our tariff repository. This data allows us to link a price grid to the site to value its energy consumption.

The contracts initialization for a site should occur after the site subscription. If a client then changes its contract, we also need to collect this information in order to provide accurate services.

## Details on the expected information to be sent

| Information | Description | Required |
| - | - | - |
| `Site identifier` | IDs associated to the site that has been generated at the end of the subscription process | Yes |
| `Point of delivery identifier (POD)` | Identification number of the electricity or gas point of delivery | Yes |
| `Fluid` | Fluid associated to the contract: electricity or gas | Yes |
| `Application date` | Functional start date of the contract | Yes |
| `Parameters` | Parameters associated with the contract (e.g. tariff, option, subscribed power) | Yes |
| `Tariff calendar` | Tariff calendar associated with the contract | No |

## Contracts Collection Process

Depending on the processing volumes and the operating mode of our clients, two types of collection processes to add or modify contracts are offered via API: **mass** collection and **unitary** collection.
These collections manage both **electricity** and **gas** contracts.

### Unitary Collection via API

For catch-up purposes or small contracts volumetry, unitary contracts collection is avaliable via the following endpoint : **POST /contracts**
This method allows you to send all contracts of a single site.

### Mass Collection via API

This method enables bulk collection of contracts of multiple sites by sending JSON files transmitted in a compressed archive in tar.gz format. The archive must contain between 1 and 10 JSON files and its size cannot exceed 5 MB.
Once an archive has been sent, it is possible to track its processing through a dedicated service.

The bulk method includes three endpoints :

* `POST /contracts-jobs`: Allows you to submit a contracts archive for processing
* `GET /contracts-jobs/{job-id}`: Allows you to monitor the processing of an archive through its statuses and the detailed report containing the OK/KO operations
* `GET /contracts-jobs`: Returns a list of jobs between two dates, with their statuses and an overview of the OK/KO operations

| Status | Description |
| - | - |
| `SUBMITTED` | The archive is received but processing has not started |
| `IN_PROGRESS` | The archive is being processed. |
| `DONE` | Archive processing is completed without errors and a detailed report on each request is accessible. |
| `ERROR` | Archive processing is completed but has encountered at least one functional error. The details are available in the detailed report. Actions on the customer's side are necessary to correct them and resend the corresponding contracts. |
| `INTERNAL_ERROR` | Archive processing stopped mid-process for an unknown reason. Actions on Datanumia's side are necessary to correct them. |

### Example of a JSON file

```json theme={null}
{
  "contracts": [
    {
      "siteId": "site_1",
      "podId": "pod_1",
      "fluid": "elec",
      "ts": "2023-08-09T00:00:00Z",
      "generationTs": "2023-08-11T14:12:37Z",
      "supplyContractParameters": {
          "TARIFF": "TARIFF_1",
          "TARIFF_OPTION": "HPHC",
          "SUBSCRIBED_POWER": "9",
          "MILLESIME": "20230801"
                },
      "tariffCalendar": {
          "timeRangeByLabels": [
            {
              "label": "cadran1",
              "ranges": [
                  {
                      "begin": "00:00:00",
                       "end": "06:00:00"
                  },
                  {
                      "begin": "22:00:00",
                      "end": "00:00:00"
                  }
            ]
          },
           {
              "label": "cadran2",
              "ranges": [
                  {
                      "begin": "06:00:00",
                       "end": "22:00:00"
                  }
            ]
          }
        ]
      }
    }
  ]
}

```