{ "openapi": "3.0.1", "info": { "title": "Partners Dashboard API", "version": "v2" }, "paths": { "/api/EgsUnits/CreateNewEgsUnit": { "post": { "tags": [ "EgsUnits" ], "summary": "Initiates the creation of a new Egs Unit.", "requestBody": { "description": "The command to create a new company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNewEgsUnitCommand" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateNewEgsUnitCommand" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateNewEgsUnitCommand" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNewEgsUnitResponse" }, "example": {"clientId":"038158dd-4e2a-4b9d-bd5b-960091bf484b","clientSecret":"1b169847-50a3-4477-809c-a7b58ff301e1","egsUnitId":"84827566-0483-4903-ac45-1fc9221289c6"} }, "text/plain": { "schema": { "$ref": "#/components/schemas/CreateNewEgsUnitResponse" }, "example": {"clientId":"038158dd-4e2a-4b9d-bd5b-960091bf484b","clientSecret":"1b169847-50a3-4477-809c-a7b58ff301e1","egsUnitId":"84827566-0483-4903-ac45-1fc9221289c6"} } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "string" }, "example": "You must login using https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit if you are an EGS unit, or https://zatcaapi.avtax.net/api/UserAuthentication/Login as partner." }, "text/plain": { "schema": { "type": "string" }, "example": "You must login using https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit if you are an EGS unit, or https://zatcaapi.avtax.net/api/UserAuthentication/Login as partner." } } } } } }, "/api/EgsUnits/GetEgsUnits": { "get": { "tags": [ "EgsUnits" ], "summary": "Retrieves the list of Egs Units associated with the current user.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EgsUnits" }, "example": [{"clientId":"c384f347-03f3-4ab3-b10a-c9a3686a20c5","clientSecret":"26ece4a8-b6f3-44e9-93c3-0b1c8d822853","egsUnitId":"1f147c12-1973-4274-8660-f3f5f7622a30","organizationName":"Company Name 1","vatNumber":"3000000000003","additionalIDSchemeID":"None","schemeIDName":"Commercial Registration Number","additionalID":"1221356","isProduction":true,"maximumNumberOfInvoicesPerMonth":10000,"rateLimitPerMinute":50},{"clientId":"f1148f11-0431-46aa-a128-fdb9dce2b6c5","clientSecret":"60a56671-502e-422a-9b65-45d9989a8353","egsUnitId":"ecfd9f47-2f74-4822-954b-4ae46a18fbec","organizationName":"Company Name 2","vatNumber":"3000000000003","additionalIDSchemeID":"None","schemeIDName":"Commercial Registration Number","additionalID":"1221356","isProduction":true,"maximumNumberOfInvoicesPerMonth":10000,"rateLimitPerMinute":50},{"clientId":"f28add1b-dfaa-4dc2-8e76-31c900ebf311","clientSecret":"6a8d56ce-98cf-4019-b2cd-ef86e98c3a84","egsUnitId":"e2410271-184a-4901-9b2e-f83d37283feb","organizationName":"Company Name 3","vatNumber":"3000000000003","additionalIDSchemeID":"None","schemeIDName":"Commercial Registration Number","additionalID":"1221356","isProduction":true,"maximumNumberOfInvoicesPerMonth":10000,"rateLimitPerMinute":50},{"clientId":"9849d5d2-e420-43e4-9359-8afae6526280","clientSecret":"0c9378c2-d775-4762-a4eb-24926da3da00","egsUnitId":"2cb87898-db4f-43af-aef2-a1822584269f","organizationName":"Company Name 4","vatNumber":"3000000000003","additionalIDSchemeID":"None","schemeIDName":"Commercial Registration Number","additionalID":"1221356","isProduction":true,"maximumNumberOfInvoicesPerMonth":10000,"rateLimitPerMinute":50},{"clientId":"80c6976e-1087-4af1-9683-610ad0c2cad3","clientSecret":"b8740891-af8a-482b-9422-668b055725a7","egsUnitId":"490a6e50-737c-4d6c-8c54-18a0375a0e4b","organizationName":"Company Name 5","vatNumber":"3000000000003","additionalIDSchemeID":"None","schemeIDName":"Commercial Registration Number","additionalID":"1221356","isProduction":true,"maximumNumberOfInvoicesPerMonth":10000,"rateLimitPerMinute":50}] }, "text/plain": { "schema": { "$ref": "#/components/schemas/EgsUnits" }, "example": [{"clientId":"c384f347-03f3-4ab3-b10a-c9a3686a20c5","clientSecret":"26ece4a8-b6f3-44e9-93c3-0b1c8d822853","egsUnitId":"1f147c12-1973-4274-8660-f3f5f7622a30","organizationName":"Company Name 1","vatNumber":"3000000000003","additionalIDSchemeID":"None","schemeIDName":"Commercial Registration Number","additionalID":"1221356","isProduction":true,"maximumNumberOfInvoicesPerMonth":10000,"rateLimitPerMinute":50},{"clientId":"f1148f11-0431-46aa-a128-fdb9dce2b6c5","clientSecret":"60a56671-502e-422a-9b65-45d9989a8353","egsUnitId":"ecfd9f47-2f74-4822-954b-4ae46a18fbec","organizationName":"Company Name 2","vatNumber":"3000000000003","additionalIDSchemeID":"None","schemeIDName":"Commercial Registration Number","additionalID":"1221356","isProduction":true,"maximumNumberOfInvoicesPerMonth":10000,"rateLimitPerMinute":50},{"clientId":"f28add1b-dfaa-4dc2-8e76-31c900ebf311","clientSecret":"6a8d56ce-98cf-4019-b2cd-ef86e98c3a84","egsUnitId":"e2410271-184a-4901-9b2e-f83d37283feb","organizationName":"Company Name 3","vatNumber":"3000000000003","additionalIDSchemeID":"None","schemeIDName":"Commercial Registration Number","additionalID":"1221356","isProduction":true,"maximumNumberOfInvoicesPerMonth":10000,"rateLimitPerMinute":50},{"clientId":"9849d5d2-e420-43e4-9359-8afae6526280","clientSecret":"0c9378c2-d775-4762-a4eb-24926da3da00","egsUnitId":"2cb87898-db4f-43af-aef2-a1822584269f","organizationName":"Company Name 4","vatNumber":"3000000000003","additionalIDSchemeID":"None","schemeIDName":"Commercial Registration Number","additionalID":"1221356","isProduction":true,"maximumNumberOfInvoicesPerMonth":10000,"rateLimitPerMinute":50},{"clientId":"80c6976e-1087-4af1-9683-610ad0c2cad3","clientSecret":"b8740891-af8a-482b-9422-668b055725a7","egsUnitId":"490a6e50-737c-4d6c-8c54-18a0375a0e4b","organizationName":"Company Name 5","vatNumber":"3000000000003","additionalIDSchemeID":"None","schemeIDName":"Commercial Registration Number","additionalID":"1221356","isProduction":true,"maximumNumberOfInvoicesPerMonth":10000,"rateLimitPerMinute":50}] } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "string" }, "example": "You must login using https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit if you are an EGS unit, or https://zatcaapi.avtax.net/api/UserAuthentication/Login as partner." }, "text/plain": { "schema": { "type": "string" }, "example": "You must login using https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit if you are an EGS unit, or https://zatcaapi.avtax.net/api/UserAuthentication/Login as partner." } } } } } }, "/api/EgsUnits/{egsUnitId}/revoke": { "post": { "tags": [ "EgsUnits" ], "summary": "Revokes the secret associated with a specific Egs Unit.", "description": "This endpoint allows the partner to revoke the secret key for an Egs Unit identified by its ID.\r\nRevoking the secret will invalidate the current key, preventing further access using that key.\r\n\r\nThe user must be authenticated and authorized as a partner to perform this operation.", "parameters": [ { "name": "egsUnitId", "in": "path", "description": "The unique identifier of the Egs Unit for which the secret should be revoked.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeEgsSecretResponse" }, "example": {"clientSecret":"new-client-secret-12345","egsUnitId":"egsunit-id-67890"} }, "text/plain": { "schema": { "$ref": "#/components/schemas/RevokeEgsSecretResponse" }, "example": {"clientSecret":"new-client-secret-12345","egsUnitId":"egsunit-id-67890"} } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "string" }, "example": "You must login using https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit if you are an EGS unit, or https://zatcaapi.avtax.net/api/UserAuthentication/Login as partner." }, "text/plain": { "schema": { "type": "string" }, "example": "You must login using https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit if you are an EGS unit, or https://zatcaapi.avtax.net/api/UserAuthentication/Login as partner." } } } } } }, "/api/Partner/CreateAccount": { "post": { "tags": [ "Partner" ], "summary": "Creates a new user and returns a JWT upon successful creation.", "requestBody": { "description": "The Request body containing the details of the new user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNewUserCommand" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateNewUserCommand" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateNewUserCommand" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/Partner/Login": { "post": { "tags": [ "Partner" ], "summary": "Endpoint for Partner Account Authentication", "description": "This endpoint, `Login`, is specifically designed for partner accounts. It provides a secure method for partners to authenticate themselves and gain access to the system.\r\n \r\nAs a partner, you are required to provide your registered email and password. Upon successful authentication, you will be able to access the `EgsUnits` endpoints.\r\n \r\nPlease note that the security of your account is paramount. Ensure that your credentials are kept confidential and secure.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginCommand" } }, "text/json": { "schema": { "$ref": "#/components/schemas/LoginCommand" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/LoginCommand" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/Partner/ChangePassword": { "post": { "tags": [ "Partner" ], "summary": "Endpoint for Changing Partner Account Password", "description": "This `ChangePassword` endpoint is designed to provide a secure method for partners to change their account password. \r\n \r\nAs a partner, you are required to be authenticated and authorized to access this endpoint. Once authenticated, you can use this endpoint to change your password, enhancing the security of your account.\r\n \r\nPlease note that it's important to choose a strong password and keep it confidential to protect your account.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordCommand" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordCommand" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ChangePasswordCommand" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/Partner/ResetPassword": { "post": { "tags": [ "Partner" ], "summary": "Endpoint for Resetting User Password", "description": "This `ResetPassword` endpoint allows partners to reset their password by providing their email address. \r\nA reset link will be sent to the provided email if it exists in our system.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordCommand" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordCommand" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ResetPasswordCommand" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/Partner/FinalizePasswordReset": { "post": { "tags": [ "Partner" ], "summary": "Endpoint for Finalizing Password Reset", "description": "This `FinalizePasswordReset` endpoint allows users to finalize their password reset by providing their email,\r\nreset token, and new password.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinalizePasswordResetCommand" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FinalizePasswordResetCommand" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FinalizePasswordResetCommand" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/Partner/GetEgsUnitStatistics": { "get": { "tags": [ "Partner" ], "summary": "Endpoint for retrieving statistics on EgsUnits and their invoices.", "description": "This endpoint returns the number of submitted EgsUnits along with the count of \r\nSimplified and Standard invoices for each EgsUnit.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EgsUnitStatisticsDto" } }, "example": [{"egsUnitId":"egs-unit-1","egsUnitName":"Example EGS Unit 1","simplifiedInvoiceCount":5,"standardInvoiceCount":10,"totalInvoices":15,"totalAmountInvoiced":1500.00,"averageInvoiceAmount":150.00,"lastInvoiceDate":"2026-04-16T10:42:57.5108383Z","isProduction":true},{"egsUnitId":"egs-unit-2","egsUnitName":"Example EGS Unit 2","simplifiedInvoiceCount":3,"standardInvoiceCount":7,"totalInvoices":10,"totalAmountInvoiced":800.00,"averageInvoiceAmount":114.29,"lastInvoiceDate":"2026-04-11T10:42:57.5108413Z","isProduction":false}] }, "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EgsUnitStatisticsDto" } }, "example": [{"egsUnitId":"egs-unit-1","egsUnitName":"Example EGS Unit 1","simplifiedInvoiceCount":5,"standardInvoiceCount":10,"totalInvoices":15,"totalAmountInvoiced":1500.00,"averageInvoiceAmount":150.00,"lastInvoiceDate":"2026-04-16T10:42:57.5108383Z","isProduction":true},{"egsUnitId":"egs-unit-2","egsUnitName":"Example EGS Unit 2","simplifiedInvoiceCount":3,"standardInvoiceCount":7,"totalInvoices":10,"totalAmountInvoiced":800.00,"averageInvoiceAmount":114.29,"lastInvoiceDate":"2026-04-11T10:42:57.5108413Z","isProduction":false}] } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "string" }, "example": "You must login using https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit if you are an EGS unit, or https://zatcaapi.avtax.net/api/UserAuthentication/Login as partner." }, "text/plain": { "schema": { "type": "string" }, "example": "You must login using https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit if you are an EGS unit, or https://zatcaapi.avtax.net/api/UserAuthentication/Login as partner." } } } } } }, "/api/Partner/GetEgsUnitMonthlyInvoiceStatistics/egsunit/{egsUnitId}/monthly-statistics": { "get": { "tags": [ "Partner" ], "summary": "Get monthly invoice statistics for an EgsUnit.", "description": "This endpoint returns the count of invoices and total amounts grouped by month for a given EgsUnit.", "parameters": [ { "name": "egsUnitId", "in": "path", "description": "The ID of the EgsUnit.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MonthlyInvoiceStatisticsDto" } }, "example": [{"year":2024,"month":1,"invoiceCount":120,"totalAmount":50000},{"year":2024,"month":2,"invoiceCount":95,"totalAmount":45000}] }, "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MonthlyInvoiceStatisticsDto" } }, "example": [{"year":2024,"month":1,"invoiceCount":120,"totalAmount":50000},{"year":2024,"month":2,"invoiceCount":95,"totalAmount":45000}] } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "string" }, "example": "You must login using https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit if you are an EGS unit, or https://zatcaapi.avtax.net/api/UserAuthentication/Login as partner." }, "text/plain": { "schema": { "type": "string" }, "example": "You must login using https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit if you are an EGS unit, or https://zatcaapi.avtax.net/api/UserAuthentication/Login as partner." } } } } } } }, "components": { "schemas": { "AdditionalIDScheme": { "enum": [ "None", "CRN", "MOM", "MLS", "Number700", "SAG", "OTH", "TIN", "NAT" ], "type": "string" }, "ChangePasswordCommand": { "type": "object", "properties": { "currrentPassword": { "type": "string", "nullable": true }, "newPassword": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CreateNewEgsUnitCommand": { "required": [ "address" ], "type": "object", "properties": { "commonName": { "type": "string", "description": "Provided by the Taxpayer for each Solution unit: Unique Name or Asset Tracking Number of the Solution Unit", "default": "Default Common Name", "nullable": true }, "organizationName": { "type": "string", "default": "Default Organization Name", "nullable": true }, "organizationUnitName": { "type": "string", "default": "Default Organization Unit Name", "nullable": true }, "serialNumber": { "type": "string", "default": "1-Manufacturer or Solution Provider Name|2-Model or Version|3-SerialNumber", "nullable": true }, "vatNumber": { "type": "string", "default": "300075588700003", "nullable": true }, "additionalID": { "type": "string", "nullable": true }, "additionalIDSchemeID": { "$ref": "#/components/schemas/AdditionalIDScheme" }, "invoiceType": { "type": "string", "default": "1100", "nullable": true }, "industry": { "type": "string", "default": "Default Industry", "nullable": true }, "isProduction": { "type": "boolean", "default": false }, "address": { "$ref": "#/components/schemas/PartyPostalAddress" }, "otp": { "type": "string", "default": "537888", "nullable": true } }, "additionalProperties": false }, "CreateNewEgsUnitResponse": { "type": "object", "properties": { "clientId": { "type": "string", "nullable": true }, "clientSecret": { "type": "string", "nullable": true }, "egsUnitId": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CreateNewUserCommand": { "type": "object", "properties": { "fullName": { "type": "string", "default": "John Doe", "nullable": true }, "email": { "type": "string", "default": "johndoe@example.com", "nullable": true }, "phoneNumber": { "type": "string", "default": "+1234567890", "nullable": true }, "password": { "type": "string", "nullable": true } }, "additionalProperties": false }, "EgsUnitStatisticsDto": { "type": "object", "properties": { "egsUnitId": { "type": "string", "description": "Unique identifier for the EgsUnit.", "nullable": true }, "egsUnitName": { "type": "string", "description": "Name or description of the EgsUnit.", "nullable": true }, "simplifiedInvoiceCount": { "type": "integer", "description": "Count of Simplified invoices.", "format": "int32" }, "standardInvoiceCount": { "type": "integer", "description": "Count of Standard invoices.", "format": "int32" }, "totalInvoices": { "type": "integer", "description": "Total number of invoices for this EgsUnit, calculated as the sum of \r\nSimplifiedInvoiceCount and StandardInvoiceCount.", "format": "int32", "readOnly": true }, "totalAmountInvoiced": { "type": "number", "description": "Total amount invoiced for both Simplified and Standard invoices.", "format": "double" }, "averageInvoiceAmount": { "type": "number", "description": "Average amount per invoice, calculated as TotalAmountInvoiced divided by TotalInvoices.", "format": "double" }, "lastInvoiceDate": { "type": "string", "description": "Date when the last invoice was submitted for this EgsUnit.", "format": "date-time", "nullable": true }, "isProduction": { "type": "boolean", "description": "Indicates whether this EgsUnit is in production." } }, "additionalProperties": false, "description": "Represents the statistics for a single EgsUnit, including details about its invoices." }, "EgsUnits": { "type": "object", "properties": { "clientId": { "type": "string", "nullable": true }, "clientSecret": { "type": "string", "nullable": true }, "egsUnitId": { "type": "string", "nullable": true }, "organizationName": { "type": "string", "nullable": true }, "vatNumber": { "type": "string", "nullable": true }, "additionalIDSchemeID": { "type": "string", "nullable": true }, "schemeIDName": { "type": "string", "nullable": true }, "additionalID": { "type": "string", "nullable": true }, "isProduction": { "type": "boolean" }, "maximumNumberOfInvoicesPerMonth": { "type": "integer", "format": "int32" }, "rateLimitPerMinute": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "FinalizePasswordResetCommand": { "type": "object", "properties": { "email": { "type": "string", "nullable": true }, "token": { "type": "string", "nullable": true }, "newPassword": { "type": "string", "nullable": true } }, "additionalProperties": false }, "LoginCommand": { "type": "object", "properties": { "email": { "type": "string", "nullable": true }, "password": { "type": "string", "nullable": true } }, "additionalProperties": false }, "MonthlyInvoiceStatisticsDto": { "type": "object", "properties": { "year": { "type": "integer", "format": "int32" }, "month": { "type": "integer", "format": "int32" }, "invoiceCount": { "type": "integer", "format": "int32" }, "totalAmount": { "type": "number", "format": "double" } }, "additionalProperties": false }, "PartyPostalAddress": { "type": "object", "properties": { "streetName": { "maxLength": 127, "minLength": 1, "type": "string", "description": "The street name of the address.", "default": "شارع الأمير محمد بن عبد العزيز", "nullable": true }, "additionalStreetName": { "type": "string", "description": "Any additional information about the street name.", "default": "الرياض", "nullable": true }, "buildingNumber": { "type": "string", "description": "The building number of the address.", "default": "1234", "nullable": true }, "plotIdentification": { "type": "string", "description": "The plot identification number of the address.", "default": "5678", "nullable": true }, "citySubdivisionName": { "type": "string", "description": "The subdivision name of the city for the address.", "default": "الرياض", "nullable": true }, "cityName": { "type": "string", "description": "The city name of the address.", "default": "الرياض", "nullable": true }, "postalZone": { "maxLength": 5, "type": "string", "description": "The postal zone (or zip code) of the address.", "default": "11564", "nullable": true }, "countrySubentity": { "type": "string", "description": "The subentity of the country for the address.", "default": "منطقة الرياض", "nullable": true }, "country": { "maxLength": 2, "type": "string", "description": "The country of the address. This property accepts only ISO 3166-1 alpha-2 country codes (e.g., \"SA\" for Saudi Arabia).", "default": "SA", "nullable": true } }, "additionalProperties": false }, "ResetPasswordCommand": { "type": "object", "properties": { "email": { "type": "string", "nullable": true } }, "additionalProperties": false }, "RevokeEgsSecretResponse": { "type": "object", "properties": { "clientSecret": { "type": "string", "description": "The newly generated client secret.", "nullable": true }, "egsUnitId": { "type": "string", "description": "The unique identifier of the Egs Unit.", "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "Bearer": { "type": "apiKey", "description": "JSON Web Token based security. Obtain a token from /UserAuthentication/Login", "name": "Authorization", "in": "header" } } }, "security": [ { "Bearer": [ ] } ] }