{ "openapi": "3.0.1", "info": { "title": "eArhiva Integration API", "description": "Machine-to-machine surface for external API clients.", "version": "v1", "x-earhiva-release": "1.0.0" }, "paths": { "/api/integration/v1/codelists/{type}": { "get": { "tags": [ "IntegrationCodelists" ], "summary": "Returns the active entries of one code list.", "description": "These are the very values used internally, read for the tenant's UJP environment. A new\r\nentry appearing in a code list is not a breaking change.", "parameters": [ { "name": "type", "in": "path", "description": "One of the eleven supported code list types.", "required": true, "schema": { "type": "string" } }, { "name": "X-Software-Id", "in": "header", "description": "Identifier of the calling software, e.g. `SSBFocus/4.2.1`. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested type and its active entries.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationCodelistResponseDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationCodelistResponseDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationCodelistResponseDto" } } } }, "400": { "description": "`EARH-2021` — unknown code list type; the response lists the supported ones. Checked before\r\nthe tenant or the lookup service is touched.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "401": { "description": "The API key is missing, unknown, expired or revoked — `EARH-1001`, `EARH-1002`, `EARH-1003`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "403": { "description": "The caller's address is outside the allowed list, or the key does not carry the IntegrationApi scope — `EARH-1004`, `EARH-1005`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "429": { "description": "The traffic limit for this key has been reached — `EARH-1006`. The response carries `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "500": { "description": "Unexpected error on our side — `EARH-9000`. The body carries `eventId`; quote it when reporting the problem.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } } } } }, "/api/integration/v1/inbound": { "get": { "tags": [ "IntegrationInbound" ], "summary": "Lists inbound documents, newest first.", "description": "With `onlyNotImported=true` only documents that have not been acknowledged yet are returned.\r\nWithout the filter the acknowledged ones come back too, each with a visible `ackedAt`.", "parameters": [ { "name": "dateFrom", "in": "query", "description": "Lower bound on arrival time; omit for no lower bound.", "schema": { "type": "string", "format": "date-time" } }, { "name": "dateTo", "in": "query", "description": "Upper bound on arrival time; omit for no upper bound.", "schema": { "type": "string", "format": "date-time" } }, { "name": "senderEdb", "in": "query", "description": "Tax number of the sender.", "schema": { "type": "string" } }, { "name": "onlyNotImported", "in": "query", "description": "When true, only documents without an acknowledgement.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "1-based page index; defaults to 1.", "schema": { "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "Documents per page; defaults to 100, maximum 500.", "schema": { "type": "integer", "format": "int32" } }, { "name": "X-Software-Id", "in": "header", "description": "Identifier of the calling software, e.g. `SSBFocus/4.2.1`. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The page of documents; an empty result is 200 with `totalCount` 0.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationInboundListResponseDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationInboundListResponseDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationInboundListResponseDto" } } } }, "400": { "description": "`EARH-3005` — the requested page size exceeds the allowed one; the response names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "401": { "description": "The API key is missing, unknown, expired or revoked — `EARH-1001`, `EARH-1002`, `EARH-1003`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "403": { "description": "The caller's address is outside the allowed list, or the key does not carry the IntegrationApi scope — `EARH-1004`, `EARH-1005`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "429": { "description": "The traffic limit for this key has been reached — `EARH-1006`. The response carries `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "500": { "description": "Unexpected error on our side — `EARH-9000`. The body carries `eventId`; quote it when reporting the problem.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } } } } }, "/api/integration/v1/inbound/{docUid}": { "get": { "tags": [ "IntegrationInbound" ], "summary": "Returns one inbound document by its identifier.", "parameters": [ { "name": "docUid", "in": "path", "description": "Identifier of the document, as it appears in the list.", "required": true, "schema": { "type": "string" } }, { "name": "X-Software-Id", "in": "header", "description": "Identifier of the calling software, e.g. `SSBFocus/4.2.1`. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The document, including `ackedAt` when it was acknowledged.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationInboundDetailDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationInboundDetailDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationInboundDetailDto" } } } }, "404": { "description": "`EARH-3001` — no such document. An unknown identifier and a document belonging to another\r\ntenant give an identical answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "400": { "description": "The `X-Software-Id` header is missing — `EARH-1008`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "401": { "description": "The API key is missing, unknown, expired or revoked — `EARH-1001`, `EARH-1002`, `EARH-1003`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "403": { "description": "The caller's address is outside the allowed list, or the key does not carry the IntegrationApi scope — `EARH-1004`, `EARH-1005`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "429": { "description": "The traffic limit for this key has been reached — `EARH-1006`. The response carries `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "500": { "description": "Unexpected error on our side — `EARH-9000`. The body carries `eventId`; quote it when reporting the problem.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } } } } }, "/api/integration/v1/inbound/{docUid}/file": { "get": { "tags": [ "IntegrationInbound" ], "summary": "Downloads one representation of an inbound document.", "description": "`original` is always available — the file exactly as it arrived. `ubl` and `pdf` are served\r\nonly if the document arrived in that shape; a representation is never produced on demand.", "parameters": [ { "name": "docUid", "in": "path", "description": "Identifier of the document.", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "One of `original`, `ubl`, `pdf`.", "schema": { "type": "string" } }, { "name": "X-Software-Id", "in": "header", "description": "Identifier of the calling software, e.g. `SSBFocus/4.2.1`. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The stored bytes of the requested representation.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "`EARH-3001` — no such document; `EARH-3002` — the document exists but did not arrive in that\r\nshape. `original` keeps working in that case.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "400": { "description": "The `X-Software-Id` header is missing — `EARH-1008`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "401": { "description": "The API key is missing, unknown, expired or revoked — `EARH-1001`, `EARH-1002`, `EARH-1003`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "403": { "description": "The caller's address is outside the allowed list, or the key does not carry the IntegrationApi scope — `EARH-1004`, `EARH-1005`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "429": { "description": "The traffic limit for this key has been reached — `EARH-1006`. The response carries `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "500": { "description": "Unexpected error on our side — `EARH-9000`. The body carries `eventId`; quote it when reporting the problem.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } } } } }, "/api/integration/v1/inbound/{docUid}/ack": { "post": { "tags": [ "IntegrationInbound" ], "summary": "Acknowledges that an inbound document was taken over.", "description": "The document then stops appearing under `onlyNotImported=true`. Acknowledging again is not\r\nan error: the time of the first acknowledgement is returned unchanged. There is no way to\r\ntake an acknowledgement back in `v1`, and the acknowledgement tells the sender nothing.", "parameters": [ { "name": "docUid", "in": "path", "description": "Identifier of the document being acknowledged.", "required": true, "schema": { "type": "string" } }, { "name": "X-Software-Id", "in": "header", "description": "Identifier of the calling software, e.g. `SSBFocus/4.2.1`. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The acknowledgement stands; `ackedAt` is the time of the first one.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationAckResponseDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationAckResponseDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationAckResponseDto" } } } }, "404": { "description": "`EARH-3001` — no such document. An unknown identifier and a document belonging to another\r\ntenant give an identical answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "400": { "description": "The `X-Software-Id` header is missing — `EARH-1008`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "401": { "description": "The API key is missing, unknown, expired or revoked — `EARH-1001`, `EARH-1002`, `EARH-1003`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "403": { "description": "The caller's address is outside the allowed list, or the key does not carry the IntegrationApi scope — `EARH-1004`, `EARH-1005`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "429": { "description": "The traffic limit for this key has been reached — `EARH-1006`. The response carries `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "500": { "description": "Unexpected error on our side — `EARH-9000`. The body carries `eventId`; quote it when reporting the problem.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } } } } }, "/api/integration/v1/outbound": { "post": { "tags": [ "IntegrationOutbound" ], "summary": "Submits one UBL 2.1 document for delivery.", "description": "The response does not wait for processing: status `10` means \"received by us\". Repeating the\r\ncall with the same `X-Idempotency-Key` and the same body within one hour returns the same\r\n`docUid` with HTTP 200 instead of creating a second document.", "parameters": [ { "name": "X-Software-Id", "in": "header", "description": "Identifier of the calling software, e.g. `SSBFocus/4.2.1`. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.", "required": true, "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "description": "Client-chosen key that makes the submission repeatable. The same key with the same body within one hour returns the same docUid instead of creating a second document; the same key with a different body is rejected with EARH-2010. Missing means EARH-2013.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "One UBL 2.1 document as raw XML. Exactly one document per request — a payload carrying more is rejected with `EARH-2011`. The bytes are stored as received and are returned unchanged by `GET outbound/{docUid}/file?format=ubl`.", "content": { "application/xml": { "schema": { "type": "string", "description": "UBL 2.1 Invoice or CreditNote." } } }, "required": true }, "responses": { "201": { "description": "The document was accepted and now carries a `docUid`.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationSubmitResultDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationSubmitResultDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationSubmitResultDto" } } } }, "200": { "description": "The same key and body were already submitted; the original `docUid` is returned and\r\n`alreadyExisted` is `true`.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationSubmitResultDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationSubmitResultDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationSubmitResultDto" } } } }, "400": { "description": "The submission cannot be processed — `EARH-1007` (a tenant value in the body),\r\n`EARH-2001` (not well-formed XML), `EARH-2002` (not UBL 2.1), `EARH-2003` (no recipient),\r\n`EARH-2004` (malformed recipient tax number), `EARH-2005` (no document type),\r\n`EARH-2006` (no amount), `EARH-2011` (more than one document),\r\n`EARH-2013` (the `X-Idempotency-Key` header is missing).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "409": { "description": "`EARH-2010` — the same idempotency key was already used with different content;\r\n`EARH-9001` — outbound over the API is not enabled for this tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "413": { "description": "`EARH-2012` — the document exceeds the working size limit; the response names the allowed one.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "401": { "description": "The API key is missing, unknown, expired or revoked — `EARH-1001`, `EARH-1002`, `EARH-1003`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "403": { "description": "The caller's address is outside the allowed list, or the key does not carry the IntegrationApi scope — `EARH-1004`, `EARH-1005`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "429": { "description": "The traffic limit for this key has been reached — `EARH-1006`. The response carries `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "500": { "description": "Unexpected error on our side — `EARH-9000`. The body carries `eventId`; quote it when reporting the problem.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } } } }, "get": { "tags": [ "IntegrationOutbound" ], "summary": "Lists outbound documents, newest first.", "description": "The order is by creation time descending, and by identifier when two documents share the\r\nsame time — independent of the filter and of the page size. Documents created before the\r\nintegration surface existed carry no `docUid` and are neither returned nor counted.", "parameters": [ { "name": "dateFrom", "in": "query", "description": "Lower bound on creation time; omit for no lower bound.", "schema": { "type": "string", "format": "date-time" } }, { "name": "dateTo", "in": "query", "description": "Upper bound on creation time; omit for no upper bound.", "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "description": "Numeric status codes; repeat the parameter for more than one.", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } }, { "name": "partnerEdb", "in": "query", "description": "Tax number of the recipient.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "1-based page index; defaults to 1.", "schema": { "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "Documents per page; defaults to 100, maximum 500.", "schema": { "type": "integer", "format": "int32" } }, { "name": "X-Software-Id", "in": "header", "description": "Identifier of the calling software, e.g. `SSBFocus/4.2.1`. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The page of documents; an empty result is 200 with `totalCount` 0.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationOutboundListResponseDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationOutboundListResponseDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationOutboundListResponseDto" } } } }, "400": { "description": "`EARH-3005` — the requested page size exceeds the allowed one; the response names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "401": { "description": "The API key is missing, unknown, expired or revoked — `EARH-1001`, `EARH-1002`, `EARH-1003`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "403": { "description": "The caller's address is outside the allowed list, or the key does not carry the IntegrationApi scope — `EARH-1004`, `EARH-1005`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "429": { "description": "The traffic limit for this key has been reached — `EARH-1006`. The response carries `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "500": { "description": "Unexpected error on our side — `EARH-9000`. The body carries `eventId`; quote it when reporting the problem.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } } } } }, "/api/integration/v1/outbound/{docUid}": { "get": { "tags": [ "IntegrationOutbound" ], "summary": "Returns one outbound document by its identifier.", "parameters": [ { "name": "docUid", "in": "path", "description": "Identifier returned when the document was submitted.", "required": true, "schema": { "type": "string" } }, { "name": "X-Software-Id", "in": "header", "description": "Identifier of the calling software, e.g. `SSBFocus/4.2.1`. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The document, with the UJP answer in its own field.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationOutboundDetailDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationOutboundDetailDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationOutboundDetailDto" } } } }, "404": { "description": "`EARH-3001` — no such document. An unknown identifier and a document belonging to another\r\ntenant give an identical answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "400": { "description": "The `X-Software-Id` header is missing — `EARH-1008`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "401": { "description": "The API key is missing, unknown, expired or revoked — `EARH-1001`, `EARH-1002`, `EARH-1003`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "403": { "description": "The caller's address is outside the allowed list, or the key does not carry the IntegrationApi scope — `EARH-1004`, `EARH-1005`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "429": { "description": "The traffic limit for this key has been reached — `EARH-1006`. The response carries `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "500": { "description": "Unexpected error on our side — `EARH-9000`. The body carries `eventId`; quote it when reporting the problem.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } } } } }, "/api/integration/v1/outbound/{docUid}/file": { "get": { "tags": [ "IntegrationOutbound" ], "summary": "Downloads one representation of an outbound document.", "description": "Only what was supplied by the client (`ubl`, and `pdf` if one arrived with the document) or\r\nwhat UJP returned as the final document (`ujp`) is served. A representation that does not\r\nexist for that document is not produced on demand.", "parameters": [ { "name": "docUid", "in": "path", "description": "Identifier of the document.", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "One of `ubl`, `pdf`, `ujp`.", "schema": { "type": "string" } }, { "name": "X-Software-Id", "in": "header", "description": "Identifier of the calling software, e.g. `SSBFocus/4.2.1`. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The stored bytes of the requested representation.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "`EARH-3001` — no such document; `EARH-3002` — the document exists but that representation\r\ndoes not. The two outcomes are told apart by the code.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "400": { "description": "The `X-Software-Id` header is missing — `EARH-1008`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "401": { "description": "The API key is missing, unknown, expired or revoked — `EARH-1001`, `EARH-1002`, `EARH-1003`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "403": { "description": "The caller's address is outside the allowed list, or the key does not carry the IntegrationApi scope — `EARH-1004`, `EARH-1005`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "429": { "description": "The traffic limit for this key has been reached — `EARH-1006`. The response carries `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "500": { "description": "Unexpected error on our side — `EARH-9000`. The body carries `eventId`; quote it when reporting the problem.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } } } } }, "/api/integration/v1/outbound/{docUid}/history": { "get": { "tags": [ "IntegrationOutbound" ], "summary": "Returns the status history of an outbound document.", "description": "Failed attempts are included, not only the successful transitions.", "parameters": [ { "name": "docUid", "in": "path", "description": "Identifier of the document.", "required": true, "schema": { "type": "string" } }, { "name": "X-Software-Id", "in": "header", "description": "Identifier of the calling software, e.g. `SSBFocus/4.2.1`. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The transitions in chronological order.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationHistoryResponseDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationHistoryResponseDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationHistoryResponseDto" } } } }, "404": { "description": "`EARH-3001` — no such document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "400": { "description": "The `X-Software-Id` header is missing — `EARH-1008`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "401": { "description": "The API key is missing, unknown, expired or revoked — `EARH-1001`, `EARH-1002`, `EARH-1003`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "403": { "description": "The caller's address is outside the allowed list, or the key does not carry the IntegrationApi scope — `EARH-1004`, `EARH-1005`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "429": { "description": "The traffic limit for this key has been reached — `EARH-1006`. The response carries `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "500": { "description": "Unexpected error on our side — `EARH-9000`. The body carries `eventId`; quote it when reporting the problem.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } } } } }, "/api/integration/v1/outbound/{docUid}/cancel": { "post": { "tags": [ "IntegrationOutbound" ], "summary": "Cancels an outbound document.", "description": "Cancelling does not delete: the document keeps being returned by its identifier, and the\r\ncancellation itself stays in the history.", "parameters": [ { "name": "docUid", "in": "path", "description": "Identifier of the document.", "required": true, "schema": { "type": "string" } }, { "name": "X-Software-Id", "in": "header", "description": "Identifier of the calling software, e.g. `SSBFocus/4.2.1`. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The document is now in status 60 (Cancelled).", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationCancelResponseDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationCancelResponseDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationCancelResponseDto" } } } }, "404": { "description": "`EARH-3001` — no such document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "409": { "description": "`EARH-3004` — already cancelled; `EARH-3003` — the current status does not allow cancelling.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "400": { "description": "The `X-Software-Id` header is missing — `EARH-1008`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "401": { "description": "The API key is missing, unknown, expired or revoked — `EARH-1001`, `EARH-1002`, `EARH-1003`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "403": { "description": "The caller's address is outside the allowed list, or the key does not carry the IntegrationApi scope — `EARH-1004`, `EARH-1005`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "429": { "description": "The traffic limit for this key has been reached — `EARH-1006`. The response carries `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "500": { "description": "Unexpected error on our side — `EARH-9000`. The body carries `eventId`; quote it when reporting the problem.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } } } } }, "/api/integration/v1/ping": { "get": { "tags": [ "IntegrationPing" ], "summary": "Confirms that the service is reachable and that the supplied API key is valid.", "parameters": [ { "name": "X-Software-Id", "in": "header", "description": "Identifier of the calling software, e.g. `SSBFocus/4.2.1`. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The service is up and the key is valid.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationPingDto" } }, "application/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationPingDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationPingDto" } } } }, "400": { "description": "The `X-Software-Id` header is missing — `EARH-1008`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "401": { "description": "The API key is missing, unknown, expired or revoked — `EARH-1001`, `EARH-1002`, `EARH-1003`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "403": { "description": "The caller's address is outside the allowed list, or the key does not carry the IntegrationApi scope — `EARH-1004`, `EARH-1005`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "429": { "description": "The traffic limit for this key has been reached — `EARH-1006`. The response carries `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } }, "500": { "description": "Unexpected error on our side — `EARH-9000`. The body carries `eventId`; quote it when reporting the problem.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/eArhivaCore.Api.Filters.IntegrationProblemDetails" } } } } } } } }, "components": { "schemas": { "eArhivaCore.Api.Filters.IntegrationProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32" }, "detail": { "type": "string", "nullable": true }, "code": { "type": "string", "nullable": true }, "eventId": { "type": "string", "description": "Само кај `EARH-9000` (§4.5). Се пополнува од ИСТИОТ `errorRef` што\r\n`ErrorRefFilter` го запишува во логот, за да не постојат два броја за ист настан.", "nullable": true } }, "additionalProperties": false, "description": "Телото на грешка за интеграциската површина — RFC 7807 `ProblemDetails` со едно проширување,\r\nполето `code` (F3.2-ApiDesign.md §4.5).\r\n \r\n⛔ Ова НЕ е Microsoft.AspNetCore.Mvc.ProblemDetails од MVC, и тоа е намерно. Постоечкиот\r\n`ErrorRefFilter` (SSBCore) на секој одговор со статус ≥ 500 го серијализира телото со\r\n`JsonSerializer.Serialize` БЕЗ опции, го чита назад како `Dictionary`\r\nи го враќа тој речник како ново тело. Стандардниот Microsoft.AspNetCore.Mvc.ProblemDetails при таква\r\nсеријализација дава клучеви со голема почетна буква (`Type`, `Title`, `Status`),\r\nа речникот потоа излегува навон токму со тие клучеви — значи договорот од §4.5 би бил скршен\r\nсамо за одговорите со 500. Со изречни System.Text.Json.Serialization.JsonPropertyNameAttribute имињата се\r\nисти пред и по тој премин, па филтерот „само додава клуч\" (`errorRef`), како што бара §4.5." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationAckResponseDto": { "type": "object", "properties": { "docUid": { "type": "string", "description": "Identifier of the acknowledged document.", "nullable": true }, "ackedAt": { "type": "string", "description": "Time of the FIRST acknowledgement; a repeated call does not move it.", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Response of `POST /api/integration/v1/inbound/{docUid}/ack` (§5.11)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationCancelResponseDto": { "type": "object", "properties": { "docUid": { "type": "string", "description": "Identifier of the cancelled document; it stays retrievable.", "nullable": true }, "status": { "type": "integer", "description": "Status after cancellation — always 60 (Cancelled).", "format": "int32" } }, "additionalProperties": false, "description": "Response of `POST /api/integration/v1/outbound/{docUid}/cancel` (§5.8)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationCodelistItemDto": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Една ставка во кодна листа од GET /api/integration/v1/codelists/{type} (§5.12)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationCodelistResponseDto": { "type": "object", "properties": { "type": { "type": "string", "description": "The requested codelist type, echoed back.", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationCodelistItemDto" }, "description": "Active entries of that codelist for the tenant's UJP environment.", "nullable": true } }, "additionalProperties": false, "description": "Response of `GET /api/integration/v1/codelists/{type}` (§5.12)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationHistoryResponseDto": { "type": "object", "properties": { "docUid": { "type": "string", "description": "Identifier of the document the history belongs to.", "nullable": true }, "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationTransitionDto" }, "description": "Status transitions in chronological order, failed attempts included.", "nullable": true } }, "additionalProperties": false, "description": "Response of `GET /api/integration/v1/outbound/{docUid}/history` (§5.7)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationInboundDetailDto": { "type": "object", "properties": { "docUid": { "type": "string", "nullable": true }, "receivedAt": { "type": "string", "format": "date-time" }, "senderName": { "type": "string", "nullable": true }, "senderEdb": { "type": "string", "nullable": true }, "ackedAt": { "type": "string", "format": "date-time", "nullable": true }, "documentNumber": { "type": "string", "nullable": true }, "amount": { "type": "number", "format": "double", "nullable": true }, "currency": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Одговор на GET /api/integration/v1/inbound/{docUid} (симетрично на IntegrationOutboundDetailDto, без Ujp)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationInboundListItemDto": { "type": "object", "properties": { "docUid": { "type": "string", "nullable": true }, "receivedAt": { "type": "string", "format": "date-time" }, "senderName": { "type": "string", "nullable": true }, "senderEdb": { "type": "string", "nullable": true }, "ackedAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Една ставка во листата од GET /api/integration/v1/inbound (§5.9)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationInboundListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationInboundListItemDto" }, "description": "Documents on the requested page, newest first.", "nullable": true }, "totalCount": { "type": "integer", "description": "Number of documents matching the filter across all pages.", "format": "int32" }, "page": { "type": "integer", "description": "1-based index of the returned page.", "format": "int32" }, "pageSize": { "type": "integer", "description": "Number of documents per page (default 100, maximum 500).", "format": "int32" }, "totalPages": { "type": "integer", "description": "Number of pages available for the current filter and page size.", "format": "int32" } }, "additionalProperties": false, "description": "Response of `GET /api/integration/v1/inbound` (§5.9)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationOutboundDetailDto": { "type": "object", "properties": { "docUid": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32" }, "failureCode": { "type": "string", "nullable": true }, "failureMessage": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "partnerEdb": { "type": "string", "nullable": true }, "documentNumber": { "type": "string", "nullable": true }, "amount": { "type": "number", "format": "double", "nullable": true }, "currency": { "type": "string", "nullable": true }, "ujp": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationUjpDto" } }, "additionalProperties": false, "description": "Одговор на GET /api/integration/v1/outbound/{docUid} (§5.5)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationOutboundListItemDto": { "type": "object", "properties": { "docUid": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "partnerEdb": { "type": "string", "nullable": true }, "documentNumber": { "type": "string", "nullable": true }, "amount": { "type": "number", "format": "double", "nullable": true }, "currency": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Една ставка во листата од GET /api/integration/v1/outbound (§5.4)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationOutboundListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/eArhivaCore.Contracts.Integration.DTOs.IntegrationOutboundListItemDto" }, "description": "Documents on the requested page, newest first.", "nullable": true }, "totalCount": { "type": "integer", "description": "Number of documents matching the filter across all pages.", "format": "int32" }, "page": { "type": "integer", "description": "1-based index of the returned page.", "format": "int32" }, "pageSize": { "type": "integer", "description": "Number of documents per page (default 100, maximum 500).", "format": "int32" }, "totalPages": { "type": "integer", "description": "Number of pages available for the current filter and page size.", "format": "int32" } }, "additionalProperties": false, "description": "Response of `GET /api/integration/v1/outbound` (§5.4)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationPingDto": { "type": "object", "properties": { "ok": { "type": "boolean" }, "keyValid": { "type": "boolean" }, "serverTime": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "Одговор на GET /api/integration/v1/ping (§5.2)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationSubmitResultDto": { "type": "object", "properties": { "docUid": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32" }, "receivedAt": { "type": "string", "format": "date-time" }, "alreadyExisted": { "type": "boolean" } }, "additionalProperties": false, "description": "Одговор на POST /api/integration/v1/outbound (§5.3)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationTransitionDto": { "type": "object", "properties": { "status": { "type": "integer", "format": "int32" }, "at": { "type": "string", "format": "date-time" }, "failureCode": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Една промена во историјата од GET /api/integration/v1/outbound/{docUid}/history (§5.7)." }, "eArhivaCore.Contracts.Integration.DTOs.IntegrationUjpDto": { "type": "object", "properties": { "state": { "type": "string", "nullable": true }, "code": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "checkedAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Одговор од УЈП, присутен во IntegrationOutboundDetailDto (§5.5)." } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "Tenant API key scoped to IntegrationApi.", "name": "X-Api-Key", "in": "header" } } }, "security": [ { "ApiKey": [ ] } ], "tags": [ { "name": "IntegrationCodelists", "description": "Reading the code lists the surface accepts and returns." }, { "name": "IntegrationInbound", "description": "Pulling inbound documents and acknowledging that they were taken over." }, { "name": "IntegrationOutbound", "description": "Submitting outbound documents and following what happens to them." }, { "name": "IntegrationPing", "description": "Connectivity check for the integration surface." } ] }