{ "openapi": "3.0.3", "info": { "title": "Yona API", "version": "1.0", "description": "The Yona API for businesses and integrators. Authenticate with an API key as a Bearer token; sk_test_ keys use the sandbox, sk_live_ keys the live service." }, "servers": [ { "url": "https://gp.useyona.com" } ], "security": [ { "bearer": [] } ], "paths": { "/a/v1/accept-invitation": { "post": { "description": "The signed-in user, whose verified email is the invitee’s, joins the organisation. No tokens are returned: to work in the new organisation, switch to it with `POST /a/v1/organizations/switch`.", "operationId": "acceptInvitation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth.AcceptInvitationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.AcceptInvitationResponseDto" } } } } } } }, "summary": "Accept an invitation", "tags": [ "invitations" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}": { "get": { "description": "The profile of the organisation the token belongs to. `orgId` must be that organisation (404 otherwise). Available to users and API keys.", "operationId": "getOrganization", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.OrganizationProfileResponseDto" } } } } } } }, "summary": "Get the organisation profile", "tags": [ "organizations" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "patch": { "description": "The same update as `PATCH /a/v1/organizations/me`; `orgId` must be the organisation of the session (404 otherwise). Changes the name, contact email, website or address. Changing `contactEmail` or `address` also needs the `organization.update_contact` capability. The response carries the organisation summary plus each contact field that was changed.", "operationId": "updateOrganization", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth.UpdateOrganizationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.UpdatedOrganizationResponseDto" } } } } } } }, "summary": "Update an organisation by id", "tags": [ "organizations" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/api-keys": { "get": { "description": "A page of the organisation’s API keys in every status. Metadata only, never a secret.", "operationId": "listApiKeys", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "active", "rotating", "revoked", "expired" ] } }, { "name": "mode", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "sandbox", "live" ] } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/auth.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/auth.ApiKeyResponseDto" } } } } } } } }, "summary": "List API keys", "tags": [ "api-keys" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] }, "post": { "description": "Creates a sandbox or live key with a preset or an explicit list of capabilities (the `read_only` preset when neither is given). A live key also needs the `live_mode.use` capability. The response is the key’s metadata plus `key`, the full secret (`sk_test_…` or `sk_live_…`): it is shown in this response only and cannot be retrieved again.", "operationId": "createApiKey", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth.CreateApiKeyDto" } } } }, "responses": { "201": { "description": "The key’s metadata and its plaintext `key`, shown once.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.CreatedApiKeyResponseDto" } } } } } } }, "summary": "Create an API key", "tags": [ "api-keys" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/api-keys/{id}": { "get": { "description": "One API key’s metadata, never its secret.", "operationId": "getApiKey", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.ApiKeyResponseDto" } } } } } } }, "summary": "Get an API key", "tags": [ "api-keys" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] }, "patch": { "description": "Changes the key’s name only. Capabilities change through `PUT …/api-keys/{id}/capabilities`.", "operationId": "renameApiKey", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth.UpdateApiKeyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.ApiKeyResponseDto" } } } } } } }, "summary": "Rename an API key", "tags": [ "api-keys" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/api-keys/{id}/capabilities": { "put": { "description": "The new list replaces the old one and may only name capabilities the caller holds. Access tokens already issued to the key stop working.", "operationId": "updateApiKeyCapabilities", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth.UpdateApiKeyCapabilitiesDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.ApiKeyResponseDto" } } } } } } }, "summary": "Replace an API key’s capabilities", "tags": [ "api-keys" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/api-keys/{id}/permissions": { "get": { "description": "What the key may do now, and which capabilities the caller could grant it.", "operationId": "getApiKeyPermissions", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.ApiKeyPermissionsResponseDto" } } } } } } }, "summary": "Get an API key’s capabilities", "tags": [ "api-keys" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/api-keys/{id}/revoke": { "patch": { "description": "The key stops working at once.", "operationId": "revokeApiKey", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.ApiKeyResponseDto" } } } } } } }, "summary": "Revoke an API key", "tags": [ "api-keys" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/api-keys/{id}/rotate": { "post": { "description": "Issues a new key with the same name, mode, capabilities and expiry. The old key keeps working for the grace period (`gracePeriodSeconds`) and is then retired. A live key also needs the `live_mode.use` capability, and the caller must hold every capability of the key. The new key’s full secret is returned once, in `current.key`.", "operationId": "rotateApiKey", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth.RotateApiKeyDto" } } } }, "responses": { "200": { "description": "The old key (`previous`, now `rotating`) and the new key (`current`) with its plaintext `key`, shown once.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.RotatedApiKeyResponseDto" } } } } } } }, "summary": "Rotate an API key", "tags": [ "api-keys" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/invitations": { "get": { "description": "A page of the organisation’s invitations (pending by default). No invitation codes are returned.", "operationId": "listInvitations", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "pending", "accepted", "withdrawn", "expired" ] } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/auth.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/auth.InvitationResponseDto" } } } } } } } }, "summary": "List invitations", "tags": [ "invitations" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] }, "post": { "description": "Emails an invitation code to the invitee. The code is never returned by the API; it exists only in the email.", "operationId": "createInvitation", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth.CreateInvitationDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.InvitationResponseDto" } } } } } } }, "summary": "Invite someone to the organisation", "tags": [ "invitations" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/invitations/{id}": { "get": { "description": "One invitation of the organisation, without its code.", "operationId": "getInvitation", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.InvitationResponseDto" } } } } } } }, "summary": "Get an invitation", "tags": [ "invitations" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "withdrawInvitation", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.InvitationWithdrawnResponseDto" } } } } } } }, "summary": "Withdraw a pending invitation", "tags": [ "invitations" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/invitations/{id}/resend": { "post": { "description": "Emails the invitee a new code; the previous code stops working.", "operationId": "resendInvitation", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.InvitationResponseDto" } } } } } } }, "summary": "Resend an invitation", "tags": [ "invitations" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/leave": { "post": { "description": "Ends the caller’s own membership in the organisation.", "operationId": "leaveOrganization", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.LeftOrganizationResponseDto" } } } } } } }, "summary": "Leave the organisation", "tags": [ "members" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/ownership-transfer": { "post": { "description": "Makes another active member the owner. The caller confirms with their password (and a second-factor code when two-factor is on) and becomes an admin unless they choose to stay an owner.", "operationId": "transferOrganizationOwnership", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth.OwnershipTransferDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.OwnershipTransferResponseDto" } } } } } } }, "summary": "Transfer ownership", "tags": [ "members" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/roles": { "get": { "description": "The system roles a member can hold, each with its capabilities.", "operationId": "listRoles", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/auth.RoleResponseDto" } } } } } } } }, "summary": "List roles", "tags": [ "roles" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/roles/{roleId}": { "get": { "operationId": "getRole", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "roleId", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.RoleResponseDto" } } } } } } }, "summary": "Get a role", "tags": [ "roles" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/roles/permissions/available": { "get": { "description": "Every capability a member can hold, with its label and properties, and the subset an API key may hold.", "operationId": "listAvailableCapabilities", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.AvailableCapabilitiesResponseDto" } } } } } } }, "summary": "List available capabilities", "tags": [ "roles" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/users": { "get": { "description": "A page of the organisation’s members, filtered by the query.", "operationId": "listMembers", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "active", "suspended" ] } }, { "name": "role", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "OWNER", "ADMIN", "ACCOUNTANT", "MEMBER", "DEVELOPER", "VIEWER" ] } }, { "name": "search", "required": false, "in": "query", "description": "Name or email prefix", "schema": { "minLength": 1, "maxLength": 100, "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/auth.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/auth.MemberResponseDto" } } } } } } } }, "summary": "List members", "tags": [ "members" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/users/{userId}": { "get": { "operationId": "getMember", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.MemberResponseDto" } } } } } } }, "summary": "Get a member", "tags": [ "members" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "removeMember", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.MemberRemovedResponseDto" } } } } } } }, "summary": "Remove a member", "tags": [ "members" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/users/{userId}/role": { "patch": { "description": "Assigns another system role to the member. Access tokens the member already holds are refused until they refresh, so the new role applies at once.", "operationId": "updateMemberRole", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth.UpdateMemberRoleDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.MemberResponseDto" } } } } } } }, "summary": "Change a member’s role", "tags": [ "members" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/{orgId}/users/{userId}/status": { "patch": { "description": "Sets the membership status in this organisation: `suspended` needs `member.suspend`, `active` needs `member.restore`.", "operationId": "updateMemberStatus", "parameters": [ { "name": "orgId", "required": true, "in": "path", "description": "Organisation id — must equal the token’s organisation — or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "userId", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth.UpdateMemberStatusDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.MemberResponseDto" } } } } } } }, "summary": "Suspend or restore a member", "tags": [ "members" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/organizations/me": { "get": { "description": "Every organisation the signed-in user is a member of, with their role and membership status. `current` marks the organisation of this session.", "operationId": "listMyOrganizations", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/auth.MyOrganizationResponseDto" } } } } } } } }, "summary": "List my organisations", "tags": [ "organizations" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] }, "patch": { "description": "Changes the name, contact email, website or address. Changing `contactEmail` or `address` also needs the `organization.update_contact` capability. The response carries the organisation summary plus each contact field that was changed.", "operationId": "updateMyOrganization", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth.UpdateOrganizationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.UpdatedOrganizationResponseDto" } } } } } } }, "summary": "Update the current organisation", "tags": [ "organizations" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/a/v1/verify-invitation": { "post": { "description": "Public. Given the invitation code and the invitee’s email, returns what the invitee may see before accepting. Any mismatch answers the same 404.", "operationId": "verifyInvitation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth.VerifyInvitationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/auth.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/auth.InvitationPreviewResponseDto" } } } } } } }, "summary": "Preview an invitation", "tags": [ "invitations" ], "security": [] } }, "/b/v1/billing-accounts/{id}/check-balance": { "get": { "description": "Whether the available balance covers `credits`, for the caller’s own account (its id or `me`). Advisory only: the charge itself decides. Requires `billing.account.read`. Reads the ledger of the token’s mode unless `mode` names another; an API key may read only its own mode (403 BIZ108).", "operationId": "checkBillingAccountBalance", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The caller’s own billing account id, or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "mode", "required": false, "in": "query", "description": "Which ledger to read. Defaults to the token's mode. API keys may only name their own mode (403 BIZ108).", "schema": { "type": "string", "enum": [ "sandbox", "live" ] } }, { "name": "credits", "required": true, "in": "query", "schema": { "minimum": 1, "maximum": 1000000000, "example": 100, "type": "integer" } } ], "responses": { "200": { "description": "Whether the balance is sufficient.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.CheckBalanceDto" } } } } } } }, "summary": "Check the balance covers an amount", "tags": [ "billing-accounts" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/billing-accounts/{id}/stats": { "get": { "description": "Balance, lifetime totals and the consumption rate over the last 30 days, for the caller’s own account (its id or `me`). Requires `billing.account.read`. Reads the ledger of the token’s mode unless `mode` names another; an API key may read only its own mode (403 BIZ108).", "operationId": "getBillingAccountStats", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The caller’s own billing account id, or `me`.", "schema": { "example": "me", "type": "string" } }, { "name": "mode", "required": false, "in": "query", "description": "Which ledger to read. Defaults to the token's mode. API keys may only name their own mode (403 BIZ108).", "schema": { "type": "string", "enum": [ "sandbox", "live" ] } } ], "responses": { "200": { "description": "The account statistics.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.AccountStatsDto" } } } } } } }, "summary": "Get billing account statistics", "tags": [ "billing-accounts" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/billing-accounts/me": { "get": { "description": "The organisation’s billing account and its credit balances. Requires `billing.account.read`. A user sees both the live and the sandbox balance; an API key sees only its own mode’s. `creditBalance` is the available balance of `mode`. 404 RES101 until the account is provisioned.", "operationId": "getBillingAccount", "parameters": [ { "name": "mode", "required": false, "in": "query", "description": "Which ledger to read. Defaults to the token's mode. API keys may only name their own mode (403 BIZ108).", "schema": { "type": "string", "enum": [ "sandbox", "live" ] } } ], "responses": { "200": { "description": "The billing account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.BillingAccountDto" } } } } } } }, "summary": "Get the billing account", "tags": [ "billing-accounts" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/billing-accounts/me/low-balance": { "patch": { "description": "Tenant user only, `billing.low_balance.configure`. Sets the live balance below which one low-balance email is sent each time the balance drops past it; 0 turns it off. Live ledger only.", "operationId": "updateLowBalanceThreshold", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing.UpdateLowBalanceThresholdDto" } } } }, "responses": { "200": { "description": "The new threshold and whether the next drop below it will notify.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.LowBalanceThresholdDto" } } } } } } }, "summary": "Set the low-balance threshold", "tags": [ "billing-accounts" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/b/v1/payments/{id}": { "get": { "description": "One payment of the organisation. Requires `billing.payment.read`. `checkoutUrl` is present only while the payment is pending. Another organisation’s payment answers 404 RES001.", "operationId": "getPayment", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The payment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.PaymentDetailDto" } } } } } } }, "summary": "Get a payment", "tags": [ "payments" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/payments/history": { "get": { "description": "The organisation’s payments, newest first, optionally filtered by status and kind. Requires `billing.payment.read`. No checkout URL in the list.", "operationId": "listPayments", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (1-based).", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "pending", "succeeded", "failed", "expired", "partially_refunded", "refunded", "disputed", "charged_back" ] } }, { "name": "kind", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "credit_purchase", "subscription", "renewal" ] } } ], "responses": { "200": { "description": "A page of payments.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/billing.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/billing.PaymentDto" } } } } } } } }, "summary": "List payments", "tags": [ "payments" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/payments/purchase": { "post": { "description": "Tenant user only, `billing.credits.purchase`, from a live-mode session. Starts a hosted checkout for one credit package in the chosen currency; the credits are granted when the provider confirms the payment. Optional `Idempotency-Key` header: the same key and body return the original checkout; the same key with another body is 409 BIZ107.", "operationId": "purchaseCredits", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing.PurchaseCreditsDto" } } } }, "responses": { "200": { "description": "The pending payment and its hosted checkout URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.CreditCheckoutDto" } } } } } }, "403": { "description": "BIZ110: the session is in SANDBOX mode — credits and plans are bought from a live session only; sandbox test credits come from POST /b/v1/sandbox/topup. Also AUTH019 (capability missing), AUTH018 (not a user).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ110" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Buy a credit package", "tags": [ "payments" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/b/v1/plans": { "get": { "description": "The public subscription plans and credit packages in one response. No token needed.", "operationId": "getPlansCatalogue", "parameters": [ { "name": "currency", "required": false, "in": "query", "description": "Only prices in this currency.", "schema": { "type": "string", "enum": [ "NGN", "USD" ] } }, { "name": "interval", "required": false, "in": "query", "description": "Only plan prices for this interval.", "schema": { "type": "string", "enum": [ "monthly", "yearly" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.PlansCatalogueDto" } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get the plans and packages catalogue", "tags": [ "catalogue" ], "security": [] } }, "/b/v1/plans/credit-costs": { "get": { "description": "The public price list: how many credits each billable action costs, grouped by section. No token needed.", "operationId": "listCreditCosts", "parameters": [ { "name": "currency", "required": false, "in": "query", "description": "Only prices in this currency.", "schema": { "type": "string", "enum": [ "NGN", "USD" ] } }, { "name": "interval", "required": false, "in": "query", "description": "Only plan prices for this interval.", "schema": { "type": "string", "enum": [ "monthly", "yearly" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/billing.CreditCostDto" } } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List credit costs", "tags": [ "catalogue" ], "security": [] } }, "/b/v1/plans/packages": { "get": { "description": "The public credit packages with their prices in integer minor units; `featured` filters on whether a package is featured. No token needed.", "operationId": "listCreditPackages", "parameters": [ { "name": "currency", "required": false, "in": "query", "description": "Only prices in this currency.", "schema": { "type": "string", "enum": [ "NGN", "USD" ] } }, { "name": "interval", "required": false, "in": "query", "description": "Only plan prices for this interval.", "schema": { "type": "string", "enum": [ "monthly", "yearly" ] } }, { "name": "featured", "required": false, "in": "query", "description": "Only featured packages (`true`) or only others (`false`).", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/billing.CreditPackageDto" } } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List credit packages", "tags": [ "catalogue" ], "security": [] } }, "/b/v1/plans/packages/{id}": { "get": { "description": "One public credit package by its id. No token needed.", "operationId": "getCreditPackage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "044e59c4-6e59-53ca-97a5-c7f50addac75", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "description": "Only prices in this currency.", "schema": { "type": "string", "enum": [ "NGN", "USD" ] } }, { "name": "interval", "required": false, "in": "query", "description": "Only plan prices for this interval.", "schema": { "type": "string", "enum": [ "monthly", "yearly" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.CreditPackageDto" } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get a credit package", "tags": [ "catalogue" ], "security": [] } }, "/b/v1/plans/subscriptions": { "get": { "description": "The public subscription plans with their prices in integer minor units, optionally narrowed to one currency or interval. No token needed.", "operationId": "listSubscriptionPlans", "parameters": [ { "name": "currency", "required": false, "in": "query", "description": "Only prices in this currency.", "schema": { "type": "string", "enum": [ "NGN", "USD" ] } }, { "name": "interval", "required": false, "in": "query", "description": "Only plan prices for this interval.", "schema": { "type": "string", "enum": [ "monthly", "yearly" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/billing.SubscriptionPlanDto" } } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List subscription plans", "tags": [ "catalogue" ], "security": [] } }, "/b/v1/plans/subscriptions/{code}": { "get": { "description": "One public subscription plan by its code. No token needed.", "operationId": "getSubscriptionPlan", "parameters": [ { "name": "code", "required": true, "in": "path", "schema": { "pattern": "^[a-z][a-z0-9_]{1,63}$", "example": "starter", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "description": "Only prices in this currency.", "schema": { "type": "string", "enum": [ "NGN", "USD" ] } }, { "name": "interval", "required": false, "in": "query", "description": "Only plan prices for this interval.", "schema": { "type": "string", "enum": [ "monthly", "yearly" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.SubscriptionPlanDto" } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get a subscription plan", "tags": [ "catalogue" ], "security": [] } }, "/b/v1/sandbox/topup": { "post": { "description": "Tenant user only, `billing.credits.purchase`. Grants test credits on the sandbox ledger (never live), expiring with the UTC month. At most the configured per-top-up cap (1,000 credits by default) per top-up, and at most the configured number of top-ups (3 by default) per organisation per UTC month. Not idempotent by key: each accepted call is one of the month’s top-ups.", "operationId": "topUpSandboxCredits", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing.SandboxTopupDto" } } } }, "responses": { "201": { "description": "The grant entry and the month’s top-up count.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.SandboxTopupResultDto" } } } } } }, "400": { "description": "`credits` not an integer ≥ 1, above the per-top-up cap, or an unknown field.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no billing.credits.purchase), AUTH018 (an API key or service token), AUTH020 (no organisation).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES101: the organisation’s billing account is not provisioned yet.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES101" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "BIZ002: the month’s allowed number of top-ups is used up; SYS005: bucket billing.money.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ002" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Top up sandbox test credits (capped, no payment)", "tags": [ "sandbox" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/b/v1/sandbox/transactions": { "get": { "description": "The sandbox ledger’s entries, newest first, with the same filters as the ledger entry list. Requires `billing.ledger.read`. A live-mode API key is refused with 403 BIZ108.", "operationId": "listSandboxTransactions", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (1-based).", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } }, { "name": "type", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "grant_plan", "grant_purchase", "grant_allowance", "grant_adjustment", "charge", "hold", "hold_release", "refund", "clawback", "adjustment_debit", "expiry", "debt_settlement" ] } }, { "name": "startDate", "required": false, "in": "query", "schema": { "format": "date-time", "example": "2026-09-01T00:00:00Z", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "schema": { "format": "date-time", "example": "2026-09-30T23:59:59Z", "type": "string" } }, { "name": "costCode", "required": false, "in": "query", "schema": { "pattern": "^[A-Z][A-Z0-9_]{2,63}$", "example": "INVOICE_CREATE", "type": "string" } }, { "name": "reference", "required": false, "in": "query", "description": "Exact business reference of the entry (no prefix or wildcard match).", "schema": { "maxLength": 255, "pattern": "^[a-z][a-z0-9_.]*:[A-Za-z0-9._:-]{1,240}$", "example": "invoice.create:018f2b4c-6a1e-7c3d-9e2f-0a1b2c3d4e5f", "type": "string" } } ], "responses": { "200": { "description": "A page of sandbox ledger entries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/billing.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/billing.LedgerEntryDto" } } } } } } } }, "summary": "List sandbox ledger entries", "tags": [ "sandbox" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/sandbox/usage": { "get": { "description": "This UTC month’s free sandbox allowance: granted, used and remaining. Requires `billing.usage.read`. A live-mode API key is refused with 403 BIZ108.", "operationId": "getSandboxUsage", "parameters": [], "responses": { "200": { "description": "The month’s sandbox allowance.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.SandboxUsageDto" } } } } } } }, "summary": "Get sandbox allowance usage", "tags": [ "sandbox" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/setup": { "get": { "description": "The dashboard’s billing overview in one call: the current subscription, the account, balances, the sandbox allowance and the plans on offer priced in the account’s currency (integer minor units). Requires `billing.account.read`. An API key sees only its own mode’s blocks.", "operationId": "getBillingSetup", "parameters": [], "responses": { "200": { "description": "The billing overview.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.SetupDto" } } } } } } }, "summary": "Get the billing overview", "tags": [ "setup" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/statements/{period}": { "get": { "description": "One UTC month (`YYYY-MM`, not in the future) of one ledger: opening and closing balance, grants by source, charges by cost code, refunds, expiries and held credits; payments on live statements. Requires `billing.statement.read`. Reads the ledger of the token’s mode unless `mode` names another; an API key may read only its own mode (403 BIZ108).", "operationId": "getBillingStatement", "parameters": [ { "name": "period", "required": true, "in": "path", "schema": { "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09", "type": "string" } }, { "name": "mode", "required": false, "in": "query", "description": "Which ledger to read. Defaults to the token's mode. API keys may only name their own mode (403 BIZ108).", "schema": { "type": "string", "enum": [ "sandbox", "live" ] } } ], "responses": { "200": { "description": "The statement.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.StatementDto" } } } } } } }, "summary": "Get a monthly statement", "tags": [ "statements" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/subscriptions/{id}": { "get": { "description": "One subscription of the organisation. Requires `billing.subscription.read`. Another organisation’s subscription answers 404 RES001.", "operationId": "getSubscription", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The subscription.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.SubscriptionDto" } } } } } } }, "summary": "Get a subscription", "tags": [ "subscriptions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/subscriptions/{id}/cancel": { "put": { "description": "Tenant user only, `billing.subscription.cancel`. An active subscription is cancelled at the end of its current period (`cancelAtPeriodEnd` becomes true). A subscription still awaiting its first payment is checked with the payment provider first: unpaid, it and its checkout expire now; already paid, the cancellation is refused with 409 BIZ004.", "operationId": "cancelSubscription", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing.CancelSubscriptionDto" } } } }, "responses": { "200": { "description": "The subscription after the cancellation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.SubscriptionDto" } } } } } } }, "summary": "Cancel a subscription", "tags": [ "subscriptions" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/b/v1/subscriptions/{id}/renew": { "post": { "description": "Tenant user only, `billing.subscription.renew`, from a live-mode session. Starts a hosted checkout to pay the overdue period of a `past_due` subscription. Optional `Idempotency-Key` header: the same key and body return the original checkout; the same key with another body is 409 BIZ107.", "operationId": "renewSubscription", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing.RenewSubscriptionDto" } } } }, "responses": { "200": { "description": "The same checkout is still pending and is returned again.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.SubscriptionCheckoutDto" } } } } } }, "201": { "description": "A new checkout was started: the subscription, the payment and the checkout URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.SubscriptionCheckoutDto" } } } } } }, "403": { "description": "BIZ110: the session is in SANDBOX mode — credits and plans are bought from a live session only; sandbox test credits come from POST /b/v1/sandbox/topup. Also AUTH019 (capability missing), AUTH018 (not a user).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ110" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Renew a past-due subscription", "tags": [ "subscriptions" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/b/v1/subscriptions/{id}/resume": { "put": { "description": "Tenant user only, `billing.subscription.resume`. Clears a cancellation scheduled for the end of the current period.", "operationId": "resumeSubscription", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The subscription after the cancellation was cleared.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.SubscriptionDto" } } } } } } }, "summary": "Resume a subscription", "tags": [ "subscriptions" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/b/v1/subscriptions/active": { "get": { "description": "The organisation’s active or past-due subscription and its current monthly allocation window (`window` is null while past due). Requires `billing.subscription.read`. 404 RES001 when there is none.", "operationId": "getActiveSubscription", "parameters": [], "responses": { "200": { "description": "The current subscription.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.ActiveSubscriptionDto" } } } } } } }, "summary": "Get the current subscription", "tags": [ "subscriptions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/subscriptions/history": { "get": { "description": "Every subscription of the organisation, newest first. Requires `billing.subscription.read`.", "operationId": "listSubscriptions", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (1-based).", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } } ], "responses": { "200": { "description": "A page of subscriptions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/billing.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/billing.SubscriptionDto" } } } } } } } }, "summary": "List subscriptions", "tags": [ "subscriptions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/subscriptions/renewals": { "get": { "description": "The billing periods of the organisation’s subscriptions and how each was charged, optionally for one subscription. Requires `billing.subscription.read`.", "operationId": "listSubscriptionRenewals", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (1-based).", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } }, { "name": "subscriptionId", "required": false, "in": "query", "description": "Only this subscription’s periods (must be the caller’s).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "A page of billing periods.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/billing.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/billing.SubscriptionPeriodDto" } } } } } } } }, "summary": "List subscription billing periods", "tags": [ "subscriptions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/subscriptions/subscribe": { "post": { "description": "Tenant user only, `billing.subscription.subscribe`, from a live-mode session. Creates a `pending_payment` subscription and starts a hosted checkout for its first period; it becomes active when the provider confirms the payment. Optional `Idempotency-Key` header: the same key and body return the original checkout; the same key with another body is 409 BIZ107.", "operationId": "subscribeToPlan", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing.SubscribeDto" } } } }, "responses": { "200": { "description": "The same checkout is still pending and is returned again.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.SubscriptionCheckoutDto" } } } } } }, "201": { "description": "A new checkout was started: the subscription, the payment and the checkout URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.SubscriptionCheckoutDto" } } } } } }, "403": { "description": "BIZ110: the session is in SANDBOX mode — credits and plans are bought from a live session only; sandbox test credits come from POST /b/v1/sandbox/topup. Also AUTH019 (capability missing), AUTH018 (not a user).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ110" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Subscribe to a plan", "tags": [ "subscriptions" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/b/v1/transactions": { "get": { "description": "Credit ledger entries (grants, charges, holds, refunds, expiries…), newest first, filtered by kind, date range, cost code or exact reference. Requires `billing.ledger.read`. Reads the ledger of the token’s mode unless `mode` names another; an API key may read only its own mode (403 BIZ108).", "operationId": "listLedgerEntries", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (1-based).", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } }, { "name": "type", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "grant_plan", "grant_purchase", "grant_allowance", "grant_adjustment", "charge", "hold", "hold_release", "refund", "clawback", "adjustment_debit", "expiry", "debt_settlement" ] } }, { "name": "mode", "required": false, "in": "query", "description": "Defaults to the token's mode; API keys may only name their own (403 BIZ108).", "schema": { "type": "string", "enum": [ "sandbox", "live" ] } }, { "name": "startDate", "required": false, "in": "query", "schema": { "format": "date-time", "example": "2026-09-01T00:00:00Z", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "schema": { "format": "date-time", "example": "2026-09-30T23:59:59Z", "type": "string" } }, { "name": "costCode", "required": false, "in": "query", "schema": { "pattern": "^[A-Z][A-Z0-9_]{2,63}$", "example": "INVOICE_CREATE", "type": "string" } }, { "name": "reference", "required": false, "in": "query", "description": "Exact business reference of the entry (no prefix or wildcard match).", "schema": { "maxLength": 255, "pattern": "^[a-z][a-z0-9_.]*:[A-Za-z0-9._:-]{1,240}$", "example": "invoice.create:018f2b4c-6a1e-7c3d-9e2f-0a1b2c3d4e5f", "type": "string" } } ], "responses": { "200": { "description": "A page of ledger entries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/billing.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/billing.LedgerEntryDto" } } } } } } } }, "summary": "List ledger entries", "tags": [ "transactions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/transactions/{id}": { "get": { "description": "One ledger entry of the organisation. Requires `billing.ledger.read`. Another organisation’s entry answers 404 RES001.", "operationId": "getLedgerEntry", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The ledger entry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/billing.LedgerEntryDto" } } } } } } }, "summary": "Get a ledger entry", "tags": [ "transactions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/transactions/analytics/usage": { "get": { "description": "Credits spent per daily, weekly (ISO week) or monthly UTC bucket over a date range (the last 30 days by default, at most 366 days). Requires `billing.usage.read`. Reads the ledger of the token’s mode unless `mode` names another; an API key may read only its own mode (403 BIZ108).", "operationId": "getUsageAnalytics", "parameters": [ { "name": "mode", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "sandbox", "live" ] } }, { "name": "startDate", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "At most 366 days after startDate.", "schema": { "format": "date-time", "type": "string" } }, { "name": "period", "required": false, "in": "query", "schema": { "default": "daily", "type": "string", "enum": [ "daily", "weekly", "monthly" ] } } ], "responses": { "200": { "description": "One row per time bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/billing.UsageBucketDto" } } } } } } } }, "summary": "Get credit usage over time", "tags": [ "transactions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/b/v1/transactions/breakdown/by-endpoint": { "get": { "description": "Credits spent per cost code, net of refunds, over a date range (the last 30 days by default, at most 366 days). Requires `billing.usage.read`. Reads the ledger of the token’s mode unless `mode` names another; an API key may read only its own mode (403 BIZ108).", "operationId": "getUsageByCostCode", "parameters": [ { "name": "mode", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "sandbox", "live" ] } }, { "name": "startDate", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "At most 366 days after startDate.", "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "description": "One row per cost code.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/billing.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/billing.CostCodeUsageDto" } } } } } } } }, "summary": "Get credit usage by cost code", "tags": [ "transactions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/buyers": { "get": { "description": "`buyer.read`. Live buyers of the organisation in the token’s mode, filtered by `search` (name, legal name or tax id) and `taxIdStatus`; `page` and `limit` (up to 100).", "operationId": "listBuyers", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Name, legal name or tax id.", "schema": { "maxLength": 100, "type": "string" } }, { "name": "taxIdStatus", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "unverified", "pending", "verified", "not_found", "name_mismatch", "unavailable", "valid_off_network", "checking" ] } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "One page of buyers, `meta.pagination` set.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/invoice.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.BuyerViewDto" } } } } } } }, "400": { "description": "VAL001: a query parameter out of range or unknown.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `buyer.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List buyers", "tags": [ "buyers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "post": { "description": "`buyer.create`; charged per buyer before it is saved (refunded if the save fails). A `taxId` is checked against the jurisdiction’s format and must not be held by another live buyer of the organisation. Status fields (`taxIdStatus` and the like) cannot be sent: they are set by the verification.", "operationId": "createBuyer", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.CreateBuyerDto" } } } }, "responses": { "201": { "description": "The new buyer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.BuyerViewDto" } } } } } }, "400": { "description": "VAL001: a field out of shape or not accepted; VAL003: the tax id breaks the jurisdiction’s format.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "402": { "description": "BIZ001: not enough credits for the charge — top up to continue.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `buyer.create`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "RES002: another live buyer of this organisation has this tax id.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES002" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant write bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS002: billing or the organisation’s verified facts could not be read; SYS201: this mode cannot charge right now. Nothing was done.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Create a buyer", "tags": [ "buyers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/buyers/{id}": { "get": { "description": "`buyer.read`. An archived buyer is readable by id (`archivedAt` set).", "operationId": "getBuyer", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The buyer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.BuyerViewDto" } } } } } }, "400": { "description": "VAL001: `id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `buyer.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: no such buyer in this organisation and mode (another organisation’s buyer answers the same).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get a buyer", "tags": [ "buyers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "patch": { "description": "`buyer.update`. The create fields, all optional; an optional field sent as null is cleared, `name` can be changed but not cleared. Charged only when the edit changes something. A changed tax identity resets the verification.", "operationId": "updateBuyer", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "8–128 characters of A–Z, a–z, 0–9, `_` or `-`. A retry with the same key is not charged twice.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.UpdateBuyerDto" } } } }, "responses": { "200": { "description": "The buyer after the edit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.BuyerViewDto" } } } } } }, "400": { "description": "VAL001: a field out of shape or not accepted, or a malformed `Idempotency-Key`; VAL003: the tax id breaks the jurisdiction’s format.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "402": { "description": "BIZ001: not enough credits for the charge — top up to continue.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `buyer.update`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: no such buyer in this organisation and mode (another organisation’s buyer answers the same).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "RES002: another live buyer of this organisation has this tax id; BIZ107: the `Idempotency-Key` was already used for a different request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES002" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant write bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS002: billing or the organisation’s verified facts could not be read; SYS201: this mode cannot charge right now. Nothing was done.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Update a buyer", "tags": [ "buyers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "delete": { "description": "`buyer.delete`. Deleted, or archived instead when an issued invoice names the buyer (`outcome` says which).", "operationId": "deleteBuyer", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "What happened to the buyer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.BuyerDeleteResultDto" } } } } } }, "400": { "description": "VAL001: `id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `buyer.delete`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: no such buyer in this organisation and mode (another organisation’s buyer answers the same).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant write bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Delete a buyer", "tags": [ "buyers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/buyers/{id}/verification-status": { "get": { "description": "`buyer.read`. The latest verification and the buyer’s tax-id status.", "operationId": "getBuyerVerificationStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The latest verification.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.BuyerVerificationStatusDto" } } } } } }, "400": { "description": "VAL001: `id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `buyer.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: no such buyer in this organisation and mode (another organisation’s buyer answers the same).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get a buyer’s tax number verification status", "tags": [ "buyers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/buyers/{id}/verify-tax-number": { "post": { "description": "`buyer.verify_tax_id`; a charge is held while the check runs. 202 when a new verification starts; 200 with the one already pending. Follow it with the verification status route.", "operationId": "verifyBuyerTaxNumber", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "A verification was already pending; this is it.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.BuyerVerificationRequestedDto" } } } } } }, "202": { "description": "A new verification was started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.BuyerVerificationRequestedDto" } } } } } }, "400": { "description": "VAL002: the buyer has no verifiable tax id; VAL003: its tax id breaks the jurisdiction’s format; VAL001: `id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL002" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "402": { "description": "BIZ001: not enough credits for the charge — top up to continue.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `buyer.verify_tax_id`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: no such buyer in this organisation and mode (another organisation’s buyer answers the same).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "RES003: the buyer changed or was removed while the verification was requested.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "422": { "description": "BIZ213: the organisation’s country is not supported for tax checks.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ213" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tax-id lookup bucket (30 per minute per caller).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS002: billing or the organisation’s verified facts could not be read; SYS201: this mode cannot charge right now. Nothing was done.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Verify a buyer’s tax number", "tags": [ "buyers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/buyers/bulk": { "delete": { "description": "`buyer.delete`. Up to 100 distinct ids, each handled like a single delete: deleted, or archived when an issued invoice names the buyer. Ids that are not found are listed, not refused.", "operationId": "bulkDeleteBuyers", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.BulkDeleteBuyersDto" } } } }, "responses": { "200": { "description": "Which ids were deleted, archived or not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.BulkDeleteResultDto" } } } } } }, "400": { "description": "VAL001: `ids` empty, over 100, repeated, or not UUIDs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `buyer.delete`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant write bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Delete several buyers", "tags": [ "buyers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/buyers/reachability": { "get": { "description": "`buyer.read`; free. Whether the tax authority’s e-invoicing network reaches this TIN — the check a form runs while a buyer TIN is typed. Cached per mode and TIN. When the tax authority cannot be asked the answer is still 200: an earlier answer with `stale: true`, or `unavailable: true`.", "operationId": "checkBuyerReachability", "parameters": [ { "name": "taxId", "required": true, "in": "query", "schema": { "minLength": 1, "maxLength": 32, "example": "33875194-0001", "type": "string" } } ], "responses": { "200": { "description": "The lookup’s answer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.BuyerReachabilityAnswerDto" } } } } } }, "400": { "description": "VAL001: `taxId` missing or out of shape; VAL003: the TIN breaks the jurisdiction’s format.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `buyer.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "422": { "description": "BIZ213: the organisation’s country is not supported for tax checks.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ213" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS002: the organisation’s verified facts could not be read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Check whether a TIN is on the e-invoicing network", "tags": [ "buyers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/buyers/reachability/check": { "post": { "description": "`buyer.read`; charged per request (refunded when no answer could be had). The same question as the free reachability check, asked afresh rather than from the cache. When the tax authority cannot be asked the answer is 200 with `unavailable: true`.", "operationId": "checkBuyerWithTaxAuthority", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "8–128 characters of A–Z, a–z, 0–9, `_` or `-`. A retry with the same key is not charged twice.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.BuyerNrsCheckDto" } } } }, "responses": { "200": { "description": "The lookup’s answer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.BuyerReachabilityAnswerDto" } } } } } }, "400": { "description": "VAL001: `taxId` missing or out of shape, or a malformed `Idempotency-Key`; VAL003: the TIN breaks the jurisdiction’s format.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "402": { "description": "BIZ001: not enough credits for the charge — top up to continue.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `buyer.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "BIZ107: the `Idempotency-Key` was already used for a different request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ107" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "422": { "description": "BIZ213: the organisation’s country is not supported for tax checks.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ213" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tax-id lookup bucket (30 per minute per caller).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS002: billing or the organisation’s verified facts could not be read; SYS201: this mode cannot charge right now. Nothing was done.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Ask the tax authority about a TIN now", "tags": [ "buyers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/buyers/search": { "get": { "description": "`buyer.read`. Live buyers whose name, legal name or tax id matches `q` (at least 2 characters); at most `limit` (default 10, up to 20).", "operationId": "searchBuyers", "parameters": [ { "name": "q", "required": true, "in": "query", "schema": { "minLength": 2, "maxLength": 100, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 20, "default": 10, "type": "number" } } ], "responses": { "200": { "description": "The matching buyers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.BuyerViewDto" } } } } } } }, "400": { "description": "VAL001: `q` shorter than 2 characters, or `limit` out of range.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `buyer.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Search buyers", "tags": [ "buyers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/buyers/setup": { "get": { "description": "`buyer.read`. The party types, the tax-id types of the organisation’s jurisdiction, and the countries.", "operationId": "getBuyerSetup", "parameters": [], "responses": { "200": { "description": "The option lists.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.BuyerSetupDto" } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `buyer.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS002: the organisation’s verified facts could not be read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get the buyer form options", "tags": [ "buyers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/inbound-invoices": { "get": { "description": "`invoice.inbound.read`; free. The invoices other businesses issued to the organisation, served from the organisation’s mirror of the authority gateway’s feed in the token’s mode, narrowed to its own tax ids (`taxpayer.taxIds`). Filters: `seller`, `accessPoint`, `transmissionStatus`, `paymentStatus` (`paid|unpaid|partial|rejected|overdue`), `issueDateFrom/To`, `receivedFrom/To`, `amountMin/Max` (major units), `currency`, `q`, `taxId`; `sort` `-receivedAt` (default) | `receivedAt` | `issueDate` | `-issueDate` | `amount` | `-amount`; `page`, `limit` ≤ 100 with `meta.pagination`. A first view reads the feed’s head before answering and the rest in the background (`sync.syncing`); a gateway outage serves the mirror with `sync.error`, never an error.", "operationId": "listInboundInvoices", "parameters": [ { "name": "seller", "required": false, "in": "query", "description": "The seller: a name (substring, any case) or a TIN (prefix).", "schema": { "maxLength": 100, "type": "string" } }, { "name": "accessPoint", "required": false, "in": "query", "description": "The seller’s access point (`supplier.app_reference`), exact.", "schema": { "maxLength": 256, "type": "string" } }, { "name": "transmissionStatus", "required": false, "in": "query", "description": "As the gateway reports it, exact.", "schema": { "maxLength": 64, "type": "string" } }, { "name": "paymentStatus", "required": false, "in": "query", "description": "`overdue`: a due date before today and not paid.", "schema": { "type": "string", "enum": [ "paid", "unpaid", "partial", "rejected", "overdue" ] } }, { "name": "issueDateFrom", "required": false, "in": "query", "description": "Inclusive.", "schema": { "example": "2026-09-01", "type": "string" } }, { "name": "issueDateTo", "required": false, "in": "query", "description": "Inclusive.", "schema": { "example": "2026-09-30", "type": "string" } }, { "name": "receivedFrom", "required": false, "in": "query", "description": "Inclusive (an instant or a day).", "schema": { "example": "2026-09-01T00:00:00Z", "type": "string" } }, { "name": "receivedTo", "required": false, "in": "query", "description": "Exclusive for an instant; a calendar day includes that whole day.", "schema": { "example": "2026-10-01T00:00:00Z", "type": "string" } }, { "name": "amountMin", "required": false, "in": "query", "description": "Payable amount, MAJOR units, inclusive.", "schema": { "example": "1000.00", "type": "string" } }, { "name": "amountMax", "required": false, "in": "query", "description": "Payable amount, MAJOR units, inclusive.", "schema": { "example": "50000", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "NGN", "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Seller name or TIN, IRN, or the seller’s invoice number (substring, any case).", "schema": { "maxLength": 100, "type": "string" } }, { "name": "taxId", "required": false, "in": "query", "description": "One of `taxpayer.taxIds` (the organisation’s own tax ids in this mode); any other is 400.", "schema": { "maxLength": 32, "type": "string" } }, { "name": "sort", "required": false, "in": "query", "schema": { "default": "-receivedAt", "type": "string", "enum": [ "-receivedAt", "receivedAt", "issueDate", "-issueDate", "amount", "-amount" ] } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } } ], "responses": { "200": { "description": "One page: `data` holds the items with the taxpayer and sync context; `meta.pagination` the page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/invoice.ApiPaginationMetaDto" } } } ] }, "data": { "$ref": "#/components/schemas/invoice.InboundPageDto" } } } } } }, "400": { "description": "VAL001: a filter out of shape, `limit` out of range, an undeclared parameter, or a `taxId` that is not one of the organisation’s.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `invoice.inbound.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List received invoices", "tags": [ "Inbound", "inbound-invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/inbound-invoices/{id}": { "get": { "description": "`invoice.inbound.read`; free. From the mirror; `document` (the decrypted authority copy) is read from the gateway once, on the first view, when the mirror does not hold it. 503 only for a row the mirror never held while the gateway is down.", "operationId": "getInboundInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "description": "The received invoice.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InboundInvoiceDetailDto" } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `invoice.inbound.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: not one sent to this organisation’s connected TIN in this mode (or no connection).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS202: the authority gateway gave no usable answer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get a received invoice", "tags": [ "Inbound", "inbound-invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/inbound-invoices/analytics": { "get": { "description": "`invoice.inbound.read`; free. The list’s filters (no sort or page); from the mirror. Amounts are MINOR units in `reportingCurrency` (the `currency` filter, else the most common); `byCurrency` gives each currency’s own.", "operationId": "getInboundInvoiceAnalytics", "parameters": [ { "name": "seller", "required": false, "in": "query", "description": "The seller: a name (substring, any case) or a TIN (prefix).", "schema": { "maxLength": 100, "type": "string" } }, { "name": "accessPoint", "required": false, "in": "query", "description": "The seller’s access point (`supplier.app_reference`), exact.", "schema": { "maxLength": 256, "type": "string" } }, { "name": "transmissionStatus", "required": false, "in": "query", "description": "As the gateway reports it, exact.", "schema": { "maxLength": 64, "type": "string" } }, { "name": "paymentStatus", "required": false, "in": "query", "description": "`overdue`: a due date before today and not paid.", "schema": { "type": "string", "enum": [ "paid", "unpaid", "partial", "rejected", "overdue" ] } }, { "name": "issueDateFrom", "required": false, "in": "query", "description": "Inclusive.", "schema": { "example": "2026-09-01", "type": "string" } }, { "name": "issueDateTo", "required": false, "in": "query", "description": "Inclusive.", "schema": { "example": "2026-09-30", "type": "string" } }, { "name": "receivedFrom", "required": false, "in": "query", "description": "Inclusive (an instant or a day).", "schema": { "example": "2026-09-01T00:00:00Z", "type": "string" } }, { "name": "receivedTo", "required": false, "in": "query", "description": "Exclusive for an instant; a calendar day includes that whole day.", "schema": { "example": "2026-10-01T00:00:00Z", "type": "string" } }, { "name": "amountMin", "required": false, "in": "query", "description": "Payable amount, MAJOR units, inclusive.", "schema": { "example": "1000.00", "type": "string" } }, { "name": "amountMax", "required": false, "in": "query", "description": "Payable amount, MAJOR units, inclusive.", "schema": { "example": "50000", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "NGN", "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Seller name or TIN, IRN, or the seller’s invoice number (substring, any case).", "schema": { "maxLength": 100, "type": "string" } }, { "name": "taxId", "required": false, "in": "query", "description": "One of `taxpayer.taxIds` (the organisation’s own tax ids in this mode); any other is 400.", "schema": { "maxLength": 32, "type": "string" } } ], "responses": { "200": { "description": "The figures.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InboundAnalyticsDto" } } } } } }, "400": { "description": "VAL001: a filter out of shape, or a `taxId` that is not one of the organisation’s.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `invoice.inbound.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get analytics over received invoices", "tags": [ "Inbound", "inbound-invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/inbound-invoices/load-older": { "post": { "description": "`invoice.inbound.read`; charged per page read (refunded when the read fails). Reads ONE more page of the gateway’s feed past where the mirror’s walk stopped (it may reach the authority’s own history, and be slow) and stores it; then list the received invoices again. `hasMore: false` — nothing older to read. With no tax connection nothing is read or charged.", "operationId": "loadOlderInboundInvoices", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "8–128 characters of A–Z, a–z, 0–9, `_` or `-`. A retry with the same key is not charged twice.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "What the page held.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InboundLoadOlderDto" } } } } } }, "400": { "description": "VAL001: a malformed `Idempotency-Key`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "402": { "description": "BIZ001: not enough credits for the page read — top up to continue.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `invoice.inbound.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "BIZ107: the `Idempotency-Key` was already used for a different request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ107" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS202: the authority gateway gave no usable answer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Load older received invoices from the tax authority", "tags": [ "Inbound", "inbound-invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoice-settings": { "get": { "description": "Requires `invoice.read`. The organisation’s invoice settings in the token’s mode; the defaults (version 0) when they were never changed. The `ETag` header carries the `version`.", "operationId": "getInvoiceSettings", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceSettingsViewDto" } } } } } } }, "summary": "Get the invoice settings", "tags": [ "invoice-settings" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "patch": { "description": "Users only, with `tax_connection.connect`. Turning `reportAutomatically` off needs a recent second-factor step-up (403 `AUTH033` with a `WWW-Authenticate` challenge otherwise); turning it on does not. `If-Match: \"\"` is optional (`\"0\"` while never changed); a stale version answers 409 `RES003`. The `ETag` header carries the new `version`.", "operationId": "updateInvoiceSettings", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.UpdateInvoiceSettingsDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceSettingsViewDto" } } } } } } }, "summary": "Update the invoice settings", "tags": [ "invoice-settings" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/i/v1/invoices": { "get": { "description": "Requires `invoice.read`. The organisation’s invoices, credit notes and debit notes in the token’s mode, filtered and sorted by the query; newest first by default. List items carry no `lineItems`.", "operationId": "listInvoices", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "draft", "finalised", "queued", "signed", "transmitted", "accepted", "rejected", "failed", "cancellation_pending", "cancelled" ] } }, { "name": "invoiceType", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "standard", "credit_note", "debit_note" ] } }, { "name": "paymentStatus", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "unpaid", "partially_paid", "paid", "payment_failed" ] } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "NGN", "type": "string" } }, { "name": "buyerId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "sellerId", "required": false, "in": "query", "description": "Only the organisation’s own seller id.", "schema": { "format": "uuid", "type": "string" } }, { "name": "createdBy", "required": false, "in": "query", "description": "Only documents created by this actor id (`createdBy.id`): an auth user id, or an API-key id with `createdByType=api_key`.", "schema": { "format": "uuid", "type": "string" } }, { "name": "createdByType", "required": false, "in": "query", "description": "Only documents created by this kind of actor (`createdBy.type`).", "schema": { "type": "string", "enum": [ "user", "api_key", "service", "system" ] } }, { "name": "invoiceDateFrom", "required": false, "in": "query", "schema": { "example": "2026-09-01", "type": "string" } }, { "name": "invoiceDateTo", "required": false, "in": "query", "schema": { "example": "2026-09-30", "type": "string" } }, { "name": "dueDateFrom", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "dueDateTo", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "createdAtFrom", "required": false, "in": "query", "schema": { "example": "2026-09-01T00:00:00Z", "type": "string" } }, { "name": "createdAtTo", "required": false, "in": "query", "description": "Exclusive.", "schema": { "example": "2026-10-01T00:00:00Z", "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Matches the document number, the number NRS holds or the IRN by prefix, and the buyer name or TIN anywhere in it. Case-insensitive; `%` and `_` are plain characters.", "schema": { "maxLength": 100, "type": "string" } }, { "name": "simpleStatus", "required": false, "in": "query", "description": "Only documents with this simple status (`simpleStatus`).", "schema": { "type": "string", "enum": [ "draft", "issued", "reported", "delivered", "paid", "part_paid", "cancelled" ] } }, { "name": "reporting", "required": false, "in": "query", "description": "Only documents at this reporting stage, as the summary cards count them (`needs_attention` = rejected or on hold, not cancelled).", "schema": { "type": "string", "enum": [ "draft", "not_reported", "in_progress", "reported", "needs_attention" ] } }, { "name": "delivery", "required": false, "in": "query", "description": "Only documents with this delivery channel (`reporting.delivery`).", "schema": { "type": "string", "enum": [ "nrs", "deliver_to_buyer", "sent_email", "shared_link", "none" ] } }, { "name": "credited", "required": false, "in": "query", "description": "`true`: documents credited by a credit note that counts against them; `false`: invoices no credit note credits.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "refundOwed", "required": false, "in": "query", "description": "`true`: documents on which a refund is still owed to the buyer; `false`: documents on which none is.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "overdue", "required": false, "in": "query", "description": "Only issued invoices still owing (net of credit notes) past their due date today.", "schema": { "type": "string", "enum": [ "true" ] } }, { "name": "amountFromMinor", "required": false, "in": "query", "description": "Payable amount at least this (minor units).", "schema": { "minimum": 0, "type": "number" } }, { "name": "amountToMinor", "required": false, "in": "query", "description": "Payable amount at most this (minor units).", "schema": { "minimum": 0, "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "sortBy", "required": false, "in": "query", "schema": { "default": "createdAt", "type": "string", "enum": [ "createdAt", "invoiceDate", "invoiceNumber", "payableMinor", "dueDate", "taxMinor" ] } }, { "name": "sortOrder", "required": false, "in": "query", "schema": { "default": "DESC", "type": "string", "enum": [ "ASC", "DESC" ] } } ], "responses": { "200": { "description": "One page of documents (without `lineItems`), `meta.pagination` set.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/invoice.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } } } } } } } }, "summary": "List invoices", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "post": { "description": "Requires `invoice.create`; charged as one invoice creation. Creates a draft (`status: draft`); the number is allocated from the series when `invoiceNumber` is omitted. Send an `Idempotency-Key` to make a retry safe: a repeated key answers the first result with `Idempotent-Replayed: true`. The `ETag` header carries the invoice `version`.", "operationId": "createInvoice", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.CreateInvoiceDto" } } } }, "responses": { "201": { "description": "The draft.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } } } } } } }, "summary": "Create a draft invoice", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}": { "get": { "description": "Requires `invoice.read`. One document with its lines. A document of another organisation or of the other mode answers 404 `RES001`, like a missing one. The `ETag` header carries the invoice `version`.", "operationId": "getInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } } } } } } }, "summary": "Get an invoice", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "patch": { "description": "Requires `invoice.update_draft`. Drafts only (409 `BIZ201` otherwise). An absent field is unchanged; `null` clears an optional one; `lineItems` replaces every line. `If-Match: \"\"` is optional; a stale version answers 409 `RES003`. The `ETag` header carries the invoice `version`.", "operationId": "updateInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.UpdateInvoiceDto" } } } }, "responses": { "200": { "description": "The updated draft.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } } } } } } }, "summary": "Update a draft invoice", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "delete": { "description": "Requires `invoice.delete_draft`. Drafts only; the draft is deleted permanently and its number is never reused.", "operationId": "deleteInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceDeletedDto" } } } } } } }, "summary": "Delete a draft invoice", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/authority-download": { "get": { "description": "Requires `invoice.download_authority_copy`. The tax authority’s own decrypted copy of a registered document, as JSON. Not charged.", "operationId": "getInvoiceAuthorityCopy", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.AuthorityCopyDto" } } } } } } }, "summary": "Get the tax authority’s copy of an invoice", "tags": [ "submissions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/cancel": { "post": { "description": "Requires `invoice.cancel`. A finalised invoice the tax authority does not hold (never submitted, rejected, or still queued) is voided locally, free of charge. A registered one is cancelled with a credit note for everything left, charged as one cancellation; it becomes `cancelled` once the credit note registers. A draft is 409 `BIZ201` (delete it instead); a document in flight to the tax authority, a credit note, or one already cancelled is 409 `BIZ004`. Accepts an `Idempotency-Key`. Answers the original as it now stands. The `ETag` header carries the invoice `version`.", "operationId": "cancelInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.CancelInvoiceDto" } } } }, "responses": { "202": { "description": "The original invoice, cancelled or being cancelled.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } } } } } } }, "summary": "Cancel an invoice", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/credit-notes": { "post": { "description": "Requires `invoice.cancel`. Credits everything left (`full`), chosen lines and quantities (`lines`), or a tax-inclusive `amount`; several credit notes may be issued as long as their total stays within the payable amount plus any debit notes. Each credit note is charged as one cancellation. Accepts an `Idempotency-Key`. With `preview: true` nothing is written or charged and the answer is 200 with the preview.", "operationId": "issueCreditNote", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.IssueCreditNoteDto" } } } }, "responses": { "200": { "description": "With `preview: true`: what would be issued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.CreditNotePreviewAnswerDto" } } } } } }, "202": { "description": "The original invoice as it now stands and the credit note just issued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.CreditNoteIssuedDto" } } } } } } }, "summary": "Issue a credit note against a registered invoice", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/debit-notes": { "post": { "description": "Requires `invoice.create` and `invoice.submit`. Adds lines to a registered invoice as a debit note and submits it; the charge is held and captured when it registers (released if the tax authority rejects it). Accepts an `Idempotency-Key`. With `preview: true` nothing is written or charged and the answer is 200 with the preview.", "operationId": "issueDebitNote", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.IssueDebitNoteDto" } } } }, "responses": { "200": { "description": "With `preview: true`: what would be issued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.DebitNotePreviewAnswerDto" } } } } } }, "202": { "description": "The original invoice as it now stands and the debit note just issued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.DebitNoteIssuedDto" } } } } } } }, "summary": "Issue a debit note against a registered invoice", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/download": { "get": { "description": "Content negotiation on `Accept`: `application/pdf` answers the PDF itself as an attachment; anything else (or no `Accept`) answers a short-lived download link in the JSON envelope. Never cached (`Cache-Control: private, no-store`, `Vary: Accept`).", "operationId": "downloadInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "format", "required": false, "in": "query", "description": "Only `pdf` exists.", "schema": { "type": "string", "enum": [ "pdf" ] } } ], "responses": { "200": { "description": "The PDF (`application/pdf`), or a download link (`application/json`).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.DownloadLinkDto" } } } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Download an invoice as a PDF", "tags": [ "output" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/finalise": { "post": { "description": "Requires `invoice.finalise`. Freezes the seller and buyer onto the document; 422 `VAL001` when the jurisdiction’s checks refuse it. The `ETag` header carries the invoice `version`.", "operationId": "finaliseInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The finalised invoice.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } } } } } } }, "summary": "Finalise a draft invoice", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/issue": { "post": { "description": "Requires `invoice.finalise` and `invoice.submit`. When the organisation is connected to NRS and reports automatically, the draft is finalised and submitted (202). Otherwise it is finalised and sent to the buyer without being reported (200, `notReportedReason` says why). Accepts an `Idempotency-Key`.", "operationId": "issueInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Finalised and sent to the buyer, not reported.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.IssueAnswerDto" } } } } } }, "202": { "description": "Finalised and queued for reporting.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.IssueAnswerDto" } } } } } } }, "summary": "Issue a draft invoice", "tags": [ "submissions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/payment-status": { "patch": { "description": "Requires `invoice.record_payment`. Only for a document registered with the tax authority; the latest report is relayed to it. Not charged. `amountPaidMinor` moves only once the tax authority accepts the report (see `payments`).", "operationId": "recordInvoicePayment", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.PaymentStatusDto" } } } }, "responses": { "200": { "description": "The invoice.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } } } } } } }, "summary": "Record an invoice’s payment status", "tags": [ "submissions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/query-status": { "post": { "description": "Requires `invoice.query_status`; charged as one status query before the call and refunded when the tax authority is unavailable (503 `SYS202`, nothing changed). The answer only ever moves the status forward. An `Idempotency-Key` is bound to this invoice; reusing it for another invoice is 409 `BIZ107`.", "operationId": "queryInvoiceStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.QueryStatusDto" } } } } } } }, "summary": "Refresh an invoice’s status from the tax authority", "tags": [ "submissions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/renumber": { "post": { "description": "Requires `invoice.submit`. Only when the current submission is on hold because the tax authority already holds the invoice number: the invoice takes the next number of its series (the old one is kept on the withdrawn submission) and a new submission is queued with a new charge hold. Otherwise 409 `BIZ004` says why. Accepts an `Idempotency-Key`; a repeated key answers 200 with `replayed: true`.", "operationId": "renumberInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A replay of an earlier request with the same key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.SubmitAnswerDto" } } } } } }, "202": { "description": "Renumbered and queued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.SubmitAnswerDto" } } } } } } }, "summary": "Renumber an invoice and resubmit it", "tags": [ "submissions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/reopen": { "post": { "description": "Requires `invoice.reopen`. Allowed while the current submission was rejected by the tax authority, or when the invoice was never submitted (then it is revised: same number, next version). `If-Match` is optional. The `ETag` header carries the invoice `version`.", "operationId": "reopenInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The draft.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } } } } } } }, "summary": "Reopen a finalised invoice as a draft", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/retry": { "post": { "description": "Requires `invoice.retry`. Resumes the same submission that is on hold, with its existing charge hold.", "operationId": "retryInvoiceSubmission", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.RetryAnswerDto" } } } } } } }, "summary": "Retry an invoice submission on hold", "tags": [ "submissions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/revise": { "post": { "description": "Requires `invoice.reopen`. An issued invoice never reported to the tax authority and unpaid goes back to a draft with the same number and the next version; otherwise 409 `BIZ201` says what to do instead. `If-Match` is optional. The `ETag` header carries the invoice `version`.", "operationId": "reviseInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The draft.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } } } } } } }, "summary": "Revise an issued invoice that was never reported", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/send": { "post": { "description": "`invoice.send_to_buyer`; charged per send (refunded if it cannot be recorded). Queues an email of a finalised invoice to the buyer email on the issued document (never an address from the request), with an optional `message`. 202 means accepted and queued, not delivered. In sandbox no email leaves: `shareUrl` links to the PDF for preview. A replayed `Idempotency-Key` answers the first result with `replayed: true`.", "operationId": "sendInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.SendInvoiceDto" } } } }, "responses": { "202": { "description": "The send was queued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.SendResultDto" } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ004" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Send an invoice to its buyer", "tags": [ "output" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/share-links": { "get": { "description": "`invoice.share`. Every link of the invoice, newest first, revoked and expired included (kept 90 days); `url` is always null here.", "operationId": "listInvoiceShareLinks", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The links, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.ShareLinkViewDto" } } } } } } }, "400": { "description": "VAL001: `:id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `invoice.share`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: no such invoice in this organisation and mode (another organisation’s or the other mode’s invoice answers the same).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List an invoice’s share links", "tags": [ "ShareLinks", "share-links" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "post": { "description": "`invoice.share`. A random, stored, revocable token; `url` is answered ONCE (only its sha256 is kept). `expiresInSeconds` 3600–2592000 (default 604800), `maxViews` 1–10000 (absent = unlimited). At most 20 live links per invoice. Emits the `invoice.share_link.created` event.", "operationId": "createInvoiceShareLink", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.CreateShareLinkDto" } } } }, "responses": { "201": { "description": "The link, with its `url` — the one time the token is shown.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ShareLinkViewDto" } } } } } }, "400": { "description": "VAL001: `:id` is not a UUID, a bound is broken, or an unknown field is sent.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `invoice.share`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: no such invoice in this organisation and mode (another organisation’s or the other mode’s invoice answers the same).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "BIZ004: the invoice is a draft, or already has 20 live links.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ004" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant write bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Create a share link to a finalised invoice", "tags": [ "ShareLinks", "share-links" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/share-links/{linkId}": { "delete": { "description": "`invoice.share`. Immediate: the next resolve is 404. Idempotent (a revoked link answers 200 with its view). Emits the `invoice.share_link.revoked` event.", "operationId": "revokeInvoiceShareLink", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } }, { "name": "linkId", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The link, revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ShareLinkViewDto" } } } } } }, "400": { "description": "VAL001: `:id` or `:linkId` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `invoice.share`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: no such link on this invoice in this organisation and mode (another organisation’s answers the same).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant write bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Revoke a share link", "tags": [ "ShareLinks", "share-links" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/status": { "get": { "description": "Requires `invoice.read`. The status as last recorded, with every submission; the tax authority is not called and nothing is charged.", "operationId": "getInvoiceStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.SubmissionStatusDto" } } } } } } }, "summary": "Get an invoice’s submission status", "tags": [ "submissions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/{id}/submit": { "post": { "description": "Requires `invoice.submit`. Queues a submission of a finalised invoice; with `finalise=true` a draft is finalised and submitted in one step. Idempotent per invoice: while a submission is in flight the same one is answered with 200 and `replayed: true`. Accepts an `Idempotency-Key`.", "operationId": "submitInvoice", "parameters": [ { "name": "finalise", "required": false, "in": "query", "description": "Finalise a draft and submit it in one step.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A submission already in flight (`replayed: true`).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.SubmitAnswerDto" } } } } } }, "202": { "description": "Queued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.SubmitAnswerDto" } } } } } } }, "summary": "Submit an invoice to the tax authority", "tags": [ "submissions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/batch-submit": { "post": { "description": "Requires `invoice.submit`. Submits 1 to 100 invoices, each independently (its own charge and outcome); the batch counts once against the rate limit. Per-invoice results say which were queued and which failed.", "operationId": "batchSubmitInvoices", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.BatchSubmitDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.BatchSubmitResultDto" } } } } } } }, "summary": "Submit several invoices", "tags": [ "submissions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/codes/used": { "get": { "description": "`item.read`. `type=goods` reads the lines’ HS codes, `type=service` their service codes, over the organisation’s invoices in the token’s mode, every status (drafts and cancelled count). Most used first, then most recent; `description` is the most recent line’s product category for the code. This reads your own invoices, not the tax authority’s code lists.", "operationId": "listUsedItemCodes", "parameters": [ { "name": "type", "required": true, "in": "query", "description": "goods → HS codes; service → service codes.", "schema": { "type": "string", "enum": [ "goods", "service" ] } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "The codes, at most `limit` (default 20).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.UsedCodeDto" } } } } } } }, "400": { "description": "VAL001: `type` missing or not goods|service; `limit` out of range.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no item.read), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List previously used HS or service codes", "tags": [ "UsedCodes", "items" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/create-and-submit": { "post": { "description": "Requires `invoice.create` and `invoice.submit`. Creates the invoice as `POST /invoices` does, then submits it. When the submit is refused the draft is kept and `submitRefusal` says why. Accepts an `Idempotency-Key`.", "operationId": "createAndSubmitInvoice", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.CreateInvoiceDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.CreateAndSubmitResultDto" } } } } } } }, "summary": "Create an invoice and submit it", "tags": [ "submissions" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/hsn-codes": { "get": { "description": "`reference.read`; free. The HS code list of the organisation’s jurisdiction, in the token’s mode, filtered by `search` and `category`; `page` and `limit`.", "operationId": "listHsCodes", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Case-insensitive text in the code, description or category.", "schema": { "maxLength": 100, "type": "string" } }, { "name": "category", "required": false, "in": "query", "description": "Exact category name (case-insensitive).", "schema": { "maxLength": 100, "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "One page of HS codes, `meta.pagination` set.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/invoice.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.HsCodeDto" } } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ213" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List HS codes", "tags": [ "invoice-reference" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/hsn-codes/categories": { "get": { "description": "`reference.read`; free. The category names of the HS code list of the organisation’s jurisdiction, in the token’s mode, sorted.", "operationId": "listHsCodeCategories", "parameters": [], "responses": { "200": { "description": "The HS code categories, sorted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "type": "string" } } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ213" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List HS code categories", "tags": [ "invoice-reference" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/lookup/tax-id/{value}": { "get": { "description": "`tax_id.lookup`; charged per lookup before the provider is asked, refunded when it could not answer (503, never \"not registered\"). An `Idempotency-Key` retry is not charged twice; the lookup is made again.", "operationId": "lookupTaxId", "parameters": [ { "name": "value", "required": true, "in": "path", "schema": { "maxLength": 64, "example": "33875194-0001", "type": "string" } }, { "name": "type", "required": false, "in": "query", "schema": { "default": "tin", "type": "string", "enum": [ "tin", "rn", "foreign" ] } }, { "name": "Idempotency-Key", "in": "header", "description": "8–128 of [A-Za-z0-9_-]", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The lookup’s answer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.TaxIdLookupDto" } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ107" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ213" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Look up a tax id", "tags": [ "invoice-reference" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/overview": { "get": { "description": "Requires `invoice.stats.read`. Key figures over the last `windowDays` compared with the window before, the daily trend, status and payment distribution, collections, alerts, readiness and the most recent documents.", "operationId": "getInvoiceOverview", "parameters": [ { "name": "windowDays", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 90, "default": 7, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceOverviewDto" } } } } } } }, "summary": "Get the invoicing dashboard overview", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/resources": { "get": { "description": "`reference.read`; free. Every code list of the organisation’s jurisdiction in the token’s mode: type, version, item count, fetch time and staleness.", "operationId": "listInvoiceReferenceLists", "parameters": [], "responses": { "200": { "description": "The lists.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.CodeListIndexDto" } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ213" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List the reference code lists", "tags": [ "invoice-reference" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/resources/{type}": { "get": { "description": "`reference.read`; free. One code list’s items; a type the jurisdiction does not serve is 404.", "operationId": "getInvoiceReferenceList", "parameters": [ { "name": "type", "required": true, "in": "path", "schema": { "pattern": "^[a-z][a-z-]{0,63}$", "example": "tax-categories", "type": "string" } } ], "responses": { "200": { "description": "The list and its items.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.CodeListDto" } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ213" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get a reference code list", "tags": [ "invoice-reference" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/setup": { "get": { "description": "Requires `invoice.read`. Currencies, invoice kinds, tax categories with their current rates, unit codes, the tax connection state, and the next invoice number (a preview, not reserved).", "operationId": "getInvoiceSetup", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceSetupDto" } } } } } } }, "summary": "Get the reference data for the invoice form", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/statistics": { "get": { "description": "Requires `invoice.stats.read`. Over documents created in the window (default the last 30 days, at most 366): counts by status and by payment status, the success rate, totals by currency, and output tax.", "operationId": "getInvoiceStatistics", "parameters": [ { "name": "from", "required": false, "in": "query", "schema": { "example": "2026-09-01T00:00:00Z", "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "Exclusive.", "schema": { "example": "2026-10-01T00:00:00Z", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceStatisticsDto" } } } } } } }, "summary": "Get invoice statistics", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/summary": { "get": { "description": "Requires `invoice.stats.read`. Takes the list’s filters (no paging or sorting) and counts the documents they select by reporting stage, with the money still owed (net of credit notes) and its overdue part per currency.", "operationId": "getInvoiceListSummary", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "draft", "finalised", "queued", "signed", "transmitted", "accepted", "rejected", "failed", "cancellation_pending", "cancelled" ] } }, { "name": "invoiceType", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "standard", "credit_note", "debit_note" ] } }, { "name": "paymentStatus", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "unpaid", "partially_paid", "paid", "payment_failed" ] } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "NGN", "type": "string" } }, { "name": "buyerId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "sellerId", "required": false, "in": "query", "description": "Only the organisation’s own seller id.", "schema": { "format": "uuid", "type": "string" } }, { "name": "createdBy", "required": false, "in": "query", "description": "Only documents created by this actor id (`createdBy.id`): an auth user id, or an API-key id with `createdByType=api_key`.", "schema": { "format": "uuid", "type": "string" } }, { "name": "createdByType", "required": false, "in": "query", "description": "Only documents created by this kind of actor (`createdBy.type`).", "schema": { "type": "string", "enum": [ "user", "api_key", "service", "system" ] } }, { "name": "invoiceDateFrom", "required": false, "in": "query", "schema": { "example": "2026-09-01", "type": "string" } }, { "name": "invoiceDateTo", "required": false, "in": "query", "schema": { "example": "2026-09-30", "type": "string" } }, { "name": "dueDateFrom", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "dueDateTo", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "createdAtFrom", "required": false, "in": "query", "schema": { "example": "2026-09-01T00:00:00Z", "type": "string" } }, { "name": "createdAtTo", "required": false, "in": "query", "description": "Exclusive.", "schema": { "example": "2026-10-01T00:00:00Z", "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Matches the document number, the number NRS holds or the IRN by prefix, and the buyer name or TIN anywhere in it. Case-insensitive; `%` and `_` are plain characters.", "schema": { "maxLength": 100, "type": "string" } }, { "name": "simpleStatus", "required": false, "in": "query", "description": "Only documents with this simple status (`simpleStatus`).", "schema": { "type": "string", "enum": [ "draft", "issued", "reported", "delivered", "paid", "part_paid", "cancelled" ] } }, { "name": "reporting", "required": false, "in": "query", "description": "Only documents at this reporting stage, as the summary cards count them (`needs_attention` = rejected or on hold, not cancelled).", "schema": { "type": "string", "enum": [ "draft", "not_reported", "in_progress", "reported", "needs_attention" ] } }, { "name": "delivery", "required": false, "in": "query", "description": "Only documents with this delivery channel (`reporting.delivery`).", "schema": { "type": "string", "enum": [ "nrs", "deliver_to_buyer", "sent_email", "shared_link", "none" ] } }, { "name": "credited", "required": false, "in": "query", "description": "`true`: documents credited by a credit note that counts against them; `false`: invoices no credit note credits.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "refundOwed", "required": false, "in": "query", "description": "`true`: documents on which a refund is still owed to the buyer; `false`: documents on which none is.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "overdue", "required": false, "in": "query", "description": "Only issued invoices still owing (net of credit notes) past their due date today.", "schema": { "type": "string", "enum": [ "true" ] } }, { "name": "amountFromMinor", "required": false, "in": "query", "description": "Payable amount at least this (minor units).", "schema": { "minimum": 0, "type": "number" } }, { "name": "amountToMinor", "required": false, "in": "query", "description": "Payable amount at most this (minor units).", "schema": { "minimum": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.InvoiceListSummaryDto" } } } } } } }, "summary": "Summarise the documents a list filter selects", "tags": [ "invoices" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/invoices/validate": { "post": { "description": "`invoice.validate`; charged per call before the tax authority gateway is asked, refunded when it could not answer. Answers 200 whether the document is valid or not: the verdict is the answer. Nothing is stored.", "operationId": "validateInvoice", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "8–128 of [A-Za-z0-9_-]", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.ValidateInvoiceDto" } } } }, "responses": { "200": { "description": "The verdict.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ValidationResultDto" } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ202" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ213" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Validate an invoice with the tax authority (dry run)", "tags": [ "invoice-reference" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/items": { "get": { "description": "`item.read`. Non-archived by default (`archived=true` archived only, `all` both); `q` is a case-insensitive substring over name, description, sku, hsnCode and serviceCode; sorted most used first (`-useCount`), by `name`, or `-lastUsedAt`. The token’s mode decides which items are read.", "operationId": "listItems", "parameters": [ { "name": "q", "required": false, "in": "query", "description": "Case-insensitive substring over name, description, sku, hsnCode, serviceCode.", "schema": { "maxLength": 100, "type": "string" } }, { "name": "itemType", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "goods", "service" ] } }, { "name": "archived", "required": false, "in": "query", "description": "`false` non-archived (default), `true` archived only, `all` both.", "schema": { "default": "false", "type": "string", "enum": [ "false", "true", "all" ] } }, { "name": "sort", "required": false, "in": "query", "schema": { "default": "-useCount", "type": "string", "enum": [ "-useCount", "name", "-lastUsedAt" ] } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "One page of items, `meta.pagination` set.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/invoice.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.ItemViewDto" } } } } } } }, "400": { "description": "VAL001: a query parameter out of range or unknown.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no item.read), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List saved items", "tags": [ "Items", "items" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "post": { "description": "`item.create`; free. A goods item needs an `hsnCode`, a service item a `serviceCode`; `productCategory` is required; `taxCategory` is a code-list id of the organisation’s jurisdiction (a line alias is stored resolved); `sku`, when sent, is unique among the organisation’s non-archived items. Emits the `invoice.item.created` event.", "operationId": "createItem", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.CreateItemDto" } } } }, "responses": { "201": { "description": "The saved item.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ItemViewDto" } } } } } }, "400": { "description": "VAL001: a field out of shape, a goods item without hsnCode, a service item without serviceCode, a tax category the jurisdiction does not serve.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no item.create), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "RES002: the sku is held by a non-archived item of this organisation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES002" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "422": { "description": "BIZ213: the organisation’s country has no jurisdiction adapter.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ213" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant write bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS002: the organisation’s verified facts could not be read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Save an item", "tags": [ "Items", "items" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/items/{id}": { "get": { "description": "`item.read`. An archived item is readable by id (`archivedAt` set).", "operationId": "getItem", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The item.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ItemViewDto" } } } } } }, "400": { "description": "VAL001: `:id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no item.read), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: no such item in this organisation and mode (another organisation’s or the other mode’s item answers the same).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get a saved item", "tags": [ "Items", "items" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "patch": { "description": "`item.update`. The create fields, all optional; `itemType` is immutable; a `sku` change obeys the unique rule; an archived item is editable but not usable on a line. Lines already built from the item never change. Emits the `invoice.item.updated` event.", "operationId": "updateItem", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.UpdateItemDto" } } } }, "responses": { "200": { "description": "The item after the edit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ItemViewDto" } } } } } }, "400": { "description": "VAL001: a field out of shape, `itemType` sent with another value, the code the type needs nulled, a tax category the jurisdiction does not serve.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no item.update), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: no such item in this organisation and mode (another organisation’s or the other mode’s item answers the same).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "RES002: the new sku is held by a non-archived item of this organisation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES002" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "422": { "description": "BIZ213: the organisation’s country has no jurisdiction adapter (a taxCategory change).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ213" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant write bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Update a saved item", "tags": [ "Items", "items" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "delete": { "description": "`item.archive`. Hard delete only while no invoice line of this mode’s database references the item (drafts included); otherwise 409 BIZ004 — archive it instead. Answers 200 `{id, deleted: true}`. Emits the `invoice.item.deleted` event.", "operationId": "deleteItem", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The item was deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ItemDeletedDto" } } } } } }, "400": { "description": "VAL001: `:id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no item.archive), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: no such item in this organisation and mode (another organisation’s or the other mode’s item answers the same).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "BIZ004: \"this item is on N invoice line(s) — archive it\".", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ004" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant write bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Delete a saved item", "tags": [ "Items", "items" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/items/{id}/archive": { "post": { "description": "`item.archive`. Idempotent (an archived item answers 200 with the same view). An archived item is left out of the item list by default and refused on a new line (409 BIZ004); lines that already carry it are untouched. Emits the `invoice.item.archived` event.", "operationId": "archiveItem", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The archived item.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ItemViewDto" } } } } } }, "400": { "description": "VAL001: `:id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no item.archive), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: no such item in this organisation and mode (another organisation’s or the other mode’s item answers the same).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant write bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Archive a saved item", "tags": [ "Items", "items" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/items/{id}/unarchive": { "post": { "description": "`item.archive`. Idempotent. Refused 409 RES002 when another non-archived item took the sku meanwhile. Emits the `invoice.item.unarchived` event.", "operationId": "unarchiveItem", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The item, live again.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ItemViewDto" } } } } } }, "400": { "description": "VAL001: `:id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no item.archive), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: no such item in this organisation and mode (another organisation’s or the other mode’s item answers the same).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "RES002: the sku is held by another non-archived item of this organisation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES002" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant write bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Unarchive a saved item", "tags": [ "Items", "items" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/sellers": { "get": { "description": "`seller.read`. The organisation’s seller as a list of one, filtered by `search` (name, legal name or tax id); `page` and `limit` (up to 100).", "operationId": "listSellers", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Name, legal name or tax id.", "schema": { "maxLength": 100, "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "One page (zero or one seller), `meta.pagination` set.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/invoice.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.SellerViewDto" } } } } } } }, "400": { "description": "VAL001: a query parameter out of range or unknown.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `seller.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS002: the organisation’s verified facts could not be read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List sellers", "tags": [ "sellers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/sellers/{id}": { "get": { "description": "`seller.read`. The organisation’s seller, by its id.", "operationId": "getSeller", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The seller.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.SellerViewDto" } } } } } }, "400": { "description": "VAL001: `id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `seller.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: the id is not the organisation’s seller id.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS002: the organisation’s verified facts could not be read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get the seller", "tags": [ "sellers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/sellers/{id}/verification-status": { "get": { "description": "`seller.read`. The organisation’s TIN status, as verified in organisation settings.", "operationId": "getSellerVerificationStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.SellerVerificationStatusDto" } } } } } }, "400": { "description": "VAL001: `id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `seller.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: the id is not the organisation’s seller id.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS002: the organisation’s verified facts could not be read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get the seller’s tax number verification status", "tags": [ "sellers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/sellers/search": { "get": { "description": "`seller.read`. The organisation’s seller when its name, legal name or tax id matches `q` (at least 2 characters); otherwise an empty list.", "operationId": "searchSellers", "parameters": [ { "name": "q", "required": true, "in": "query", "schema": { "minLength": 2, "maxLength": 100, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 20, "default": 10, "type": "number" } } ], "responses": { "200": { "description": "Zero or one seller.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.SellerViewDto" } } } } } } }, "400": { "description": "VAL001: `q` shorter than 2 characters, or `limit` out of range.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `seller.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS002: the organisation’s verified facts could not be read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Search sellers", "tags": [ "sellers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/sellers/setup": { "get": { "description": "`seller.read`. The organisation’s seller, that no further sellers can be added, the tax-id types of its jurisdiction, and the countries.", "operationId": "getSellerSetup", "parameters": [], "responses": { "200": { "description": "The seller and options.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.SellerSetupDto" } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `seller.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS002: the organisation’s verified facts could not be read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get the seller and its form options", "tags": [ "sellers" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/i/v1/tax-connection": { "get": { "description": "`tax_connection.read`. The organisation’s connection to the tax authority in the token’s mode — its state, the key, what must happen next — or, with none, what stands between it and connecting. API keys may read it to learn whether a live submission will pass (`submissionsAllowed`).", "operationId": "getTaxConnection", "parameters": [], "responses": { "200": { "description": "The connection.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ConnectionViewDto" } } } } } }, "400": { "description": "VAL001: a query parameter was sent (none is accepted).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `tax_connection.read`), AUTH020 (no organisation), AUTH018 (principal type).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the tenant read bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS002: the organisation’s verified facts could not be read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get the tax connection", "tags": [ "tax-connection" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "post": { "description": "`tax_connection.connect`; users only, with a recent step-up. Requests the grant for the organisation’s verified tax id (never a tax id from the body) after the consent is accepted. 201 for a new connection; 200 with the existing live one. A replayed `Idempotency-Key` answers the first result with `Idempotent-Replayed: true`.", "operationId": "connectTaxConnection", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "8–128 characters of A–Z, a–z, 0–9, `_` or `-`.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.ConnectDto" } } } }, "responses": { "200": { "description": "The organisation already has a live connection in this mode; this is it.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ConnectionViewDto" } } } } } }, "201": { "description": "A new connection was requested.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ConnectionViewDto" } } } } } }, "400": { "description": "VAL001: a query parameter was sent (none is accepted), a field out of shape or not accepted (a `taxId` in the body is refused), or a malformed `Idempotency-Key`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `tax_connection.connect`), AUTH020 (no organisation), AUTH018 (users only; API keys are refused), AUTH033 (a recent second-factor step-up is required; prove it and retry).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "BIZ203: the organisation’s tax id is not verified; BIZ218: the verified tax id is not in the form the tax authority connects; BIZ217: the tax id is connected by another organisation; BIZ206: the identifiers sent do not match what the tax authority reports; BIZ107: the `Idempotency-Key` was used for a different request; RES003: a concurrent change, retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ203" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "422": { "description": "BIZ213: the organisation’s country is not supported.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ213" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the per-organisation tax-connection bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS202: the tax authority gateway gave no usable answer; SYS201: this mode cannot reach it right now; SYS002: the organisation’s verified facts could not be read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Connect to the tax authority", "tags": [ "tax-connection" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] }, "delete": { "description": "`tax_connection.disconnect`; users only, with a recent step-up. Revokes the grant; the access point keeps the key material (it offers no delete). When the other mode’s connection shares the same grant, the grant is kept for it (`grantKeptFor`). Optional body `{reason}`.", "operationId": "disconnectTaxConnection", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.DisconnectDto" } } } }, "responses": { "200": { "description": "The connection, revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.DisconnectViewDto" } } } } } }, "400": { "description": "VAL001: a query parameter was sent (none is accepted) or `reason` out of shape.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `tax_connection.disconnect`), AUTH020 (no organisation), AUTH018 (users only; API keys are refused), AUTH033 (a recent second-factor step-up is required; prove it and retry).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: the organisation has no live tax connection in this mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the per-organisation tax-connection bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS202: the tax authority gateway gave no usable answer; SYS201: this mode cannot reach it right now; SYS002: the organisation’s verified facts could not be read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Disconnect from the tax authority", "tags": [ "tax-connection" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/i/v1/tax-connection/crypto-key": { "put": { "description": "`tax_connection.install_key`; users only, with a recent step-up. The key file downloaded from the tax authority’s portal, encrypted in the browser to the key-upload encryption key. It is opened in memory, relayed to the access point and not stored; only its certificate fingerprint is kept.", "operationId": "installTaxConnectionKey", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice.InstallKeyDto" } } } }, "responses": { "200": { "description": "The connection with the key installed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ConnectionViewDto" } } } } } }, "400": { "description": "VAL201: the envelope could not be opened (wrong key, binding or age); VAL001: a field out of shape or a query parameter sent.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL201" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `tax_connection.install_key`), AUTH020 (no organisation), AUTH018 (users only; API keys are refused), AUTH033 (a recent second-factor step-up is required; prove it and retry).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "BIZ004: no live connection to install a key on, or one requested with the tax id in a form the tax authority does not show (disconnect, then connect again).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ004" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "422": { "description": "BIZ208: the key file is malformed; BIZ209: its platform key is unknown; BIZ210: its certificate is invalid; BIZ211: it cannot be used.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ208" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the key-install bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS202: the tax authority gateway gave no usable answer; SYS201: this mode cannot reach it right now; SYS002: the organisation’s verified facts could not be read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Upload the signing key", "tags": [ "tax-connection" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/i/v1/tax-connection/refresh": { "post": { "description": "`tax_connection.read`; users only. Asks the tax authority gateway about the grant again and answers the connection as it now stands. Limited per organisation.", "operationId": "refreshTaxConnection", "parameters": [], "responses": { "200": { "description": "The connection after the check.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.ConnectionViewDto" } } } } } }, "400": { "description": "VAL001: a query parameter was sent (none is accepted).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `tax_connection.read`), AUTH020 (no organisation), AUTH018 (users only; API keys are refused).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "RES001: the organisation has no live tax connection in this mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the per-organisation tax-connection bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "SYS202: the tax authority gateway gave no usable answer; SYS201: this mode cannot reach it right now; SYS002: the organisation’s verified facts could not be read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Re-check the tax connection", "tags": [ "tax-connection" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/i/v1/tax-connection/transport-key": { "get": { "description": "`tax_connection.read`; users only. This mode’s current public key for encrypting a signing key file in the browser before it is uploaded, and the binding the encrypted envelope must carry.", "operationId": "getTaxConnectionTransportKey", "parameters": [], "responses": { "200": { "description": "The public key and binding.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/invoice.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/invoice.TransportKeyViewDto" } } } } } }, "400": { "description": "VAL001: a query parameter was sent (none is accepted).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (wrong plane or no mode), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no `tax_connection.read`), AUTH020 (no organisation), AUTH018 (users only; API keys are refused).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Rate limit: the per-organisation tax-connection bucket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/invoice.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get the key-upload encryption key", "tags": [ "tax-connection" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/n/v1/webhook-deliveries": { "get": { "description": "Only deliveries of types the caller’s own capabilities could subscribe to.", "operationId": "listWebhookDeliveries", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "integer" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "endpointId", "required": false, "in": "query", "schema": { "format": "uuid", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "pending", "delivering", "retrying", "delivered", "failed" ] } }, { "name": "type", "required": false, "in": "query", "schema": { "example": "invoice.signed", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/notification.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/notification.WebhookDeliveryDto" } } } } } } }, "400": { "description": "A filter or the paging is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no webhook.delivery.read).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List webhook deliveries (by endpoint, status or type)", "tags": [ "WebhookDeliveries", "webhooks" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/n/v1/webhook-deliveries/{id}": { "get": { "operationId": "getWebhookDelivery", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/notification.WebhookDeliveryDetailDto" } } } } } }, "400": { "description": "`id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no webhook.delivery.read).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "No such delivery in the caller’s organisation and mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get a webhook delivery and its attempt log", "tags": [ "WebhookDeliveries", "webhooks" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/n/v1/webhook-deliveries/{id}/redeliver": { "post": { "description": "The stored bytes, to the endpoint’s current URL and secret. Appends an attempt; never rewrites one; never charged again.", "operationId": "redeliverWebhookDelivery", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/notification.WebhookDeliveryDto" } } } } } }, "400": { "description": "`id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no webhook.delivery.redeliver).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "No such delivery in the caller’s organisation and mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "The delivery is still in progress, or its endpoint is disabled or deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ004" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.write.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Redeliver a webhook delivery (one more attempt)", "tags": [ "WebhookDeliveries", "webhooks" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/n/v1/webhook-endpoints": { "get": { "description": "Never a secret, sealed or not, and never a capability snapshot.", "operationId": "listWebhookEndpoints", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/notification.WebhookEndpointDto" } } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no webhook.endpoint.read).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List the webhook endpoints of the caller’s organisation and mode", "tags": [ "WebhookEndpoints", "webhooks" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "post": { "description": "The endpoint belongs to the organisation and MODE of the caller’s token. Each pattern is stored with the capabilities the caller holds, and delivers only the types those read.", "operationId": "createWebhookEndpoint", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification.CreateWebhookEndpointDto" } } } }, "responses": { "201": { "description": "The endpoint and its `whsec_…` secret — no route returns the secret again.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/notification.WebhookEndpointSecretDto" } } } } } }, "400": { "description": "Body invalid; the URL is not a public https URL on the default port; a pattern is malformed or matches no catalogue type.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no webhook.endpoint.create), AUTH018 (an API key: endpoints are managed by a signed-in member); or a pattern names events the caller may not read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "The organisation already has 16 endpoints in this mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ004" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.write.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Create a webhook endpoint (its signing secret is shown once)", "tags": [ "WebhookEndpoints", "webhooks" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/n/v1/webhook-endpoints/{id}": { "get": { "operationId": "getWebhookEndpoint", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/notification.WebhookEndpointDto" } } } } } }, "400": { "description": "`id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no webhook.endpoint.read).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "No such endpoint in the caller’s organisation and mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get a webhook endpoint (never its secret)", "tags": [ "WebhookEndpoints", "webhooks" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] }, "patch": { "description": "New patterns take the editor’s capability snapshot. `enabled: false` stops every open delivery of the endpoint; `enabled: true` clears its failure run.", "operationId": "updateWebhookEndpoint", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification.UpdateWebhookEndpointDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/notification.WebhookEndpointDto" } } } } } }, "400": { "description": "Body invalid or empty; the URL or a pattern is refused as on create.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no webhook.endpoint.update), AUTH018 (an API key: endpoints are managed by a signed-in member); or a pattern names events the caller may not read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "No such endpoint in the caller’s organisation and mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.write.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Update a webhook endpoint: URL, description or patterns; enable or disable it", "tags": [ "WebhookEndpoints", "webhooks" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] }, "delete": { "description": "Its open deliveries fail `endpoint_disabled`; its delivery log stays readable.", "operationId": "deleteWebhookEndpoint", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/notification.DeletedWebhookEndpointDto" } } } } } }, "400": { "description": "`id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no webhook.endpoint.delete), AUTH018 (an API key: endpoints are managed by a signed-in member).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "No such endpoint in the caller’s organisation and mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.write.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Delete a webhook endpoint", "tags": [ "WebhookEndpoints", "webhooks" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/n/v1/webhook-endpoints/{id}/rotate-secret": { "post": { "description": "During the overlap every request carries two `v1=` signatures, one per secret, so a receiver can switch without downtime.", "operationId": "rotateWebhookEndpointSecret", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification.RotateWebhookSecretDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/notification.WebhookEndpointSecretDto" } } } } } }, "400": { "description": "`overlapSeconds` outside 0–604800, or `id` not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no webhook.endpoint.rotate_secret), AUTH018 (an API key: endpoints are managed by a signed-in member).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "No such endpoint in the caller’s organisation and mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.write.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Rotate a webhook endpoint’s signing secret (shown once), with an overlap window", "tags": [ "WebhookEndpoints", "webhooks" ], "x-accepts-principals": [ "user" ], "security": [ { "bearer": [] } ] } }, "/n/v1/webhook-endpoints/{id}/test": { "post": { "description": "One delivery, `\"test\": true`, attempted once, never charged. A sample may be of any catalogue type the caller may read, whatever the endpoint subscribes to.", "operationId": "testWebhookEndpoint", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification.TestWebhookEndpointDto" } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/notification.WebhookTestResultDto" } } } } } }, "400": { "description": "`type` is not a catalogue type.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no webhook.endpoint.test); or the caller may not read the type asked for.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "No such endpoint in the caller’s organisation and mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.write.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Send a test ping, or a sample of one event type, to a webhook endpoint", "tags": [ "WebhookEndpoints", "webhooks" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/n/v1/webhook-event-types": { "get": { "description": "The webhook event catalogue: type, version, family, scope, status and the capability a subscription needs. `subscribable` says whether the caller holds it.", "operationId": "listWebhookEventTypes", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/notification.WebhookEventTypeDto" } } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List webhook event types, with whether the caller can subscribe to each", "tags": [ "WebhookEventTypes", "webhooks" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/n/v1/webhook-events": { "get": { "description": "The events of the caller’s mode plus the organisation-scoped ones, each with its public `data`; only types the caller may read.", "operationId": "listWebhookEvents", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "integer" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "type", "required": false, "in": "query", "schema": { "example": "invoice.signed", "type": "string" } }, { "name": "from", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } }, { "name": "to", "required": false, "in": "query", "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/notification.ApiPaginationMetaDto" } } } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/notification.WebhookEventDto" } } } } } } }, "400": { "description": "A filter, the range (at most 31 days) or the paging is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no webhook.delivery.read).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "List logged webhook events (last 30 days)", "tags": [ "WebhookEvents", "webhooks" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/n/v1/webhook-events/{id}": { "get": { "operationId": "getWebhookEvent", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/notification.WebhookEventDto" } } } } } }, "400": { "description": "`id` is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no webhook.delivery.read).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "No such event in the caller’s organisation and mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Get a logged webhook event", "tags": [ "WebhookEvents", "webhooks" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } }, "/n/v1/webhook-events/{id}/redeliver": { "post": { "description": "Also to an endpoint that did not receive it when it happened (disabled, or not subscribed). Never to an endpoint of a mode the event’s scope does not reach.", "operationId": "redeliverWebhookEvent", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification.RedeliverWebhookEventDto" } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/notification.ApiSuccessMetaDto" }, "data": { "$ref": "#/components/schemas/notification.WebhookDeliveryDto" } } } } } }, "400": { "description": "`endpointId` is not one of the caller’s endpoints in this mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "VAL001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "401": { "description": "AUTH004 (no token), AUTH003 (invalid, or a platform-plane token), AUTH002, AUTH006, AUTH011.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH003" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "403": { "description": "AUTH019 (no webhook.delivery.redeliver).", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "AUTH019" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "404": { "description": "No such event in the caller’s organisation and mode.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "RES001" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "409": { "description": "The endpoint is disabled or deleted, the event’s scope does not reach it, or the delivery is in progress.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "BIZ004" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "429": { "description": "Bucket n.write.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS005" } } } ] }, "data": { "nullable": true, "example": null } } } } } }, "503": { "description": "Webhooks are not enabled on this deployment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "allOf": [ { "$ref": "#/components/schemas/notification.ApiErrorMetaDto" }, { "type": "object", "properties": { "errorCode": { "example": "SYS001" } } } ] }, "data": { "nullable": true, "example": null } } } } } } }, "summary": "Replay a logged webhook event to one endpoint", "tags": [ "WebhookEvents", "webhooks" ], "x-accepts-principals": [ "user", "api_key" ], "security": [ { "bearer": [] }, { "apiKey": [] } ] } } }, "components": { "schemas": { "auth.AcceptInvitationDto": { "type": "object", "properties": { "invitationCode": { "type": "string", "example": "K7M2Q9XA", "minLength": 8, "maxLength": 8, "description": "8 Crockford base32 characters; case, spaces and hyphens are ignored" } }, "required": [ "invitationCode" ] }, "auth.AcceptInvitationResponseDto": { "type": "object", "properties": { "organization": { "$ref": "#/components/schemas/auth.OrgSummaryResponseDto" }, "membership": { "$ref": "#/components/schemas/auth.MembershipSummaryResponseDto" } }, "required": [ "organization", "membership" ] }, "auth.AddressDto": { "type": "object", "properties": { "line1": { "type": "string", "example": "12 Marina Road", "minLength": 1, "maxLength": 200 }, "line2": { "type": "string", "minLength": 1, "maxLength": 200 }, "city": { "type": "string", "example": "Lagos", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "example": "Lagos State", "minLength": 1, "maxLength": 100 }, "postalCode": { "type": "string", "example": "100001", "minLength": 1, "maxLength": 20 }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "example": "NG" } }, "required": [ "line1", "city", "state", "country" ] }, "auth.AddressResponseDto": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string", "nullable": true }, "city": { "type": "string" }, "state": { "type": "string" }, "postalCode": { "type": "string", "nullable": true }, "country": { "type": "string", "example": "NG" } }, "required": [ "line1", "city", "state", "country" ] }, "auth.ApiKeyPermissionsResponseDto": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "string" } }, "grantable": { "description": "The capabilities the caller may grant this key: those an API key can hold that the caller also holds.", "type": "array", "items": { "type": "string" } } }, "required": [ "capabilities", "grantable" ] }, "auth.ApiKeyResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "publicId": { "type": "string", "example": "abcdefghijklmnop", "description": "16 base32 characters; public, used for lookup." }, "displayKey": { "type": "string", "example": "sk_live_abcdefghijklmnop_…wxyz" }, "capabilities": { "example": [ "organization.read" ], "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "rotating", "revoked", "expired" ] }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "validUntil": { "type": "string", "format": "date-time", "nullable": true, "description": "End of the rotation grace." }, "rotatedToKeyId": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string", "format": "uuid", "description": "User who created the key." }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Written at most once a minute." } }, "required": [ "id", "name", "mode", "publicId", "displayKey", "capabilities", "status", "expiresAt", "validUntil", "rotatedToKeyId", "createdAt", "createdBy", "lastUsedAt" ] }, "auth.ApiPaginationMetaDto": { "type": "object", "properties": { "total": { "type": "number", "example": 137, "minimum": 0 }, "page": { "type": "number", "example": 1, "minimum": 1, "description": "1-based page number." }, "pageSize": { "type": "number", "example": 20, "description": "Items per page (the `limit` query parameter)." }, "totalPages": { "type": "number", "example": 7, "minimum": 0, "description": "`ceil(total / pageSize)`; an empty set is 0 pages." }, "hasNext": { "type": "boolean", "example": true }, "hasPrevious": { "type": "boolean", "example": false }, "nextPage": { "type": "string" }, "previousPage": { "type": "string" }, "currentPage": { "type": "string" } }, "required": [ "total", "page", "pageSize", "totalPages", "hasNext", "hasPrevious" ] }, "auth.ApiSuccessMetaDto": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 200 }, "success": { "type": "boolean", "enum": [ true ], "example": true }, "message": { "type": "string", "example": "Success", "description": "Copy for humans. Never branch on it." }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "maxItems": 0, "example": [] }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-29T10:00:00.000Z" }, "requestId": { "type": "string", "description": "This service’s request id (also the `x-request-id` header) — quote it in a bug report." }, "pagination": { "description": "Present on list responses.", "allOf": [ { "$ref": "#/components/schemas/auth.ApiPaginationMetaDto" } ] } }, "required": [ "statusCode", "success", "message", "errors", "timestamp", "requestId" ] }, "auth.AvailableCapabilitiesResponseDto": { "type": "object", "properties": { "tenant": { "type": "array", "items": { "$ref": "#/components/schemas/auth.CapabilityInfoResponseDto" } }, "apiKeyGrantable": { "type": "array", "items": { "$ref": "#/components/schemas/auth.CapabilityInfoResponseDto" } } }, "required": [ "tenant", "apiKeyGrantable" ] }, "auth.CapabilityInfoResponseDto": { "type": "object", "properties": { "key": { "type": "string", "example": "organization.read" }, "label": { "type": "string", "example": "View organisation" }, "group": { "type": "string", "enum": [ "organization", "team", "roles", "api_keys", "billing", "webhooks", "audit", "invoicing", "parties", "tax_connection" ] }, "service": { "type": "string", "enum": [ "auth", "billing", "notification", "worker", "invoice" ], "description": "The service whose routes enforce it." }, "sensitivity": { "type": "string", "enum": [ "L", "M", "H", "C" ], "description": "Low, medium, high, critical." }, "stepUp": { "type": "string", "enum": [ "always", "live", "never" ], "description": "Whether its routes need a recent second factor (always, or for live targets)." }, "charged": { "type": "boolean", "description": "Its routes spend credits." }, "customRoleGrantable": { "type": "boolean", "description": "A custom role may hold it (false for the OWNER-only names)." } }, "required": [ "key", "label", "group", "service", "sensitivity", "stepUp", "charged", "customRoleGrantable" ] }, "auth.CreateApiKeyDto": { "type": "object", "properties": { "name": { "type": "string", "example": "ERP integration", "minLength": 1, "maxLength": 100 }, "mode": { "type": "string", "description": "Fixed for the life of the key: sk_test_ or sk_live_", "example": "sandbox", "enum": [ "sandbox", "live" ] }, "preset": { "type": "string", "description": "Default read_only", "enum": [ "read_only", "invoicing", "full_integration" ] }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "organization.read", "billing.account.read", "billing.usage.read", "billing.ledger.read", "billing.statement.read", "billing.payment.read", "billing.subscription.read", "webhook.endpoint.read", "webhook.endpoint.test", "webhook.delivery.read", "webhook.delivery.redeliver", "invoice.read", "invoice.stats.read", "invoice.create", "invoice.update_draft", "invoice.delete_draft", "invoice.finalise", "invoice.validate", "invoice.submit", "invoice.retry", "invoice.query_status", "invoice.cancel", "invoice.record_payment", "invoice.send_to_buyer", "invoice.download_pdf", "invoice.download_authority_copy", "invoice.reopen", "invoice.share", "invoice.inbound.read", "reference.read", "tax_id.lookup", "buyer.read", "buyer.create", "buyer.update", "buyer.delete", "buyer.verify_tax_id", "item.read", "item.create", "item.update", "item.archive", "seller.read", "tax_connection.read" ] } }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO-8601 instant with an offset, more than 1 hour and at most 2 years from now" } }, "required": [ "name", "mode" ] }, "auth.CreateInvitationDto": { "type": "object", "properties": { "email": { "type": "string", "example": "ada@acme.ng", "format": "email", "maxLength": 254 }, "fullName": { "type": "string", "example": "Ada Obi", "minLength": 2, "maxLength": 255 }, "roleId": { "type": "string", "description": "A system role other than OWNER, ranked ≤ the inviter; default MEMBER.", "format": "uuid" }, "message": { "type": "string", "description": "Included in the invitation email.", "minLength": 1, "maxLength": 500 } }, "required": [ "email", "fullName" ] }, "auth.CreatedApiKeyResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "publicId": { "type": "string", "example": "abcdefghijklmnop", "description": "16 base32 characters; public, used for lookup." }, "displayKey": { "type": "string", "example": "sk_live_abcdefghijklmnop_…wxyz" }, "capabilities": { "example": [ "organization.read" ], "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "rotating", "revoked", "expired" ] }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "validUntil": { "type": "string", "format": "date-time", "nullable": true, "description": "End of the rotation grace." }, "rotatedToKeyId": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string", "format": "uuid", "description": "User who created the key." }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Written at most once a minute." }, "key": { "type": "string", "description": "sk_{test|live}__. Shown once; store it now." } }, "required": [ "id", "name", "mode", "publicId", "displayKey", "capabilities", "status", "expiresAt", "validUntil", "rotatedToKeyId", "createdAt", "createdBy", "lastUsedAt", "key" ] }, "auth.InvitationPreviewResponseDto": { "type": "object", "properties": { "organizationName": { "type": "string" }, "role": { "$ref": "#/components/schemas/auth.RoleKeyLabelResponseDto" }, "inviterName": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "emailHasAccount": { "type": "boolean", "description": "Whether the invitee should sign in (true) or sign up (false)." } }, "required": [ "organizationName", "role", "inviterName", "expiresAt", "emailHasAccount" ] }, "auth.InvitationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "fullName": { "type": "string" }, "role": { "$ref": "#/components/schemas/auth.RoleRefResponseDto" }, "status": { "type": "string", "enum": [ "pending", "accepted", "withdrawn", "expired" ], "description": "`expired` is derived when `expiresAt` has passed." }, "expiresAt": { "type": "string", "format": "date-time" }, "invitedBy": { "$ref": "#/components/schemas/auth.InviterResponseDto" }, "createdAt": { "type": "string", "format": "date-time" }, "resentCount": { "type": "number", "minimum": 0, "maximum": 5 } }, "required": [ "id", "email", "fullName", "role", "status", "expiresAt", "invitedBy", "createdAt", "resentCount" ] }, "auth.InvitationWithdrawnResponseDto": { "type": "object", "properties": { "withdrawn": { "type": "boolean", "enum": [ true ] } }, "required": [ "withdrawn" ] }, "auth.InviterResponseDto": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "userId", "name" ] }, "auth.LeftOrganizationResponseDto": { "type": "object", "properties": { "left": { "type": "boolean", "enum": [ true ] } }, "required": [ "left" ] }, "auth.MemberRemovedResponseDto": { "type": "object", "properties": { "removed": { "type": "boolean", "enum": [ true ] } }, "required": [ "removed" ] }, "auth.MemberResponseDto": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "membershipId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "role": { "$ref": "#/components/schemas/auth.RoleRefResponseDto" }, "status": { "type": "string", "enum": [ "active", "suspended", "removed" ] }, "joinedAt": { "type": "string", "format": "date-time", "nullable": true }, "twoFactorEnabled": { "type": "boolean" } }, "required": [ "userId", "membershipId", "email", "firstName", "lastName", "role", "status", "joinedAt", "twoFactorEnabled" ] }, "auth.MembershipSummaryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "$ref": "#/components/schemas/auth.RoleRefResponseDto" }, "capabilities": { "example": [ "organization.read" ], "type": "array", "items": { "type": "string" } } }, "required": [ "id", "role", "capabilities" ] }, "auth.MyOrganizationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "legalName": { "type": "string", "nullable": true }, "role": { "$ref": "#/components/schemas/auth.RoleRefResponseDto" }, "membershipStatus": { "type": "string", "enum": [ "active", "suspended", "removed" ] }, "isDefault": { "type": "boolean" }, "liveStatus": { "type": "string", "enum": [ "not_requested", "pending_review", "approved", "rejected", "revoked" ] }, "current": { "type": "boolean", "description": "True for the organisation of the current session." } }, "required": [ "id", "name", "legalName", "role", "membershipStatus", "isDefault", "liveStatus", "current" ] }, "auth.OrgSummaryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "legalName": { "type": "string", "nullable": true, "description": "The tax authority’s name for the TIN, once verified." }, "tinStatus": { "type": "string", "enum": [ "unverified", "pending", "verified", "failed", "unavailable" ] }, "liveStatus": { "type": "string", "enum": [ "not_requested", "pending_review", "approved", "rejected", "revoked" ] }, "country": { "type": "string", "example": "NG" }, "logoUrl": { "type": "string", "nullable": true, "description": "Public URL of the confirmed logo, null when unset." } }, "required": [ "id", "name", "legalName", "tinStatus", "liveStatus", "country", "logoUrl" ] }, "auth.OrganizationProfileResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "legalName": { "type": "string", "nullable": true }, "tin": { "type": "string", "nullable": true, "description": "Normalised TIN, set only by a verification." }, "tinStatus": { "type": "string", "enum": [ "unverified", "pending", "verified", "failed", "unavailable" ] }, "tinVerifiedAt": { "type": "string", "format": "date-time", "nullable": true }, "country": { "type": "string", "example": "NG" }, "contactEmail": { "type": "string", "format": "email", "nullable": true }, "contactPhone": { "type": "string", "nullable": true, "example": "+2348012345678" }, "phoneVerified": { "type": "boolean" }, "website": { "type": "string", "nullable": true }, "address": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/auth.AddressResponseDto" } ] }, "logoUrl": { "type": "string", "nullable": true, "description": "Public URL of the organisation logo, or null when none is set." }, "onboardingCompletedAt": { "type": "string", "format": "date-time", "nullable": true }, "liveStatus": { "type": "string", "enum": [ "not_requested", "pending_review", "approved", "rejected", "revoked" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "legalName", "tin", "tinStatus", "tinVerifiedAt", "country", "contactEmail", "contactPhone", "phoneVerified", "website", "address", "logoUrl", "onboardingCompletedAt", "liveStatus", "createdAt" ] }, "auth.OwnershipPartyResponseDto": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "OWNER", "ADMIN", "ACCOUNTANT", "MEMBER", "DEVELOPER", "VIEWER" ] } }, "required": [ "userId", "role" ] }, "auth.OwnershipTransferDto": { "type": "object", "properties": { "toUserId": { "type": "string", "description": "An active member with a verified email, not the caller.", "format": "uuid" }, "password": { "type": "string", "format": "password", "minLength": 1, "maxLength": 128 }, "code": { "type": "string", "description": "Required when the caller has TOTP: a TOTP or recovery code", "example": "104829" }, "retainOwnership": { "type": "boolean", "description": "Keep OWNER as well (default false: the caller becomes ADMIN)." } }, "required": [ "toUserId", "password" ] }, "auth.OwnershipTransferResponseDto": { "type": "object", "properties": { "from": { "description": "The previous owner and the role they now hold.", "allOf": [ { "$ref": "#/components/schemas/auth.OwnershipPartyResponseDto" } ] }, "to": { "description": "The new owner (`role` is always OWNER).", "allOf": [ { "$ref": "#/components/schemas/auth.OwnershipPartyResponseDto" } ] } }, "required": [ "from", "to" ] }, "auth.RoleKeyLabelResponseDto": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "OWNER", "ADMIN", "ACCOUNTANT", "MEMBER", "DEVELOPER", "VIEWER" ] }, "label": { "type": "string", "example": "Owner" } }, "required": [ "key", "label" ] }, "auth.RoleRefResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "enum": [ "OWNER", "ADMIN", "ACCOUNTANT", "MEMBER", "DEVELOPER", "VIEWER" ] }, "label": { "type": "string", "example": "Owner" } }, "required": [ "id", "key", "label" ] }, "auth.RoleResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "enum": [ "OWNER", "ADMIN", "ACCOUNTANT", "MEMBER", "DEVELOPER", "VIEWER" ] }, "label": { "type": "string" }, "rank": { "type": "number", "minimum": 1, "maximum": 3, "description": "OWNER 3 > ADMIN 2 > every other role 1" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "isSystem": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "key", "label", "rank", "capabilities", "isSystem" ] }, "auth.RotateApiKeyDto": { "type": "object", "properties": { "gracePeriodSeconds": { "type": "number", "description": "Seconds the old key keeps working after the rotation, from 0 to 604800 (7 days). Defaults to the configured grace period (86400 seconds, 24 hours, by default).", "minimum": 0, "maximum": 604800 } } }, "auth.RotatedApiKeyResponseDto": { "type": "object", "properties": { "previous": { "description": "The old key, now `rotating` until `validUntil`.", "allOf": [ { "$ref": "#/components/schemas/auth.ApiKeyResponseDto" } ] }, "current": { "description": "The new key, with its plaintext `key` shown in this response only.", "allOf": [ { "$ref": "#/components/schemas/auth.CreatedApiKeyResponseDto" } ] } }, "required": [ "previous", "current" ] }, "auth.UpdateApiKeyCapabilitiesDto": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "organization.read", "billing.account.read", "billing.usage.read", "billing.ledger.read", "billing.statement.read", "billing.payment.read", "billing.subscription.read", "webhook.endpoint.read", "webhook.endpoint.test", "webhook.delivery.read", "webhook.delivery.redeliver", "invoice.read", "invoice.stats.read", "invoice.create", "invoice.update_draft", "invoice.delete_draft", "invoice.finalise", "invoice.validate", "invoice.submit", "invoice.retry", "invoice.query_status", "invoice.cancel", "invoice.record_payment", "invoice.send_to_buyer", "invoice.download_pdf", "invoice.download_authority_copy", "invoice.reopen", "invoice.share", "invoice.inbound.read", "reference.read", "tax_id.lookup", "buyer.read", "buyer.create", "buyer.update", "buyer.delete", "buyer.verify_tax_id", "item.read", "item.create", "item.update", "item.archive", "seller.read", "tax_connection.read" ] } } }, "required": [ "capabilities" ] }, "auth.UpdateApiKeyDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ] }, "auth.UpdateMemberRoleDto": { "type": "object", "properties": { "roleId": { "type": "string", "description": "A system role id (fixed per role key); OWNER is refused by the service.", "format": "uuid" } }, "required": [ "roleId" ] }, "auth.UpdateMemberStatusDto": { "type": "object", "properties": { "status": { "type": "string", "example": "suspended", "enum": [ "active", "suspended" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "status" ] }, "auth.UpdateOrganizationDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Acme Trading", "minLength": 1, "maxLength": 255 }, "contactEmail": { "type": "string", "example": "accounts@acme.ng", "format": "email", "maxLength": 254 }, "website": { "type": "string", "example": "https://acme.ng", "format": "uri", "maxLength": 255 }, "address": { "$ref": "#/components/schemas/auth.AddressDto" } } }, "auth.UpdatedOrganizationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "legalName": { "type": "string", "nullable": true, "description": "The tax authority’s name for the TIN, once verified." }, "tinStatus": { "type": "string", "enum": [ "unverified", "pending", "verified", "failed", "unavailable" ] }, "liveStatus": { "type": "string", "enum": [ "not_requested", "pending_review", "approved", "rejected", "revoked" ] }, "country": { "type": "string", "example": "NG" }, "logoUrl": { "type": "string", "nullable": true, "description": "Public URL of the confirmed logo, null when unset." }, "contactEmail": { "type": "string", "format": "email", "nullable": true }, "website": { "type": "string", "nullable": true }, "address": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/auth.AddressResponseDto" } ] } }, "required": [ "id", "name", "legalName", "tinStatus", "liveStatus", "country", "logoUrl" ] }, "auth.VerifyInvitationDto": { "type": "object", "properties": { "invitationCode": { "type": "string", "example": "K7M2Q9XA", "minLength": 8, "maxLength": 8, "description": "8 Crockford base32 characters; case, spaces and hyphens are ignored" }, "email": { "type": "string", "format": "email", "maxLength": 254, "example": "ada@example.com" } }, "required": [ "invitationCode", "email" ] }, "billing.AccountStatsDto": { "type": "object", "properties": { "currentBalance": { "type": "integer" }, "lifetimeConsumed": { "type": "integer" }, "lifetimePurchased": { "type": "integer" }, "averageDailyConsumption": { "type": "number", "description": "Credits per day over the last 30 days. A rate, not money: may be fractional." }, "daysUntilDepleted": { "type": "integer", "nullable": true, "description": "At the current rate; null when nothing was consumed." }, "isLowBalance": { "type": "boolean" } }, "required": [ "currentBalance", "lifetimeConsumed", "lifetimePurchased", "averageDailyConsumption", "daysUntilDepleted", "isLowBalance" ] }, "billing.ActiveSubscriptionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "planCode": { "type": "string", "example": "starter" }, "planName": { "type": "string" }, "planVersion": { "type": "integer", "description": "Catalogue plan version this subscription is priced at." }, "interval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "status": { "type": "string", "enum": [ "pending_payment", "active", "past_due", "cancelled", "expired" ] }, "amountMinor": { "type": "integer", "description": "Integer minor units per period (0 for Free)." }, "currency": { "type": "string", "enum": [ "NGN", "USD" ] }, "monthlyCredits": { "type": "integer" }, "currentPeriodStart": { "type": "string", "format": "date-time", "nullable": true }, "currentPeriodEnd": { "type": "string", "format": "date-time", "nullable": true }, "cancelAtPeriodEnd": { "type": "boolean" }, "pastDueSince": { "type": "string", "format": "date-time", "nullable": true }, "graceEndsAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the grace period after the missed payment ends (pastDueSince plus the configured grace days); null unless past_due." }, "createdAt": { "type": "string", "format": "date-time" }, "window": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/billing.AllocationWindowDto" } ] } }, "required": [ "id", "planCode", "planName", "planVersion", "interval", "status", "amountMinor", "currency", "monthlyCredits", "currentPeriodStart", "currentPeriodEnd", "cancelAtPeriodEnd", "pastDueSince", "graceEndsAt", "createdAt", "window" ] }, "billing.AllocationWindowDto": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "allocated": { "type": "integer", "description": "Credits granted for this window." }, "used": { "type": "integer", "description": "Credits drawn from this window’s lot." } }, "required": [ "start", "end", "allocated", "used" ] }, "billing.ApiErrorMetaDto": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "success": { "type": "boolean", "enum": [ false ], "example": false }, "message": { "type": "string", "example": "Some fields are invalid — please review and try again" }, "errorCode": { "type": "string", "pattern": "^(AUTH|VAL|RES|BIZ|SYS)\\d{3}$", "example": "VAL001", "description": "The machine identity of the refusal — branch on this. Every 5xx is SYS001." }, "errors": { "type": "array", "items": { "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": { "type": "string" } }, "example": [ { "email": "must be an email" } ], "description": "Single-key objects: `{ field-or-code: message }`." }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-29T10:00:00.000Z" }, "requestId": { "type": "string", "description": "This service’s request id (also the `x-request-id` header) — quote it in a bug report." } }, "required": [ "statusCode", "success", "message", "errorCode", "errors", "timestamp", "requestId" ] }, "billing.ApiPaginationMetaDto": { "type": "object", "properties": { "total": { "type": "number", "example": 137, "minimum": 0 }, "page": { "type": "number", "example": 1, "minimum": 1, "description": "1-based page number." }, "pageSize": { "type": "number", "example": 20, "description": "Items per page (the `limit` query parameter)." }, "totalPages": { "type": "number", "example": 7, "minimum": 0, "description": "`ceil(total / pageSize)`; an empty set is 0 pages." }, "hasNext": { "type": "boolean", "example": true }, "hasPrevious": { "type": "boolean", "example": false }, "nextPage": { "type": "string" }, "previousPage": { "type": "string" }, "currentPage": { "type": "string" } }, "required": [ "total", "page", "pageSize", "totalPages", "hasNext", "hasPrevious" ] }, "billing.ApiSuccessMetaDto": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 200 }, "success": { "type": "boolean", "enum": [ true ], "example": true }, "message": { "type": "string", "example": "Success", "description": "Copy for humans. Never branch on it." }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "maxItems": 0, "example": [] }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-29T10:00:00.000Z" }, "requestId": { "type": "string", "description": "This service’s request id (also the `x-request-id` header) — quote it in a bug report." }, "pagination": { "description": "Present on list responses.", "allOf": [ { "$ref": "#/components/schemas/billing.ApiPaginationMetaDto" } ] } }, "required": [ "statusCode", "success", "message", "errors", "timestamp", "requestId" ] }, "billing.AvailablePlanDto": { "type": "object", "properties": { "code": { "type": "string", "example": "starter" }, "name": { "type": "string" }, "description": { "type": "string" }, "currency": { "type": "string", "enum": [ "NGN", "USD" ], "description": "The account’s defaultCurrency." }, "monthlyPrice": { "type": "integer", "description": "Integer minor units." }, "yearlyPrice": { "type": "integer", "nullable": true, "description": "Integer minor units; null when not offered yearly." }, "monthlyCredits": { "type": "integer" }, "yearlyCredits": { "type": "integer" }, "badge": { "type": "string", "nullable": true }, "features": { "type": "array", "items": { "type": "string" } }, "isCurrent": { "type": "boolean" } }, "required": [ "code", "name", "description", "currency", "monthlyPrice", "yearlyPrice", "monthlyCredits", "yearlyCredits", "badge", "features", "isCurrent" ] }, "billing.BalanceBySourceDto": { "type": "object", "properties": { "plan": { "type": "integer", "description": "Plan allocation lots (expire with the plan window)." }, "purchase": { "type": "integer", "description": "Purchased credit-pack lots (never expire)." }, "allowance": { "type": "integer", "description": "Sandbox allowance lots — always 0 on live." }, "adjustment": { "type": "integer", "description": "Operator adjustment lots." } }, "required": [ "plan", "purchase", "allowance", "adjustment" ] }, "billing.BillingAccountDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "defaultCurrency": { "type": "string", "enum": [ "NGN", "USD" ] }, "lowBalanceThreshold": { "type": "integer", "description": "Live low-balance threshold; 0 disables." }, "createdAt": { "type": "string", "format": "date-time" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ], "description": "The ledger `creditBalance` reports." }, "creditBalance": { "type": "integer", "description": "The `available` balance of `mode`." }, "balances": { "$ref": "#/components/schemas/billing.LedgerBalancesDto" } }, "required": [ "id", "organizationId", "defaultCurrency", "lowBalanceThreshold", "createdAt", "mode", "creditBalance", "balances" ] }, "billing.CancelSubscriptionDto": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500, "description": "Why the subscription is being cancelled." } } }, "billing.CheckBalanceDto": { "type": "object", "properties": { "hasSufficientBalance": { "type": "boolean" }, "requestedCredits": { "type": "integer" }, "currentBalance": { "type": "integer" } }, "required": [ "hasSufficientBalance", "requestedCredits", "currentBalance" ] }, "billing.CostCodeUsageDto": { "type": "object", "properties": { "costCode": { "type": "string", "example": "INVOICE_CREATE" }, "label": { "type": "string", "example": "Create invoice" }, "count": { "type": "integer" }, "credits": { "type": "integer", "description": "Credits spent, net of refunds." } }, "required": [ "costCode", "label", "count", "credits" ] }, "billing.CreditCheckoutDto": { "type": "object", "properties": { "paymentId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] }, "checkoutUrl": { "type": "string", "description": "Hosted checkout page. Shown to the payer only; never emailed or logged." }, "amountMinor": { "type": "integer", "description": "Integer minor units." }, "currency": { "type": "string", "enum": [ "NGN", "USD" ] }, "credits": { "type": "integer", "description": "Credits the settled payment grants (credits + bonus)." }, "provider": { "type": "string", "enum": [ "paystack", "stripe" ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "paymentId", "status", "checkoutUrl", "amountMinor", "currency", "credits", "provider", "expiresAt" ] }, "billing.CreditCostDto": { "type": "object", "properties": { "action": { "type": "string", "example": "INVOICE_CREATE", "description": "The cost code producers charge." }, "label": { "type": "string", "example": "Create invoice" }, "description": { "type": "string" }, "credits": { "type": "integer", "example": 1, "description": "Integer credits per unit." }, "version": { "type": "integer", "example": 1, "description": "Catalogue version of this cost code." }, "group": { "type": "string", "enum": [ "nrs", "invoices", "sharing", "buyers_items", "received", "data", "api" ], "example": "invoices", "description": "The price-list section the action is listed under." }, "available": { "type": "boolean", "example": true, "description": "False for an action priced ahead of the feature that charges it: list it as coming, never as chargeable." } }, "required": [ "action", "label", "description", "credits", "version", "group", "available" ] }, "billing.CreditPackageDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The package's stable id (uuidv5 of its code), not a version id." }, "name": { "type": "string" }, "description": { "type": "string" }, "credits": { "type": "integer", "example": 1000 }, "bonusCredits": { "type": "integer", "example": 0 }, "totalCredits": { "type": "integer", "example": 1000, "description": "credits + bonusCredits — what a purchase grants." }, "displayOrder": { "type": "integer" }, "isFeatured": { "type": "boolean" }, "pricing": { "type": "array", "items": { "$ref": "#/components/schemas/billing.PackagePriceDto" } } }, "required": [ "id", "name", "description", "credits", "bonusCredits", "totalCredits", "displayOrder", "isFeatured", "pricing" ] }, "billing.LedgerBalanceDto": { "type": "object", "properties": { "available": { "type": "integer", "description": "Spendable now: Σ remaining over unexpired lots." }, "held": { "type": "integer", "description": "Reserved by open holds." }, "nextExpiry": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/billing.NextExpiryDto" } ] }, "bySource": { "description": "Live ledger only: `available` by lot source.", "allOf": [ { "$ref": "#/components/schemas/billing.BalanceBySourceDto" } ] } }, "required": [ "available", "held", "nextExpiry" ] }, "billing.LedgerBalancesDto": { "type": "object", "properties": { "live": { "$ref": "#/components/schemas/billing.LedgerBalanceDto" }, "sandbox": { "$ref": "#/components/schemas/billing.LedgerBalanceDto" } } }, "billing.LedgerEntryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "kind": { "type": "string", "enum": [ "grant_plan", "grant_purchase", "grant_allowance", "grant_adjustment", "charge", "hold", "hold_release", "refund", "clawback", "adjustment_debit", "expiry", "debt_settlement" ] }, "credits": { "type": "integer", "description": "Signed delta: positive for grants/releases/refunds." }, "balanceAfter": { "type": "integer" }, "reference": { "type": "string", "example": "invoice.create:018f2b4c-6a1e-7c3d-9e2f-0a1b2c3d4e5f" }, "costCode": { "type": "string", "nullable": true }, "quantity": { "type": "integer", "nullable": true }, "description": { "type": "string", "nullable": true, "description": "Human label (cost-code label or grant source)." }, "paymentId": { "type": "string", "format": "uuid", "nullable": true }, "holdState": { "type": "string", "enum": [ "held", "captured", "released", "expired" ], "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "mode", "kind", "credits", "balanceAfter", "reference", "costCode", "quantity", "description", "paymentId", "holdState", "createdAt" ] }, "billing.LiveUsageDto": { "type": "object", "properties": { "available": { "type": "integer" }, "held": { "type": "integer" }, "window": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/billing.AllocationWindowDto" } ] } }, "required": [ "available", "held", "window" ] }, "billing.LowBalanceThresholdDto": { "type": "object", "properties": { "threshold": { "type": "integer" }, "armed": { "type": "boolean", "description": "Whether the next downward crossing will notify." } }, "required": [ "threshold", "armed" ] }, "billing.NextExpiryDto": { "type": "object", "properties": { "credits": { "type": "integer", "description": "Credits in the soonest-expiring lot(s)." }, "at": { "type": "string", "format": "date-time" } }, "required": [ "credits", "at" ] }, "billing.PackagePriceDto": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "NGN", "USD" ] }, "amount": { "type": "integer", "example": 1000000, "description": "Integer minor units." } }, "required": [ "currency", "amount" ] }, "billing.PaymentDetailDto": { "type": "object", "properties": { "paymentId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "credit_purchase", "subscription", "renewal" ] }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "expired", "partially_refunded", "refunded", "disputed", "charged_back" ] }, "statusReason": { "type": "string", "nullable": true, "example": "amount_mismatch" }, "provider": { "type": "string", "enum": [ "paystack", "stripe" ] }, "amountMinor": { "type": "integer", "description": "Integer minor units." }, "currency": { "type": "string", "enum": [ "NGN", "USD" ] }, "credits": { "type": "integer", "nullable": true, "description": "Credits a credit purchase grants; null otherwise." }, "refundedMinor": { "type": "integer", "description": "Integer minor units refunded so far." }, "subscriptionId": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "settledAt": { "type": "string", "format": "date-time", "nullable": true }, "checkoutUrl": { "type": "string", "description": "Present only while status is pending; absent otherwise." } }, "required": [ "paymentId", "kind", "status", "statusReason", "provider", "amountMinor", "currency", "credits", "refundedMinor", "subscriptionId", "createdAt", "settledAt" ] }, "billing.PaymentDto": { "type": "object", "properties": { "paymentId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "credit_purchase", "subscription", "renewal" ] }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "expired", "partially_refunded", "refunded", "disputed", "charged_back" ] }, "statusReason": { "type": "string", "nullable": true, "example": "amount_mismatch" }, "provider": { "type": "string", "enum": [ "paystack", "stripe" ] }, "amountMinor": { "type": "integer", "description": "Integer minor units." }, "currency": { "type": "string", "enum": [ "NGN", "USD" ] }, "credits": { "type": "integer", "nullable": true, "description": "Credits a credit purchase grants; null otherwise." }, "refundedMinor": { "type": "integer", "description": "Integer minor units refunded so far." }, "subscriptionId": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "settledAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "paymentId", "kind", "status", "statusReason", "provider", "amountMinor", "currency", "credits", "refundedMinor", "subscriptionId", "createdAt", "settledAt" ] }, "billing.PlanPriceDto": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "NGN", "USD" ] }, "interval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "amount": { "type": "integer", "example": 5000000, "description": "Integer minor units (kobo, cents)." } }, "required": [ "currency", "interval", "amount" ] }, "billing.PlanRolloverDto": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": false, "description": "Whether a month's unused plan credits carry into the next month. False: they expire at the window end." }, "maxMonths": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "example": null, "description": "How many months past its own a credit may be carried; null when disabled." }, "capCredits": { "type": "integer", "nullable": true, "minimum": 1, "example": null, "description": "The most credits carried into one month; null when disabled or uncapped." } }, "required": [ "enabled", "maxMonths", "capCredits" ] }, "billing.PlanVersionInfoDto": { "type": "object", "properties": { "planVersion": { "type": "integer", "example": 1 }, "monthlyCredits": { "type": "integer", "example": 5000 }, "yearlyCredits": { "type": "integer", "example": 60000, "description": "Always 12 × monthlyCredits." }, "yearlyAllocationMode": { "type": "string", "enum": [ "monthly" ], "description": "Yearly plans allocate their credits monthly." }, "rollover": { "$ref": "#/components/schemas/billing.PlanRolloverDto" } }, "required": [ "planVersion", "monthlyCredits", "yearlyCredits", "yearlyAllocationMode", "rollover" ] }, "billing.PlansCatalogueDto": { "type": "object", "properties": { "subscriptionPlans": { "type": "array", "items": { "$ref": "#/components/schemas/billing.SubscriptionPlanDto" } }, "creditPackages": { "type": "array", "items": { "$ref": "#/components/schemas/billing.CreditPackageDto" } } }, "required": [ "subscriptionPlans", "creditPackages" ] }, "billing.PurchaseCreditsDto": { "type": "object", "properties": { "packageId": { "type": "string", "format": "uuid", "description": "The package id listed by GET /plans/packages." }, "currency": { "type": "string", "enum": [ "NGN", "USD" ], "description": "Required; 422 BIZ101 when no provider is routed for it." }, "returnPath": { "type": "string", "description": "Dashboard path to return to after checkout; must be one of the allowed dashboard return paths. Absolute URLs are refused.", "example": "/settings/billing", "pattern": "^\\/(?![/\\\\])(?!.*\\.\\.)[A-Za-z0-9/_.-]{0,199}$" } }, "required": [ "packageId", "currency" ] }, "billing.RenewSubscriptionDto": { "type": "object", "properties": { "returnPath": { "type": "string", "description": "Dashboard path to return to after checkout; must be one of the allowed dashboard return paths. Absolute URLs are refused.", "example": "/settings/billing", "pattern": "^\\/(?![/\\\\])(?!.*\\.\\.)[A-Za-z0-9/_.-]{0,199}$" } } }, "billing.SandboxBalanceDto": { "type": "object", "properties": { "available": { "type": "integer" }, "held": { "type": "integer" } }, "required": [ "available", "held" ] }, "billing.SandboxTopupDto": { "type": "object", "properties": { "credits": { "type": "integer", "minimum": 1, "example": 1000, "description": "Test credits to add to the sandbox ledger, from 1 up to the per-top-up cap (1,000 by default); absent means the cap." } } }, "billing.SandboxTopupResultDto": { "type": "object", "properties": { "entryId": { "type": "string", "format": "uuid", "description": "The `grant_allowance` ledger entry." }, "mode": { "type": "string", "enum": [ "sandbox" ] }, "credits": { "type": "integer" }, "balanceAfter": { "type": "integer", "description": "Sandbox available balance after the grant." }, "reference": { "type": "string", "description": "The entry reference: `grant:sandbox_topup:::`." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Top-up credits expire with the UTC month." }, "topupsUsed": { "type": "integer", "description": "Top-ups used this UTC month, this one included." }, "topupsLimit": { "type": "integer", "description": "Top-ups allowed per UTC month (3 by default)." } }, "required": [ "entryId", "mode", "credits", "balanceAfter", "reference", "expiresAt", "topupsUsed", "topupsLimit" ] }, "billing.SandboxUsageDto": { "type": "object", "properties": { "creditsUsed": { "type": "integer" }, "creditsLimit": { "type": "integer", "description": "This month’s allowance (catalogue `sandbox_monthly`)." }, "creditsRemaining": { "type": "integer" }, "periodStart": { "type": "string", "format": "date-time", "description": "Start of the current UTC month." }, "periodEnd": { "type": "string", "format": "date-time", "description": "Start of the next UTC month (exclusive end)." } }, "required": [ "creditsUsed", "creditsLimit", "creditsRemaining", "periodStart", "periodEnd" ] }, "billing.SetupBillingAccountDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "defaultCurrency": { "type": "string", "enum": [ "NGN", "USD" ] }, "lowBalanceThreshold": { "type": "integer" } }, "required": [ "id", "organizationId", "defaultCurrency", "lowBalanceThreshold" ] }, "billing.SetupDto": { "type": "object", "properties": { "subscription": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/billing.SubscriptionDto" } ] }, "billingAccount": { "$ref": "#/components/schemas/billing.SetupBillingAccountDto" }, "usage": { "$ref": "#/components/schemas/billing.SetupUsageDto" }, "sandboxUsage": { "description": "Absent for a live-mode API key.", "allOf": [ { "$ref": "#/components/schemas/billing.SandboxUsageDto" } ] }, "availablePlans": { "type": "array", "items": { "$ref": "#/components/schemas/billing.AvailablePlanDto" } } }, "required": [ "subscription", "billingAccount", "usage", "availablePlans" ] }, "billing.SetupUsageDto": { "type": "object", "properties": { "live": { "$ref": "#/components/schemas/billing.LiveUsageDto" }, "sandbox": { "$ref": "#/components/schemas/billing.SandboxBalanceDto" } } }, "billing.StatementChargeLineDto": { "type": "object", "properties": { "costCode": { "type": "string", "example": "INVOICE_CREATE" }, "count": { "type": "integer" }, "credits": { "type": "integer" } }, "required": [ "costCode", "count", "credits" ] }, "billing.StatementDto": { "type": "object", "properties": { "period": { "type": "string", "example": "2026-09" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "openingBalance": { "type": "integer" }, "closingBalance": { "type": "integer" }, "grants": { "$ref": "#/components/schemas/billing.StatementGrantsDto" }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/billing.StatementChargeLineDto" } }, "refunds": { "type": "integer" }, "clawbacks": { "type": "integer" }, "expired": { "type": "integer" }, "debtSettled": { "type": "integer" }, "holdsOutstanding": { "type": "integer", "description": "Credits still held at the end of the month." }, "payments": { "description": "Live statements only.", "type": "array", "items": { "$ref": "#/components/schemas/billing.StatementPaymentDto" } } }, "required": [ "period", "mode", "openingBalance", "closingBalance", "grants", "charges", "refunds", "clawbacks", "expired", "debtSettled", "holdsOutstanding" ] }, "billing.StatementGrantsDto": { "type": "object", "properties": { "plan": { "type": "integer" }, "purchase": { "type": "integer" }, "allowance": { "type": "integer" }, "adjustment": { "type": "integer" } }, "required": [ "plan", "purchase", "allowance", "adjustment" ] }, "billing.StatementPaymentDto": { "type": "object", "properties": { "paymentId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "credit_purchase", "subscription", "renewal" ] }, "amountMinor": { "type": "integer", "description": "Integer minor units." }, "currency": { "type": "string", "enum": [ "NGN", "USD" ] }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "expired", "partially_refunded", "refunded", "disputed", "charged_back" ] }, "settledAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "paymentId", "kind", "amountMinor", "currency", "status", "settledAt" ] }, "billing.SubscribeDto": { "type": "object", "properties": { "planCode": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,63}$", "example": "starter" }, "interval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "currency": { "type": "string", "enum": [ "NGN", "USD" ], "description": "Required; 422 BIZ101 when no provider is routed for it." }, "returnPath": { "type": "string", "description": "Dashboard path to return to after checkout; must be one of the allowed dashboard return paths. Absolute URLs are refused.", "example": "/settings/billing", "pattern": "^\\/(?![/\\\\])(?!.*\\.\\.)[A-Za-z0-9/_.-]{0,199}$" } }, "required": [ "planCode", "interval", "currency" ] }, "billing.SubscriptionCheckoutDto": { "type": "object", "properties": { "subscriptionId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending_payment", "active", "past_due", "cancelled", "expired" ], "description": "On subscribe: `pending_payment`. On renew: the renewing subscription’s status (`past_due`)." }, "paymentId": { "type": "string", "format": "uuid" }, "checkoutUrl": { "type": "string", "description": "Hosted checkout page. Shown to the payer only; never emailed." }, "amountMinor": { "type": "integer", "description": "Integer minor units." }, "currency": { "type": "string", "enum": [ "NGN", "USD" ] }, "planCode": { "type": "string", "example": "starter" }, "interval": { "type": "string", "enum": [ "monthly", "yearly" ] } }, "required": [ "subscriptionId", "status", "paymentId", "checkoutUrl", "amountMinor", "currency", "planCode", "interval" ] }, "billing.SubscriptionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "planCode": { "type": "string", "example": "starter" }, "planName": { "type": "string" }, "planVersion": { "type": "integer", "description": "Catalogue plan version this subscription is priced at." }, "interval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "status": { "type": "string", "enum": [ "pending_payment", "active", "past_due", "cancelled", "expired" ] }, "amountMinor": { "type": "integer", "description": "Integer minor units per period (0 for Free)." }, "currency": { "type": "string", "enum": [ "NGN", "USD" ] }, "monthlyCredits": { "type": "integer" }, "currentPeriodStart": { "type": "string", "format": "date-time", "nullable": true }, "currentPeriodEnd": { "type": "string", "format": "date-time", "nullable": true }, "cancelAtPeriodEnd": { "type": "boolean" }, "pastDueSince": { "type": "string", "format": "date-time", "nullable": true }, "graceEndsAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the grace period after the missed payment ends (pastDueSince plus the configured grace days); null unless past_due." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "planCode", "planName", "planVersion", "interval", "status", "amountMinor", "currency", "monthlyCredits", "currentPeriodStart", "currentPeriodEnd", "cancelAtPeriodEnd", "pastDueSince", "graceEndsAt", "createdAt" ] }, "billing.SubscriptionPeriodDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subscriptionId": { "type": "string", "format": "uuid" }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" }, "chargeStatus": { "type": "string", "enum": [ "not_required", "pending", "succeeded", "failed" ] }, "paymentId": { "type": "string", "format": "uuid", "nullable": true }, "amountMinor": { "type": "integer", "description": "Integer minor units." }, "currency": { "type": "string", "enum": [ "NGN", "USD" ] }, "createdAt": { "type": "string", "format": "date-time" }, "settledAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "subscriptionId", "periodStart", "periodEnd", "chargeStatus", "paymentId", "amountMinor", "currency", "createdAt", "settledAt" ] }, "billing.SubscriptionPlanDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable across environments (uuidv5 of the plan code)." }, "code": { "type": "string", "example": "starter" }, "name": { "type": "string" }, "description": { "type": "string" }, "badge": { "type": "string", "nullable": true }, "sortOrder": { "type": "integer" }, "version": { "$ref": "#/components/schemas/billing.PlanVersionInfoDto" }, "pricing": { "type": "array", "items": { "$ref": "#/components/schemas/billing.PlanPriceDto" } } }, "required": [ "id", "code", "name", "description", "badge", "sortOrder", "version", "pricing" ] }, "billing.UpdateLowBalanceThresholdDto": { "type": "object", "properties": { "threshold": { "type": "integer", "minimum": 0, "maximum": 100000000, "example": 100, "description": "Live balance below which one low-balance email is sent per crossing; 0 disables." } }, "required": [ "threshold" ] }, "billing.UsageBucketDto": { "type": "object", "properties": { "bucketStart": { "type": "string", "format": "date-time", "description": "UTC bucket start (ISO week for weekly)." }, "credits": { "type": "integer" }, "count": { "type": "integer" } }, "required": [ "bucketStart", "credits", "count" ] }, "invoice.AccessPointBucketDto": { "type": "object", "properties": { "count": { "type": "number" }, "grossPayableMinor": { "type": "number", "description": "MINOR units, reporting currency." }, "accessPoint": { "type": "string", "nullable": true } }, "required": [ "count", "grossPayableMinor", "accessPoint" ] }, "invoice.AmountBucketDto": { "type": "object", "properties": { "count": { "type": "number" }, "grossPayableMinor": { "type": "number", "description": "MINOR units, reporting currency." } }, "required": [ "count", "grossPayableMinor" ] }, "invoice.AnalyticsTotalsDto": { "type": "object", "properties": { "count": { "type": "number" }, "pricedCount": { "type": "number", "description": "Rows in the reporting currency with a known amount: the base of the sums." }, "grossPayableMinor": { "type": "number" }, "inputVatMinor": { "type": "number" }, "byCurrency": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.CurrencyBucketDto" } } }, "required": [ "count", "pricedCount", "grossPayableMinor", "inputVatMinor", "byCurrency" ] }, "invoice.ApiErrorMetaDto": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "success": { "type": "boolean", "enum": [ false ], "example": false }, "message": { "type": "string", "example": "Some fields are invalid — please review and try again" }, "errorCode": { "type": "string", "pattern": "^(AUTH|VAL|RES|BIZ|SYS)\\d{3}$", "example": "VAL001", "description": "The machine identity of the refusal — branch on this. Every 5xx is SYS001." }, "errors": { "type": "array", "items": { "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": { "type": "string" } }, "example": [ { "email": "must be an email" } ], "description": "Single-key objects: `{ field-or-code: message }`." }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-29T10:00:00.000Z" }, "requestId": { "type": "string", "description": "This service’s request id (also the `x-request-id` header) — quote it in a bug report." } }, "required": [ "statusCode", "success", "message", "errorCode", "errors", "timestamp", "requestId" ] }, "invoice.ApiPaginationMetaDto": { "type": "object", "properties": { "total": { "type": "number", "example": 137, "minimum": 0 }, "page": { "type": "number", "example": 1, "minimum": 1, "description": "1-based page number." }, "pageSize": { "type": "number", "example": 20, "description": "Items per page (the `limit` query parameter)." }, "totalPages": { "type": "number", "example": 7, "minimum": 0, "description": "`ceil(total / pageSize)`; an empty set is 0 pages." }, "hasNext": { "type": "boolean", "example": true }, "hasPrevious": { "type": "boolean", "example": false }, "nextPage": { "type": "string" }, "previousPage": { "type": "string" }, "currentPage": { "type": "string" } }, "required": [ "total", "page", "pageSize", "totalPages", "hasNext", "hasPrevious" ] }, "invoice.ApiSuccessMetaDto": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 200 }, "success": { "type": "boolean", "enum": [ true ], "example": true }, "message": { "type": "string", "example": "Success", "description": "Copy for humans. Never branch on it." }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "maxItems": 0, "example": [] }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-29T10:00:00.000Z" }, "requestId": { "type": "string", "description": "This service’s request id (also the `x-request-id` header) — quote it in a bug report." }, "pagination": { "description": "Present on list responses.", "allOf": [ { "$ref": "#/components/schemas/invoice.ApiPaginationMetaDto" } ] } }, "required": [ "statusCode", "success", "message", "errors", "timestamp", "requestId" ] }, "invoice.AuthorityCopyDto": { "type": "object", "properties": { "authorityReference": { "type": "string", "description": "The IRN." }, "document": { "type": "object", "additionalProperties": true, "description": "The tax authority’s own copy of the document, decrypted, as it returns it." } }, "required": [ "authorityReference", "document" ] }, "invoice.AuthorityIdentifiersDto": { "type": "object", "properties": { "businessId": { "type": "string", "format": "uuid", "description": "The authority business id the tenant believes is theirs." }, "serviceId": { "type": "string", "pattern": "^[A-Za-z0-9]{8}$", "example": "F2D927D9" } } }, "invoice.AuthorityIdentifiersViewDto": { "type": "object", "properties": { "businessId": { "type": "string", "nullable": true }, "serviceId": { "type": "string", "nullable": true }, "entityId": { "type": "string", "nullable": true } }, "required": [ "businessId", "serviceId", "entityId" ] }, "invoice.AuthorityNextActionDto": { "type": "object", "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "steps": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "title", "steps" ] }, "invoice.AuthorityStatusDto": { "type": "object", "properties": { "transmitted": { "type": "boolean" }, "delivered": { "type": "boolean" }, "paymentStatus": { "type": "string", "description": "The payment status the tax authority holds, when it gave one." }, "checkedAt": { "type": "string", "format": "date-time" } }, "required": [ "transmitted", "delivered", "checkedAt" ] }, "invoice.BatchItemResultDto": { "type": "object", "properties": { "invoiceId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "failed" ] }, "submissionId": { "type": "string", "format": "uuid", "description": "When queued." }, "replayed": { "type": "boolean", "description": "When queued: a submission already in flight was returned." }, "errorCode": { "type": "string", "description": "When failed: the error code.", "example": "BIZ201" }, "message": { "type": "string", "description": "When failed." } }, "required": [ "invoiceId", "status" ] }, "invoice.BatchSubmitDto": { "type": "object", "properties": { "invoiceIds": { "minItems": 1, "maxItems": 100, "uniqueItems": true, "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "invoiceIds" ] }, "invoice.BatchSubmitResultDto": { "type": "object", "properties": { "totalQueued": { "type": "integer" }, "totalFailed": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.BatchItemResultDto" } } }, "required": [ "totalQueued", "totalFailed", "results" ] }, "invoice.BulkDeleteBuyersDto": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "ids" ] }, "invoice.BulkDeleteResultDto": { "type": "object", "properties": { "deleted": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "archived": { "description": "Kept as archived because an issued invoice names them.", "type": "array", "items": { "type": "string", "format": "uuid" } }, "notFound": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "deleted", "archived", "notFound" ] }, "invoice.BuyerAddressDto": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "maxLength": 255 }, "line2": { "type": "string", "maxLength": 255 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "maxLength": 100 }, "lga": { "type": "string", "maxLength": 100, "description": "Local government area." }, "postalCode": { "type": "string", "maxLength": 20 }, "country": { "type": "string", "example": "NG", "description": "ISO 3166-1 alpha-2." } }, "required": [ "line1", "city", "country" ] }, "invoice.BuyerDeleteResultDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "deleted", "archived" ], "description": "`archived` when an issued invoice names the buyer, so it is kept." } }, "required": [ "id", "outcome" ] }, "invoice.BuyerNrsCheckDto": { "type": "object", "properties": { "taxId": { "type": "string", "minLength": 1, "maxLength": 32, "example": "33875194-0001" } }, "required": [ "taxId" ] }, "invoice.BuyerReachabilityAnswerDto": { "type": "object", "properties": { "taxId": { "type": "string", "description": "The TIN in the form the tax authority shows it." }, "onNetwork": { "type": "boolean", "nullable": true, "description": "Whether the e-invoicing network reaches the TIN; null when no answer could be had." }, "accessPoint": { "type": "string", "nullable": true }, "businessName": { "type": "string", "nullable": true }, "checkedAt": { "type": "string", "format": "date-time", "nullable": true }, "stale": { "type": "boolean", "description": "The answer is not fresh: an earlier lookup, served because the tax authority could not be asked now." }, "unavailable": { "type": "boolean", "description": "No answer could be had and none is known: `onNetwork`, `accessPoint`, `businessName` and `checkedAt` are null." } }, "required": [ "taxId", "onNetwork", "accessPoint", "businessName", "checkedAt", "stale", "unavailable" ] }, "invoice.BuyerReachabilityViewDto": { "type": "object", "properties": { "onNetwork": { "type": "boolean", "description": "Whether the tax authority’s e-invoicing network reaches the TIN." }, "accessPoint": { "type": "string", "nullable": true, "description": "The access point the buyer receives through, when on the network." }, "businessName": { "type": "string", "nullable": true, "description": "The business name the tax authority holds for the TIN." }, "checkedAt": { "type": "string", "format": "date-time" } }, "required": [ "onNetwork", "accessPoint", "businessName", "checkedAt" ] }, "invoice.BuyerSetupDto": { "type": "object", "properties": { "partyTypes": { "type": "array", "items": { "type": "string", "enum": [ "individual", "company", "partnership", "non_profit", "government" ] } }, "taxIdTypes": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.TaxIdTypeOptionDto" } }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.CountryOptionDto" } } }, "required": [ "partyTypes", "taxIdTypes", "countries" ] }, "invoice.BuyerVerificationRequestedDto": { "type": "object", "properties": { "verificationId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "pending" ] } }, "required": [ "verificationId", "state" ] }, "invoice.BuyerVerificationStatusDto": { "type": "object", "properties": { "verificationId": { "type": "string", "format": "uuid", "nullable": true, "description": "The latest verification; null when none was ever requested." }, "state": { "type": "string", "enum": [ "pending", "verified", "not_found", "name_mismatch", "unavailable" ], "nullable": true }, "taxIdStatus": { "type": "string", "enum": [ "unverified", "pending", "verified", "not_found", "name_mismatch", "unavailable", "valid_off_network", "checking" ] }, "checkedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the latest verification finished; null while pending or never run." }, "registeredName": { "type": "string", "description": "The registered name the TIN check returned; left out when none." } }, "required": [ "verificationId", "state", "taxIdStatus", "checkedAt" ] }, "invoice.BuyerViewDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "legalName": { "type": "string", "nullable": true }, "taxId": { "type": "string", "nullable": true }, "taxIdType": { "type": "string", "enum": [ "tin", "rn", "foreign", "none" ] }, "taxIdStatus": { "type": "string", "enum": [ "unverified", "pending", "verified", "not_found", "name_mismatch", "unavailable", "valid_off_network", "checking" ], "description": "`verified` (found on the tax authority’s e-invoicing network, or confirmed by the TIN check — see `taxIdVerifiedSource`), `valid_off_network` (a valid TIN not on the e-invoicing network; usable), `checking` (the network lookup is being retried), `unverified` (no TIN, or a tax id the lookup cannot check), and the TIN check’s own `pending`, `not_found`, `name_mismatch` and `unavailable`." }, "taxIdVerifiedAt": { "type": "string", "format": "date-time", "nullable": true }, "taxIdVerifiedName": { "type": "string", "nullable": true, "description": "The name the verification returned." }, "taxIdVerifiedSource": { "type": "string", "enum": [ "nrs", "tin_check" ], "nullable": true, "description": "Who verified a `verified` TIN: `nrs` (the e-invoicing network lookup) or `tin_check`; null otherwise." }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true, "description": "E.164." }, "address": { "nullable": true, "description": "Null when no address, or one missing line1, city or country, is recorded.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.PartyAddressDto" } ] }, "partyType": { "type": "string", "nullable": true, "example": "company" }, "businessDescription": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true, "description": "Your own reference for this buyer." }, "nrsReachability": { "nullable": true, "description": "The last e-invoicing network lookup for the buyer’s tax id; null until one answered, and again after the tax identity changes.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.BuyerReachabilityViewDto" } ] }, "tinUsable": { "type": "boolean", "description": "Whether the buyer’s TIN can go on a document. False when it fails the jurisdiction’s format rule or the TIN check found no such taxpayer: invoices to this buyer are then issued as B2C with no buyer TIN." }, "tinProblem": { "type": "string", "enum": [ "format", "not_found" ], "nullable": true, "description": "Why `tinUsable` is false; null when it is true." }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Set when the buyer was archived (kept because an issued invoice names it)." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "legalName", "taxId", "taxIdType", "taxIdStatus", "taxIdVerifiedAt", "taxIdVerifiedName", "taxIdVerifiedSource", "email", "phone", "address", "partyType", "businessDescription", "reference", "nrsReachability", "tinUsable", "tinProblem", "archivedAt", "createdAt", "updatedAt" ] }, "invoice.CancelInvoiceDto": { "type": "object", "properties": { "reason": { "type": "string", "example": "Issued to the wrong buyer", "minLength": 3, "maxLength": 500 } }, "required": [ "reason" ] }, "invoice.ClaimedIdentifiersViewDto": { "type": "object", "properties": { "businessId": { "type": "string", "description": "Left out when not claimed." }, "serviceId": { "type": "string", "description": "Left out when not claimed." } } }, "invoice.CodeListDto": { "type": "object", "properties": { "type": { "type": "string", "example": "tax-categories" }, "version": { "type": "number", "example": 2 }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "`countries`: {code, name}. `services-codes`: {code, description, category}. Any other list: the tax authority’s own item, as it publishes it (free-form)." }, "fetchedAt": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean" } }, "required": [ "type", "version", "items", "fetchedAt", "stale" ] }, "invoice.CodeListIndexDto": { "type": "object", "properties": { "jurisdiction": { "type": "string", "example": "NG", "description": "The organisation’s tax jurisdiction." }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.CodeListSummaryDto" } } }, "required": [ "jurisdiction", "lists" ] }, "invoice.CodeListSummaryDto": { "type": "object", "properties": { "type": { "type": "string", "example": "tax-categories" }, "version": { "type": "number", "nullable": true, "example": 2 }, "itemCount": { "type": "number", "example": 27 }, "fetchedAt": { "type": "string", "nullable": true, "format": "date-time" }, "stale": { "type": "boolean", "description": "Older than the authority gateway’s 48 h stale window, or not stored yet." } }, "required": [ "type", "itemCount", "stale" ] }, "invoice.ConnectDto": { "type": "object", "properties": { "taxId": { "type": "string", "deprecated": true, "description": "Refused (400 VAL001): the tax number is the organisation’s verified TIN; change it in the organisation profile." }, "authorityIdentifiers": { "$ref": "#/components/schemas/invoice.AuthorityIdentifiersDto" }, "consent": { "$ref": "#/components/schemas/invoice.ConsentDto" } }, "required": [ "consent" ] }, "invoice.ConnectionFallbackDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test_entity" ] }, "taxId": { "type": "string", "description": "The sandbox test entity’s TIN." }, "serviceId": { "type": "string", "description": "The sandbox test entity’s service id." } }, "required": [ "kind", "taxId", "serviceId" ] }, "invoice.ConnectionKeyDto": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "none", "installed", "platform" ], "description": "Whether a signing key is installed with the access point." }, "certificateFingerprint": { "type": "string", "nullable": true, "description": "SHA-256 of the installed certificate, hex. Nothing else about the key is returned." }, "installedAt": { "type": "string", "format": "date-time", "nullable": true }, "installedBy": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InstalledByDto" } ] }, "previous": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.PreviousKeyDto" } ] } }, "required": [ "state", "certificateFingerprint", "installedAt", "installedBy", "previous" ] }, "invoice.ConnectionNextActionDto": { "type": "object", "properties": { "code": { "type": "string", "example": "install_key" }, "actor": { "type": "string", "enum": [ "taxpayer", "provider", "tenant" ], "description": "Who must act." }, "message": { "type": "string", "description": "Plain-language guidance for the code." } }, "required": [ "code", "actor", "message" ] }, "invoice.ConnectionPrerequisitesViewDto": { "type": "object", "properties": { "taxIdVerified": { "type": "boolean", "description": "The organisation’s tax id is verified." }, "taxIdConnectable": { "type": "boolean", "description": "The verified tax id is in the form the tax authority opens a connection for (Nigeria: the 12-digit TIN `12345678-0001`). False: connecting answers 409 `BIZ218`." }, "jurisdictionSupported": { "type": "boolean", "description": "The organisation’s country is supported." }, "taxpayerEnabled": { "type": "boolean", "nullable": true, "description": "Whether the taxpayer enabled e-invoicing with this access point; null with no connection." } }, "required": [ "taxIdVerified", "taxIdConnectable", "jurisdictionSupported", "taxpayerEnabled" ] }, "invoice.ConnectionViewDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "sandbox", "live" ], "description": "The token’s mode." }, "jurisdiction": { "type": "string", "nullable": true, "example": "NG" }, "kind": { "type": "string", "enum": [ "organization" ] }, "state": { "type": "string", "enum": [ "not_connected", "pending_taxpayer_enablement", "pending_grant_approval", "pending_key", "connected", "suspended", "revoked" ] }, "issuesAs": { "type": "string", "enum": [ "organisation", "test_entity" ], "description": "The identity a submission made now goes out under: `organisation`, or in sandbox `test_entity` until the organisation is connected." }, "fallback": { "nullable": true, "description": "The sandbox test entity while `issuesAs` is `test_entity`; null otherwise and always in live.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.ConnectionFallbackDto" } ] }, "taxId": { "type": "string", "nullable": true, "description": "The organisation’s own verified tax id the connection is for." }, "taxIdType": { "type": "string", "example": "tin" }, "authorityIdentifiers": { "nullable": true, "description": "The identifiers the tax authority reports, shown once a connected grant showed them.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.AuthorityIdentifiersViewDto" } ] }, "claimedIdentifiers": { "nullable": true, "description": "The identifiers sent when connecting; null when none were.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.ClaimedIdentifiersViewDto" } ] }, "nextAction": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.ConnectionNextActionDto" } ] }, "prerequisites": { "$ref": "#/components/schemas/invoice.ConnectionPrerequisitesViewDto" }, "key": { "$ref": "#/components/schemas/invoice.ConnectionKeyDto" }, "authorityNextAction": { "nullable": true, "description": "The tax authority gateway’s own guidance on what must happen next, relayed as the last check showed it; null when nothing is to do, before any check, and with no connection.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.AuthorityNextActionDto" } ] }, "authorityLastCheckedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the gateway last checked the grant with the tax authority." }, "authorityNextCheckAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the gateway will next check the grant; null when not scheduled or unknown." }, "submissionsAllowed": { "type": "boolean", "description": "Whether a live submission would be accepted now." }, "lastCheckedAt": { "type": "string", "format": "date-time", "nullable": true }, "connectedAt": { "type": "string", "format": "date-time", "nullable": true }, "disconnectedAt": { "type": "string", "format": "date-time", "nullable": true }, "history": { "description": "Every tax id the organisation’s grant was connected for in this mode, newest first; at most one open.", "type": "array", "items": { "$ref": "#/components/schemas/invoice.TaxIdentityViewDto" } }, "sharedWith": { "type": "string", "enum": [ "sandbox", "live" ], "nullable": true, "description": "The other mode whose connection shares this grant (disconnecting here then keeps it for that mode); null otherwise." }, "businessProfile": { "type": "object", "additionalProperties": true, "nullable": true, "description": "The business the tax authority knows under this tax id, as the gateway relayed it (free-form, the authority’s fields); null until a check showed one, and with no connection." }, "legalNameMatches": { "type": "boolean", "nullable": true, "description": "Whether that profile’s business name is the organisation’s verified legal name (case, spacing, punctuation and `LTD`/`LIMITED` ignored); null when either is unknown." } }, "required": [ "mode", "jurisdiction", "kind", "state", "issuesAs", "fallback", "taxId", "taxIdType", "authorityIdentifiers", "claimedIdentifiers", "nextAction", "prerequisites", "key", "authorityNextAction", "authorityLastCheckedAt", "authorityNextCheckAt", "submissionsAllowed", "lastCheckedAt", "connectedAt", "disconnectedAt", "history", "sharedWith", "businessProfile", "legalNameMatches" ] }, "invoice.ConsentDto": { "type": "object", "properties": { "accepted": { "type": "boolean", "enum": [ true ], "description": "The tenant accepts Yona as its transmitting tax partner." }, "textVersion": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,32}$", "example": "2026-09-30" } }, "required": [ "accepted", "textVersion" ] }, "invoice.CountryOptionDto": { "type": "object", "properties": { "code": { "type": "string", "example": "NG", "description": "ISO 3166-1 alpha-2, upper case." }, "name": { "type": "string", "example": "Nigeria" } }, "required": [ "code", "name" ] }, "invoice.CreateAndSubmitResultDto": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" }, "submission": { "nullable": true, "description": "The queued submission; null when the submit was refused (the draft is kept).", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.SubmissionViewDto" } ] }, "submitRefusal": { "nullable": true, "description": "Why the submit was refused; null when it was queued.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.SubmitRefusalDto" } ] } }, "required": [ "invoice", "submission", "submitRefusal" ] }, "invoice.CreateBuyerDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "legalName": { "type": "string", "maxLength": 255, "nullable": true }, "taxId": { "type": "string", "maxLength": 64, "nullable": true, "example": "12345678-0001" }, "taxIdType": { "type": "string", "enum": [ "tin", "rn", "foreign", "none" ], "description": "Defaults to `tin` when a taxId is sent; `none` when there is none." }, "email": { "type": "string", "maxLength": 320, "nullable": true }, "phone": { "type": "string", "example": "+2348098765432", "description": "E.164.", "nullable": true }, "address": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.BuyerAddressDto" } ] }, "partyType": { "type": "string", "enum": [ "individual", "company", "partnership", "non_profit", "government" ], "nullable": true }, "businessDescription": { "type": "string", "maxLength": 1000, "nullable": true }, "reference": { "type": "string", "maxLength": 100, "nullable": true, "description": "The tenant’s own reference for this buyer." } }, "required": [ "name" ] }, "invoice.CreateInvoiceDto": { "type": "object", "properties": { "sellerId": { "type": "string", "format": "uuid", "description": "Only the organisation’s own seller id." }, "buyerId": { "type": "string", "format": "uuid" }, "invoiceKind": { "type": "string", "example": "B2B", "description": "A kind of the jurisdiction (Nigeria: B2B, B2C, B2G, G2B)." }, "invoiceNumber": { "type": "string", "example": "INV00042", "description": "Alphanumeric, 1–50; allocated when absent." }, "invoiceType": { "type": "string", "enum": [ "standard" ], "description": "Only `standard`: credit and debit notes are issued against an invoice (cancel, credit-notes, debit-notes)." }, "invoiceDate": { "type": "string", "example": "2026-09-30", "description": "The issue date." }, "issueTime": { "type": "string", "example": "14:30:00" }, "dueDate": { "type": "string", "example": "2026-10-30", "description": "≥ the issue date." }, "currency": { "type": "string", "example": "NGN" }, "lineItems": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "$ref": "#/components/schemas/invoice.InvoiceLineItemDto" } }, "allowanceAmount": { "oneOf": [ { "type": "string", "example": "12.50" }, { "type": "number", "example": 12.5 } ], "example": "0", "description": "Document allowance, major units, ≤ 2 decimals." }, "chargeAmount": { "oneOf": [ { "type": "string", "example": "12.50" }, { "type": "number", "example": 12.5 } ], "example": "0", "description": "Document charge, major units, ≤ 2 decimals." }, "paymentTerms": { "type": "string", "maxLength": 500 }, "notes": { "type": "string", "maxLength": 2000 }, "purchaseOrderReference": { "type": "string", "maxLength": 100 }, "buyerReference": { "type": "string", "maxLength": 100 }, "accountingCost": { "type": "string", "maxLength": 100 } }, "required": [ "invoiceKind", "invoiceDate", "currency", "lineItems" ] }, "invoice.CreateItemDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "Consulting hour" }, "description": { "type": "string", "maxLength": 1000, "nullable": true }, "itemType": { "type": "string", "enum": [ "goods", "service" ], "example": "service" }, "hsnCode": { "type": "string", "pattern": "^[0-9A-Za-z.]{1,20}$", "nullable": true, "example": "8471.30", "description": "Required for goods." }, "serviceCode": { "type": "string", "pattern": "^[0-9A-Za-z.]{1,20}$", "nullable": true, "example": "6201", "description": "Required for services." }, "productCategory": { "type": "string", "minLength": 1, "maxLength": 500, "example": "Machinery" }, "unitCode": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,16}$", "example": "EA" }, "unitPriceMinor": { "type": "string", "pattern": "^\\d{1,18}$", "example": "150050", "description": "Minor units as a decimal string (₦1,500.50 → \"150050\"); at most 10^14 — the same maximum as an invoice line’s unit price." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "NGN" }, "taxCategory": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,64}$", "example": "STANDARD_VAT", "description": "A tax-category id the jurisdiction serves, or a line alias (standard | zero | exempt)." }, "sku": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9._-]+$", "nullable": true, "example": "CONS-HR", "description": "Unique among the organisation’s non-archived items." } }, "required": [ "name", "itemType", "productCategory", "unitCode", "unitPriceMinor", "currency", "taxCategory" ] }, "invoice.CreateShareLinkDto": { "type": "object", "properties": { "expiresInSeconds": { "type": "number", "description": "Lifetime in seconds: 3600 (1 hour) to 2592000 (30 days); default 604800 (7 days).", "minimum": 3600, "maximum": 2592000, "example": 604800 }, "maxViews": { "type": "number", "description": "How many times the link may be opened (1 = open once); absent = unlimited.", "minimum": 1, "maximum": 10000, "example": 1 } } }, "invoice.CreditNoteIssuedDto": { "type": "object", "properties": { "invoice": { "description": "The original invoice as it now stands.", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } ] }, "creditNote": { "description": "The credit note just issued.", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } ] } }, "required": [ "invoice", "creditNote" ] }, "invoice.CreditNoteLineDto": { "type": "object", "properties": { "lineNo": { "type": "number", "example": 1, "description": "the ORIGINAL invoice's line number" }, "quantity": { "oneOf": [ { "type": "string", "example": "12.50" }, { "type": "number", "example": 12.5 } ], "example": "2", "description": "decimal > 0, at most 6 decimals, ≤ what is left of the line" } }, "required": [ "lineNo", "quantity" ] }, "invoice.CreditNotePreviewAnswerDto": { "type": "object", "properties": { "preview": { "$ref": "#/components/schemas/invoice.CreditNotePreviewDto" } }, "required": [ "preview" ] }, "invoice.CreditNotePreviewDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "full", "lines", "amount" ] }, "closing": { "type": "boolean", "description": "The note would credit the invoice in full." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.NotePreviewLineDto" } }, "totals": { "$ref": "#/components/schemas/invoice.NotePreviewTotalsDto" }, "currency": { "type": "string", "example": "NGN" }, "creditedBeforeMinor": { "type": "integer", "description": "Credited before this note. Integer minor units." }, "netReceivableBeforeMinor": { "type": "integer", "description": "Integer minor units." }, "netReceivableAfterMinor": { "type": "integer", "description": "Integer minor units." }, "refundOwedMinor": { "type": "integer", "description": "The refund this note would owe the buyer. Integer minor units." } }, "required": [ "mode", "closing", "lines", "totals", "currency", "creditedBeforeMinor", "netReceivableBeforeMinor", "netReceivableAfterMinor", "refundOwedMinor" ] }, "invoice.CurrencyAmountCountDto": { "type": "object", "properties": { "currency": { "type": "string", "example": "NGN" }, "amountMinor": { "type": "integer", "description": "Integer minor units." }, "count": { "type": "integer" } }, "required": [ "currency", "amountMinor", "count" ] }, "invoice.CurrencyAmountDto": { "type": "object", "properties": { "currency": { "type": "string", "example": "NGN" }, "amountMinor": { "type": "integer", "description": "Integer minor units." } }, "required": [ "currency", "amountMinor" ] }, "invoice.CurrencyBucketDto": { "type": "object", "properties": { "count": { "type": "number" }, "grossPayableMinor": { "type": "number", "description": "MINOR units, reporting currency." }, "currency": { "type": "string" }, "inputVatMinor": { "type": "number", "description": "MINOR units of this currency." } }, "required": [ "count", "grossPayableMinor", "currency", "inputVatMinor" ] }, "invoice.CurrencyTotalDto": { "type": "object", "properties": { "currency": { "type": "string", "example": "NGN" }, "count": { "type": "integer" }, "payableMinor": { "type": "integer", "description": "Integer minor units." } }, "required": [ "currency", "count", "payableMinor" ] }, "invoice.DebitNoteIssuedDto": { "type": "object", "properties": { "invoice": { "description": "The original invoice as it now stands.", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } ] }, "debitNote": { "description": "The debit note just issued.", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } ] } }, "required": [ "invoice", "debitNote" ] }, "invoice.DebitNotePreviewAnswerDto": { "type": "object", "properties": { "preview": { "$ref": "#/components/schemas/invoice.DebitNotePreviewDto" } }, "required": [ "preview" ] }, "invoice.DebitNotePreviewDto": { "type": "object", "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.NotePreviewLineDto" } }, "totals": { "$ref": "#/components/schemas/invoice.NotePreviewTotalsDto" }, "currency": { "type": "string", "example": "NGN" }, "netReceivableBeforeMinor": { "type": "integer", "description": "Integer minor units." }, "netReceivableAfterMinor": { "type": "integer", "description": "Integer minor units." } }, "required": [ "lines", "totals", "currency", "netReceivableBeforeMinor", "netReceivableAfterMinor" ] }, "invoice.DisconnectDto": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } } }, "invoice.DisconnectViewDto": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "revoked" ] }, "disconnectedAt": { "type": "string", "format": "date-time" }, "keyRetainedByAccessPoint": { "type": "boolean", "enum": [ true ], "description": "The access point keeps the key material; it offers no delete." }, "grantKeptFor": { "type": "string", "enum": [ "sandbox", "live" ], "nullable": true, "description": "The other mode whose connection holds the same grant, which was therefore kept and stays connected; null when the grant was revoked." } }, "required": [ "state", "disconnectedAt", "keyRetainedByAccessPoint", "grantKeptFor" ] }, "invoice.DownloadLinkDto": { "type": "object", "properties": { "downloadUrl": { "type": "string", "description": "Presigned GET on the private documents bucket." }, "fileName": { "type": "string", "example": "INV00001.pdf" }, "expiresAt": { "type": "string", "format": "date-time" }, "fileSize": { "type": "number", "description": "Bytes.", "example": 7683 } }, "required": [ "downloadUrl", "fileName", "expiresAt", "fileSize" ] }, "invoice.HsCodeDto": { "type": "object", "properties": { "code": { "type": "string", "example": "9983" }, "description": { "type": "string", "example": "Other professional, technical and business services" }, "category": { "type": "string", "nullable": true, "example": "Services" } }, "required": [ "code", "description" ] }, "invoice.InboundAnalyticsDto": { "type": "object", "properties": { "reportingCurrency": { "type": "string", "nullable": true, "description": "The currency every amount (except `byCurrency`) is in: the filter’s, else the most common." }, "totals": { "$ref": "#/components/schemas/invoice.AnalyticsTotalsDto" }, "byMonth": { "description": "By issue month (else received month), ascending.", "type": "array", "items": { "$ref": "#/components/schemas/invoice.MonthBucketDto" } }, "topSuppliers": { "$ref": "#/components/schemas/invoice.TopSuppliersDto" }, "paymentStatus": { "$ref": "#/components/schemas/invoice.PaymentBreakdownDto" }, "accessPoints": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.AccessPointBucketDto" } }, "averageDaysToPay": { "type": "number", "nullable": true, "description": "Mean days from issue to the last payment over paid invoices that name both; null when none do." }, "averageDaysToPayBasis": { "type": "number" }, "truncated": { "type": "boolean", "description": "More rows matched than analytics reads (100 000): the figures cover the first." }, "taxpayer": { "$ref": "#/components/schemas/invoice.InboundTaxpayerDto" }, "sync": { "$ref": "#/components/schemas/invoice.InboundSyncDto" } }, "required": [ "reportingCurrency", "totals", "byMonth", "topSuppliers", "paymentStatus", "accessPoints", "averageDaysToPay", "averageDaysToPayBasis", "truncated", "taxpayer", "sync" ] }, "invoice.InboundInvoiceDetailDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The gateway’s row id (the `id` of `GET /i/v1/inbound-invoices/{id}`)." }, "irn": { "type": "string", "description": "The SELLER’s IRN: `--`." }, "sellerInvoiceNumber": { "type": "string", "nullable": true, "description": "The document’s number, else parsed from the IRN." }, "sellerIssueDate": { "type": "string", "nullable": true, "description": "Parsed from the IRN (YYYY-MM-DD)." }, "taxpayerTaxId": { "type": "string", "nullable": true, "description": "The organisation’s TIN it was sent to (the authority’s form)." }, "taxpayerRole": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "supplier": { "type": "object", "additionalProperties": true, "nullable": true, "description": "The seller as the tax authority gateway sends it (free-form: business reference, access point, and the document’s party fields)." }, "customer": { "type": "object", "additionalProperties": true, "nullable": true, "description": "The buyer as the tax authority gateway sends it (free-form)." }, "accessPoint": { "type": "string", "nullable": true, "description": "The seller’s access point (`supplier.app_reference`)." }, "currency": { "type": "string", "nullable": true }, "totals": { "type": "object", "additionalProperties": true, "nullable": true, "description": "The totals as the tax authority gateway sends them (free-form)." }, "payableAmountMinor": { "type": "number", "nullable": true, "description": "Payable amount in MINOR units (the gateway’s summary, else the document’s `legal_monetary_total`)." }, "taxAmountMinor": { "type": "number", "nullable": true, "description": "Tax (input VAT) in MINOR units (the gateway’s summary, else the sum of the document’s `tax_total`)." }, "paymentStatus": { "type": "string", "nullable": true, "enum": [ "paid", "unpaid", "partial", "rejected" ], "description": "The authority’s payment status (PENDING → `unpaid`); null until the gateway or the document says." }, "issueDate": { "type": "string", "nullable": true, "description": "YYYY-MM-DD (the document’s, else the IRN’s)." }, "dueDate": { "type": "string", "nullable": true }, "transmissionStatus": { "type": "string", "nullable": true }, "ackStatus": { "type": "string", "nullable": true }, "acknowledgedAt": { "type": "string", "nullable": true }, "documentRef": { "type": "string", "nullable": true }, "receivedAt": { "type": "string", "nullable": true, "description": "When the access point received it." }, "grantId": { "type": "string", "nullable": true, "description": "The authority grant whose window received it (one of the organisation’s own)." }, "sortAt": { "type": "string", "nullable": true, "description": "The gateway’s ordering instant." }, "updatedAt": { "type": "string", "nullable": true, "description": "The gateway’s `updated_at`." }, "supplierName": { "type": "string", "nullable": true }, "supplierTin": { "type": "string", "nullable": true, "description": "The seller’s TIN from the document (unmasked), when the gateway gives it." }, "customerName": { "type": "string", "nullable": true }, "customerTin": { "type": "string", "nullable": true }, "supplierNameSource": { "type": "string", "nullable": true, "description": "Where `supplierName` came from: `nrs`, `document` or `reference`." }, "customerNameSource": { "type": "string", "nullable": true, "description": "Where `customerName` came from: `nrs`, `document` or `reference`." }, "syncedAt": { "type": "string", "description": "When the mirror last confirmed this row with the gateway." }, "confirmedAt": { "type": "string", "nullable": true, "description": "NRS’s receiver-side confirmation time (`raw_payload.confirmed_at`), when given." }, "rawPayload": { "type": "object", "additionalProperties": true, "nullable": true, "description": "NRS’s own record of the invoice as the gateway stored it (free-form)." }, "document": { "type": "object", "additionalProperties": true, "nullable": true, "description": "The decrypted authority copy (parties, lines, totals; free-form, in the authority’s fields); null when the gateway has none (yet) or could not be asked." }, "documentFetchedAt": { "type": "string", "nullable": true, "description": "When the detail (document) was last read from the gateway; null = never." } }, "required": [ "id", "irn", "sellerInvoiceNumber", "sellerIssueDate", "taxpayerTaxId", "taxpayerRole", "source", "supplier", "customer", "accessPoint", "currency", "totals", "payableAmountMinor", "taxAmountMinor", "paymentStatus", "issueDate", "dueDate", "transmissionStatus", "ackStatus", "acknowledgedAt", "documentRef", "receivedAt", "grantId", "sortAt", "updatedAt", "supplierName", "supplierTin", "customerName", "customerTin", "supplierNameSource", "customerNameSource", "syncedAt", "confirmedAt", "rawPayload", "document", "documentFetchedAt" ] }, "invoice.InboundInvoiceViewDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The gateway’s row id (the `id` of `GET /i/v1/inbound-invoices/{id}`)." }, "irn": { "type": "string", "description": "The SELLER’s IRN: `--`." }, "sellerInvoiceNumber": { "type": "string", "nullable": true, "description": "The document’s number, else parsed from the IRN." }, "sellerIssueDate": { "type": "string", "nullable": true, "description": "Parsed from the IRN (YYYY-MM-DD)." }, "taxpayerTaxId": { "type": "string", "nullable": true, "description": "The organisation’s TIN it was sent to (the authority’s form)." }, "taxpayerRole": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "supplier": { "type": "object", "additionalProperties": true, "nullable": true, "description": "The seller as the tax authority gateway sends it (free-form: business reference, access point, and the document’s party fields)." }, "customer": { "type": "object", "additionalProperties": true, "nullable": true, "description": "The buyer as the tax authority gateway sends it (free-form)." }, "accessPoint": { "type": "string", "nullable": true, "description": "The seller’s access point (`supplier.app_reference`)." }, "currency": { "type": "string", "nullable": true }, "totals": { "type": "object", "additionalProperties": true, "nullable": true, "description": "The totals as the tax authority gateway sends them (free-form)." }, "payableAmountMinor": { "type": "number", "nullable": true, "description": "Payable amount in MINOR units (the gateway’s summary, else the document’s `legal_monetary_total`)." }, "taxAmountMinor": { "type": "number", "nullable": true, "description": "Tax (input VAT) in MINOR units (the gateway’s summary, else the sum of the document’s `tax_total`)." }, "paymentStatus": { "type": "string", "nullable": true, "enum": [ "paid", "unpaid", "partial", "rejected" ], "description": "The authority’s payment status (PENDING → `unpaid`); null until the gateway or the document says." }, "issueDate": { "type": "string", "nullable": true, "description": "YYYY-MM-DD (the document’s, else the IRN’s)." }, "dueDate": { "type": "string", "nullable": true }, "transmissionStatus": { "type": "string", "nullable": true }, "ackStatus": { "type": "string", "nullable": true }, "acknowledgedAt": { "type": "string", "nullable": true }, "documentRef": { "type": "string", "nullable": true }, "receivedAt": { "type": "string", "nullable": true, "description": "When the access point received it." }, "grantId": { "type": "string", "nullable": true, "description": "The authority grant whose window received it (one of the organisation’s own)." }, "sortAt": { "type": "string", "nullable": true, "description": "The gateway’s ordering instant." }, "updatedAt": { "type": "string", "nullable": true, "description": "The gateway’s `updated_at`." }, "supplierName": { "type": "string", "nullable": true }, "supplierTin": { "type": "string", "nullable": true, "description": "The seller’s TIN from the document (unmasked), when the gateway gives it." }, "customerName": { "type": "string", "nullable": true }, "customerTin": { "type": "string", "nullable": true }, "supplierNameSource": { "type": "string", "nullable": true, "description": "Where `supplierName` came from: `nrs`, `document` or `reference`." }, "customerNameSource": { "type": "string", "nullable": true, "description": "Where `customerName` came from: `nrs`, `document` or `reference`." }, "syncedAt": { "type": "string", "description": "When the mirror last confirmed this row with the gateway." } }, "required": [ "id", "irn", "sellerInvoiceNumber", "sellerIssueDate", "taxpayerTaxId", "taxpayerRole", "source", "supplier", "customer", "accessPoint", "currency", "totals", "payableAmountMinor", "taxAmountMinor", "paymentStatus", "issueDate", "dueDate", "transmissionStatus", "ackStatus", "acknowledgedAt", "documentRef", "receivedAt", "grantId", "sortAt", "updatedAt", "supplierName", "supplierTin", "customerName", "customerTin", "supplierNameSource", "customerNameSource", "syncedAt" ] }, "invoice.InboundLoadOlderDto": { "type": "object", "properties": { "fetched": { "type": "number", "description": "Rows the page held for this organisation (new or refreshed)." }, "hasMore": { "type": "boolean", "description": "The gateway has another older page." }, "historyExhausted": { "type": "boolean", "nullable": true }, "sync": { "$ref": "#/components/schemas/invoice.InboundSyncDto" } }, "required": [ "fetched", "hasMore", "historyExhausted", "sync" ] }, "invoice.InboundPageDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.InboundInvoiceViewDto" } }, "taxpayer": { "$ref": "#/components/schemas/invoice.InboundTaxpayerDto" }, "sync": { "$ref": "#/components/schemas/invoice.InboundSyncDto" } }, "required": [ "items", "taxpayer", "sync" ] }, "invoice.InboundSyncDto": { "type": "object", "properties": { "lastSyncedAt": { "type": "string", "nullable": true, "description": "The last successful read of the feed’s head; null = never." }, "historyExhausted": { "type": "boolean", "nullable": true, "description": "The gateway has fetched everything the authority holds for these tax ids; null before a first sync." }, "syncing": { "type": "boolean", "description": "A sync is running or queued: the list may grow; poll again." }, "error": { "type": "string", "nullable": true, "description": "The last sync failure (a code, e.g. `unavailable:http_5xx`); the mirror is served as it is." } }, "required": [ "lastSyncedAt", "historyExhausted", "syncing", "error" ] }, "invoice.InboundTaxpayerDto": { "type": "object", "properties": { "taxId": { "type": "string", "nullable": true, "description": "The tax id of the organisation’s live connection in this mode, as stored." }, "connectionState": { "type": "string", "nullable": true, "description": "The connection state in this mode (null: no live connection). Received invoices are shown while the organisation has any tax-identity history or a connected grant." }, "taxIds": { "description": "The organisation’s tax ids in this mode (authority form, deduped, the current connected one first). Empty: nothing is shown.", "type": "array", "items": { "type": "string" } } }, "required": [ "taxId", "connectionState", "taxIds" ] }, "invoice.InstallKeyDto": { "type": "object", "properties": { "envelope": { "type": "string", "description": "JWE compact serialisation (RSA-OAEP-256 key wrap, AES-256-GCM content) of the key file, encrypted in the browser to the key-upload encryption key (`GET /i/v1/tax-connection/transport-key`).", "maxLength": 16384 } }, "required": [ "envelope" ] }, "invoice.InstalledByDto": { "type": "object", "properties": { "type": { "type": "string", "example": "user" }, "id": { "type": "string", "nullable": true } }, "required": [ "type", "id" ] }, "invoice.InvoiceActorDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "api_key", "service", "system" ], "description": "The kind of actor." }, "id": { "type": "string", "nullable": true, "description": "The auth user id for `user`, the API-key id for `api_key`; may be null for `service` and `system`." } }, "required": [ "type", "id" ] }, "invoice.InvoiceAdjustmentDto": { "type": "object", "properties": { "invoiceId": { "type": "string", "format": "uuid" }, "invoiceNumber": { "type": "string", "description": "The linked document’s own number." }, "id": { "type": "string", "format": "uuid", "description": "Same as `invoiceId`." }, "number": { "type": "string", "description": "The number NRS holds once the linked document is registered; its own number before." }, "irn": { "type": "string", "nullable": true, "description": "Its IRN once registered." }, "registeredAt": { "type": "string", "format": "date-time", "nullable": true }, "kind": { "type": "string", "enum": [ "credit_note", "debit_note" ] }, "issueDate": { "type": "string", "format": "date", "example": "2026-09-30" }, "payableMinor": { "type": "integer", "description": "Integer minor units." }, "status": { "type": "string", "enum": [ "draft", "finalised", "queued", "signed", "transmitted", "accepted", "rejected", "failed", "cancellation_pending", "cancelled" ] }, "counts": { "type": "boolean", "description": "False once NRS refused the note (it no longer counts)." }, "closing": { "type": "boolean", "description": "The credit note that credits the invoice in full." }, "refundOwedMinor": { "type": "integer", "nullable": true, "description": "A credit note’s share of the refund owed; null on a debit note. Integer minor units." } }, "required": [ "invoiceId", "invoiceNumber", "id", "number", "irn", "registeredAt", "kind", "issueDate", "payableMinor", "status", "counts", "closing", "refundOwedMinor" ] }, "invoice.InvoiceBuyerDeliveryDto": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "nrs", "email", "none" ], "description": "`nrs`: through the NRS network; `email`: off the network, emailed once registered; `none`: no buyer, or no way to reach them." }, "reason": { "type": "string", "enum": [ "buyer_off_network", "buyer_on_network", "no_buyer", "unknown" ] }, "sentToBuyerAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "channel", "reason", "sentToBuyerAt" ] }, "invoice.InvoiceBuyerSnapshotDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "legalName": { "type": "string", "nullable": true }, "taxId": { "type": "string", "nullable": true }, "taxIdType": { "type": "string", "example": "tin" }, "taxIdStatus": { "type": "string", "enum": [ "unverified", "pending", "verified", "not_found", "name_mismatch", "unavailable", "valid_off_network", "checking" ], "description": "As it stood when the document was finalised (see `buyerVerification` for now)." }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoicePostalAddressDto" } ] }, "partyType": { "type": "string", "nullable": true, "example": "business" }, "partyName": { "type": "string", "description": "The buyer’s name on the document, in capitals: the business name NRS holds, else the verified legal name, else the name entered." }, "nameSource": { "type": "string", "enum": [ "nrs", "tin_check", "entered" ], "description": "Where `partyName` came from." }, "tinProblem": { "type": "string", "enum": [ "format", "not_found" ], "description": "Present only when the buyer’s TIN could not be used (`format`: malformed; `not_found`): why the document was issued without it." } }, "required": [ "id", "name", "legalName", "taxId", "taxIdType", "taxIdStatus", "email", "phone", "address", "partyType", "partyName", "nameSource" ] }, "invoice.InvoiceBuyerVerificationDto": { "type": "object", "properties": { "taxIdStatus": { "type": "string", "enum": [ "unverified", "pending", "verified", "not_found", "name_mismatch", "unavailable", "valid_off_network", "checking" ] }, "taxIdVerifiedSource": { "type": "string", "enum": [ "nrs", "tin_check" ], "nullable": true, "description": "`nrs` (the network lookup) or `tin_check` (the charged check); null unless verified." }, "taxIdVerifiedName": { "type": "string", "nullable": true }, "taxIdVerifiedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "taxIdStatus", "taxIdVerifiedSource", "taxIdVerifiedName", "taxIdVerifiedAt" ] }, "invoice.InvoiceCreditSettlementDto": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "settled", "refund_owed", "partly_refunded", "refunded" ], "description": "`settled`: nothing was paid, the credit settles the debt; otherwise a refund is owed to the buyer." }, "refundOwedMinor": { "type": "integer", "description": "What the seller owes the buyer back. Integer minor units." }, "refundedMinor": { "type": "integer", "description": "What has been recorded as refunded. Integer minor units." }, "refundOutstandingMinor": { "type": "integer", "description": "`refundOwedMinor − refundedMinor`, never below zero. Integer minor units." } }, "required": [ "state", "refundOwedMinor", "refundedMinor", "refundOutstandingMinor" ] }, "invoice.InvoiceDeletedDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invoiceNumber": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "invoiceNumber", "deleted" ] }, "invoice.InvoiceDocumentLinkDto": { "type": "object", "properties": { "invoiceId": { "type": "string", "format": "uuid" }, "invoiceNumber": { "type": "string", "description": "The linked document’s own number." }, "id": { "type": "string", "format": "uuid", "description": "Same as `invoiceId`." }, "number": { "type": "string", "description": "The number NRS holds once the linked document is registered; its own number before." }, "irn": { "type": "string", "nullable": true, "description": "Its IRN once registered." }, "registeredAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "invoiceId", "invoiceNumber", "id", "number", "irn", "registeredAt" ] }, "invoice.InvoiceIssuedAsDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organisation", "test_entity" ], "description": "`organisation`: the organisation’s own connected tax identity; `test_entity`: the sandbox test taxpayer." }, "taxId": { "type": "string", "description": "The tax id the document was issued under." }, "serviceId": { "type": "string", "nullable": true, "description": "The service id the tax authority gave the issuer, when there is one." } }, "required": [ "kind", "taxId", "serviceId" ] }, "invoice.InvoiceLineItemDto": { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid", "description": "A saved item of the organisation: every field of the line left out is filled from the item, and a field sent wins." }, "description": { "type": "string", "example": "Consulting services", "minLength": 1, "maxLength": 500, "description": "Required without an itemId." }, "itemName": { "type": "string", "maxLength": 255 }, "hsnCode": { "type": "string", "example": "1006.30", "description": "HS code (goods)." }, "productCategory": { "type": "string", "description": "The HS description (goods).", "maxLength": 500 }, "isicCode": { "type": "string", "example": "0112", "description": "ISIC code (services); stored as the service code." }, "serviceCategory": { "type": "string", "description": "The ISIC description (services). Stored as the line’s product category; send it or productCategory, not both.", "maxLength": 500 }, "quantity": { "oneOf": [ { "type": "string", "example": "12.50" }, { "type": "number", "example": 12.5 } ], "example": "2.5", "description": "Decimal string (≤ 6 decimals) or number; > 0." }, "unitCode": { "type": "string", "example": "EA", "description": "A unit code of the jurisdiction’s list. Required without an itemId." }, "unitPrice": { "oneOf": [ { "type": "string", "example": "12.50" }, { "type": "number", "example": 12.5 } ], "example": "50000.00", "description": "Major units, decimal string (≤ 4 decimals) or number; ≥ 0. Required without an itemId." }, "discountAmount": { "oneOf": [ { "type": "string", "example": "12.50" }, { "type": "number", "example": 12.5 } ], "example": "0", "description": "Major units, ≤ 2 decimals." }, "feeAmount": { "oneOf": [ { "type": "string", "example": "12.50" }, { "type": "number", "example": 12.5 } ], "example": "0", "description": "Major units, ≤ 2 decimals." }, "taxCategory": { "type": "string", "example": "STANDARD_VAT", "description": "A tax-category code-list id, or a short alias (standard | zero | exempt). Required without an itemId." } }, "required": [ "quantity" ] }, "invoice.InvoiceLineViewDto": { "type": "object", "properties": { "lineNo": { "type": "integer", "example": 1 }, "description": { "type": "string" }, "itemName": { "type": "string", "nullable": true }, "hsnCode": { "type": "string", "nullable": true, "description": "HS code (goods)." }, "productCategory": { "type": "string", "nullable": true }, "serviceCode": { "type": "string", "nullable": true, "description": "ISIC code (services)." }, "unitCode": { "type": "string", "example": "EA" }, "quantity": { "type": "string", "example": "2.000000", "description": "Exact decimal string." }, "unitPrice": { "type": "string", "example": "50000.0000", "description": "Major units, exact decimal string." }, "discountMinor": { "type": "integer", "description": "Integer minor units." }, "feeMinor": { "type": "integer", "description": "Integer minor units." }, "taxCategory": { "type": "string", "example": "STANDARD_VAT" }, "taxRate": { "type": "string", "example": "7.5", "description": "Percent, decimal string." }, "lineNetMinor": { "type": "integer", "description": "Integer minor units." }, "lineTaxMinor": { "type": "integer", "description": "Integer minor units." }, "lineTotalMinor": { "type": "integer", "description": "Integer minor units." }, "itemId": { "type": "string", "format": "uuid", "nullable": true, "description": "The saved item the line was filled from." }, "creditedQuantity": { "type": "string", "nullable": true, "example": "0.000000", "description": "On an invoice: the quantity credit notes have credited (what is left is `quantity − creditedQuantity`). Null on a note." }, "creditsLineNo": { "type": "integer", "nullable": true, "description": "On a credit-note line: the original invoice’s line it credits; null on an amount credit and elsewhere." } }, "required": [ "lineNo", "description", "itemName", "hsnCode", "productCategory", "serviceCode", "unitCode", "quantity", "unitPrice", "discountMinor", "feeMinor", "taxCategory", "taxRate", "lineNetMinor", "lineTaxMinor", "lineTotalMinor", "itemId", "creditedQuantity", "creditsLineNo" ] }, "invoice.InvoiceListSummaryDto": { "type": "object", "properties": { "total": { "type": "integer" }, "drafts": { "type": "integer" }, "issued": { "type": "integer", "description": "Not drafts: `notReported + inProgress + reported + needsAttention`." }, "notReported": { "type": "integer" }, "inProgress": { "type": "integer" }, "reported": { "type": "integer" }, "needsAttention": { "type": "integer", "description": "Rejected or on hold, not cancelled." }, "outstanding": { "description": "Per currency: what buyers still owe on issued invoices, net of credit notes.", "type": "array", "items": { "$ref": "#/components/schemas/invoice.CurrencyAmountCountDto" } }, "overdue": { "description": "Per currency: the part of `outstanding` past its due date.", "type": "array", "items": { "$ref": "#/components/schemas/invoice.CurrencyAmountCountDto" } } }, "required": [ "total", "drafts", "issued", "notReported", "inProgress", "reported", "needsAttention", "outstanding", "overdue" ] }, "invoice.InvoiceOverviewDto": { "type": "object", "properties": { "window": { "$ref": "#/components/schemas/invoice.OverviewWindowDto" }, "kpis": { "$ref": "#/components/schemas/invoice.OverviewKpisDto" }, "trend": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.OverviewTrendPointDto" } }, "statusDistribution": { "$ref": "#/components/schemas/invoice.InvoiceStatusCountsDto" }, "paymentStatus": { "$ref": "#/components/schemas/invoice.OverviewPaymentStatusDto" }, "collections": { "$ref": "#/components/schemas/invoice.OverviewCollectionsDto" }, "alerts": { "$ref": "#/components/schemas/invoice.OverviewAlertsDto" }, "readiness": { "$ref": "#/components/schemas/invoice.OverviewReadinessDto" }, "recentInvoices": { "description": "The most recent documents (without `lineItems`).", "type": "array", "items": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" } }, "outputTax": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.OutputTaxTotalDto" } } }, "required": [ "window", "kpis", "trend", "statusDistribution", "paymentStatus", "collections", "alerts", "readiness", "recentInvoices", "outputTax" ] }, "invoice.InvoicePaymentEntryDto": { "type": "object", "properties": { "seq": { "type": "integer" }, "status": { "type": "string", "enum": [ "unpaid", "partially_paid", "paid", "payment_failed" ], "description": "What was recorded." }, "amountPaidMinor": { "type": "integer", "nullable": true, "description": "The cumulative amount paid this report stands for; null for `unpaid` and `payment_failed`. Integer minor units." }, "installmentMinor": { "type": "integer", "nullable": true, "description": "What was actually sent to the tax authority; null when nothing was sent. Integer minor units." }, "authorityStatus": { "type": "string", "enum": [ "unpaid", "partially_paid", "paid", "payment_failed" ], "nullable": true, "description": "The status the tax authority was sent; null while pending or when superseded." }, "state": { "type": "string", "enum": [ "pending", "sent", "superseded", "refused", "local" ], "description": "`pending`: waiting for the tax authority." }, "authorityMessage": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "seq", "status", "amountPaidMinor", "installmentMinor", "authorityStatus", "state", "authorityMessage", "reference", "createdAt", "sentAt" ] }, "invoice.InvoicePaymentStatusCountsDto": { "type": "object", "properties": { "unpaid": { "type": "integer" }, "partially_paid": { "type": "integer" }, "paid": { "type": "integer" }, "payment_failed": { "type": "integer" } }, "required": [ "unpaid", "partially_paid", "paid", "payment_failed" ] }, "invoice.InvoicePostalAddressDto": { "type": "object", "properties": { "line1": { "type": "string", "example": "12 Marina Road" }, "line2": { "type": "string" }, "city": { "type": "string", "example": "Lagos" }, "state": { "type": "string", "example": "Lagos" }, "lga": { "type": "string", "description": "Local government area." }, "postalCode": { "type": "string" }, "country": { "type": "string", "example": "NG", "description": "ISO 3166-1 alpha-2 country code." } }, "required": [ "line1", "city", "country" ] }, "invoice.InvoiceReportingDto": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "not_submitted", "in_progress", "reported", "rejected", "on_hold" ], "description": "How the document stands with the tax authority." }, "delivery": { "type": "string", "enum": [ "nrs", "deliver_to_buyer", "sent_email", "shared_link", "none" ], "description": "How the buyer gets the document." }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "reason": { "type": "string", "enum": [ "buyer_off_network", "b2c_invalid_tin", "b2c" ], "nullable": true, "description": "Why the document is delivered the way it is, when that needs saying." }, "irn": { "type": "string", "nullable": true }, "nextAction": { "type": "string", "enum": [ "renumber", "retry" ], "nullable": true, "description": "What the seller can do next (renumber and resubmit, or retry), when anything." }, "nextActionMessage": { "type": "string", "nullable": true } }, "required": [ "state", "delivery", "deliveredAt", "reason", "irn", "nextAction", "nextActionMessage" ] }, "invoice.InvoiceSellerSnapshotDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "organization" ] }, "legalName": { "type": "string", "nullable": true }, "name": { "type": "string" }, "taxId": { "type": "string", "nullable": true }, "taxIdType": { "type": "string", "example": "tin" }, "taxIdStatus": { "type": "string", "enum": [ "unverified", "pending", "verified", "not_found", "name_mismatch", "unavailable", "valid_off_network", "checking" ] }, "country": { "type": "string", "nullable": true, "example": "NG" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoicePostalAddressDto" } ] }, "partyName": { "type": "string", "description": "The seller’s name on the document, in capitals: the business name NRS holds when connected, else the verified legal name, else the name entered." }, "nameSource": { "type": "string", "enum": [ "nrs", "tin_check", "entered" ], "description": "Where `partyName` came from." } }, "required": [ "id", "kind", "legalName", "name", "taxId", "taxIdType", "taxIdStatus", "country", "email", "phone", "address", "partyName", "nameSource" ] }, "invoice.InvoiceSettingsViewDto": { "type": "object", "properties": { "reportAutomatically": { "type": "boolean", "description": "Whether every invoice issued while connected to NRS is reported automatically." }, "version": { "type": "integer", "description": "0 while the settings were never changed; send it back as `If-Match` (also the `ETag`)." }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Null while the settings were never changed." } }, "required": [ "reportAutomatically", "version", "updatedAt" ] }, "invoice.InvoiceSetupDto": { "type": "object", "properties": { "nextInvoiceNumber": { "type": "string", "example": "INV00042", "description": "The next number the series would allocate (a preview, not reserved)." }, "jurisdiction": { "type": "string", "nullable": true, "example": "NG" }, "defaultCurrency": { "type": "string", "nullable": true, "example": "NGN" }, "currencies": { "type": "array", "items": { "type": "string" } }, "invoiceKinds": { "example": [ "B2B", "B2C", "B2G", "G2B" ], "type": "array", "items": { "type": "string" } }, "taxCategories": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.InvoiceTaxCategoryOptionDto" } }, "unitCodes": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.InvoiceUnitCodeOptionDto" } }, "taxConnection": { "$ref": "#/components/schemas/invoice.InvoiceSetupTaxConnectionDto" } }, "required": [ "nextInvoiceNumber", "jurisdiction", "defaultCurrency", "currencies", "invoiceKinds", "taxCategories", "unitCodes", "taxConnection" ] }, "invoice.InvoiceSetupTaxConnectionDto": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "pending_taxpayer_enablement", "pending_grant_approval", "pending_key", "connected", "suspended", "revoked", "not_connected" ], "description": "The organisation’s tax connection in this mode (always `connected` in sandbox)." } }, "required": [ "state" ] }, "invoice.InvoiceStatisticsDto": { "type": "object", "properties": { "window": { "$ref": "#/components/schemas/invoice.StatisticsWindowDto" }, "total": { "type": "integer" }, "byStatus": { "$ref": "#/components/schemas/invoice.InvoiceStatusCountsDto" }, "submitted": { "type": "integer" }, "registered": { "type": "integer" }, "successRate": { "type": "number", "example": 97.5, "description": "Percent with one decimal: registered (or later) over submitted; 0 when nothing was submitted." }, "totalsByCurrency": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.CurrencyTotalDto" } }, "byPaymentStatus": { "$ref": "#/components/schemas/invoice.InvoicePaymentStatusCountsDto" }, "creditNotes": { "type": "integer" }, "outputTax": { "description": "Per currency: tax of registered invoices issued in the window less that of registered credit notes.", "type": "array", "items": { "$ref": "#/components/schemas/invoice.OutputTaxTotalDto" } } }, "required": [ "window", "total", "byStatus", "submitted", "registered", "successRate", "totalsByCurrency", "byPaymentStatus", "creditNotes", "outputTax" ] }, "invoice.InvoiceStatusCountsDto": { "type": "object", "properties": { "draft": { "type": "integer" }, "finalised": { "type": "integer" }, "queued": { "type": "integer" }, "signed": { "type": "integer" }, "transmitted": { "type": "integer" }, "accepted": { "type": "integer" }, "rejected": { "type": "integer" }, "failed": { "type": "integer" }, "cancellation_pending": { "type": "integer" }, "cancelled": { "type": "integer" } }, "required": [ "draft", "finalised", "queued", "signed", "transmitted", "accepted", "rejected", "failed", "cancellation_pending", "cancelled" ] }, "invoice.InvoiceTaxCategoryOptionDto": { "type": "object", "properties": { "id": { "type": "string", "example": "STANDARD_VAT" }, "label": { "type": "string", "example": "Standard VAT" }, "rate": { "type": "string", "example": "7.5", "description": "Percent, decimal string." } }, "required": [ "id", "label", "rate" ] }, "invoice.InvoiceTaxSubtotalDto": { "type": "object", "properties": { "taxCategory": { "type": "string", "example": "STANDARD_VAT" }, "taxRate": { "type": "string", "example": "7.5" }, "taxableMinor": { "type": "integer", "description": "Integer minor units." }, "taxMinor": { "type": "integer", "description": "Integer minor units." } }, "required": [ "taxCategory", "taxRate", "taxableMinor", "taxMinor" ] }, "invoice.InvoiceTotalsDto": { "type": "object", "properties": { "lineExtensionMinor": { "type": "integer", "description": "Σ line nets. Integer minor units." }, "discountMinor": { "type": "integer", "description": "Integer minor units." }, "feeMinor": { "type": "integer", "description": "Integer minor units." }, "taxExclusiveMinor": { "type": "integer", "description": "Integer minor units." }, "taxMinor": { "type": "integer", "description": "Integer minor units." }, "taxInclusiveMinor": { "type": "integer", "description": "Integer minor units." }, "allowanceMinor": { "type": "integer", "description": "Document allowance. Integer minor units." }, "chargeMinor": { "type": "integer", "description": "Document charge. Integer minor units." }, "payableMinor": { "type": "integer", "description": "The amount payable. Integer minor units." } }, "required": [ "lineExtensionMinor", "discountMinor", "feeMinor", "taxExclusiveMinor", "taxMinor", "taxInclusiveMinor", "allowanceMinor", "chargeMinor", "payableMinor" ] }, "invoice.InvoiceUnitCodeOptionDto": { "type": "object", "properties": { "code": { "type": "string", "example": "EA" }, "label": { "type": "string", "example": "Each" } }, "required": [ "code", "label" ] }, "invoice.InvoiceVerificationDto": { "type": "object", "properties": { "artefact": { "type": "string", "enum": [ "qr" ] }, "payload": { "type": "string", "description": "The verification payload persisted when the document registered." } }, "required": [ "artefact", "payload" ] }, "invoice.InvoiceViewDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "jurisdiction": { "type": "string", "example": "NG" }, "invoiceNumber": { "type": "string", "example": "INV00042", "description": "The document’s own number, unique per organisation." }, "authorityInvoiceNumber": { "type": "string", "nullable": true, "description": "The number NRS holds, once registered; null until then." }, "displayNumber": { "type": "string", "description": "The number to show: `authorityInvoiceNumber`, else `invoiceNumber`." }, "invoiceType": { "type": "string", "enum": [ "standard", "credit_note", "debit_note" ] }, "invoiceKind": { "type": "string", "example": "B2B" }, "status": { "type": "string", "enum": [ "draft", "finalised", "queued", "signed", "transmitted", "accepted", "rejected", "failed", "cancellation_pending", "cancelled" ] }, "authorityState": { "type": "string", "enum": [ "queued", "handed_off", "registered", "transmitted", "delivered", "rejected", "parked", "withdrawn" ], "nullable": true, "description": "The current submission’s state." }, "authorityReference": { "type": "string", "nullable": true, "description": "The IRN, once assigned." }, "parkReason": { "type": "string", "nullable": true, "description": "Why the current submission is on hold." }, "issuedAs": { "nullable": true, "description": "The identity the document was issued under; null until its first submission.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceIssuedAsDto" } ] }, "issueDate": { "type": "string", "format": "date", "example": "2026-09-30" }, "issueTime": { "type": "string", "nullable": true, "example": "14:30:00" }, "dueDate": { "type": "string", "format": "date", "example": "2026-09-30", "nullable": true }, "currency": { "type": "string", "example": "NGN" }, "taxCurrency": { "type": "string", "example": "NGN" }, "seller": { "nullable": true, "description": "A draft shows the seller as it is now; a finalised document as it was when finalised.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceSellerSnapshotDto" } ] }, "buyer": { "nullable": true, "description": "A draft shows the buyer as it is now; a finalised document as it was when finalised.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceBuyerSnapshotDto" } ] }, "buyerVerification": { "nullable": true, "description": "The buyer’s verification as it stands now; null with no buyer or tax id, or once the buyer’s tax id differs from the document’s.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceBuyerVerificationDto" } ] }, "lineItems": { "description": "The lines. Absent on list items.", "type": "array", "items": { "$ref": "#/components/schemas/invoice.InvoiceLineViewDto" } }, "totals": { "$ref": "#/components/schemas/invoice.InvoiceTotalsDto" }, "taxSubtotals": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.InvoiceTaxSubtotalDto" } }, "paymentStatus": { "type": "string", "enum": [ "unpaid", "partially_paid", "paid", "payment_failed" ], "description": "What the buyer paid (on a credit note: its refund status). Never moved by a cancellation." }, "amountPaidMinor": { "type": "integer", "description": "What the tax authority accepted as paid. Integer minor units." }, "creditedMinor": { "type": "integer", "nullable": true, "description": "On an invoice: Σ its counting credit notes (0 when none). Null on a note. Integer minor units." }, "debitedMinor": { "type": "integer", "nullable": true, "description": "On an invoice: Σ its counting debit notes (0 when none). Null on a note. Integer minor units." }, "netReceivableMinor": { "type": "integer", "nullable": true, "description": "On an invoice: payable + debited − credited, never below zero (also what can still be credited). Null on a note. Integer minor units." }, "creditStatus": { "type": "string", "enum": [ "none", "partly_credited", "credited" ], "nullable": true, "description": "On an invoice; null on a note." }, "adjustments": { "description": "An invoice’s credit and debit notes, in issue order (empty on a note).", "type": "array", "items": { "$ref": "#/components/schemas/invoice.InvoiceAdjustmentDto" } }, "creditNoteSettlement": { "nullable": true, "description": "On an invoice with a counting credit note, or on a credit note: settled, or a refund owed. Null otherwise.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceCreditSettlementDto" } ] }, "refundOwedMinor": { "type": "integer", "nullable": true, "description": "`creditNoteSettlement.refundOwedMinor`, or null with it. Integer minor units." }, "payments": { "description": "Every payment report, oldest first.", "type": "array", "items": { "$ref": "#/components/schemas/invoice.InvoicePaymentEntryDto" } }, "deliveryStatus": { "type": "string", "example": "not_sent", "description": "`not_sent` or `sent`." }, "sentToBuyerAt": { "type": "string", "format": "date-time", "nullable": true }, "buyerDelivery": { "$ref": "#/components/schemas/invoice.InvoiceBuyerDeliveryDto" }, "reporting": { "$ref": "#/components/schemas/invoice.InvoiceReportingDto" }, "simpleStatus": { "type": "string", "enum": [ "draft", "issued", "reported", "delivered", "paid", "part_paid", "cancelled" ], "description": "The one status a person reads." }, "reportedToNrs": { "type": "boolean", "description": "The tax authority registered the document; false on a draft." }, "refundOwed": { "type": "boolean", "description": "A refund to the buyer is still owed (`refundOwedMinor > 0`)." }, "notes": { "type": "string", "nullable": true }, "paymentTerms": { "type": "string", "nullable": true }, "purchaseOrderReference": { "type": "string", "nullable": true }, "buyerReference": { "type": "string", "nullable": true }, "accountingCost": { "type": "string", "nullable": true }, "creditNoteOf": { "nullable": true, "description": "A credit note: the invoice it credits.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceDocumentLinkDto" } ] }, "credits": { "nullable": true, "description": "A credit note: the invoice it credits (same as `creditNoteOf`).", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceDocumentLinkDto" } ] }, "debits": { "nullable": true, "description": "A debit note: the invoice it increases.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceDocumentLinkDto" } ] }, "cancelledByCreditNote": { "nullable": true, "description": "A cancelled (or being cancelled) invoice: its credit note.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceDocumentLinkDto" } ] }, "verification": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceVerificationDto" } ] }, "finalisedAt": { "type": "string", "format": "date-time", "nullable": true }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true }, "createdBy": { "description": "Who created the document.", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceActorDto" } ] }, "submittedBy": { "nullable": true, "description": "Who submitted it to the tax authority; null while never submitted.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceActorDto" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "description": "The concurrency token: send it back as `If-Match: \"\"` (also the `ETag`)." } }, "required": [ "id", "jurisdiction", "invoiceNumber", "authorityInvoiceNumber", "displayNumber", "invoiceType", "invoiceKind", "status", "authorityState", "authorityReference", "parkReason", "issuedAs", "issueDate", "issueTime", "dueDate", "currency", "taxCurrency", "seller", "buyer", "buyerVerification", "totals", "taxSubtotals", "paymentStatus", "amountPaidMinor", "creditedMinor", "debitedMinor", "netReceivableMinor", "creditStatus", "adjustments", "creditNoteSettlement", "refundOwedMinor", "payments", "deliveryStatus", "sentToBuyerAt", "buyerDelivery", "reporting", "simpleStatus", "reportedToNrs", "refundOwed", "notes", "paymentTerms", "purchaseOrderReference", "buyerReference", "accountingCost", "creditNoteOf", "credits", "debits", "cancelledByCreditNote", "verification", "finalisedAt", "cancelledAt", "createdBy", "submittedBy", "createdAt", "updatedAt", "version" ] }, "invoice.IssueAnswerDto": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" }, "submission": { "nullable": true, "description": "The queued submission when the invoice is being reported; null otherwise.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.SubmissionViewDto" } ] }, "reporting": { "type": "string", "enum": [ "queued", "not_reported" ], "description": "`queued`: being reported; `not_reported`: finalised and sent, not reported." }, "notReportedReason": { "type": "string", "enum": [ "not_connected", "auto_report_off" ], "nullable": true, "description": "Why the invoice was not reported; null when it was queued." }, "sentToBuyer": { "type": "boolean", "description": "Whether the document was emailed to the buyer." }, "replayed": { "type": "boolean", "description": "True when the answer replays an earlier request with the same key." } }, "required": [ "invoice", "submission", "reporting", "notReportedReason", "sentToBuyer", "replayed" ] }, "invoice.IssueCreditNoteDto": { "type": "object", "properties": { "reason": { "type": "string", "example": "Two units returned", "minLength": 3, "maxLength": 500 }, "mode": { "type": "string", "enum": [ "full", "lines", "amount" ] }, "lines": { "description": "mode 'lines' only (required there)", "type": "array", "items": { "$ref": "#/components/schemas/invoice.CreditNoteLineDto" } }, "amountMinor": { "type": "number", "example": 107500, "description": "mode 'amount' only (required there): the TAX-INCLUSIVE amount, minor units" }, "lineNo": { "type": "number", "example": 1, "description": "mode 'amount' only: the original line whose text, codes and VAT the credit line takes (default 1)" }, "preview": { "type": "boolean", "description": "true: answer what would be issued; nothing is written or charged" } }, "required": [ "reason", "mode" ] }, "invoice.IssueDebitNoteDto": { "type": "object", "properties": { "reason": { "type": "string", "example": "Delivery charge omitted", "maxLength": 500 }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.InvoiceLineItemDto" } }, "preview": { "type": "boolean", "description": "true: answer what would be issued; nothing is written or charged" } }, "required": [ "lineItems" ] }, "invoice.ItemDeletedDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "deleted" ] }, "invoice.ItemViewDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "itemType": { "type": "string", "enum": [ "goods", "service" ] }, "hsnCode": { "type": "string", "nullable": true }, "serviceCode": { "type": "string", "nullable": true }, "productCategory": { "type": "string" }, "unitCode": { "type": "string", "example": "EA" }, "unitPriceMinor": { "type": "string", "example": "150050", "description": "Minor units as a decimal string." }, "currency": { "type": "string", "example": "NGN" }, "taxCategory": { "type": "string", "example": "STANDARD_VAT", "description": "Stored resolved to the code-list id." }, "sku": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastUsedAt": { "type": "string", "nullable": true, "format": "date-time" }, "useCount": { "type": "number", "example": 3, "description": "Finalised invoice lines built from this item." }, "referenced": { "type": "boolean", "example": false, "description": "Whether any invoice line, drafts included, references the item — while true, the item cannot be deleted (archive it instead)." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "itemType", "hsnCode", "serviceCode", "productCategory", "unitCode", "unitPriceMinor", "currency", "taxCategory", "sku", "archivedAt", "lastUsedAt", "useCount", "referenced", "createdAt", "updatedAt" ] }, "invoice.MonthBucketDto": { "type": "object", "properties": { "count": { "type": "number" }, "grossPayableMinor": { "type": "number", "description": "MINOR units, reporting currency." }, "month": { "type": "string", "example": "2026-09" }, "inputVatMinor": { "type": "number" } }, "required": [ "count", "grossPayableMinor", "month", "inputVatMinor" ] }, "invoice.NotePreviewLineDto": { "type": "object", "properties": { "lineNo": { "type": "integer" }, "creditsLineNo": { "type": "integer", "nullable": true, "description": "The original line it credits." }, "description": { "type": "string" }, "quantity": { "type": "string", "example": "2.000000" }, "unitPrice": { "type": "string", "example": "50000.0000" }, "lineNetMinor": { "type": "integer", "description": "Integer minor units." }, "lineTaxMinor": { "type": "integer", "description": "Integer minor units." }, "lineTotalMinor": { "type": "integer", "description": "Integer minor units." } }, "required": [ "lineNo", "creditsLineNo", "description", "quantity", "unitPrice", "lineNetMinor", "lineTaxMinor", "lineTotalMinor" ] }, "invoice.NotePreviewTotalsDto": { "type": "object", "properties": { "taxExclusiveMinor": { "type": "integer", "description": "Integer minor units." }, "taxMinor": { "type": "integer", "description": "Integer minor units." }, "payableMinor": { "type": "integer", "description": "Integer minor units." } }, "required": [ "taxExclusiveMinor", "taxMinor", "payableMinor" ] }, "invoice.OutputTaxTotalDto": { "type": "object", "properties": { "currency": { "type": "string", "example": "NGN" }, "invoicesTaxMinor": { "type": "integer", "description": "Tax of the registered invoices. Integer minor units." }, "creditNotesTaxMinor": { "type": "integer", "description": "Tax of the registered credit notes. Integer minor units." }, "netTaxMinor": { "type": "integer", "description": "Invoices’ tax less credit notes’ tax; negative when credits exceed sales. Integer minor units." } }, "required": [ "currency", "invoicesTaxMinor", "creditNotesTaxMinor", "netTaxMinor" ] }, "invoice.OverviewAlertsDto": { "type": "object", "properties": { "failedInvoices": { "type": "integer" }, "unverifiedSellers": { "type": "integer" }, "unverifiedBuyers": { "type": "integer" } }, "required": [ "failedInvoices", "unverifiedSellers", "unverifiedBuyers" ] }, "invoice.OverviewCollectionsDto": { "type": "object", "properties": { "outstanding": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.CurrencyAmountDto" } }, "overdueCount": { "type": "integer" } }, "required": [ "outstanding", "overdueCount" ] }, "invoice.OverviewCurrencyValueDto": { "type": "object", "properties": { "currency": { "type": "string", "example": "NGN" }, "valueMinor": { "type": "integer", "description": "Integer minor units." }, "count": { "type": "integer" } }, "required": [ "currency", "valueMinor", "count" ] }, "invoice.OverviewKpisDto": { "type": "object", "properties": { "volume": { "$ref": "#/components/schemas/invoice.OverviewVolumeKpiDto" }, "successRate": { "$ref": "#/components/schemas/invoice.OverviewSuccessRateKpiDto" }, "valueProcessed": { "$ref": "#/components/schemas/invoice.OverviewValueProcessedKpiDto" }, "avgProcessingTime": { "$ref": "#/components/schemas/invoice.OverviewProcessingTimeKpiDto" } }, "required": [ "volume", "successRate", "valueProcessed", "avgProcessingTime" ] }, "invoice.OverviewPaymentStatusDto": { "type": "object", "properties": { "unpaid": { "type": "integer" }, "partiallyPaid": { "type": "integer" }, "paid": { "type": "integer" }, "overdue": { "type": "integer" } }, "required": [ "unpaid", "partiallyPaid", "paid", "overdue" ] }, "invoice.OverviewProcessingTimeKpiDto": { "type": "object", "properties": { "seconds": { "type": "number", "nullable": true }, "deltaSeconds": { "type": "number", "nullable": true } }, "required": [ "seconds", "deltaSeconds" ] }, "invoice.OverviewReadinessDto": { "type": "object", "properties": { "sellers": { "type": "integer" }, "sellersVerified": { "type": "integer" }, "buyers": { "type": "integer" }, "buyersVerified": { "type": "integer" } }, "required": [ "sellers", "sellersVerified", "buyers", "buyersVerified" ] }, "invoice.OverviewSuccessRateKpiDto": { "type": "object", "properties": { "value": { "type": "number" }, "deltaPp": { "type": "number", "nullable": true, "description": "Change on the previous window, percentage points." }, "spark": { "type": "array", "items": { "type": "number" } } }, "required": [ "value", "deltaPp", "spark" ] }, "invoice.OverviewTrendPointDto": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "example": "2026-09-30" }, "created": { "type": "integer" }, "submitted": { "type": "integer" }, "accepted": { "type": "integer" }, "failed": { "type": "integer" }, "successRate": { "type": "number" } }, "required": [ "date", "created", "submitted", "accepted", "failed", "successRate" ] }, "invoice.OverviewValueProcessedKpiDto": { "type": "object", "properties": { "primaryCurrency": { "type": "string", "nullable": true, "example": "NGN" }, "primaryValueMinor": { "type": "integer", "description": "Integer minor units." }, "deltaPct": { "type": "number", "nullable": true }, "byCurrency": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.OverviewCurrencyValueDto" } }, "sparkMinor": { "description": "Integer minor units.", "type": "array", "items": { "type": "integer" } } }, "required": [ "primaryCurrency", "primaryValueMinor", "deltaPct", "byCurrency", "sparkMinor" ] }, "invoice.OverviewVolumeKpiDto": { "type": "object", "properties": { "value": { "type": "integer" }, "deltaPct": { "type": "number", "nullable": true, "description": "Percent change on the previous window." }, "spark": { "type": "array", "items": { "type": "integer" } } }, "required": [ "value", "deltaPct", "spark" ] }, "invoice.OverviewWindowDto": { "type": "object", "properties": { "days": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } }, "required": [ "days", "start", "end" ] }, "invoice.PartyAddressDto": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string", "description": "Left out when not recorded." }, "city": { "type": "string" }, "state": { "type": "string", "description": "Left out when not recorded." }, "lga": { "type": "string", "description": "Local government area; left out when not recorded." }, "postalCode": { "type": "string", "description": "Left out when not recorded." }, "country": { "type": "string", "example": "NG", "description": "ISO 3166-1 alpha-2." } }, "required": [ "line1", "city", "country" ] }, "invoice.PaymentBreakdownDto": { "type": "object", "properties": { "paid": { "$ref": "#/components/schemas/invoice.AmountBucketDto" }, "unpaid": { "$ref": "#/components/schemas/invoice.AmountBucketDto" }, "partial": { "$ref": "#/components/schemas/invoice.AmountBucketDto" }, "rejected": { "$ref": "#/components/schemas/invoice.AmountBucketDto" }, "unknown": { "description": "No payment status known yet.", "allOf": [ { "$ref": "#/components/schemas/invoice.AmountBucketDto" } ] }, "overdue": { "description": "Overlaps the others: due before today and not paid.", "allOf": [ { "$ref": "#/components/schemas/invoice.AmountBucketDto" } ] } }, "required": [ "paid", "unpaid", "partial", "rejected", "unknown", "overdue" ] }, "invoice.PaymentStatusDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unpaid", "partially_paid", "paid", "payment_failed" ], "description": "unpaid is local only (refused once anything was reported); payment_failed follows an accepted part or full payment." }, "amountMinor": { "type": "integer", "description": "Integer minor units; required for partially_paid: the TOTAL received to date (cumulative), not the installment." }, "reference": { "type": "string", "maxLength": 100 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "status" ] }, "invoice.PreviousKeyDto": { "type": "object", "properties": { "certificateFingerprint": { "type": "string", "description": "SHA-256 of the retired certificate, hex." }, "retiredAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "certificateFingerprint", "retiredAt" ] }, "invoice.QueryStatusDto": { "type": "object", "properties": { "invoiceId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "finalised", "queued", "signed", "transmitted", "accepted", "rejected", "failed", "cancellation_pending", "cancelled" ] }, "authorityState": { "type": "string", "enum": [ "queued", "handed_off", "registered", "transmitted", "delivered", "rejected", "parked", "withdrawn" ], "nullable": true }, "authorityReference": { "type": "string", "nullable": true, "description": "The IRN, once assigned." }, "parkReason": { "type": "string", "nullable": true }, "lastSyncedAt": { "type": "string", "format": "date-time", "nullable": true }, "submissions": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.SubmissionViewDto" } }, "authority": { "description": "What the tax authority answered.", "allOf": [ { "$ref": "#/components/schemas/invoice.AuthorityStatusDto" } ] } }, "required": [ "invoiceId", "status", "authorityState", "authorityReference", "parkReason", "lastSyncedAt", "submissions", "authority" ] }, "invoice.RetryAnswerDto": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" }, "submission": { "$ref": "#/components/schemas/invoice.SubmissionViewDto" } }, "required": [ "invoice", "submission" ] }, "invoice.SellerSetupDto": { "type": "object", "properties": { "seller": { "$ref": "#/components/schemas/invoice.SellerViewDto" }, "additionalSellersAvailable": { "type": "boolean", "enum": [ false ], "description": "Always false: the organisation is the only seller." }, "taxIdTypes": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.TaxIdTypeOptionDto" } }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.CountryOptionDto" } } }, "required": [ "seller", "additionalSellersAvailable", "taxIdTypes", "countries" ] }, "invoice.SellerVerificationStatusDto": { "type": "object", "properties": { "taxIdStatus": { "type": "string", "enum": [ "unverified", "pending", "verified", "not_found", "name_mismatch", "unavailable", "valid_off_network", "checking" ] }, "taxIdVerifiedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "taxIdStatus", "taxIdVerifiedAt" ] }, "invoice.SellerViewDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "organization" ], "description": "The organisation is its own seller." }, "legalName": { "type": "string", "nullable": true }, "name": { "type": "string" }, "taxId": { "type": "string", "nullable": true }, "taxIdType": { "type": "string", "enum": [ "tin", "rn", "foreign", "none" ] }, "taxIdStatus": { "type": "string", "enum": [ "unverified", "pending", "verified", "not_found", "name_mismatch", "unavailable", "valid_off_network", "checking" ], "description": "The organisation’s TIN verification status, as recorded in organisation settings." }, "taxIdVerifiedAt": { "type": "string", "format": "date-time", "nullable": true }, "country": { "type": "string", "nullable": true, "example": "NG" }, "address": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.PartyAddressDto" } ] }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "partyName": { "type": "string", "description": "The name the seller appears under on its documents and to the tax authority, upper case: the tax authority’s business name while the tax connection is connected, else the verified legal name, else `name`." }, "nameSource": { "type": "string", "enum": [ "nrs", "tin_check", "entered" ], "description": "Where `partyName` came from: `nrs`, `tin_check` or `entered`." } }, "required": [ "id", "kind", "legalName", "name", "taxId", "taxIdType", "taxIdStatus", "taxIdVerifiedAt", "country", "address", "email", "phone", "partyName", "nameSource" ] }, "invoice.SendInvoiceDto": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 1000, "example": "Please find our invoice attached." } } }, "invoice.SendResultDto": { "type": "object", "properties": { "sendId": { "type": "string", "format": "uuid" }, "deliveryStatus": { "type": "string", "enum": [ "sent" ], "description": "\"sent\" means queued, not received." }, "shareUrl": { "type": "string", "description": "Sandbox only (no email leaves): a presigned link to the PDF for preview." }, "replayed": { "type": "boolean", "enum": [ true ], "description": "Present when an Idempotency-Key replayed." } }, "required": [ "sendId", "deliveryStatus" ] }, "invoice.ShareLinkCreatorDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "api_key", "service", "system" ] }, "id": { "type": "string", "nullable": true, "description": "The user or key id; null for the system." } }, "required": [ "type", "id" ] }, "invoice.ShareLinkViewDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invoiceId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "nullable": true, "description": "The full link — on the create answer ONLY (the token exists once); null elsewhere.", "example": "https://app.useyona.com/v/sAbc…" }, "expiresAt": { "type": "string", "format": "date-time" }, "maxViews": { "type": "number", "nullable": true }, "viewCount": { "type": "number", "example": 0 }, "lastViewedAt": { "type": "string", "nullable": true, "format": "date-time" }, "revokedAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "$ref": "#/components/schemas/invoice.ShareLinkCreatorDto" } }, "required": [ "id", "invoiceId", "url", "expiresAt", "maxViews", "viewCount", "lastViewedAt", "revokedAt", "createdAt", "createdBy" ] }, "invoice.StatisticsWindowDto": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time", "description": "Exclusive." } }, "required": [ "from", "to" ] }, "invoice.SubmissionBillingDto": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "held", "captured", "released", "capture_lost", "not_charged" ], "description": "The state of the submission’s charge." } }, "required": [ "state" ] }, "invoice.SubmissionRejectReasonDto": { "type": "object", "properties": { "code": { "type": "string", "description": "The tax authority’s code." }, "field": { "type": "string", "description": "The field the authority named, when it named one." }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "invoice.SubmissionStatusDto": { "type": "object", "properties": { "invoiceId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "finalised", "queued", "signed", "transmitted", "accepted", "rejected", "failed", "cancellation_pending", "cancelled" ] }, "authorityState": { "type": "string", "enum": [ "queued", "handed_off", "registered", "transmitted", "delivered", "rejected", "parked", "withdrawn" ], "nullable": true }, "authorityReference": { "type": "string", "nullable": true, "description": "The IRN, once assigned." }, "parkReason": { "type": "string", "nullable": true }, "lastSyncedAt": { "type": "string", "format": "date-time", "nullable": true }, "submissions": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.SubmissionViewDto" } } }, "required": [ "invoiceId", "status", "authorityState", "authorityReference", "parkReason", "lastSyncedAt", "submissions" ] }, "invoice.SubmissionVerificationDto": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "pending", "captured", "unavailable" ] }, "capturedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "state", "capturedAt" ] }, "invoice.SubmissionViewDto": { "type": "object", "properties": { "submissionId": { "type": "string", "format": "uuid" }, "invoiceId": { "type": "string", "format": "uuid" }, "attemptNo": { "type": "integer", "example": 1 }, "authorityState": { "type": "string", "enum": [ "queued", "handed_off", "registered", "transmitted", "delivered", "rejected", "parked", "withdrawn" ] }, "status": { "type": "string", "enum": [ "draft", "finalised", "queued", "signed", "transmitted", "accepted", "rejected", "failed", "cancellation_pending", "cancelled" ] }, "authorityReference": { "type": "string", "nullable": true, "description": "The IRN, once assigned." }, "authoritySubmissionId": { "type": "string", "nullable": true }, "parkReason": { "type": "string", "nullable": true, "description": "Why the submission is on hold." }, "rejectReasons": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.SubmissionRejectReasonDto" } }, "issuedAs": { "nullable": true, "description": "The identity this submission went out under.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceIssuedAsDto" } ] }, "verification": { "nullable": true, "description": "The verification artefact’s capture; null when there is none.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.SubmissionVerificationDto" } ] }, "billing": { "$ref": "#/components/schemas/invoice.SubmissionBillingDto" }, "queuedAt": { "type": "string", "format": "date-time" }, "handedOffAt": { "type": "string", "format": "date-time", "nullable": true }, "registeredAt": { "type": "string", "format": "date-time", "nullable": true }, "transmittedAt": { "type": "string", "format": "date-time", "nullable": true }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "rejectedAt": { "type": "string", "format": "date-time", "nullable": true }, "parkedAt": { "type": "string", "format": "date-time", "nullable": true }, "authorityNote": { "type": "string", "nullable": true, "description": "A plain-language note while the submission has waited long for the tax authority to confirm delivery; null otherwise." }, "authorityLastCheckedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the tax authority was last asked." }, "authorityNextCheckAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When it will next be asked; null when it will not." }, "createdBy": { "description": "Who queued this submission.", "allOf": [ { "$ref": "#/components/schemas/invoice.InvoiceActorDto" } ] } }, "required": [ "submissionId", "invoiceId", "attemptNo", "authorityState", "status", "authorityReference", "authoritySubmissionId", "parkReason", "rejectReasons", "issuedAs", "verification", "billing", "queuedAt", "handedOffAt", "registeredAt", "transmittedAt", "deliveredAt", "rejectedAt", "parkedAt", "authorityNote", "authorityLastCheckedAt", "authorityNextCheckAt", "createdBy" ] }, "invoice.SubmitAnswerDto": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/invoice.InvoiceViewDto" }, "submission": { "$ref": "#/components/schemas/invoice.SubmissionViewDto" }, "replayed": { "type": "boolean", "description": "True when the answer is a submission already in flight." } }, "required": [ "invoice", "submission", "replayed" ] }, "invoice.SubmitRefusalDto": { "type": "object", "properties": { "errorCode": { "type": "string", "example": "BIZ204" }, "message": { "type": "string" } }, "required": [ "errorCode", "message" ] }, "invoice.SupplierBucketDto": { "type": "object", "properties": { "count": { "type": "number" }, "grossPayableMinor": { "type": "number", "description": "MINOR units, reporting currency." }, "name": { "type": "string", "nullable": true }, "tin": { "type": "string", "nullable": true } }, "required": [ "count", "grossPayableMinor", "name", "tin" ] }, "invoice.TaxIdLookupDto": { "type": "object", "properties": { "value": { "type": "string", "example": "33875194-0001" }, "type": { "type": "string", "enum": [ "tin", "rn", "foreign" ] }, "outcome": { "type": "string", "enum": [ "verified", "not_found" ] }, "registeredName": { "type": "string", "description": "The registered name, when verified." }, "reference": { "type": "string", "description": "The provider’s verification reference, when verified." } }, "required": [ "value", "type", "outcome" ] }, "invoice.TaxIdTypeOptionDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tin", "rn", "foreign", "none" ] }, "description": { "type": "string" }, "verifiable": { "type": "boolean", "description": "Whether a tax id of this type can be verified." } }, "required": [ "type", "description", "verifiable" ] }, "invoice.TaxIdentityViewDto": { "type": "object", "properties": { "taxId": { "type": "string", "description": "In the form the tax authority displays it." }, "connectedAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": "string", "format": "date-time", "nullable": true }, "revokedReason": { "type": "string", "nullable": true } }, "required": [ "taxId", "connectedAt", "revokedAt", "revokedReason" ] }, "invoice.TopSuppliersDto": { "type": "object", "properties": { "byAmount": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.SupplierBucketDto" } }, "byCount": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.SupplierBucketDto" } } }, "required": [ "byAmount", "byCount" ] }, "invoice.TransportBindingDto": { "type": "object", "properties": { "organizationId": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "purpose": { "type": "string", "enum": [ "tax-crypto-key" ] } }, "required": [ "organizationId", "mode", "purpose" ] }, "invoice.TransportJwkDto": { "type": "object", "properties": { "kty": { "type": "string", "enum": [ "RSA" ] }, "n": { "type": "string", "description": "RSA modulus, base64url." }, "e": { "type": "string", "description": "RSA exponent, base64url." }, "kid": { "type": "string" }, "alg": { "type": "string", "enum": [ "RSA-OAEP-256" ] }, "use": { "type": "string", "enum": [ "enc" ] } }, "required": [ "kty", "n", "e", "kid", "alg", "use" ] }, "invoice.TransportKeyViewDto": { "type": "object", "properties": { "kid": { "type": "string" }, "alg": { "type": "string", "enum": [ "RSA-OAEP-256" ] }, "enc": { "type": "string", "enum": [ "A256GCM" ], "description": "Content encryption: AES-256-GCM." }, "jwk": { "description": "The public key, as a JWK.", "allOf": [ { "$ref": "#/components/schemas/invoice.TransportJwkDto" } ] }, "binding": { "description": "What the encrypted envelope must be bound to.", "allOf": [ { "$ref": "#/components/schemas/invoice.TransportBindingDto" } ] }, "maxAgeSeconds": { "type": "number", "description": "How old an envelope may be when it arrives, in seconds." } }, "required": [ "kid", "alg", "enc", "jwk", "binding", "maxAgeSeconds" ] }, "invoice.UpdateBuyerDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "legalName": { "type": "string", "maxLength": 255, "nullable": true }, "taxId": { "type": "string", "maxLength": 64, "nullable": true }, "taxIdType": { "type": "string", "enum": [ "tin", "rn", "foreign", "none" ] }, "email": { "type": "string", "maxLength": 320, "nullable": true }, "phone": { "type": "string", "description": "E.164.", "nullable": true }, "address": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/invoice.BuyerAddressDto" } ] }, "partyType": { "type": "string", "enum": [ "individual", "company", "partnership", "non_profit", "government" ], "nullable": true }, "businessDescription": { "type": "string", "maxLength": 1000, "nullable": true }, "reference": { "type": "string", "maxLength": 100, "nullable": true } } }, "invoice.UpdateInvoiceDto": { "type": "object", "properties": { "sellerId": { "type": "string", "format": "uuid" }, "buyerId": { "type": "string", "format": "uuid", "nullable": true, "description": "`null` removes the buyer." }, "invoiceKind": { "type": "string", "example": "B2C" }, "invoiceNumber": { "type": "string", "example": "INV00042" }, "invoiceDate": { "type": "string", "example": "2026-09-30" }, "issueTime": { "type": "string", "nullable": true, "example": "14:30:00" }, "dueDate": { "type": "string", "nullable": true, "example": "2026-10-30" }, "currency": { "type": "string", "example": "NGN" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.InvoiceLineItemDto" } }, "allowanceAmount": { "oneOf": [ { "type": "string", "example": "12.50" }, { "type": "number", "example": 12.5 } ], "nullable": true, "description": "Document allowance, major units, ≤ 2 decimals." }, "chargeAmount": { "oneOf": [ { "type": "string", "example": "12.50" }, { "type": "number", "example": 12.5 } ], "nullable": true, "description": "Document charge, major units, ≤ 2 decimals." }, "paymentTerms": { "type": "string", "nullable": true, "maxLength": 500 }, "notes": { "type": "string", "nullable": true, "maxLength": 2000 }, "purchaseOrderReference": { "type": "string", "nullable": true, "maxLength": 100 }, "buyerReference": { "type": "string", "nullable": true, "maxLength": 100 }, "accountingCost": { "type": "string", "nullable": true, "maxLength": 100 } } }, "invoice.UpdateInvoiceSettingsDto": { "type": "object", "properties": { "reportAutomatically": { "type": "boolean", "description": "On (the default): an organisation connected to NRS reports every invoice it issues. Off: issuing finalises the invoice and sends it to the buyer without reporting it; it can be submitted to NRS later.", "example": true } }, "required": [ "reportAutomatically" ] }, "invoice.UpdateItemDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000, "nullable": true }, "itemType": { "type": "string", "enum": [ "goods", "service" ], "description": "Immutable: only the stored value is accepted." }, "hsnCode": { "type": "string", "pattern": "^[0-9A-Za-z.]{1,20}$", "nullable": true }, "serviceCode": { "type": "string", "pattern": "^[0-9A-Za-z.]{1,20}$", "nullable": true }, "productCategory": { "type": "string", "minLength": 1, "maxLength": 500 }, "unitCode": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,16}$" }, "unitPriceMinor": { "type": "string", "pattern": "^\\d{1,18}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "taxCategory": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,64}$" }, "sku": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9._-]+$", "nullable": true } } }, "invoice.UsedCodeDto": { "type": "object", "properties": { "code": { "type": "string", "example": "8471.30" }, "description": { "type": "string", "nullable": true, "description": "The most recent line’s product category for this code." }, "useCount": { "type": "number", "example": 12, "description": "Invoice lines carrying the code, in every status (drafts and cancelled included)." }, "lastUsedAt": { "type": "string", "format": "date-time", "description": "The most recent invoice’s createdAt." } }, "required": [ "code", "description", "useCount", "lastUsedAt" ] }, "invoice.ValidateInvoiceDto": { "type": "object", "properties": { "invoiceId": { "type": "string", "format": "uuid", "description": "Validate a stored invoice (alone)." }, "sellerId": { "type": "string", "format": "uuid", "description": "Only the organisation’s own seller id." }, "buyerId": { "type": "string", "format": "uuid" }, "invoiceKind": { "type": "string", "pattern": "^[A-Z0-9]{2,8}$", "example": "B2B" }, "invoiceNumber": { "type": "string", "pattern": "^[A-Za-z0-9]{1,50}$" }, "invoiceType": { "type": "string", "enum": [ "standard" ], "description": "Only `standard`: credit notes are not validated here." }, "invoiceDate": { "type": "string", "example": "2026-09-30", "description": "The issue date (required with an invoice body)." }, "issueTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d)?$", "example": "10:30:00" }, "dueDate": { "type": "string", "example": "2026-10-30" }, "currency": { "type": "string", "example": "NGN", "description": "ISO 4217 (required with an invoice body)." }, "lineItems": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "$ref": "#/components/schemas/invoice.ValidateLineItemDto" } }, "allowanceAmount": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "chargeAmount": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "paymentTerms": { "type": "string", "maxLength": 500 }, "notes": { "type": "string", "maxLength": 2000 }, "purchaseOrderReference": { "type": "string", "maxLength": 100 }, "buyerReference": { "type": "string", "maxLength": 100 }, "accountingCost": { "type": "string", "maxLength": 100 } } }, "invoice.ValidateLineItemDto": { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid", "description": "A saved item of the organisation: every omitted field below is filled from it." }, "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Required without an itemId." }, "itemName": { "type": "string", "maxLength": 255 }, "hsnCode": { "type": "string", "maxLength": 32, "example": "9983" }, "productCategory": { "type": "string", "maxLength": 100 }, "isicCode": { "type": "string", "maxLength": 32, "description": "The service code." }, "serviceCategory": { "type": "string", "maxLength": 100 }, "quantity": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "example": "2", "description": "> 0, ≤ 6 decimals" }, "unitCode": { "type": "string", "pattern": "^[A-Za-z0-9]{1,16}$", "example": "EA", "description": "Required without an itemId." }, "unitPrice": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "example": "15000.00", "description": "≥ 0, ≤ 4 decimals, major units. Required without an itemId." }, "discountAmount": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "major units, ≤ 2 decimals" }, "feeAmount": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "major units, ≤ 2 decimals" }, "taxCategory": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$", "example": "STANDARD_VAT", "description": "Required without an itemId." } }, "required": [ "quantity" ] }, "invoice.ValidationFindingDto": { "type": "object", "properties": { "code": { "type": "string", "example": "TAX_CATEGORY_UNKNOWN" }, "field": { "type": "string", "example": "tax_total[0].tax_subtotal[0].tax_category.id" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "invoice.ValidationResultDto": { "type": "object", "properties": { "valid": { "type": "boolean" }, "previewAuthorityReference": { "type": "string", "nullable": true, "description": "The reference the authority WOULD mint — a preview, nothing is registered." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/invoice.ValidationFindingDto" } } }, "required": [ "valid", "errors" ] }, "notification.ApiErrorMetaDto": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "success": { "type": "boolean", "enum": [ false ], "example": false }, "message": { "type": "string", "example": "Some fields are invalid — please review and try again" }, "errorCode": { "type": "string", "pattern": "^(AUTH|VAL|RES|BIZ|SYS)\\d{3}$", "example": "VAL001", "description": "The machine identity of the refusal — branch on this. Every 5xx is SYS001." }, "errors": { "type": "array", "items": { "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": { "type": "string" } }, "example": [ { "email": "must be an email" } ], "description": "Single-key objects: `{ field-or-code: message }`." }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-29T10:00:00.000Z" }, "requestId": { "type": "string", "description": "This service’s request id (also the `x-request-id` header) — quote it in a bug report." } }, "required": [ "statusCode", "success", "message", "errorCode", "errors", "timestamp", "requestId" ] }, "notification.ApiPaginationMetaDto": { "type": "object", "properties": { "total": { "type": "number", "example": 137, "minimum": 0 }, "page": { "type": "number", "example": 1, "minimum": 1, "description": "1-based page number." }, "pageSize": { "type": "number", "example": 20, "description": "Items per page (the `limit` query parameter)." }, "totalPages": { "type": "number", "example": 7, "minimum": 0, "description": "`ceil(total / pageSize)`; an empty set is 0 pages." }, "hasNext": { "type": "boolean", "example": true }, "hasPrevious": { "type": "boolean", "example": false }, "nextPage": { "type": "string" }, "previousPage": { "type": "string" }, "currentPage": { "type": "string" } }, "required": [ "total", "page", "pageSize", "totalPages", "hasNext", "hasPrevious" ] }, "notification.ApiSuccessMetaDto": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 200 }, "success": { "type": "boolean", "enum": [ true ], "example": true }, "message": { "type": "string", "example": "Success", "description": "Copy for humans. Never branch on it." }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "maxItems": 0, "example": [] }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-29T10:00:00.000Z" }, "requestId": { "type": "string", "description": "This service’s request id (also the `x-request-id` header) — quote it in a bug report." }, "pagination": { "description": "Present on list responses.", "allOf": [ { "$ref": "#/components/schemas/notification.ApiPaginationMetaDto" } ] } }, "required": [ "statusCode", "success", "message", "errors", "timestamp", "requestId" ] }, "notification.CreateWebhookEndpointDto": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "example": "https://example.com/hooks/yona" }, "description": { "type": "string", "maxLength": 200 }, "events": { "minItems": 1, "maxItems": 100, "example": [ "invoice.*", "billing.payment.succeeded" ], "description": "Event patterns: an exact type, a `prefix.*` wildcard, or `*`.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "events" ] }, "notification.DeletedWebhookEndpointDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "deleted" ] }, "notification.RedeliverWebhookEventDto": { "type": "object", "properties": { "endpointId": { "type": "string", "format": "uuid", "description": "One of the organisation’s endpoints in the caller’s mode." } }, "required": [ "endpointId" ] }, "notification.RotateWebhookSecretDto": { "type": "object", "properties": { "overlapSeconds": { "type": "integer", "minimum": 0, "maximum": 604800, "default": 86400, "description": "How long requests also carry a signature made with the previous secret." } } }, "notification.TestWebhookEndpointDto": { "type": "object", "properties": { "type": { "type": "string", "example": "invoice.signed", "description": "Send a sample event of this type; when absent, a `webhook_endpoint.pinged` ping is sent." } } }, "notification.UpdateWebhookEndpointDto": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048 }, "description": { "type": "string", "maxLength": 200 }, "events": { "minItems": 1, "maxItems": 100, "example": [ "invoice.*", "billing.payment.succeeded" ], "description": "Event patterns: an exact type, a `prefix.*` wildcard, or `*`.", "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean", "description": "`false` disables the endpoint (cause `manual`) and stops its open deliveries; `true` re-enables it and clears its failure run. (`status` itself is set by the server only.)" }, "upgradeVersions": { "type": "boolean", "description": "Move the endpoint to the latest version of every event type. Every type is version 1 today, so this changes nothing yet." } } }, "notification.WebhookDeliveryAttemptDto": { "type": "object", "properties": { "attemptNo": { "type": "number", "minimum": 1 }, "startedAt": { "type": "string", "format": "date-time" }, "durationMs": { "type": "number", "minimum": 0 }, "outcome": { "type": "string", "enum": [ "ok", "retryable", "permanent", "timeout", "refused" ] }, "httpStatus": { "type": "integer", "nullable": true }, "errorClass": { "type": "string", "enum": [ "http_status", "redirect", "timeout", "network", "tls", "dns", "egress_refused", "gone" ], "nullable": true } }, "required": [ "attemptNo", "startedAt", "durationMs", "outcome", "httpStatus", "errorClass" ] }, "notification.WebhookDeliveryDetailDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "endpointId": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "status": { "type": "string", "enum": [ "pending", "delivering", "retrying", "delivered", "failed" ] }, "failureReason": { "type": "string", "enum": [ "attempts_exhausted", "endpoint_disabled", "gone", "url_refused" ], "nullable": true }, "attempts": { "type": "number", "minimum": 0 }, "maxAttempts": { "type": "number", "minimum": 1 }, "nextAttemptAt": { "type": "string", "format": "date-time", "nullable": true }, "lastHttpStatus": { "type": "integer", "nullable": true }, "lastErrorClass": { "type": "string", "enum": [ "http_status", "redirect", "timeout", "network", "tls", "dns", "egress_refused", "gone" ], "nullable": true }, "test": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "failedAt": { "type": "string", "format": "date-time", "nullable": true }, "attemptLog": { "type": "array", "items": { "$ref": "#/components/schemas/notification.WebhookDeliveryAttemptDto" } } }, "required": [ "id", "eventId", "endpointId", "type", "mode", "status", "failureReason", "attempts", "maxAttempts", "nextAttemptAt", "lastHttpStatus", "lastErrorClass", "test", "createdAt", "deliveredAt", "failedAt", "attemptLog" ] }, "notification.WebhookDeliveryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "endpointId": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "status": { "type": "string", "enum": [ "pending", "delivering", "retrying", "delivered", "failed" ] }, "failureReason": { "type": "string", "enum": [ "attempts_exhausted", "endpoint_disabled", "gone", "url_refused" ], "nullable": true }, "attempts": { "type": "number", "minimum": 0 }, "maxAttempts": { "type": "number", "minimum": 1 }, "nextAttemptAt": { "type": "string", "format": "date-time", "nullable": true }, "lastHttpStatus": { "type": "integer", "nullable": true }, "lastErrorClass": { "type": "string", "enum": [ "http_status", "redirect", "timeout", "network", "tls", "dns", "egress_refused", "gone" ], "nullable": true }, "test": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "failedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "eventId", "endpointId", "type", "mode", "status", "failureReason", "attempts", "maxAttempts", "nextAttemptAt", "lastHttpStatus", "lastErrorClass", "test", "createdAt", "deliveredAt", "failedAt" ] }, "notification.WebhookEndpointDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "type": "string", "nullable": true }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "events": { "description": "The subscription patterns.", "type": "array", "items": { "type": "string" } }, "resolvedTypes": { "description": "The catalogue types the patterns deliver today, under the capabilities of the member who wrote them.", "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "disabledCause": { "type": "string", "enum": [ "consecutive_failures", "gone", "manual", "live_access_revoked" ], "nullable": true }, "failingSince": { "type": "string", "format": "date-time", "nullable": true }, "consecutiveFailures": { "type": "number", "minimum": 0 }, "previousSecretExpiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Until when requests also carry a signature for the previous secret." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "description", "mode", "events", "resolvedTypes", "status", "disabledCause", "failingSince", "consecutiveFailures", "previousSecretExpiresAt", "createdAt", "updatedAt" ] }, "notification.WebhookEndpointSecretDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "type": "string", "nullable": true }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "events": { "description": "The subscription patterns.", "type": "array", "items": { "type": "string" } }, "resolvedTypes": { "description": "The catalogue types the patterns deliver today, under the capabilities of the member who wrote them.", "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "disabledCause": { "type": "string", "enum": [ "consecutive_failures", "gone", "manual", "live_access_revoked" ], "nullable": true }, "failingSince": { "type": "string", "format": "date-time", "nullable": true }, "consecutiveFailures": { "type": "number", "minimum": 0 }, "previousSecretExpiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Until when requests also carry a signature for the previous secret." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "`whsec_…` — store it now; no route returns it again." } }, "required": [ "id", "url", "description", "mode", "events", "resolvedTypes", "status", "disabledCause", "failingSince", "consecutiveFailures", "previousSecretExpiresAt", "createdAt", "updatedAt", "secret" ] }, "notification.WebhookEventDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The public event id (the envelope `id`)." }, "type": { "type": "string" }, "version": { "type": "number", "minimum": 1 }, "scope": { "type": "string", "enum": [ "mode", "live", "organization", "endpoint" ] }, "mode": { "type": "string", "enum": [ "sandbox", "live" ], "nullable": true, "description": "Null for an organisation-scoped event." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the fact happened." }, "data": { "type": "object", "additionalProperties": true, "description": "The type’s public `data`." }, "test": { "type": "boolean" }, "matchedEndpoints": { "type": "number", "minimum": 0 }, "receivedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "version", "scope", "mode", "createdAt", "data", "test", "matchedEndpoints", "receivedAt" ] }, "notification.WebhookEventTypeDto": { "type": "object", "properties": { "type": { "type": "string", "example": "invoice.signed" }, "version": { "type": "number", "minimum": 1 }, "family": { "type": "string" }, "scope": { "type": "string", "enum": [ "mode", "live", "organization", "endpoint" ] }, "status": { "type": "string", "enum": [ "available", "pending_source", "invoice", "future" ] }, "requiredCapability": { "type": "string", "example": "invoice.read" }, "subscribable": { "type": "boolean", "description": "Whether the caller holds the capability the type needs." } }, "required": [ "type", "version", "family", "scope", "status", "requiredCapability", "subscribable" ] }, "notification.WebhookTestResultDto": { "type": "object", "properties": { "deliveryId": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "test": { "type": "boolean", "enum": [ true ] } }, "required": [ "deliveryId", "eventId", "type" ] } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "A user access token." }, "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Yona API key: sk_test_… or sk_live_…" } } } }