Daily Reports

Daily reports (Tagesberichte) document what happened on a construction site or project on a single calendar day: who was on site and for how long, the weather, subcontractors, activities, material usage, comments, photos, and signatures. A report is identified by the combination of a project and a date — it is not a stored object of its own, but materializes from the individual entries recorded for that day, either authored on site in the mobile app or filled in automatically from time tracking.

The Report Object

A report is the group of all entries that share a project and a date. Reports only exist for projects that have daily reports enabled in the project's settings, and only for days that have at least one entry. The tag_id is the project's id as returned by the Projects API.

Every report has a computed status describing its position in the review lifecycle:

• draft — the report is being worked on and can be edited on site.
• submitted — the site crew handed the report in for review. Only supervisors (users with the approve permission) may still change it.
• closed — the report was approved. Like submitted, it is locked for regular editors.
• archived — the report was archived by a supervisor. Archived reports are immutable (including the time-tracking autofill) until a supervisor moves them back to draft.

Field Configurations

Which fields a daily report contains is configurable per organization, and the configuration is versioned by date. Your organization keeps a list of configurations, each with a valid_from date; the configuration that applies to a report is the one with the most recent valid_from on or before the report's date (a configuration becomes active on its valid_from day).

A report whose date lies before every stored valid_from uses your organization's oldest configuration. The first version is written when daily reports are switched on, so reports for days before that switch match no version at all — they are rendered with the oldest field set your organization ever had, not with the built-in default form. The default form below applies only to organizations that have no configuration at all:

Versioning has two consequences you will notice in the API:

• Every entry is interpreted and validated against the configuration that is active on the entry's date, not the one active today. Historical reports keep the form they were written with, even after the organization changes its report layout.
• Entries whose field id does not exist in the configuration active for their date (for example, a field that was later removed) are omitted from entry listings and PDFs — they have no schema to render.

Use the field-types endpoint to discover the available field types and how entries of each type are grouped.

The Entry Object

Entries are append-only: nothing is ever updated in place. Each entry belongs to a logical group identified by its group_id, which combines the report's date and tag_id with type-specific keys (for example, one group per employee for working times, or one group per author-and-text for comments). The most recent entry of a group is its current value; older entries are the group's history. An entry with burned: true is a tombstone that marks its group as deleted.

Entries written by the system — the time-tracking autofill and the automatic weather capture — have author_id: null; the affected employee is carried in on_behalf_of_id. Manually authored entries carry the author, and on_behalf_of_id names the person the entry is about (e.g. who signed, or whose working time was corrected).

Type-specific value fields

In addition to the common properties above, each entry carries the value fields of its type:

• weather — time (string, a clock time such as 08:00), temperature (number or null), and weather_condition: one of sunny, cloudy, precipitation or snow, or null when the reading carries no usable condition. The four categories are the ones listed under choices.condition in the field types response. Grouped by time, so a report holds one weather row per configured time slot.

  Writes may additionally carry precipitation and cloud_cover (numbers) and wind (a [speed, direction] pair with the direction in degrees 0–359). Those keys are still validated and stored, but reads no longer return them. Automatically captured readings are reduced the same way: the weather provider's detailed response stays server-side and is folded into the single weather_condition category.

