# Wisnots Netzanmeldung API

> Register PV, storage, heat pumps, wallboxes and air conditioning with the responsible German grid operator, through one API. Base URL https://netz-api.wisnots.com, the key in `Authorization: Bearer`, JSON in and out; files as `multipart/form-data` on the `/upload` routes.

A `wnz_test_` key is the sandbox and a `wnz_live_` key is live; the prefix is the whole switch, same host and same calls. Keys come from the console at https://www.wisnots.com/netzanmeldung/portal under Entwickler; a free account gets a sandbox key. Nothing on the sandbox reaches a grid operator.

## The model

- A case registers one Anlagentyp: `pv`, `speicher`, `waermepumpe`, `ladeeinrichtung` or `klimaanlage`; `14a` is the one route that does not pin the device.
- Give a case `material` (files, a pasted mail, or a `fixture` the sandbox reads for free) and it is read; give it `declared` fields and they are authoritative; both compose.
- It answers with `fields` (each with its source and, when extracted, the quote it came from), `open` (what is still needed, who is expected to know it, whether it blocks filing), `conflicts`, `notices` and `status`.
- Field paths are readable (`site.street`); every field carries its number in the national data set as `nr`; `declared.nr` reaches any field by number. `GET /v1/anmeldungen/{typ}/fields` is the dictionary to build forms and mappings from.

## Workflow

1. `POST /v1/anmeldungen/{typ}` with a JSON body, or `POST /v1/anmeldungen/{typ}/upload` with files, `intent: "draft"`, and an `Idempotency-Key`.
2. Wait for `case.extraction_completed` on a webhook (`POST /v1/webhooks`), or poll `GET /v1/anmeldungen/{id}` until `status` leaves `extracting`. Poll the case, not a material: `pending` and `reading` both mean wait.
3. `PATCH /v1/anmeldungen/{id}` with `declared` for the blocking entries of `open[]`.
4. `POST /v1/anmeldungen/{id}/file`, with an `Idempotency-Key`. On the sandbox add `sandbox_outcome` and `sandbox_pace`.

A refusal is an RFC 9457 problem document: `code` from a closed enum, `detail`, and `errors[]` naming each refused field.

## Routes

- `GET /v1/netzbetreiber`: Which grid operators, and which one here
- `POST /v1/webhooks`: Register an endpoint
- `GET /v1/webhooks`: Your endpoints
- `DELETE /v1/webhooks/{webhookId}`: Remove an endpoint
- `POST /v1/anmeldungen/pv`: Register a PV array
- `POST /v1/anmeldungen/pv/upload`: Upload files for a PV array
- `GET /v1/anmeldungen/pv/fields`: The PV field dictionary
- `POST /v1/anmeldungen/speicher`: Register a battery storage unit
- `POST /v1/anmeldungen/speicher/upload`: Upload files for a battery storage unit
- `GET /v1/anmeldungen/speicher/fields`: Fields for a battery storage unit
- `POST /v1/anmeldungen/waermepumpe`: Register a heat pump
- `POST /v1/anmeldungen/waermepumpe/upload`: Upload files for a heat pump
- `GET /v1/anmeldungen/waermepumpe/fields`: Fields for a heat pump
- `POST /v1/anmeldungen/ladeeinrichtung`: Register a charge point
- `POST /v1/anmeldungen/ladeeinrichtung/upload`: Upload files for a charge point
- `GET /v1/anmeldungen/ladeeinrichtung/fields`: Fields for a charge point
- `POST /v1/anmeldungen/klimaanlage`: Register an air conditioning unit
- `POST /v1/anmeldungen/klimaanlage/upload`: Upload files for an air conditioning unit
- `GET /v1/anmeldungen/klimaanlage/fields`: Fields for an air conditioning unit
- `POST /v1/anmeldungen/14a`: Create a § 14a registration
- `POST /v1/anmeldungen/14a/upload`: Upload files for a § 14a registration
- `GET /v1/anmeldungen/14a/fields`: The field dictionary
- `GET /v1/anmeldungen`: List your cases
- `GET /v1/anmeldungen/{id}`: Read a case
- `PATCH /v1/anmeldungen/{id}`: Declare or correct values
- `DELETE /v1/anmeldungen/{id}`: Discard a draft
- `POST /v1/anmeldungen/{id}/material`: Add raw material
- `POST /v1/anmeldungen/{id}/upload`: Upload files to a case
- `POST /v1/anmeldungen/{id}/documents`: Get an upload target
- `POST /v1/anmeldungen/{id}/file`: File the registration
- `GET /v1/anmeldungen/{id}/events`: Replay the log
- `GET /v1/anmeldungen/{id}/information-requests/{requestId}`: Read an operator information request
- `POST /v1/anmeldungen/{id}/information-requests/{requestId}/responses`: Provide the requested information
- `POST /v1/anmeldungen/{id}/information-requests/{requestId}/responses/upload`: Provide requested documents
- `POST /v1/anmeldungen/{id}/information-requests/{requestId}/responses/{responseId}/submit`: Submit a completed response

## Documents

- [OpenAPI 3.1](https://www.wisnots.com/netz-api/openapi.json): every route, schema, example and error, rendered at https://www.wisnots.com/netzanmeldung/api.
- [Full text](https://www.wisnots.com/netz-api/llms-full.txt): the overview and every operation's description in one file.
- [Agent skill](https://www.wisnots.com/netz-api/skills/wisnots-netz/SKILL.md): the workflow and the rules as a SKILL.md, for `.agents/skills/wisnots-netz/` or `.claude/skills/wisnots-netz/`.
- [Setup prompt](https://www.wisnots.com/netz-api/agent-prompt.txt): what the "Set up your agent" button copies.
- [Example bodies](https://www.wisnots.com/netz-api/examples/create-pv-raw.json): one JSON file per example in the spec, named after it (`create-pv-fixture.json`, `create-pv-raw.json`, `create-pv-declared.json`, and so on per type).
- [TypeScript client](https://www.wisnots.com/netz-api/sdk/README.md): dependency-free, four files to vendor: `index.ts`, `client.ts`, `types.gen.ts`, `webhooks.ts`, `README.md`, all under https://www.wisnots.com/netz-api/sdk/.
- [Console](https://www.wisnots.com/netzanmeldung/portal): keys, webhooks, the request log, and every case.