> ## 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.
# get a job execution report
> This API retruns a **job** execution current **state**. Depending on the **state**, a **report** specifying the **request** processing details is accessible.
The **job** execution **state** and **report** is only acessible during 21 days after its submission.
**State** | Description
---------|----------
**SUBMITTED** | The archive is received but processing has not started. No detailed **report** accessible
**IN_PROGRESS** | The archive is being processed. No detailed **report** accessible
**DONE** | Archive processing is completed without errors. A detailed **report** is accessible
**ERROR** | Archive processing is completed but has encountered at least one functional error. A detailed **report** is accessible. Actions on the client side is necessary to correct errors and rerun the corresponding **requests**
**INTERNAL_ERROR** | Archive processing stopped mid-process for an unknown reason. A detailed **report** is accessible but is probably not complete. Actions on Datanumia's side are necessary to correct them. The corresponding archive should be sent again for a complete retry
**TIMEOUT** | Archive processing stopped mid-process because of a slow processing time. A detailed **report** is accessible but is probably not complete. Actions on Datanumia's side is necessary to correct them. The corresponding archive should be sent again for a complete retry
Examples:
```json
{
"archive": "SMTRequests.tar.gz",
"state": {
"current": "SUBMITTED",
"history": [
{
"status": "SUBMITTED",
"ts": "2025-03-13T13:15:19.067283Z"
}
]
}
// No report
"_links": {
// ...
}
}
```
Or
```json
{
"archive": "SMTRequests.tar.gz",
"state": {
"current": "DONE",
"history": [
{
"status": "SUBMITTED",
"ts": "2025-03-13T13:32:47Z"
},
{
"status": "IN_PROGRESS",
"ts": "2025-03-13T13:35:22Z"
},
{
"status": "DONE",
"ts": "2025-03-13T13:35:23Z"
}
]
},
"report": {
"overview": {
"nbOperationsTotal": 1000,
"nbOperationsOK": 1000,
"nbOperationsKO": 0
},
// ...
},
"_links": {
// ...
}
}
```
If the job **state** is **DONE**, **ERROR** or **INTERNAL_ERROR**, the **report** contains a **file** object for each JSON **file** sent in the archive.
For each **request** in a **file**, there is a corresponding **request status** list that specify if the requests is successful or not.
Request name | Request status name
----------|---------
SMTRequests | SMTStatus
Example:
```json
{
"archive": "SMTRequests.tar.gz",
"state": {
// ...
},
"report": {
// ...
"files": [
{
"file": "SMTRequests.json",
"content": {
"SMTStatus": [
//...
]
}
}
]
},
"_links": {
// ...
}
}
```
The **request status** is described by the Person and sites Ids and a status object.
The **status code** can be **OK** meaning the request is well processed. Or in **error** with an error code and a message specifying the problem encountered. Also, in case of multu sites Person, Ids are lined to the error in order to specify which object caused an error.
Error code | Description
----------|---------
**FIELD_IS_INVALID** | A field content do not match the regex specified in the documentation
**FIELD_IS_MANDATORY** | A required field is missing
**INTERNAL_ERROR** | Requires an investigation to restore the service and/or correct the anomaly on Datanumia's side
**INVALID_SERVICE_OFFER_CODE** | One of a service offer code does not match the configured service offers
**OFFER_DUPLICATED** | The serviceOffers list contains the same offer code multiple times
**OFFER_MANDATORY** | The serviceOffers list is missing in the site object
**OPERATION_ALREADY_IN_PROGRESS** | Two requests on the same person or site are executed concurrently. Do not send two requests on the same person or site in the same archive
**OPERATION_NOT_SUPPORTED** | A modification, termination or subscription operation is not supported
**SITE_DUPLICATED** | A person's site list contains the same site multiple times
**SITE_MANDATORY** | The list of sites is empty or missing for a person not yet subscribed
**OK example:**
This is where you can retreive **person** and **site** Home Ids: personId, siteId.
```json
{
"person": {
"ids": {
"personCustomerId": "a_random_person_id_1",
"personId": "3cfa1b03-3bad-4d97-85b8-673c4cab99e7"
},
"sites": [
{
"ids": {
"siteCustomerId": "a_random_site_id_1",
"siteId": "dceb704f-e3fa-4128-aef3-ece501e425aa"
}
}
]
},
"status": [
{
"code": "OK"
}
]
}
```
**Error example:**
In cas of an error, the person and its sites are rollbacked to their previous state.
```json
{
"person": {
"ids": {
"personCustomerId": "a_random_person_id_2"
},
"sites": [
{
"ids": {
"siteCustomerId": "a_random_site_id_2"
}
}
]
},
"status": [
{
"code": "FIELD_IS_MANDATORY",
"message": "siteZipCode is mandatory!",
"target": {
"personCustomerId": "a_random_person_id_2",
"siteCustomerId": "a_random_site_id_2"
}
},
{
"code": "FIELD_IS_MANDATORY",
"message": "elecMeterType is mandatory!",
"target": {
"personCustomerId": "a_random_person_id_2",
"siteCustomerId": "a_random_site_id_2"
}
}
]
}
```
## OpenAPI
````yaml /api-reference/persons-sites-service-offers.yaml get /smt-jobs/{job-id}
openapi: 3.0.3
info:
title: Person, Site and Service Offer lifecycle
description: >
This API manages the lifecycle of persons, sites and service offers as
described
[here](https://datanumia.stoplight.io/docs/DatanumiaHome/YXBpOjQ0ODQzMjMy-person-site-and-service-offer-lifecycle)
Please refer to the following link to get a better understanding of the
[core
concepts](https://datanumia.stoplight.io/docs/DatanumiaHome/ZG9jOjM4MDg2NDE5-core-concepts)
of the Home platform.
Important notice with regard to those APIs:
- When subscribing or deleting multiple subscribed offers on a site or
subscribed offers on multiple sites please provide all sites and subscribe
offer data in a single POST subscriptions call.
- They are idempotent. Launching multiple times the same operation will lead
to the same result
- They require a complete snapshot of all the objects involved in the
operation. Those new objects overwrite the existing one. In other words,
missing properties will be considered empty or null when operations will be
executed on existing person/site objects
termsOfService: TODO
contact:
email: api@datanumia.com
version: 2.0.0
servers:
- url: https://api.home.datanumia.com/api/v2
description: Production Server
security: []
paths:
/smt-jobs/{job-id}:
get:
tags:
- bulk mode smt
summary: get a job execution report
description: >-
This API retruns a **job** execution current **state**. Depending on the
**state**, a **report** specifying the **request** processing details is
accessible.
The **job** execution **state** and **report** is only acessible during
21 days after its submission.
**State** | Description
---------|----------
**SUBMITTED** | The archive is received but processing has not started.
No detailed **report** accessible
**IN_PROGRESS** | The archive is being processed. No detailed
**report** accessible
**DONE** | Archive processing is completed without errors. A detailed
**report** is accessible
**ERROR** | Archive processing is completed but has encountered at
least one functional error. A detailed **report** is accessible. Actions
on the client side is necessary to correct errors and rerun the
corresponding **requests**
**INTERNAL_ERROR** | Archive processing stopped mid-process for an
unknown reason. A detailed **report** is accessible but is probably not
complete. Actions on Datanumia's side are necessary to correct them. The
corresponding archive should be sent again for a complete retry
**TIMEOUT** | Archive processing stopped mid-process because of a slow
processing time. A detailed **report** is accessible but is probably not
complete. Actions on Datanumia's side is necessary to correct them. The
corresponding archive should be sent again for a complete retry
Examples:
```json
{
"archive": "SMTRequests.tar.gz",
"state": {
"current": "SUBMITTED",
"history": [
{
"status": "SUBMITTED",
"ts": "2025-03-13T13:15:19.067283Z"
}
]
}
// No report
"_links": {
// ...
}
}
```
Or
```json
{
"archive": "SMTRequests.tar.gz",
"state": {
"current": "DONE",
"history": [
{
"status": "SUBMITTED",
"ts": "2025-03-13T13:32:47Z"
},
{
"status": "IN_PROGRESS",
"ts": "2025-03-13T13:35:22Z"
},
{
"status": "DONE",
"ts": "2025-03-13T13:35:23Z"
}
]
},
"report": {
"overview": {
"nbOperationsTotal": 1000,
"nbOperationsOK": 1000,
"nbOperationsKO": 0
},
// ...
},
"_links": {
// ...
}
}
```
If the job **state** is **DONE**, **ERROR** or **INTERNAL_ERROR**, the
**report** contains a **file** object for each JSON **file** sent in the
archive.
For each **request** in a **file**, there is a corresponding **request
status** list that specify if the requests is successful or not.
Request name | Request status name
----------|---------
SMTRequests | SMTStatus
Example:
```json
{
"archive": "SMTRequests.tar.gz",
"state": {
// ...
},
"report": {
// ...
"files": [
{
"file": "SMTRequests.json",
"content": {
"SMTStatus": [
//...
]
}
}
]
},
"_links": {
// ...
}
}
```
The **request status** is described by the Person and sites Ids and a
status object.
The **status code** can be **OK** meaning the request is well processed.
Or in **error** with an error code and a message specifying the problem
encountered. Also, in case of multu sites Person, Ids are lined to the
error in order to specify which object caused an error.
Error code | Description
----------|---------
**FIELD_IS_INVALID** | A field content do not match the regex specified
in the documentation
**FIELD_IS_MANDATORY** | A required field is missing
**INTERNAL_ERROR** | Requires an investigation to restore the service
and/or correct the anomaly on Datanumia's side
**INVALID_SERVICE_OFFER_CODE** | One of a service offer code does not
match the configured service offers
**OFFER_DUPLICATED** | The serviceOffers list contains the same offer
code multiple times
**OFFER_MANDATORY** | The serviceOffers list is missing in the site
object
**OPERATION_ALREADY_IN_PROGRESS** | Two requests on the same person or
site are executed concurrently. Do not send two requests on the same
person or site in the same archive
**OPERATION_NOT_SUPPORTED** | A modification, termination or
subscription operation is not supported
**SITE_DUPLICATED** | A person's site list contains the same site
multiple times
**SITE_MANDATORY** | The list of sites is empty or missing for a person
not yet subscribed
**OK example:**
This is where you can retreive **person** and **site** Home Ids:
personId, siteId.
```json
{
"person": {
"ids": {
"personCustomerId": "a_random_person_id_1",
"personId": "3cfa1b03-3bad-4d97-85b8-673c4cab99e7"
},
"sites": [
{
"ids": {
"siteCustomerId": "a_random_site_id_1",
"siteId": "dceb704f-e3fa-4128-aef3-ece501e425aa"
}
}
]
},
"status": [
{
"code": "OK"
}
]
}
```
**Error example:**
In cas of an error, the person and its sites are rollbacked to their
previous state.
```json
{
"person": {
"ids": {
"personCustomerId": "a_random_person_id_2"
},
"sites": [
{
"ids": {
"siteCustomerId": "a_random_site_id_2"
}
}
]
},
"status": [
{
"code": "FIELD_IS_MANDATORY",
"message": "siteZipCode is mandatory!",
"target": {
"personCustomerId": "a_random_person_id_2",
"siteCustomerId": "a_random_site_id_2"
}
},
{
"code": "FIELD_IS_MANDATORY",
"message": "elecMeterType is mandatory!",
"target": {
"personCustomerId": "a_random_person_id_2",
"siteCustomerId": "a_random_site_id_2"
}
}
]
}
```
operationId: getBulkDetailedExecutionStatus
parameters:
- name: job-id
in: path
description: the job id of job to inspect
required: true
schema:
type: string
- name: view
in: query
description: >
The overview option return a global execution report about the job
execution.
In addition, the details option returns a detailed execution report
of each ran operation in the job
example: overview
required: true
schema:
type: string
enum:
- overview
- details
default: overview
responses:
'200':
description: Job detail in success
content:
application/json:
schema:
$ref: '#/components/schemas/BulkDetailedExecutionStatus'
'400':
description: Functional Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
errorCode: INVALID_AUTHORIZATION_HEADER_VALUE
errorDescription: The Authorization header is invalid
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
errorCode: ACCESS_DENIED
errorDescription: >-
The Authorization token does not have permission to the
resource
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
errorCode: JOB_NOT_FOUND
errorDescription: The job xxxx does not exist
'500':
description: Server error
content: {}
security:
- Bearer:
- home:referential:smt-jobs:read
components:
schemas:
BulkDetailedExecutionStatus:
required:
- archive
- state
- _links
type: object
properties:
archive:
type: string
description: |
Name of the archive associated with this job execution.
example: myOperationsArchive.tar.gz
state:
$ref: '#/components/schemas/BulkExecutionState'
report:
$ref: '#/components/schemas/BulkDetailExecutionReport'
_links:
$ref: '#/components/schemas/JobLinks'
ErrorResponse:
required:
- errorCode
- errorDescription
type: object
properties:
errorCode:
description: The error code. Refer to the table bellow
type: string
errorDescription:
type: string
description: The error description
description: ErrorResponse
BulkExecutionState:
properties:
current:
type: string
description: |
current state of the bulk job.
enum:
- ERROR
- DONE
- IN_PROGRESS
- SUBMITTED
- TIMEOUT
example: DONE
history:
$ref: '#/components/schemas/ExecutionStateHistory'
BulkDetailExecutionReport:
properties:
error:
$ref: '#/components/schemas/ErrorDescriptionJob'
overview:
$ref: '#/components/schemas/ExecutionReportOverview'
files:
type: array
items:
$ref: '#/components/schemas/BulkDetailExecutionFileReport'
JobLinks:
required:
- self
type: object
properties:
self:
$ref: '#/components/schemas/JobLinkSelf'
ExecutionStateHistory:
type: array
description: contain all the state change timestamp for a job
example: |
[
{
"status": "SUBMITTED",
"ts": "2024-01-23T15:50:40+01:00"
},
{
"status": "IN_PROGRESS",
"ts": "2024-01-23T15:50:44+01:00"
},
{
"status": "DONE",
"ts": "2024-01-23T15:50:46+01:00"
}
]
items:
$ref: '#/components/schemas/ExecutionStateMapItem'
ErrorDescriptionJob:
required:
- code
- message
type: object
properties:
code:
type: string
enum:
- INVALID_ARCHIVE_FORMAT
message:
type: string
ExecutionReportOverview:
properties:
nbOperationsTotal:
type: integer
description: |
number of executed smt operations
example: 146
nbOperationsOK:
type: integer
description: |
number of successful smt operations
example: 146
nbOperationsKO:
type: integer
description: |
number of failed smt operations
example: 0
BulkDetailExecutionFileReport:
properties:
file:
type: string
description: file name in the archive
example: test.json
error:
$ref: '#/components/schemas/ErrorDescriptionFile'
content:
$ref: '#/components/schemas/BulkDetailExecutionFileReportContent'
JobLinkSelf:
required:
- href
type: object
properties:
href:
type: string
example: https:///smt-jobs/{job-id}
ExecutionStateMapItem:
type: object
properties:
status:
type: string
description: |
current state of the bulk job.
enum:
- ERROR
- DONE
- IN_PROGRESS
- SUBMITTED
- TIMEOUT
example: IN_PROGRESS
ts:
type: string
description: >
Timestamp of the state change as defined by RFC 3339, section 5.6
using the following format: full-date'T'partial-time'Z'
format: date-time
example: '2017-07-21T17:32:28Z'
ErrorDescriptionFile:
required:
- code
- message
type: object
properties:
code:
type: string
enum:
- INVALID_FILE_FORMAT
message:
type: string
BulkDetailExecutionFileReportContent:
properties:
subscriptionStatus:
type: array
items:
$ref: '#/components/schemas/SubscriptionBulkStatus'
siteModificationStatus:
type: array
items:
$ref: '#/components/schemas/SiteModificationBulkStatus'
personModificationStatus:
type: array
items:
$ref: '#/components/schemas/PersonModificationBulkStatus'
addServiceOfferStatus:
type: array
items:
$ref: '#/components/schemas/AddServiceOfferBulkStatus'
terminateServiceOfferStatus:
type: array
items:
$ref: '#/components/schemas/TerminateServiceOfferBulkStatus'
SMTStatus:
type: array
items:
$ref: '#/components/schemas/SMTBulkStatus'
SubscriptionBulkStatus:
required:
- ids
- serviceOfferCode
- status
type: object
properties:
ids:
$ref: '#/components/schemas/SiteAndPersonIds'
serviceOfferCode:
type: string
status:
type: array
items:
$ref: '#/components/schemas/Status'
SiteModificationBulkStatus:
required:
- ids
- status
type: object
properties:
ids:
$ref: '#/components/schemas/SiteAndPersonIds'
status:
type: array
items:
$ref: '#/components/schemas/Status'
PersonModificationBulkStatus:
required:
- ids
- status
type: object
properties:
ids:
$ref: '#/components/schemas/PersonIds'
status:
type: array
items:
$ref: '#/components/schemas/Status'
AddServiceOfferBulkStatus:
required:
- ids
- serviceOfferCode
- status
type: object
properties:
ids:
$ref: '#/components/schemas/SiteAndPersonIds'
serviceOfferCode:
type: string
status:
type: array
items:
$ref: '#/components/schemas/Status'
TerminateServiceOfferBulkStatus:
required:
- ids
- serviceOfferCode
- status
type: object
properties:
ids:
$ref: '#/components/schemas/SiteAndPersonIds'
serviceOfferCode:
type: string
status:
type: array
items:
$ref: '#/components/schemas/Status'
SMTBulkStatus:
required:
- person
- status
type: object
properties:
person:
$ref: '#/components/schemas/SMTSiteAndPersonIds'
status:
type: array
items:
$ref: '#/components/schemas/Status'
SiteAndPersonIds:
required:
- personCustomerId
- siteCustomerId
type: object
properties:
personCustomerId:
type: string
example: person-customer-id-1234
personId:
type: string
example: person-home-id-367
siteCustomerId:
type: string
example: site-customer-id-978
siteId:
type: string
example: site-home-id-451
Status:
required:
- code
- message
- target
type: object
properties:
code:
type: string
example: SITE_ALREADY_ASSIGNED
message:
type: string
example: the site is already associated to another person
target:
type: object
description: input id
properties:
personCustomerId:
type: string
personId:
type: string
siteCustomerId:
type: string
siteId:
type: string
PersonIds:
required:
- personId
- personCustomerId
type: object
properties:
personId:
description: >-
the id of the person object. It is the id from the Home perspective,
not the external id one
type: string
example: personId1
pattern: '[A-Za-z0-9-_]+'
personCustomerId:
type: string
description: Your person identifier. This id is unique.
pattern: '[A-Za-z0-9-_]+'
example: person-45634
SMTSiteAndPersonIds:
required:
- ids
type: object
properties:
ids:
$ref: '#/components/schemas/SMTPersonIds'
sites:
type: array
items:
$ref: '#/components/schemas/SMTSitesIds'
SMTPersonIds:
type: object
properties:
personCustomerId:
type: string
personId:
type: string
SMTSitesIds:
type: object
properties:
ids:
$ref: '#/components/schemas/SMTSiteIds'
SMTSiteIds:
type: object
properties:
siteCustomerId:
type: string
siteId:
type: string
securitySchemes:
Bearer:
type: http
scheme: bearer
````