• employee-working-times — hours (number between 0 and 24), plus a snapshot of the employee at the time the entry was written: employee_account_id (string), employee_name (string), and employee_position (string, from the employee's position custom field; empty string if unset). The snapshot keeps the report accurate even if the employee's account or custom fields change later. Grouped by on_behalf_of_id: one row per employee and day.

• subcontractors — name (string), employees (integer), hours (number or null), comment (string or null). Grouped by on_behalf_of_id and name.

• activities — text (string). Grouped by on_behalf_of_id and text, so the same activity text for the same person deduplicates.

• string — value (string). Used by the default materials and comments fields. Grouped by on_behalf_of_id and value.

• image — image_id (string), image_key (string or null, the S3 object key from the photo upload flow), image_url (string or null — a pre-signed download URL derived from image_key, valid for one hour), thumb_key (string or null, the object key of the downscaled preview), thumb_url (string or null — a pre-signed download URL derived from thumb_key, valid for one hour), latitude / longitude (numbers or null), and taken_at (string or null). Grouped by on_behalf_of_id and image_id. thumb_key and thumb_url are null for entries whose client did not upload a preview; fall back to image_url in that case.

• signature — image (string, a data:image/... data URL of the signature). Grouped by on_behalf_of_id: one signature per person per report.

List all Reports

Retrieve a paginated list of report descriptors, one per project and date that has at least one entry. Results are ordered by date descending, then by project id, and cover only projects that have daily reports enabled and that your token is allowed to see.

Query Parameters

curl -X GET "https://api.zeitstrom.com/api/v2/daily-reports/reports/?date_from=2024-06-17&date_to=2024-06-18&status=draft|submitted" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31|2024-06-18",
      "date": "2024-06-18",
      "tag_id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
      "status": "submitted",
      "tag": {
        "id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
        "name": "Neubau Lagerhalle",
        "code": "P-2024-018",
        "color": "#2563eb"
      },
      "address": "Industriestraße 12, 44269 Dortmund",
      "cost_center": "4711",
      "client": "Musterbau GmbH",
      "contributor_count": 2,
      "employees": [
        { "id": "508d5250-7399-4b65-a574-3da53d9ddc25", "first_name": "Anna", "last_name": "Schmidt" }
      ],
      "total_hours": 7.75,
      "weather": [
        { "time": "08:00", "temperature": 14.2, "weather_condition": "cloudy" }
      ],
      "values": [
        {
          "type": "weather",
          "time": "08:00",
          "temperature": 14.2,
          "weather_condition": "cloudy"
        },
        {
          "type": "employee-working-times",
          "on_behalf_of_id": "508d5250-7399-4b65-a574-3da53d9ddc25",
          "on_behalf_of_name": "Anna Schmidt",
          "hours": 7.75
        }
      ]
    },
    {
      "id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31|2024-06-17",
      "date": "2024-06-17",
      "tag_id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
      "status": "draft",
      "tag": {
        "id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
        "name": "Neubau Lagerhalle",
        "code": "P-2024-018",
        "color": "#2563eb"
      },
      "address": "Industriestraße 12, 44269 Dortmund",
      "cost_center": "4711",
      "client": "Musterbau GmbH",
      "contributor_count": 0,
      "employees": [],
      "total_hours": 0,
      "weather": [],
      "values": []
    }
  ]
}

List Field Types

Retrieve the available field types, the keys entries of each type are grouped by, and a human-readable description of what the type is for. Every group_by list starts with the common date and tag_id keys, followed by the type's own grouping values.

Each type also carries choices, an object of named choice lists for the value fields that accept a fixed set of values. Every list holds {id, label} objects, where id is what entries store and label is the German text to show. Types without such a field return an empty object, so clients can read the picker options from the server instead of hard-coding them. Today only weather defines choices, under the key condition.

curl -X GET "https://api.zeitstrom.com/api/v2/daily-reports/reports/field-types/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

{
  "count": 7,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "weather",
      "group_by": ["date", "tag_id", "time"],
      "description": "Weather readings for configured local report times.\n\nConfig: requires `times`, a list of HHMM strings such as `[\"0800\"]`, and\n`autofill_from_api`, a boolean that controls weather autofill from an API.",
      "choices": {
        "condition": [
          { "id": "sunny", "label": "Sonnig" },
          { "id": "cloudy", "label": "Bewölkt" },
          { "id": "precipitation", "label": "Niederschlag" },
          { "id": "snow", "label": "Schnee" }
        ]
      }
    },
    {
      "id": "employee-working-times",
      "group_by": ["date", "tag_id", "on_behalf_of_id"],
      "description": "Working-time totals for employees contributing to a daily report.\n\nConfig: requires `autofill_from_tracking`, a boolean that controls whether\ntracked working times are imported automatically.",
      "choices": {}
    },
    {
      "id": "subcontractors",
      "group_by": ["date", "tag_id", "on_behalf_of_id", "name"],
      "description": "Per-day list of subcontractor companies present on a project.\n\nConfig: no options are supported; pass `{}` or omit the config.\nValues require `name` and `employees`; `hours` and `comment` are optional.",
      "choices": {}
    },
    {
      "id": "activities",
      "group_by": ["date", "tag_id", "on_behalf_of_id", "text"],
      "description": "Activity notes for work performed on a daily report.\n\nConfig: requires `autofill_from_tracking`, a boolean that controls whether\ntime-tracking comments are imported automatically.",
      "choices": {}
    },
    {
      "id": "string",
      "group_by": ["date", "tag_id", "on_behalf_of_id", "value"],
      "description": "Free-text report entry used for configurable text fields.\n\nConfig: no options are supported; pass `{}` or omit the config.",
      "choices": {}
    },
    {
      "id": "image",
      "group_by": ["date", "tag_id", "on_behalf_of_id", "image_id"],
      "description": "Photo attachment for a daily report, including optional capture metadata.\n\nConfig: no options are supported; pass `{}` or omit the config.",
      "choices": {}
    },
    {
      "id": "signature",
      "group_by": ["date", "tag_id", "on_behalf_of_id"],
      "description": "Signature image captured for a report participant.\n\nConfig: no options are supported; pass `{}` or omit the config.",
      "choices": {}
    }
  ]
}

