describe usage

README.md

@@ -8,6 +8,18 @@ the Norwegian accounting and invoicing platform.
 - Automatic pagination with `auto_paging_each`
 - HTTP errors mapped to typed exceptions, with retry on rate limits (429) and server errors
 
+> **API reference.** This gem is a thin transport over the Fiken API — it does not
+> redefine the data model. Request bodies and response fields use exactly the names,
+> types and nesting from the official OpenAPI (Swagger) specification. Keep it open
+> while you build:
+>
+> - Interactive docs: <https://api.fiken.no/api/v2/docs>
+> - OpenAPI spec (YAML): <https://api.fiken.no/api/v2/docs/swagger.yaml>
+>
+> Each resource below maps to a tag in that spec, and every `Fiken::Object` you get
+> back mirrors the corresponding response schema. See
+> [Response objects & data structures](#response-objects--data-structures).
+
 ## Installation
 
 ```ruby
@@ -135,6 +147,37 @@ client.invoices(slug).attachments(456).add(io: pdf_io, filename: "invoice.pdf",
 client.inbox(slug).create(path: "receipt.pdf", name: "Office supplies")
 ```
 
+## Response objects & data structures
+
+Responses are wrapped in `Fiken::Object`, a lightweight, read-only struct built
+recursively from the JSON. The gem deliberately does **not** impose its own typed
+models — the shape of every object is defined by the Fiken OpenAPI spec, so that is
+your source of truth for field names and types:
+
+- OpenAPI spec (YAML): <https://api.fiken.no/api/v2/docs/swagger.yaml>
+- Interactive docs: <https://api.fiken.no/api/v2/docs>
+
+For example, an invoice returned by `client.invoices(slug).find(id)` mirrors the
+spec's `invoiceResult` schema, so the keys documented there are exactly what you
+access:
+
+```ruby
+invoice = client.invoices(slug).find(456)
+
+invoice.invoiceNumber          # camelCase — exactly as in the spec
+invoice.invoice_number         # snake_case alias for the same field
+invoice[:invoiceNumber]        # hash-style access
+invoice.lines.first.vatType    # nested objects/arrays wrapped recursively
+invoice.to_h                   # plain Hash with the original (camelCase) keys
+invoice.keys                   # inspect available fields at runtime
+```
+
+Because access maps straight onto the spec schema, the schema name to look up for a
+given call is predictable: `*Result` schemas for responses (e.g. `invoiceResult`,
+`saleResult`, `contact`) and `*Request` schemas for the hashes you pass to
+`create`/`update` (e.g. `invoiceRequest`, `fullCreditNoteRequest`). When in doubt,
+`obj.to_h` shows you the raw structure as Fiken returned it.
+
 ## Error handling
 
 Non-success responses raise a typed subclass of `Fiken::Error`, each carrying