{ "openapi": "3.0.1", "info": { "title": "Apps Valley Zatca integration", "description": "The Apps Valley Zatca Integration API serves as a seamless bridge between taxpayer systems and ZATCA. It simplifies the complexities of integrating with ZATCA by accepting a simple JSON object, processing it to meet ZATCA's requirements, and validating the invoice through over 100 validation steps before submission. The API ensures that all invoices are compliant with ZATCA's standards, thereby providing a smooth and efficient way to handle tax reporting. The response from ZATCA is returned to the user, providing a complete end-to-end solution for tax invoice management.", "contact": { "name": "Apps Valley", "email": "info@apps-valley.net" }, "version": "v1" }, "paths": { "/api/Invoice/SubmitInvoice": { "post": { "tags": [ "Invoice" ], "summary": "Endpoint for EGS Units to Submit Invoices", "description": "Welcome to the `SubmitInvoice` endpoint. This endpoint is specifically designed for authenticated EGS units to submit invoices of any type to ZATCA.\r\n \r\nAs an EGS unit, after successfully authenticating using the `LoginAsEgsUnit` endpoint and obtaining a bearer token, you can use this endpoint to submit invoices. The invoice data should be provided in the `SubmitInvoiceCommand` parameter.\r\n \r\nThis process ensures a secure and efficient way for EGS units to send invoices to ZATCA. Please note that the bearer token must be included in the Authorization header of the request.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitInvoiceCommand" }, "example": {"validateWarnings":true,"documentType":"TaxInvoice","invoiceIndicator":"Nominal","currency":"SAR","exchangeRate":null,"documentIssueDateTime":"2026-04-21T14:34:39.9513116","supplyDate":"2026-04-21T14:34:39.9513122","buyer":{"buyerAddress":{"streetName":null,"additionalStreetName":null,"buildingNumber":null,"plotIdentification":null,"citySubdivisionName":null,"cityName":"الرياض","postalZone":null,"countrySubentity":null,"country":null},"buyerName":"Taj Al Mulook General Trading LLC","buyerVatId":"310285784400003","additionalIDSchemeID":"None","additionalCustomerID":null},"documentLineItems":[{"lineItemName":"POLYETHYLENE HDPE HHM TR - 131","lineItemPrice":3950,"lineItemQty":27.5,"discountOnLineItem":0,"allowanceCode":null,"taxCategoryCode":"Z","taxReasonCode":"VATEX_SA_32","taxReasonDescription":null,"vatRateOnLineItem":0},{"lineItemName":"POLYETHYLENE HDPE HHM TR - 132","lineItemPrice":3950,"lineItemQty":27.5,"discountOnLineItem":0,"allowanceCode":null,"taxCategoryCode":"S","taxReasonCode":"None","taxReasonDescription":null,"vatRateOnLineItem":15}],"referenceId":null,"documentId":"7788","notes":null,"orderReferenceId":null,"documentAllowanceOrChange":[{"allowanceChargeReasonCode":"95","amount":10,"taxCategoryCode":"S","taxReasonCode":"None","vatRate":15}],"invoiceTypeReason":null,"payment":{"paymentMethod":"InCash","paymentAccountIdentifier":null,"paymentNote":null},"prepaymentDetails":[{"sequentialInvoiceUUID":"892a7039-d5bd-47e9-8f70-7fe44ad15ce9"}]} }, "text/json": { "schema": { "$ref": "#/components/schemas/SubmitInvoiceCommand" }, "example": {"validateWarnings":true,"documentType":"TaxInvoice","invoiceIndicator":"Nominal","currency":"SAR","exchangeRate":null,"documentIssueDateTime":"2026-04-21T14:34:39.9513116","supplyDate":"2026-04-21T14:34:39.9513122","buyer":{"buyerAddress":{"streetName":null,"additionalStreetName":null,"buildingNumber":null,"plotIdentification":null,"citySubdivisionName":null,"cityName":"الرياض","postalZone":null,"countrySubentity":null,"country":null},"buyerName":"Taj Al Mulook General Trading LLC","buyerVatId":"310285784400003","additionalIDSchemeID":"None","additionalCustomerID":null},"documentLineItems":[{"lineItemName":"POLYETHYLENE HDPE HHM TR - 131","lineItemPrice":3950,"lineItemQty":27.5,"discountOnLineItem":0,"allowanceCode":null,"taxCategoryCode":"Z","taxReasonCode":"VATEX_SA_32","taxReasonDescription":null,"vatRateOnLineItem":0},{"lineItemName":"POLYETHYLENE HDPE HHM TR - 132","lineItemPrice":3950,"lineItemQty":27.5,"discountOnLineItem":0,"allowanceCode":null,"taxCategoryCode":"S","taxReasonCode":"None","taxReasonDescription":null,"vatRateOnLineItem":15}],"referenceId":null,"documentId":"7788","notes":null,"orderReferenceId":null,"documentAllowanceOrChange":[{"allowanceChargeReasonCode":"95","amount":10,"taxCategoryCode":"S","taxReasonCode":"None","vatRate":15}],"invoiceTypeReason":null,"payment":{"paymentMethod":"InCash","paymentAccountIdentifier":null,"paymentNote":null},"prepaymentDetails":[{"sequentialInvoiceUUID":"892a7039-d5bd-47e9-8f70-7fe44ad15ce9"}]} }, "application/*+json": { "schema": { "$ref": "#/components/schemas/SubmitInvoiceCommand" }, "example": {"validateWarnings":true,"documentType":"TaxInvoice","invoiceIndicator":"Nominal","currency":"SAR","exchangeRate":null,"documentIssueDateTime":"2026-04-21T14:34:39.9513116","supplyDate":"2026-04-21T14:34:39.9513122","buyer":{"buyerAddress":{"streetName":null,"additionalStreetName":null,"buildingNumber":null,"plotIdentification":null,"citySubdivisionName":null,"cityName":"الرياض","postalZone":null,"countrySubentity":null,"country":null},"buyerName":"Taj Al Mulook General Trading LLC","buyerVatId":"310285784400003","additionalIDSchemeID":"None","additionalCustomerID":null},"documentLineItems":[{"lineItemName":"POLYETHYLENE HDPE HHM TR - 131","lineItemPrice":3950,"lineItemQty":27.5,"discountOnLineItem":0,"allowanceCode":null,"taxCategoryCode":"Z","taxReasonCode":"VATEX_SA_32","taxReasonDescription":null,"vatRateOnLineItem":0},{"lineItemName":"POLYETHYLENE HDPE HHM TR - 132","lineItemPrice":3950,"lineItemQty":27.5,"discountOnLineItem":0,"allowanceCode":null,"taxCategoryCode":"S","taxReasonCode":"None","taxReasonDescription":null,"vatRateOnLineItem":15}],"referenceId":null,"documentId":"7788","notes":null,"orderReferenceId":null,"documentAllowanceOrChange":[{"allowanceChargeReasonCode":"95","amount":10,"taxCategoryCode":"S","taxReasonCode":"None","vatRate":15}],"invoiceTypeReason":null,"payment":{"paymentMethod":"InCash","paymentAccountIdentifier":null,"paymentNote":null},"prepaymentDetails":[{"sequentialInvoiceUUID":"892a7039-d5bd-47e9-8f70-7fe44ad15ce9"}]} } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitInvoiceSuccessResult" }, "example": {"uuid":"fb7526b4-f6d2-45aa-bb1e-f2d8f0a1d04d","status":"CLEARED","validationResults":{"infoMessages":[{"type":"INFO","code":"XSD_ZATCA_VALID","category":"XSD validation","message":"Complied with UBL 2.1 standards in line with ZATCA specifications","status":"PASS"}],"warningMessages":[{"type":null,"code":"BR-KSA-09","category":"Seller-Address","message":"Seller address must contain additional number (KSA-23), street name (BT-35), building number (KSA-17), postal code (BT-38), city (BT-37), Neighborhood (KSA-3), country code (BT-40). \n For more information please access this link: https://www.address.gov.sa/en/address-format/overview","status":null}],"errorMessages":null,"status":"PASS"},"qrCodeString":"SampleQRCodeString","signedInvoice":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCiAgICA8SW52b2ljZT4NCiAgICAgICAgPFNlbGxlcj4NCiAgICAgICAgICAgIDxOYW1lPkpvaG4gRG9lPC9OYW1lPg0KICAgICAgICAgICAgPEFkZHJlc3M+DQogICAgICAgICAgICAgICAgPFN0cmVldD5NYWluIFN0PC9TdHJlZXQ+DQogICAgICAgICAgICAgICAgPENpdHk+Uml5YWRoPC9DaXR5Pg0KICAgICAgICAgICAgICAgIDxQb3N0YWxDb2RlPjEyMzQ1PC9Qb3N0YWxDb2RlPg0KICAgICAgICAgICAgICAgIDxDb3VudHJ5PktTQTwvQ291bnRyeT4NCiAgICAgICAgICAgIDwvQWRkcmVzcz4NCiAgICAgICAgPC9TZWxsZXI+DQogICAgICAgIDxBbW91bnQ+MTAwLjAwPC9BbW91bnQ+DQogICAgPC9JbnZvaWNlPg=="} }, "text/plain": { "schema": { "$ref": "#/components/schemas/SubmitInvoiceSuccessResult" }, "example": {"uuid":"fb7526b4-f6d2-45aa-bb1e-f2d8f0a1d04d","status":"CLEARED","validationResults":{"infoMessages":[{"type":"INFO","code":"XSD_ZATCA_VALID","category":"XSD validation","message":"Complied with UBL 2.1 standards in line with ZATCA specifications","status":"PASS"}],"warningMessages":[{"type":null,"code":"BR-KSA-09","category":"Seller-Address","message":"Seller address must contain additional number (KSA-23), street name (BT-35), building number (KSA-17), postal code (BT-38), city (BT-37), Neighborhood (KSA-3), country code (BT-40). \n For more information please access this link: https://www.address.gov.sa/en/address-format/overview","status":null}],"errorMessages":null,"status":"PASS"},"qrCodeString":"SampleQRCodeString","signedInvoice":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCiAgICA8SW52b2ljZT4NCiAgICAgICAgPFNlbGxlcj4NCiAgICAgICAgICAgIDxOYW1lPkpvaG4gRG9lPC9OYW1lPg0KICAgICAgICAgICAgPEFkZHJlc3M+DQogICAgICAgICAgICAgICAgPFN0cmVldD5NYWluIFN0PC9TdHJlZXQ+DQogICAgICAgICAgICAgICAgPENpdHk+Uml5YWRoPC9DaXR5Pg0KICAgICAgICAgICAgICAgIDxQb3N0YWxDb2RlPjEyMzQ1PC9Qb3N0YWxDb2RlPg0KICAgICAgICAgICAgICAgIDxDb3VudHJ5PktTQTwvQ291bnRyeT4NCiAgICAgICAgICAgIDwvQWRkcmVzcz4NCiAgICAgICAgPC9TZWxsZXI+DQogICAgICAgIDxBbW91bnQ+MTAwLjAwPC9BbW91bnQ+DQogICAgPC9JbnZvaWNlPg=="} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": {"errors":["The seller's tax registration number is required.","The seller's tax registration number must consist of 15 digits.","The street must contain at least one character.","The street must be between 1 and 127 characters.","RoundingAmount must contain up to two decimal places.","In case of 'Zero rated' tax category, the tax amount (TaxAmount) must be 0 (zero)."]} }, "text/plain": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": {"errors":["The seller's tax registration number is required.","The seller's tax registration number must consist of 15 digits.","The street must contain at least one character.","The street must be between 1 and 127 characters.","RoundingAmount must contain up to two decimal places.","In case of 'Zero rated' tax category, the tax amount (TaxAmount) must be 0 (zero)."]} } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceAccess" }, "example": {"message":"You must be associated with a Egs Unit to access this resource.","currentEgsUnitsUrl":"https://zatcaapi.avtax.net/api/EgsUnits/GetEgsUnits","loginAsEgsUnitsUrl":"https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit"} }, "text/plain": { "schema": { "$ref": "#/components/schemas/ResourceAccess" }, "example": {"message":"You must be associated with a Egs Unit to access this resource.","currentEgsUnitsUrl":"https://zatcaapi.avtax.net/api/EgsUnits/GetEgsUnits","loginAsEgsUnitsUrl":"https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit"} } } }, "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/Invoice/GetInvoices": { "get": { "tags": [ "Invoice" ], "summary": "Retrieves the invoices associated with the current user.", "parameters": [ { "name": "InvoiceTypes", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceKind" } } }, { "name": "PageNumber", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "PageSize", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "From", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "To", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDataDto" }, "example": {"invoiceStatus":{"invoiceUUID":"12345678-90ab-cdef-1234-567890abcdef","invoiceStatus":"REPORTED","invoiceReportingResponse":{"validationResults":{"infoMessages":null,"warningMessages":[{"type":null,"code":"BR-KSA-09","category":"Seller-Address","message":"Seller address must contain additional number (KSA-23), street name (BT-35), building number (KSA-17), postal code (BT-38), city (BT-37), Neighborhood (KSA-3), country code (BT-40). \n For more information please access this link: https://www.address.gov.sa/en/address-format/overview","status":null}],"errorMessages":null,"status":null},"reportingStatus":"REPORTED"},"invoiceClearanceResponse":{"validationResults":{"infoMessages":null,"warningMessages":[{"type":null,"code":"BR-KSA-09","category":"Seller-Address","message":"Seller address must contain additional number (KSA-23), street name (BT-35), building number (KSA-17), postal code (BT-38), city (BT-37), Neighborhood (KSA-3), country code (BT-40). \n For more information please access this link: https://www.address.gov.sa/en/address-format/overview","status":null}],"errorMessages":null,"status":null},"clearedInvoice":null,"clearanceStatus":"CLEARED"}},"invoiceTotal":0,"validateWarnings":true,"documentType":"SimplifiedTaxInvoice","invoiceIndicator":"None","currency":"SAR","exchangeRate":null,"documentIssueDateTime":"2026-04-21T12:34:39.953875+02:00","supplyDate":"2026-04-20T12:34:39.9538734+02:00","buyer":{"buyerAddress":{"streetName":"123 Main St","additionalStreetName":null,"buildingNumber":"456","plotIdentification":null,"citySubdivisionName":"Downtown","cityName":"Cityville","postalZone":"7890","countrySubentity":null,"country":"SA"},"buyerName":"Buyer Company Ltd.","buyerVatId":"300000000000003","additionalIDSchemeID":"None","additionalCustomerID":null},"documentLineItems":[{"lineItemName":"Product A","lineItemPrice":20.00,"lineItemQty":5,"discountOnLineItem":10.00,"allowanceCode":null,"taxCategoryCode":"Z","taxReasonCode":"VATEX_SA_34_5","taxReasonDescription":"Export goods","vatRateOnLineItem":0}],"referenceId":null,"documentId":null,"notes":null,"orderReferenceId":null,"documentAllowanceOrChange":null,"invoiceTypeReason":null,"payment":null,"prepaymentDetails":null} }, "text/plain": { "schema": { "$ref": "#/components/schemas/InvoiceDataDto" }, "example": {"invoiceStatus":{"invoiceUUID":"12345678-90ab-cdef-1234-567890abcdef","invoiceStatus":"REPORTED","invoiceReportingResponse":{"validationResults":{"infoMessages":null,"warningMessages":[{"type":null,"code":"BR-KSA-09","category":"Seller-Address","message":"Seller address must contain additional number (KSA-23), street name (BT-35), building number (KSA-17), postal code (BT-38), city (BT-37), Neighborhood (KSA-3), country code (BT-40). \n For more information please access this link: https://www.address.gov.sa/en/address-format/overview","status":null}],"errorMessages":null,"status":null},"reportingStatus":"REPORTED"},"invoiceClearanceResponse":{"validationResults":{"infoMessages":null,"warningMessages":[{"type":null,"code":"BR-KSA-09","category":"Seller-Address","message":"Seller address must contain additional number (KSA-23), street name (BT-35), building number (KSA-17), postal code (BT-38), city (BT-37), Neighborhood (KSA-3), country code (BT-40). \n For more information please access this link: https://www.address.gov.sa/en/address-format/overview","status":null}],"errorMessages":null,"status":null},"clearedInvoice":null,"clearanceStatus":"CLEARED"}},"invoiceTotal":0,"validateWarnings":true,"documentType":"SimplifiedTaxInvoice","invoiceIndicator":"None","currency":"SAR","exchangeRate":null,"documentIssueDateTime":"2026-04-21T12:34:39.953875+02:00","supplyDate":"2026-04-20T12:34:39.9538734+02:00","buyer":{"buyerAddress":{"streetName":"123 Main St","additionalStreetName":null,"buildingNumber":"456","plotIdentification":null,"citySubdivisionName":"Downtown","cityName":"Cityville","postalZone":"7890","countrySubentity":null,"country":"SA"},"buyerName":"Buyer Company Ltd.","buyerVatId":"300000000000003","additionalIDSchemeID":"None","additionalCustomerID":null},"documentLineItems":[{"lineItemName":"Product A","lineItemPrice":20.00,"lineItemQty":5,"discountOnLineItem":10.00,"allowanceCode":null,"taxCategoryCode":"Z","taxReasonCode":"VATEX_SA_34_5","taxReasonDescription":"Export goods","vatRateOnLineItem":0}],"referenceId":null,"documentId":null,"notes":null,"orderReferenceId":null,"documentAllowanceOrChange":null,"invoiceTypeReason":null,"payment":null,"prepaymentDetails":null} } } }, "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." } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceAccess" }, "example": {"message":"You must be associated with a Egs Unit to access this resource.","currentEgsUnitsUrl":"https://zatcaapi.avtax.net/api/EgsUnits/GetEgsUnits","loginAsEgsUnitsUrl":"https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit"} }, "text/plain": { "schema": { "$ref": "#/components/schemas/ResourceAccess" }, "example": {"message":"You must be associated with a Egs Unit to access this resource.","currentEgsUnitsUrl":"https://zatcaapi.avtax.net/api/EgsUnits/GetEgsUnits","loginAsEgsUnitsUrl":"https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit"} } } } } } }, "/api/Invoice/GetInvoiceStatus/{invoiceUuid}/status": { "get": { "tags": [ "Invoice" ], "summary": "Retrieves the status of an invoice based on the provided Invoice UUID.", "parameters": [ { "name": "invoiceUuid", "in": "path", "description": "The unique identifier of the invoice.", "required": true, "schema": { "type": "string" } } ], "responses": { "403": { "description": "Forbidden", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ResourceAccess" }, "example": {"message":"You must be associated with a Egs Unit to access this resource.","currentEgsUnitsUrl":"https://zatcaapi.avtax.net/api/EgsUnits/GetEgsUnits","loginAsEgsUnitsUrl":"https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit"} }, "application/json": { "schema": { "$ref": "#/components/schemas/ResourceAccess" }, "example": {"message":"You must be associated with a Egs Unit to access this resource.","currentEgsUnitsUrl":"https://zatcaapi.avtax.net/api/EgsUnits/GetEgsUnits","loginAsEgsUnitsUrl":"https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit"} }, "text/json": { "schema": { "$ref": "#/components/schemas/ResourceAccess" }, "example": {"message":"You must be associated with a Egs Unit to access this resource.","currentEgsUnitsUrl":"https://zatcaapi.avtax.net/api/EgsUnits/GetEgsUnits","loginAsEgsUnitsUrl":"https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit"} } } } } } }, "/api/Invoice/PrintInvoice/{invoiceUuid}/PrintA3": { "post": { "tags": [ "Invoice" ], "summary": "Retrieves and prints an invoice based on the provided Invoice UUID and XML data.\r\n\r\nUsage Notes:\r\n- For standard templates (ZatcaTemplate, SimplifiedTemplate), provide only the SignedInvoice (base64 XML)\r\n- For CustomTemplate, you can optionally provide:\r\n - PdfInvoiceBase64: A base64-encoded PDF file that will be converted to PDF/A-3 with embedded XML\r\n - If PdfInvoiceBase64 is not provided, the system will generate a PDF from the XML data using the default custom template\r\n- Providing PdfInvoiceBase64 requires using CustomTemplate (PdfA3Templete must be set to CustomTemplate)", "parameters": [ { "name": "invoiceUuid", "in": "path", "description": "The unique identifier of the invoice.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The request containing the base64-encoded XML representation of the invoice and optional PDF for custom templates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintInvoiceRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PrintInvoiceRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/PrintInvoiceRequest" } } } }, "responses": { "403": { "description": "Forbidden", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ResourceAccess" }, "example": {"message":"You must be associated with a Egs Unit to access this resource.","currentEgsUnitsUrl":"https://zatcaapi.avtax.net/api/EgsUnits/GetEgsUnits","loginAsEgsUnitsUrl":"https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit"} }, "application/json": { "schema": { "$ref": "#/components/schemas/ResourceAccess" }, "example": {"message":"You must be associated with a Egs Unit to access this resource.","currentEgsUnitsUrl":"https://zatcaapi.avtax.net/api/EgsUnits/GetEgsUnits","loginAsEgsUnitsUrl":"https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit"} }, "text/json": { "schema": { "$ref": "#/components/schemas/ResourceAccess" }, "example": {"message":"You must be associated with a Egs Unit to access this resource.","currentEgsUnitsUrl":"https://zatcaapi.avtax.net/api/EgsUnits/GetEgsUnits","loginAsEgsUnitsUrl":"https://zatcaapi.avtax.net/api/UserAuthentication/LoginAsEgsUnit"} } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ErrorDetails" }, "example": {"statusCode":500,"message":"Internal Server Error","details":"Invalid Base64 string provided."} }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetails" }, "example": {"statusCode":500,"message":"Internal Server Error","details":"Invalid Base64 string provided."} }, "text/json": { "schema": { "$ref": "#/components/schemas/ErrorDetails" }, "example": {"statusCode":500,"message":"Internal Server Error","details":"Invalid Base64 string provided."} } } } } } }, "/api/UserAuthentication/LoginAsEgsUnit": { "post": { "tags": [ "UserAuthentication" ], "summary": "Endpoint for EGS Unit Authentication", "description": "This endpoint facilitates secure authentication for EGS units. As an EGS unit, you'll use the `ClientId` and `ClientSecret` obtained during EGS unit creation via the `/api/EgsUnits/CreateNewEgsUnit` endpoint. These credentials ensure system security and integrity.\r\n s\r\nUpon successful authentication, a Bearer JWT token will be issued. This token serves as a key granting access to our Invoice endpoints. Additionally, authenticated EGS units gain access to `ZatcaUIData`, providing valuable insights for an enhanced user experience.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAsEgsUnitCommand" }, "example": {"clientId":"1b3f8b06-7008-421b-bbda-ffa20832886d","clientSecret":"8ec1a1f0-2ed8-439d-a87c-4db7badad238"} }, "text/json": { "schema": { "$ref": "#/components/schemas/LoginAsEgsUnitCommand" }, "example": {"clientId":"1b3f8b06-7008-421b-bbda-ffa20832886d","clientSecret":"8ec1a1f0-2ed8-439d-a87c-4db7badad238"} }, "application/*+json": { "schema": { "$ref": "#/components/schemas/LoginAsEgsUnitCommand" }, "example": {"clientId":"1b3f8b06-7008-421b-bbda-ffa20832886d","clientSecret":"8ec1a1f0-2ed8-439d-a87c-4db7badad238"} } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAsEgsUnitResponse" }, "example": {"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","expires":"2026-04-22T10:34:39.9585287Z"} } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": {"errors":["The client ID or client secret you entered is incorrect. Please check and try again."]} } } } } } }, "/api/ZatcaUIData/ReasonForAllowances": { "get": { "tags": [ "ZatcaUIData" ], "summary": "This endpoint retrieves all reasons for allowances.", "responses": { "200": { "description": "OK" } } } }, "/api/ZatcaUIData/Countries": { "get": { "tags": [ "ZatcaUIData" ], "summary": "This endpoint gets a list of all countries", "responses": { "200": { "description": "OK" } } } }, "/api/ZatcaUIData/Currencies": { "get": { "tags": [ "ZatcaUIData" ], "summary": "This endpoint retrieves information on all available currencies.", "responses": { "200": { "description": "OK" } } } }, "/api/ZatcaUIData/InvoiceTypes": { "get": { "tags": [ "ZatcaUIData" ], "summary": "This endpoint fetches a list of different types of invoices", "responses": { "200": { "description": "OK" } } } }, "/api/ZatcaUIData/TaxReasonCodes": { "get": { "tags": [ "ZatcaUIData" ], "summary": "Process a request To get all Tax Reason Codes", "description": "Use the 'TaxReasonCode' field in the request.\r\nThe 'Description' field is for UI purposes only and should not be used in requests.", "responses": { "200": { "description": "OK" } } } }, "/api/ZatcaUIData/InvoiceIndicators": { "get": { "tags": [ "ZatcaUIData" ], "summary": "Process a request To get all Invoice Indicators", "description": "Use the 'InvoiceIndicator' field in the request.\r\nThe 'Description' field is for UI purposes only and should not be used in requests.", "responses": { "200": { "description": "OK" } } } }, "/api/ZatcaUIData/TaxCategories": { "get": { "tags": [ "ZatcaUIData" ], "summary": "Process a request To get all Tax Categories", "description": "Use the 'TaxCategory' field in the request.\r\nThe 'Description' field is for UI purposes only and should not be used in requests.", "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "AdditionalIDScheme": { "enum": [ "None", "CRN", "MOM", "MLS", "Number700", "SAG", "OTH", "TIN", "NAT" ], "type": "string" }, "Buyer": { "type": "object", "properties": { "buyerAddress": { "$ref": "#/components/schemas/PartyPostalAddress" }, "buyerName": { "type": "string", "nullable": true }, "buyerVatId": { "type": "string", "nullable": true }, "additionalIDSchemeID": { "$ref": "#/components/schemas/AdditionalIDScheme" }, "additionalCustomerID": { "type": "string", "nullable": true } }, "additionalProperties": false }, "Currency": { "enum": [ "SAR", "EGP", "USD", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "ERN", "ETB", "EUR", "FJD", "FKP", "FOK", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KID", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK" ], "type": "string" }, "DocumentAllowanceOrChanges": { "type": "object", "properties": { "allowanceChargeReasonCode": { "type": "string", "nullable": true }, "amount": { "type": "number", "format": "double" }, "taxCategoryCode": { "$ref": "#/components/schemas/TaxCategories" }, "taxReasonCode": { "$ref": "#/components/schemas/TaxReasonCode" }, "vatRate": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "DocumentLineItem": { "type": "object", "properties": { "lineItemName": { "type": "string", "description": "Name of the line item.", "nullable": true }, "lineItemPrice": { "type": "number", "description": "Price of the line item. Default value is 250.", "format": "double", "default": 250 }, "lineItemQty": { "type": "number", "description": "Quantity of the line item. Default value is 2.", "format": "double", "default": 2 }, "discountOnLineItem": { "type": "number", "description": "Discount applied to this line item.", "format": "double" }, "allowanceCode": { "type": "string", "description": "Allowance code for this line item.\r\nThe user must provide a value only if the allowance type on the invoice \r\nis not a discount and represents another type of allowance.", "nullable": true }, "taxCategoryCode": { "$ref": "#/components/schemas/TaxCategories" }, "taxReasonCode": { "$ref": "#/components/schemas/TaxReasonCode" }, "taxReasonDescription": { "type": "string", "description": "Description of the tax reason, if applicable.", "nullable": true }, "vatRateOnLineItem": { "type": "number", "description": "VAT rate applied to this line item.", "format": "double" } }, "additionalProperties": false }, "ErrorDetails": { "type": "object", "properties": { "statusCode": { "type": "integer", "format": "int32" }, "message": { "type": "string", "nullable": true }, "details": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "InvoiceClearanceResponse": { "type": "object", "properties": { "validationResults": { "$ref": "#/components/schemas/ValidationResult" }, "clearedInvoice": { "type": "string", "nullable": true }, "clearanceStatus": { "$ref": "#/components/schemas/InvoiceStatus" } }, "additionalProperties": false }, "InvoiceDataDto": { "type": "object", "properties": { "validateWarnings": { "type": "boolean", "description": "Controls whether warning-level validations (BR-KSA-08, BR-KSA-09, BR-KSA-37, BR-KSA-66, etc.) should be executed.\r\nSet to false to skip warning validations and only validate error-level rules.", "default": true, "example": true }, "documentType": { "$ref": "#/components/schemas/InvoiceKind" }, "invoiceIndicator": { "$ref": "#/components/schemas/InvoiceIndicator" }, "currency": { "$ref": "#/components/schemas/Currency" }, "exchangeRate": { "type": "number", "format": "double", "nullable": true }, "documentIssueDateTime": { "type": "string", "description": "Gets or sets the document issue date time.", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "supplyDate": { "type": "string", "format": "date-time", "default": null, "nullable": true }, "buyer": { "$ref": "#/components/schemas/Buyer" }, "documentLineItems": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLineItem" }, "nullable": true }, "referenceId": { "type": "string", "nullable": true }, "documentId": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "orderReferenceId": { "type": "string", "description": "An identifier of a referenced purchase order, issued by the Buyer.", "nullable": true }, "documentAllowanceOrChange": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentAllowanceOrChanges" }, "description": "Each document level allowance and/or charge must have the Document level allowance and/or charge VAT category code", "nullable": true }, "invoiceTypeReason": { "type": "string", "nullable": true }, "payment": { "$ref": "#/components/schemas/Payment" }, "prepaymentDetails": { "type": "array", "items": { "$ref": "#/components/schemas/PrepaymentDetail" }, "description": "Details of the prepayment made towards the invoice.", "nullable": true }, "invoiceStatus": { "$ref": "#/components/schemas/InvoiceStatusDto" }, "invoiceTotal": { "type": "number", "format": "double" } }, "additionalProperties": false }, "InvoiceIndicator": { "enum": [ "None", "ThirdParty", "SelfBilled", "Nominal", "Export", "Summary" ], "type": "string" }, "InvoiceKind": { "enum": [ "TaxInvoiceCreditNote", "SimplifiedCreditNote", "TaxInvoiceDebitNote", "SimplifiedDebitNote", "PrepaymentTaxInvoice", "PrepaymentSimplifiedTaxInvoice", "TaxInvoice", "SimplifiedTaxInvoice" ], "type": "string" }, "InvoiceReportingResponse": { "type": "object", "properties": { "validationResults": { "$ref": "#/components/schemas/ValidationResult" }, "reportingStatus": { "$ref": "#/components/schemas/InvoiceStatus" } }, "additionalProperties": false }, "InvoiceStatus": { "enum": [ "Draft", "REPORTED", "NOT_REPORTED", "CLEARED", "NOT_CLEARED" ], "type": "string" }, "InvoiceStatusDto": { "type": "object", "properties": { "invoiceUUID": { "type": "string", "nullable": true }, "invoiceStatus": { "$ref": "#/components/schemas/InvoiceStatus" }, "invoiceReportingResponse": { "$ref": "#/components/schemas/InvoiceReportingResponse" }, "invoiceClearanceResponse": { "$ref": "#/components/schemas/InvoiceClearanceResponse" } }, "additionalProperties": false }, "LoginAsEgsUnitCommand": { "type": "object", "properties": { "clientId": { "type": "string", "default": "adb14ccd-76d8-4d38-bf56-1d395660be0f", "nullable": true }, "clientSecret": { "type": "string", "nullable": true } }, "additionalProperties": false }, "LoginAsEgsUnitResponse": { "type": "object", "properties": { "access_token": { "type": "string", "nullable": true }, "expires": { "type": "string", "format": "date-time" } }, "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 }, "Payment": { "type": "object", "properties": { "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod" }, "paymentAccountIdentifier": { "type": "string", "nullable": true }, "paymentNote": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PaymentMethod": { "enum": [ "None", "InstrumentNotDefined", "InCash", "Credit", "PaymentToBankAccount", "BankCard" ], "type": "string" }, "PdfA3Templete": { "enum": [ "ZatcaTemplate", "SimplifiedTemplate", "SimplifiedTemplateAr", "CustomTemplate", "ModernTemplate", "ModernTemplateAr", "SimplifiedMixedTemplate" ], "type": "string" }, "PrepaymentDetail": { "type": "object", "properties": { "sequentialInvoiceUUID": { "type": "string", "description": "Sequential invoice uuid of the prepayment invoice (UUID)", "nullable": true } }, "additionalProperties": false }, "PrintInvoiceRequest": { "type": "object", "properties": { "signedInvoice": { "type": "string", "description": "Base64-encoded XML representation of the invoice.", "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "pdfInvoiceBase64": { "type": "string", "nullable": true }, "pdfA3Templete": { "$ref": "#/components/schemas/PdfA3Templete" } }, "additionalProperties": false, "description": "Represents the request for printing an invoice." }, "ResourceAccess": { "type": "object", "properties": { "message": { "type": "string", "nullable": true }, "currentEgsUnitsUrl": { "type": "string", "nullable": true }, "loginAsEgsUnitsUrl": { "type": "string", "nullable": true } }, "additionalProperties": false }, "SubmitInvoiceCommand": { "type": "object", "properties": { "validateWarnings": { "type": "boolean", "description": "Controls whether warning-level validations (BR-KSA-08, BR-KSA-09, BR-KSA-37, BR-KSA-66, etc.) should be executed.\r\nSet to false to skip warning validations and only validate error-level rules.", "default": true, "example": true }, "documentType": { "$ref": "#/components/schemas/InvoiceKind" }, "invoiceIndicator": { "$ref": "#/components/schemas/InvoiceIndicator" }, "currency": { "$ref": "#/components/schemas/Currency" }, "exchangeRate": { "type": "number", "format": "double", "nullable": true }, "documentIssueDateTime": { "type": "string", "description": "Gets or sets the document issue date time.", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "supplyDate": { "type": "string", "format": "date-time", "default": null, "nullable": true }, "buyer": { "$ref": "#/components/schemas/Buyer" }, "documentLineItems": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLineItem" }, "nullable": true }, "referenceId": { "type": "string", "nullable": true }, "documentId": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "orderReferenceId": { "type": "string", "description": "An identifier of a referenced purchase order, issued by the Buyer.", "nullable": true }, "documentAllowanceOrChange": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentAllowanceOrChanges" }, "description": "Each document level allowance and/or charge must have the Document level allowance and/or charge VAT category code", "nullable": true }, "invoiceTypeReason": { "type": "string", "nullable": true }, "payment": { "$ref": "#/components/schemas/Payment" }, "prepaymentDetails": { "type": "array", "items": { "$ref": "#/components/schemas/PrepaymentDetail" }, "description": "Details of the prepayment made towards the invoice.", "nullable": true } }, "additionalProperties": false }, "SubmitInvoiceSuccessResult": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier for the invoice submission.", "nullable": true }, "status": { "type": "string", "description": "Status of the invoice submission. Possible values include \"CLEARED\", \"REPORTED\".", "nullable": true }, "validationResults": { "$ref": "#/components/schemas/ValidationResult" }, "qrCodeString": { "type": "string", "description": "String representation of the QR code for the invoice.", "nullable": true }, "signedInvoice": { "type": "string", "description": "Base64-encoded XML signed version of the invoice, typically used for verification purposes.", "nullable": true } }, "additionalProperties": false }, "TaxCategories": { "enum": [ "None", "E", "S", "Z", "O" ], "type": "string", "description": " Represents tax categories for requests\r\n information to support the following VAT use cases:\r\n- Invoices for supplies for which VAT is charged\r\n- Invoices for supplies for which VAT is not charged(exempt supplies,\r\nZero rated Supplies, out of scope supplies)\r\n- Invoices for several supplies which part of them are taxable and part\r\nof them are not, so VAT to be considered at line level" }, "TaxReasonCode": { "enum": [ "None", "VATEX_SA_29", "VATEX_SA_29_7", "VATEX_SA_30", "VATEX_SA_32", "VATEX_SA_33", "VATEX_SA_34_1", "VATEX_SA_34_2", "VATEX_SA_34_3", "VATEX_SA_34_4", "VATEX_SA_34_5", "VATEX_SA_35", "VATEX_SA_36", "VATEX_SA_EDU", "VATEX_SA_HEA", "VATEX_SA_MLTRY", "VATEX_SA_OOS" ], "type": "string" }, "ValidationMessage": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "code": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ValidationResult": { "type": "object", "properties": { "infoMessages": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationMessage" }, "nullable": true }, "warningMessages": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationMessage" }, "nullable": true }, "errorMessages": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationMessage" }, "nullable": true }, "status": { "type": "string", "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": [ ] } ] }