Retrieve Report Status

Get the current status of a single report. A report without any recorded status transition is a draft.

Query Parameters

curl -X GET "https://api.zeitstrom.com/api/v2/daily-reports/reports/status/?tag=3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31&date=2024-06-18" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

{
  "tag_id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
  "date": "2024-06-18",
  "status": "submitted"
}

Autofill a Report

Compute and store report entries from the day's time tracking on the project. Only fields whose active configuration carries autofill_from_tracking and whose type is employee-working-times or activities are filled — with the default configuration these are employee-working-times (each employee's tracked hours on the project, rounded to two decimals) and activities (one entry per distinct tracking comment and employee).

The operation creates entries as a side effect. System-written entries have author_id: null. The autofill is idempotent: repeated calls converge to the same state, unchanged values are skipped, and a value that was manually corrected by a user is never overwritten.

Autofilling a report that is submitted or closed requires the daily_reports:approve permission; without it the request returns 403 Forbidden.

curl -X POST "https://api.zeitstrom.com/api/v2/daily-reports/reports/autofill/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
    "date": "2024-06-18"
  }'

{
  "tag_id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
  "date": "2024-06-18",
  "filled": ["employee-working-times", "activities"]
}

Download a Report PDF

Render a single report as a print-friendly PDF. The response streams the PDF binary (Content-Type: application/pdf) with a filename of the form Tagesbericht-<project code>-<date>.pdf. The PDF contains the fields of the configuration active for the report's date, with the report's status shown in the header.

The id is the report's synthetic identifier <tag_id>|<date> as returned by List all Reports. The | may be sent literally or percent-encoded as %7C. An id without a date part, a date that is not a valid YYYY-MM-DD, or a project that is unknown, disabled or outside your visible set all return a 400 validation error.

curl -X GET "https://api.zeitstrom.com/api/v2/daily-reports/reports/3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31%7C2024-06-18/pdf/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -o "Tagesbericht-2024-06-18.pdf"

List all Entries

Retrieve a paginated list of report entries, projected through the field configuration active for each entry's date. Entries of fields that no longer exist in the active configuration are omitted. To reconstruct the current content of a report, request grouped=1 for a single project and date and treat groups whose latest entry is burned: true as deleted.

Query Parameters

