Class: Api::V1::CanadaPost::ReturnsController

Inherits:
BaseController
  • Object
show all
Includes:
ActionController::HttpAuthentication::Basic::ControllerMethods
Defined in:
app/controllers/api/v1/canada_post/returns_controller.rb

Overview

Canada Post Manage Returns — RA (Return Authorization) number validation
web service.

Canada Post calls this endpoint when a customer enters an RA number on the
hosted returns page, before issuing a box-free / paperless QR return label.
We answer pass/fail; Canada Post only lets the customer retrieve a label when
we return a valid status.

Contract — Canada Post "Web service requirements for return authorization
numbers — REST" (REST-JSON variant selected in the return policy):

GET https:////
Authorization: Basic (set on the return policy)
200 => "ValidateRsaResponse":{"ValidationStatus":true|false}

Canada Post stores the policy's web-service URL verbatim and substitutes only
the [RsaNumber] token, so the exact path it calls depends on what was typed
into the policy. To avoid guessing the path, a catch-all route sends any GET
under /v1/canada_post/ here and we validate on the trailing path segment (the
RA number is always last). #log_canada_post_request records the real
request so the contract can be confirmed from live traffic.

The number 99999999999999 (14 nines) is Canada Post's mandatory operational
ping and must always validate true so Canada Post can confirm the service is
up. Errors surface as a non-2xx (Canada Post treats 4xx/5xx as "service
unavailable"); the inherited BaseController StandardError rescue covers that.

https://www.canadapost-postescanada.ca/cpc/en/support/kb/business/manage-returns/web-service-requirements-for-return-authorization-numbers-rest.page

Constant Summary collapse

PING_RSA_NUMBER =

Canada Post's mandatory operational ping number (14 nines).

('9' * 14).freeze

Instance Method Summary collapse

Instance Method Details

#validate_return_number ⇒ void

This method returns an undefined value.

Validates the RA (RMA) number Canada Post forwards from the hosted returns
page. Responds true for the mandatory 14-nines health-check ping or any
open, Canada-origin RMA; false otherwise.



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'app/controllers/api/v1/canada_post/returns_controller.rb', line 47

def validate_return_number
  if rsa_number == PING_RSA_NUMBER
    valid = true
  else
    rma = Rma.canada_post_returnable.find_by(rma_number: rsa_number)
    valid = rma.present?
    # Read Canada Post's optional params straight from the raw query string —
    # BaseController#underscore_params calls params.to_h, which drops
    # unpermitted query params, so params[:additional_info] would be nil.
    rma&.record_canada_post_return_inquiry(
      additional_info: request.query_parameters['AdditionalInfo'],
      rsa_number_issue_date: request.query_parameters['RsaNumberIssueDate']
    )
  end

  render json: { ValidateRsaResponse: { ValidationStatus: valid } }, status: :ok
end