# Keikkalasku Partner API

> Create invoicing requests for gig workers through Keikkalasku. A partner invites each worker once (POST /v1/connections), reports gigs (POST /v1/gigs) with each worker's VAT-excluded share, and polls status (GET /v1/gigs?updated_since=). Keikkalasku invoices the partner and pays the workers. Amounts are strings with two decimals ("200.00"), EUR, VAT-excluded. Errors are RFC 9457 problem documents with code, field, hint and docs_url.

Test API: https://api-test-pp.keikkis.fi/v1 with kl_test_ keys — validates for real, answers from fixed data, stores nothing.
Production: https://api-pp.keikkis.fi/v1 with kl_live_ keys.
Auth: Authorization: Bearer <key>. Keys are created in the partner portal (https://kumppani-pp.keikkis.fi).

## Docs

- [OpenAPI spec](https://kumppani-pp.keikkis.fi/v1/openapi.json): every endpoint, field, example and error code
- [Overview](https://kumppani-pp.keikkis.fi/docs/en/index.md)
- [Quickstart](https://kumppani-pp.keikkis.fi/docs/en/quickstart.md)
- [Test API and magic values](https://kumppani-pp.keikkis.fi/docs/en/test-api.md)
- [Work types and VAT](https://kumppani-pp.keikkis.fi/docs/en/work-types.md)
- [Statuses](https://kumppani-pp.keikkis.fi/docs/en/statuses.md)
- [Errors](https://kumppani-pp.keikkis.fi/docs/en/errors.md)

## Magic values (test API only)

- connection email local part active / declined / expired / revoked → that status; otherwise pending
- worker external_user_id ending _pending → that worker awaiting_worker
- gig external_id ending _invoiced / _paid / _completed / _cancelled / _rejected → every worker in that status (invoiced and later include test invoice details)
- gig external_id ending _conflict → 409 idempotency_conflict
- DELETE /v1/gigs/<id ending _invoiced, _paid or _completed> → 409 already_invoiced
- POST /v1/gigs?dry_run=true → validates and previews without saving; identical in both environments
- The test API does not enforce the daily euro cap and GET returns fixture data, not what you posted.

## Rules worth knowing

- external_id is the idempotency key: same content → 200 with the existing gig; different content → 409.
- work_type: worker → gig → partner default; GET /v1/work_types lists the allowed codes. Never send a VAT rate.
- The VAT rate follows the gig date (date the work was performed).
- Worker statuses: awaiting_worker, received, invoiced, paid, completed, declined, expired, cancelled, rejected.
- Keys: kl_test_ only on the test host, kl_live_ only on the production host (401 wrong_environment).