curl -X GET "https://api.zeitstrom.com/api/v2/daily-reports/entries/?tags=3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31&daterange=2024-06-18|2024-06-18&grouped=1" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "group_id": "2024-06-18|3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31|508d5250-7399-4b65-a574-3da53d9ddc25",
      "id": "6b0f2d84-3c9e-4f17-8a52-b1d4e7c90a63",
      "field_id": "employee-working-times",
      "type": "employee-working-times",
      "created_at": "2024-06-18T17:02:11",
      "modified_at": "2024-06-18T17:02:11",
      "submitted_at": null,
      "date": "2024-06-18",
      "tag_id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
      "author_id": null,
      "on_behalf_of_id": "508d5250-7399-4b65-a574-3da53d9ddc25",
      "author_name": null,
      "on_behalf_of_name": "Anna Schmidt",
      "burned": false,
      "hours": 7.75,
      "group_count": 1
    },
    {
      "group_id": "2024-06-18|3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31|e7c9a4d2-1f38-4b6a-9c05-8d2f7b3e6a14|Lieferung Schalholz verspätet",
      "id": "9d47c1f0-5e2b-4a86-b3f9-0c61d8a24e57",
      "field_id": "comments",
      "type": "string",
      "created_at": "2024-06-18T16:42:09",
      "modified_at": "2024-06-18T16:42:09",
      "submitted_at": "2024-06-18T16:42:07",
      "date": "2024-06-18",
      "tag_id": "3f2b8c1e-9a47-4d05-b8a1-6c2d94e07f31",
      "author_id": "e7c9a4d2-1f38-4b6a-9c05-8d2f7b3e6a14",
      "on_behalf_of_id": "e7c9a4d2-1f38-4b6a-9c05-8d2f7b3e6a14",
      "author_name": "Jonas Weber",
      "on_behalf_of_name": "Jonas Weber",
      "burned": false,
      "value": "Lieferung Schalholz verspätet",
      "group_count": 1
    }
  ]
}

Get a Photo Upload Token

Generate a pre-signed upload token for a daily-report photo (at most 2 MB). Photos are capped well below the 15 MB allowed for document attachments elsewhere in the API, because they are rendered into the PDF export — downscale on the client before uploading. The response contains a pre-signed S3 url and form fields, valid for 12 hours. Upload the photo as a multipart/form-data POST to url, including all fields plus the file itself. The returned fields.key is the object key that photo entries store as their image_key; when entries are read, the server signs it back into a temporary image_url download link. Both image_key and thumb_key are validated to lie inside your organization's upload namespace — scoped to the authenticated user rather than a specific employee — before an entry is persisted; a key pointing anywhere else is rejected.

The response also contains thumb_fields, a second set of signed form fields for uploading a downscaled preview alongside the original. Both tokens POST to the same url and share the same bucket, size limit and 12-hour lifetime — only the signed fields differ. thumb_fields.key is fields.key with a .thumb infix before the extension (…/photo.jpg → …/photo.thumb.jpg), so either key can be derived from the other. Uploading the preview is optional. When you do upload one, persist thumb_fields.key on the photo entry as thumb_key alongside image_key: reads then sign it into a thumb_url download link of its own, so clients can show the preview without fetching the full-size original. Entries that carry no thumb_key return null for both thumb_key and thumb_url.

curl -X POST "https://api.zeitstrom.com/api/v2/daily-reports/entries/upload-photo-token/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "betonage-nord",
    "filetype": "image/jpeg",
    "filesize": 2048576
  }'

{
  "url": "https://s3.eu-central-1.amazonaws.com/zeitstrom-uploads",
  "fields": {
    "key": "i-f4a5b6c7-d8e9-0123-fabc-456789012345/u-a1b2c3d4-e5f6-7890-abcd-ef1234567890/daily-reports/2024/06/18/0d3e2b1a-4c5d-6e7f-8901-234567890abc/2024-06-18_4f2a_betonage-nord.jpg",
    "AWSAccessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "policy": "eyJleHBpcmF0aW9uIjogIjIwMjQtMDYtMTlUMDY6MzA6MDBaIiwgImNvbmRpdGlvbnMiOiBbXX0=",
    "signature": "hV0kwGx0ZQKgQnJ1zW0m9dEXAMPLE"
  },
  "thumb_fields": {
    "key": "i-f4a5b6c7-d8e9-0123-fabc-456789012345/u-a1b2c3d4-e5f6-7890-abcd-ef1234567890/daily-reports/2024/06/18/0d3e2b1a-4c5d-6e7f-8901-234567890abc/2024-06-18_4f2a_betonage-nord.thumb.jpg",
    "AWSAccessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "policy": "eyJleHBpcmF0aW9uIjogIjIwMjQtMDYtMTlUMDY6MzA6MDBaIiwgImNvbmRpdGlvbnMiOiBbXX0=",
    "signature": "yQ2mNpR7bTfLc0aVzX4jE9EXAMPLE"
  }
}