Class: ZATCA::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/zatca/client.rb

Overview

This wraps the API described here: sandbox.zatca.gov.sa/IntegrationSandbox

Constant Summary collapse

PRODUCTION_BASE_URL =

API URLs are not present in developer portal, they can only be found in a PDF called Fatoora Portal User Manual, here: zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/Fatoora%20portal%20user%20manual.pdf

"https://gw-fatoora.zatca.gov.sa/e-invoicing/core".freeze
SANDBOX_BASE_URL = 
"https://gw-apic-gov.gazt.gov.sa/e-invoicing/developer-portal".freeze
SIMULATION_BASE_URL = 
"https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation".freeze
ENVIRONMENTS_TO_URLS_MAP = 
{
  production: PRODUCTION_BASE_URL,
  sandbox: SANDBOX_BASE_URL,
  simulation: SIMULATION_BASE_URL
}.freeze
DEFAULT_API_VERSION = 
"V2".freeze
LANGUAGES = 
%w[ar en].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(username:, password:, language: "ar", version: DEFAULT_API_VERSION, environment: :production, verbose: false, before_submitting_request: nil, before_parsing_response: nil) ⇒ Client

Returns a new instance of Client.



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/zatca/client.rb', line 25

def initialize(
  username:,
  password:,
  language: "ar",
  version: DEFAULT_API_VERSION,
  environment: :production,
  verbose: false,
  before_submitting_request: nil,
  before_parsing_response: nil
)
  raise "Invalid language: #{language}, Please use one of: #{LANGUAGES}" unless LANGUAGES.include?(language)

  @username = username
  @password = password
  @language = language
  @version = version
  @verbose = verbose

  @base_url = ENVIRONMENTS_TO_URLS_MAP[environment.to_sym] || PRODUCTION_BASE_URL

  @before_submitting_request = before_submitting_request
  @before_parsing_response = before_parsing_response
end

Instance Attribute Details

#before_parsing_response ⇒ Object

Returns the value of attribute before_parsing_response.



7
8
9
 
# File 'lib/zatca/client.rb', line 7

def before_parsing_response
  @before_parsing_response
end

#before_submitting_request ⇒ Object

Returns the value of attribute before_submitting_request.



7
8
9
 
# File 'lib/zatca/client.rb', line 7

def before_submitting_request
  @before_submitting_request
end

Instance Method Details

#clear_invoice(uuid:, invoice_hash:, invoice:, cleared:) ⇒ Object

Clearance API



66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/zatca/client.rb', line 66

def clear_invoice(uuid:, invoice_hash:, invoice:, cleared:)
  request(
    path: "invoices/clearance/single",
    method: :post,
    body: {
      uuid: uuid,
      invoiceHash: invoice_hash,
      invoice: invoice
    },
    headers: {
      "Clearance-Status" => cleared ? "1" : "0"
    }
  )
end

#compliance_check(uuid:, invoice_hash:, invoice:) ⇒ Object

Compliance Invoice API



108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/zatca/client.rb', line 108

def compliance_check(uuid:, invoice_hash:, invoice:)
  request(
    path: "compliance/invoices",
    method: :post,
    body: {
      uuid: uuid,
      invoiceHash: invoice_hash,
      invoice: invoice
    }
  )
end

#issue_csid(csr:, otp:) ⇒ Object

Compliance CSID API This should be used to obtain credentials to issue a certificate in the next request (issue_production_csid)

csid stands for Cryptographic Stamp Identifier

csr stands for Certificate Signing Request

You should generate this via the ZATCA::Signing::CSR class

otp stands for One Time Password.

You can get this from the fatoora portal

Returns: 

"binarySecurityToken": "string" # To be used as a username in next request
"secret": "string" # To be used as a password in next request




97
98
99
100
101
102
103
104
105
 
# File 'lib/zatca/client.rb', line 97

def issue_csid(csr:, otp:)
  request(
    path: "compliance",
    method: :post,
    body: {csr: csr},
    headers: {"OTP" => otp},
    authenticated: false
  )
end

#issue_production_csid(compliance_request_id:) ⇒ Object

Production CSID (Onboarding) API This endpoint gives you the Base64-encoded certificate back compliance_request_id is retrieved from the issue_csid request, and is in the response as responseID



124
125
126
127
128
129
130
 
# File 'lib/zatca/client.rb', line 124

def issue_production_csid(compliance_request_id:)
  request(
    path: "production/csids",
    method: :post,
    body: {compliance_request_id: compliance_request_id}
  )
end

#renew_production_csid(otp:, csr:) ⇒ Object

Production CSID (Renewal) API csr stands for Certificate Signing Request otp stands for One Time Password



135
136
137
138
139
140
141
142
 
# File 'lib/zatca/client.rb', line 135

def renew_production_csid(otp:, csr:)
  request(
    path: "production/csids",
    method: :patch,
    body: {csr: csr},
    headers: {"OTP" => otp}
  )
end

#report_invoice(uuid:, invoice_hash:, invoice:, cleared:) ⇒ Object

Reporting API



50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/zatca/client.rb', line 50

def report_invoice(uuid:, invoice_hash:, invoice:, cleared:)
  request(
    path: "invoices/reporting/single",
    method: :post,
    body: {
      uuid: uuid,
      invoiceHash: invoice_hash,
      invoice: invoice
    },
    headers: {
      "Clearance-Status" => cleared ? "1" : "0"
    }
  )
end