{ "openapi": "3.1.0", "info": { "title": "Ledgerly API", "version": "1.0.0", "description": "Multi-tenant invoicing & expenses API. All amounts are integer minor units (cents). Errors use RFC 7807 application/problem+json. Fictional demo project." }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": {} }, "paths": { "/health": { "get": { "summary": "Liveness probe", "tags": [ "Health" ], "description": "Returns 200 while the process is up. Does not touch the database.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "uptimeSeconds": { "type": "number" } }, "required": [ "status", "uptimeSeconds" ], "additionalProperties": false } } } } } } }, "/ready": { "get": { "summary": "Readiness probe", "tags": [ "Health" ], "description": "Returns 200 when the database answers, 503 otherwise.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready" ] }, "checks": { "type": "object", "properties": { "database": { "type": "string", "enum": [ "ok" ] } }, "required": [ "database" ], "additionalProperties": false } }, "required": [ "status", "checks" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unavailable" ] }, "checks": { "type": "object", "properties": { "database": { "type": "string", "enum": [ "down" ] } }, "required": [ "database" ], "additionalProperties": false } }, "required": [ "status", "checks" ], "additionalProperties": false } } } } } } }, "/v1/auth/register": { "post": { "summary": "Create an account and its organization", "tags": [ "Auth" ], "description": "The new user becomes the owner of a new organization (tenant).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "password": { "type": "string", "minLength": 10, "maxLength": 128, "allOf": [ { "pattern": "[A-Za-z]" }, { "pattern": "\\d" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "organizationName": { "type": "string", "minLength": 1, "maxLength": 120 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code", "default": "USD" } }, "required": [ "email", "password", "name", "organizationName" ], "additionalProperties": false } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" } }, "required": [ "id", "email", "name" ], "additionalProperties": false }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "id", "name", "currency" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "owner", "member" ] }, "tokens": { "type": "object", "properties": { "accessToken": { "type": "string" }, "tokenType": { "type": "string", "enum": [ "Bearer" ] }, "expiresIn": { "type": "integer", "description": "Access token lifetime in seconds" }, "refreshToken": { "type": "string" }, "refreshExpiresAt": { "type": "string" } }, "required": [ "accessToken", "tokenType", "expiresIn", "refreshToken", "refreshExpiresAt" ], "additionalProperties": false } }, "required": [ "user", "organization", "role", "tokens" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "409": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "429": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/auth/login": { "post": { "summary": "Exchange credentials for tokens", "tags": [ "Auth" ], "description": "Pass organizationId to sign into a specific organization when you belong to several.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "password": { "type": "string", "minLength": 1, "maxLength": 128 }, "organizationId": { "type": "string" } }, "required": [ "email", "password" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string" }, "tokenType": { "type": "string", "enum": [ "Bearer" ] }, "expiresIn": { "type": "integer", "description": "Access token lifetime in seconds" }, "refreshToken": { "type": "string" }, "refreshExpiresAt": { "type": "string" }, "organizationId": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ] } }, "required": [ "accessToken", "tokenType", "expiresIn", "refreshToken", "refreshExpiresAt", "organizationId", "role" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "429": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/auth/refresh": { "post": { "summary": "Rotate a refresh token", "tags": [ "Auth" ], "description": "Returns a new access/refresh pair and revokes the old refresh token. Re-using a revoked token revokes the whole token family (theft detection).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 20 } }, "required": [ "refreshToken" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string" }, "tokenType": { "type": "string", "enum": [ "Bearer" ] }, "expiresIn": { "type": "integer", "description": "Access token lifetime in seconds" }, "refreshToken": { "type": "string" }, "refreshExpiresAt": { "type": "string" } }, "required": [ "accessToken", "tokenType", "expiresIn", "refreshToken", "refreshExpiresAt" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "429": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/auth/logout": { "post": { "summary": "Revoke a refresh token (and its family)", "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 20 } }, "required": [ "refreshToken" ], "additionalProperties": false } } }, "required": true }, "responses": { "204": { "description": "Default Response", "content": { "application/json": { "schema": { "enum": [ "null" ], "nullable": true } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/auth/me": { "get": { "summary": "Current user, organization and role", "tags": [ "Auth" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" } }, "required": [ "id", "email", "name" ], "additionalProperties": false }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" } }, "required": [ "id", "name", "currency" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "owner", "member" ] }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "role": { "type": "string", "enum": [ "owner", "member" ] } }, "required": [ "id", "name", "currency", "role" ], "additionalProperties": false } } }, "required": [ "user", "organization", "role", "organizations" ], "additionalProperties": false } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/members/": { "get": { "summary": "List organization members", "tags": [ "Members" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ] }, "joinedAt": { "type": "string" } }, "required": [ "userId", "email", "name", "role", "joinedAt" ], "additionalProperties": false } } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } }, "post": { "summary": "Add a member (owner only)", "tags": [ "Members" ], "description": "Adds an existing user by email, or creates the account with the given initial password.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "role": { "type": "string", "enum": [ "owner", "member" ], "default": "member" }, "initialPassword": { "type": "string", "minLength": 10, "maxLength": 128 } }, "required": [ "email", "name" ], "additionalProperties": false } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ] }, "joinedAt": { "type": "string" } }, "required": [ "userId", "email", "name", "role", "joinedAt" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "403": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "409": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "422": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/members/{userId}": { "patch": { "summary": "Change a member's role (owner only)", "tags": [ "Members" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "member" ] } }, "required": [ "role" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "userId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ] }, "joinedAt": { "type": "string" } }, "required": [ "userId", "email", "name", "role", "joinedAt" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "403": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "404": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "409": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } }, "delete": { "summary": "Remove a member (owner only)", "tags": [ "Members" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "userId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Default Response", "content": { "application/json": { "schema": { "enum": [ "null" ], "nullable": true } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "403": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "404": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "409": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/customers/": { "get": { "summary": "List customers", "tags": [ "Customers" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "pageSize", "required": false }, { "schema": { "type": "string", "enum": [ "name", "-name", "createdAt", "-createdAt" ], "default": "-name" }, "in": "query", "name": "sort", "required": false, "description": "Sort field; prefix with \"-\" for descending. One of: name, createdAt" }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "q", "required": false, "description": "Search in name and email" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "taxId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "email", "taxId", "createdAt" ], "additionalProperties": false } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "data", "page", "pageSize", "total", "totalPages" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } }, "post": { "summary": "Create a customer", "tags": [ "Customers" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "nullable": true }, "taxId": { "type": "string", "maxLength": 50, "nullable": true } }, "required": [ "name" ], "additionalProperties": false } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "taxId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "email", "taxId", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/customers/{id}": { "get": { "summary": "Get a customer", "tags": [ "Customers" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "taxId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "email", "taxId", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "404": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } }, "patch": { "summary": "Update a customer", "tags": [ "Customers" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "nullable": true }, "taxId": { "type": "string", "maxLength": 50, "nullable": true } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "taxId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "email", "taxId", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "404": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } }, "delete": { "summary": "Delete a customer (owner only)", "tags": [ "Customers" ], "description": "Customers with invoices cannot be deleted (409), to keep the ledger intact.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Default Response", "content": { "application/json": { "schema": { "enum": [ "null" ], "nullable": true } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "403": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "404": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "409": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/invoices/": { "get": { "summary": "List invoices", "tags": [ "Invoices" ], "description": "Filter by status, customer, overdue flag and issue-date range; paginate and sort.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "pageSize", "required": false }, { "schema": { "type": "string", "enum": [ "issueDate", "-issueDate", "dueDate", "-dueDate", "totalCents", "-totalCents", "number", "-number", "createdAt", "-createdAt" ], "default": "-issueDate" }, "in": "query", "name": "sort", "required": false, "description": "Sort field; prefix with \"-\" for descending. One of: issueDate, dueDate, totalCents, number, createdAt" }, { "schema": { "type": "string", "enum": [ "draft", "sent", "partially_paid", "paid", "void" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "customerId", "required": false }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "overdue", "required": false }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "issuedFrom", "required": false }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "issuedTo", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "partially_paid", "paid", "void" ] }, "customerId": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "subtotalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "taxCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "totalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "amountPaidCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "balanceCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "overdue": { "type": "boolean", "description": "Derived: past due date and not fully paid" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "number", "status", "customerId", "currency", "issueDate", "dueDate", "subtotalCents", "taxCents", "totalCents", "amountPaidCents", "balanceCents", "overdue", "createdAt", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "data", "page", "pageSize", "total", "totalPages" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } }, "post": { "summary": "Create a draft invoice", "tags": [ "Invoices" ], "description": "Totals are computed server-side (per-line tax, half-up rounding). Numbers are sequential per organization.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1 }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Defaults to today" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Defaults to issueDate + 30 days" }, "notes": { "type": "string", "maxLength": 2000, "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "quantity": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 1000000 }, "unitPriceCents": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "taxRateBp": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Tax rate in basis points (825 = 8.25%)" } }, "required": [ "description", "quantity", "unitPriceCents" ], "additionalProperties": false }, "minItems": 1, "maxItems": 200 } }, "required": [ "customerId", "lines" ], "additionalProperties": false } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "partially_paid", "paid", "void" ] }, "customerId": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "subtotalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "taxCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "totalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "amountPaidCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "balanceCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "overdue": { "type": "boolean", "description": "Derived: past due date and not fully paid" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "notes": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "nullable": true }, "voidedAt": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "quantity": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 1000000 }, "unitPriceCents": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "taxRateBp": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Tax rate in basis points (825 = 8.25%)" }, "id": { "type": "string" }, "position": { "type": "integer" }, "subtotalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "taxCents": { "type": "integer", "description": "Amount in minor units (cents)" } }, "required": [ "description", "quantity", "unitPriceCents", "id", "position", "subtotalCents", "taxCents" ], "additionalProperties": false } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "amountCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "method": { "type": "string", "enum": [ "card", "bank_transfer", "cash", "other" ] }, "paidAt": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "invoiceId", "amountCents", "method", "paidAt", "reference", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "number", "status", "customerId", "currency", "issueDate", "dueDate", "subtotalCents", "taxCents", "totalCents", "amountPaidCents", "balanceCents", "overdue", "createdAt", "updatedAt", "notes", "sentAt", "voidedAt", "lines", "payments" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/invoices/{id}": { "get": { "summary": "Get an invoice with lines and payments", "tags": [ "Invoices" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "partially_paid", "paid", "void" ] }, "customerId": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "subtotalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "taxCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "totalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "amountPaidCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "balanceCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "overdue": { "type": "boolean", "description": "Derived: past due date and not fully paid" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "notes": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "nullable": true }, "voidedAt": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "quantity": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 1000000 }, "unitPriceCents": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "taxRateBp": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Tax rate in basis points (825 = 8.25%)" }, "id": { "type": "string" }, "position": { "type": "integer" }, "subtotalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "taxCents": { "type": "integer", "description": "Amount in minor units (cents)" } }, "required": [ "description", "quantity", "unitPriceCents", "id", "position", "subtotalCents", "taxCents" ], "additionalProperties": false } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "amountCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "method": { "type": "string", "enum": [ "card", "bank_transfer", "cash", "other" ] }, "paidAt": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "invoiceId", "amountCents", "method", "paidAt", "reference", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "number", "status", "customerId", "currency", "issueDate", "dueDate", "subtotalCents", "taxCents", "totalCents", "amountPaidCents", "balanceCents", "overdue", "createdAt", "updatedAt", "notes", "sentAt", "voidedAt", "lines", "payments" ], "additionalProperties": false } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "404": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } }, "patch": { "summary": "Update a draft invoice", "tags": [ "Invoices" ], "description": "Only drafts can be edited (409 otherwise). Passing `lines` replaces all line items.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1 }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "notes": { "type": "string", "maxLength": 2000, "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "quantity": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 1000000 }, "unitPriceCents": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "taxRateBp": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Tax rate in basis points (825 = 8.25%)" } }, "required": [ "description", "quantity", "unitPriceCents" ], "additionalProperties": false }, "minItems": 1, "maxItems": 200 } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "partially_paid", "paid", "void" ] }, "customerId": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "subtotalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "taxCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "totalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "amountPaidCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "balanceCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "overdue": { "type": "boolean", "description": "Derived: past due date and not fully paid" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "notes": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "nullable": true }, "voidedAt": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "quantity": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 1000000 }, "unitPriceCents": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "taxRateBp": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Tax rate in basis points (825 = 8.25%)" }, "id": { "type": "string" }, "position": { "type": "integer" }, "subtotalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "taxCents": { "type": "integer", "description": "Amount in minor units (cents)" } }, "required": [ "description", "quantity", "unitPriceCents", "id", "position", "subtotalCents", "taxCents" ], "additionalProperties": false } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "amountCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "method": { "type": "string", "enum": [ "card", "bank_transfer", "cash", "other" ] }, "paidAt": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "invoiceId", "amountCents", "method", "paidAt", "reference", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "number", "status", "customerId", "currency", "issueDate", "dueDate", "subtotalCents", "taxCents", "totalCents", "amountPaidCents", "balanceCents", "overdue", "createdAt", "updatedAt", "notes", "sentAt", "voidedAt", "lines", "payments" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "404": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "409": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } }, "delete": { "summary": "Delete a draft invoice (owner only)", "tags": [ "Invoices" ], "description": "Sent invoices are part of the ledger: void them instead.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Default Response", "content": { "application/json": { "schema": { "enum": [ "null" ], "nullable": true } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "403": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "404": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "409": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/invoices/{id}/send": { "post": { "summary": "Send (finalize) a draft invoice", "tags": [ "Invoices" ], "description": "draft -> sent. After sending, line items are locked.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "partially_paid", "paid", "void" ] }, "customerId": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "subtotalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "taxCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "totalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "amountPaidCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "balanceCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "overdue": { "type": "boolean", "description": "Derived: past due date and not fully paid" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "notes": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "nullable": true }, "voidedAt": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "quantity": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 1000000 }, "unitPriceCents": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "taxRateBp": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Tax rate in basis points (825 = 8.25%)" }, "id": { "type": "string" }, "position": { "type": "integer" }, "subtotalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "taxCents": { "type": "integer", "description": "Amount in minor units (cents)" } }, "required": [ "description", "quantity", "unitPriceCents", "id", "position", "subtotalCents", "taxCents" ], "additionalProperties": false } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "amountCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "method": { "type": "string", "enum": [ "card", "bank_transfer", "cash", "other" ] }, "paidAt": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "invoiceId", "amountCents", "method", "paidAt", "reference", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "number", "status", "customerId", "currency", "issueDate", "dueDate", "subtotalCents", "taxCents", "totalCents", "amountPaidCents", "balanceCents", "overdue", "createdAt", "updatedAt", "notes", "sentAt", "voidedAt", "lines", "payments" ], "additionalProperties": false } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "404": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "409": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/invoices/{id}/void": { "post": { "summary": "Void an invoice", "tags": [ "Invoices" ], "description": "draft|sent -> void, only while no payments have been recorded.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "partially_paid", "paid", "void" ] }, "customerId": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "subtotalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "taxCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "totalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "amountPaidCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "balanceCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "overdue": { "type": "boolean", "description": "Derived: past due date and not fully paid" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "notes": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "nullable": true }, "voidedAt": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "quantity": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 1000000 }, "unitPriceCents": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "taxRateBp": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Tax rate in basis points (825 = 8.25%)" }, "id": { "type": "string" }, "position": { "type": "integer" }, "subtotalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "taxCents": { "type": "integer", "description": "Amount in minor units (cents)" } }, "required": [ "description", "quantity", "unitPriceCents", "id", "position", "subtotalCents", "taxCents" ], "additionalProperties": false } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "amountCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "method": { "type": "string", "enum": [ "card", "bank_transfer", "cash", "other" ] }, "paidAt": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "invoiceId", "amountCents", "method", "paidAt", "reference", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "number", "status", "customerId", "currency", "issueDate", "dueDate", "subtotalCents", "taxCents", "totalCents", "amountPaidCents", "balanceCents", "overdue", "createdAt", "updatedAt", "notes", "sentAt", "voidedAt", "lines", "payments" ], "additionalProperties": false } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "404": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "409": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/payments/": { "post": { "summary": "Record a payment (idempotent)", "tags": [ "Payments" ], "description": "Requires an `Idempotency-Key` header. Retrying with the same key and body returns the original response (header `Idempotent-Replayed: true`) without charging twice; reusing a key with a different body returns 422. Payments move the invoice to partially_paid / paid and can never exceed the outstanding balance.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string", "minLength": 1 }, "amountCents": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 1000000000 }, "method": { "type": "string", "enum": [ "card", "bank_transfer", "cash", "other" ] }, "paidAt": { "type": "string", "format": "date-time", "description": "Defaults to now" }, "reference": { "type": "string", "maxLength": 200, "nullable": true } }, "required": [ "invoiceId", "amountCents", "method" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,100}$" }, "in": "header", "name": "idempotency-key", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "amountCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "method": { "type": "string", "enum": [ "card", "bank_transfer", "cash", "other" ] }, "paidAt": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "invoiceId", "amountCents", "method", "paidAt", "reference", "createdAt" ], "additionalProperties": false }, "invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "partially_paid", "paid", "void" ] }, "customerId": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code" }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "subtotalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "taxCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "totalCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "amountPaidCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "balanceCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "overdue": { "type": "boolean", "description": "Derived: past due date and not fully paid" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "number", "status", "customerId", "currency", "issueDate", "dueDate", "subtotalCents", "taxCents", "totalCents", "amountPaidCents", "balanceCents", "overdue", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "payment", "invoice" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "404": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "409": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "422": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } }, "get": { "summary": "List payments", "tags": [ "Payments" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "pageSize", "required": false }, { "schema": { "type": "string", "enum": [ "paidAt", "-paidAt" ], "default": "-paidAt" }, "in": "query", "name": "sort", "required": false, "description": "Sort field; prefix with \"-\" for descending. One of: paidAt" }, { "schema": { "type": "string" }, "in": "query", "name": "invoiceId", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "amountCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "method": { "type": "string", "enum": [ "card", "bank_transfer", "cash", "other" ] }, "paidAt": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "invoiceId", "amountCents", "method", "paidAt", "reference", "createdAt" ], "additionalProperties": false } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "data", "page", "pageSize", "total", "totalPages" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/expenses/": { "get": { "summary": "List expenses", "tags": [ "Expenses" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "pageSize", "required": false }, { "schema": { "type": "string", "enum": [ "spentAt", "-spentAt", "amountCents", "-amountCents" ], "default": "-spentAt" }, "in": "query", "name": "sort", "required": false, "description": "Sort field; prefix with \"-\" for descending. One of: spentAt, amountCents" }, { "schema": { "type": "string", "enum": [ "software", "travel", "office", "marketing", "contractors", "taxes", "other" ] }, "in": "query", "name": "category", "required": false }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "to", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "vendor": { "type": "string", "nullable": true }, "amountCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "spentAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "createdBy": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "category", "description", "vendor", "amountCents", "spentAt", "createdBy", "createdAt" ], "additionalProperties": false } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "data", "page", "pageSize", "total", "totalPages" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } }, "post": { "summary": "Record an expense", "tags": [ "Expenses" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "software", "travel", "office", "marketing", "contractors", "taxes", "other" ] }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "vendor": { "type": "string", "maxLength": 200, "nullable": true }, "amountCents": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 1000000000 }, "spentAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "category", "description", "amountCents", "spentAt" ], "additionalProperties": false } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "vendor": { "type": "string", "nullable": true }, "amountCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "spentAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "createdBy": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "category", "description", "vendor", "amountCents", "spentAt", "createdBy", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/expenses/{id}": { "delete": { "summary": "Delete an expense", "tags": [ "Expenses" ], "description": "Owners can delete any expense; members only the ones they created.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Default Response", "content": { "application/json": { "schema": { "enum": [ "null" ], "nullable": true } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "403": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "404": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } }, "/v1/reports/summary": { "get": { "summary": "Financial summary for a period", "tags": [ "Reports" ], "description": "Invoiced (non-void invoices issued in the period), collected (payments in the period), expenses by category, net cash flow, and receivables aging as of `to`.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": false, "description": "Defaults to Jan 1 of the current year" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "to", "required": false, "description": "Defaults to today" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "from", "to" ], "additionalProperties": false }, "invoicedCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "invoiceCount": { "type": "integer" }, "collectedCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "expensesCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "netCashFlowCents": { "type": "integer", "description": "collected - expenses" }, "outstandingCents": { "type": "integer", "description": "Amount in minor units (cents)" }, "overdueCount": { "type": "integer" }, "expensesByCategory": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "amountCents": { "type": "integer", "description": "Amount in minor units (cents)" } }, "required": [ "category", "amountCents" ], "additionalProperties": false } }, "aging": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string" }, "count": { "type": "integer" }, "balanceCents": { "type": "integer", "description": "Amount in minor units (cents)" } }, "required": [ "bucket", "count", "balanceCents" ], "additionalProperties": false } } }, "required": [ "period", "invoicedCents", "invoiceCount", "collectedCents", "expensesCents", "netCashFlowCents", "outstandingCents", "overdueCount", "expensesByCategory", "aging" ], "additionalProperties": false } } } }, "400": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } }, "401": { "description": "RFC 7807 problem details (application/problem+json)", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status" ], "additionalProperties": true, "description": "RFC 7807 problem details (application/problem+json)" } } } } } } } }, "servers": [ { "url": "http://localhost:3000", "description": "Local development" } ], "tags": [ { "name": "Health" }, { "name": "Auth" }, { "name": "Members" }, { "name": "Customers" }, { "name": "Invoices" }, { "name": "Payments" }, { "name": "Expenses" }, { "name": "Reports" } ] }