Class: TqlOtrFactoringDataExchange::InvoicesApi

Inherits:
BaseApi
  • Object
show all
Defined in:
lib/tql_otr_factoring_data_exchange/apis/invoices_api.rb

Overview

InvoicesApi

Constant Summary

Constants inherited from BaseApi

BaseApi::GLOBAL_ERRORS

Instance Attribute Summary

Attributes inherited from BaseApi

#config, #http_call_back

Instance Method Summary collapse

Methods inherited from BaseApi

#initialize, #new_parameter, #new_request_builder, #new_response_handler, user_agent, user_agent_parameters

Constructor Details

This class inherits a constructor from TqlOtrFactoringDataExchange::BaseApi

Instance Method Details

#get_invoice_status(invoice_number) ⇒ ApiResponse

Retrieve the current processing status of a previously submitted invoice. If processing is complete, the response indicates success. If there are outstanding exceptions (missing documents, charge discrepancies, data mismatches, etc.), they are listed in the ‘exceptions` array. This endpoint also confirms whether data you submitted has been ingested —if `status` is `Received` or beyond, the data is in the system. invoice number (provided when submitting via `POST /api/invoices`).

Parameters:

  • invoice_number (String) —

    Required parameter: The factoring company’s

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/tql_otr_factoring_data_exchange/apis/invoices_api.rb', line 54

def get_invoice_status(invoice_number)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/api/invoices/{invoiceNumber}',
                                 Server::DEFAULT)
               .template_param(new_parameter(invoice_number, key: 'invoiceNumber')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('bearerAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(InvoiceStatusResponse.method(:from_hash))
                .is_api_response(true)
                .local_error('404',
                             "Invoice not found — no invoice exists with the specified'\
                              ' invoice number.\n",
                             ProblemDetailsErrorException))
    .execute
end

#search_invoices(body) ⇒ ApiResponse

Search for invoices using optional filter criteria. Returns a paginated list of invoice summaries including the invoice ID, a direct URI to retrieve full details, the factoring company invoice number, TQL load number, current status, and the last-updated timestamp. Scoping: Results are automatically scoped to invoices submitted by the authenticated factoring company. You will only see invoices where you are the factor — you cannot query invoices submitted by other parties. **Filter logic:** Filters use AND across different fields and OR within array-valued fields. For example, searching with ‘lastUpdatedAfter

2026-04-03` and ‘statuses = [Approved, PendingExceptions]` returns

invoices updated today that are in either ‘Approved` or `PendingExceptions` status. This is a synchronous call — results are returned immediately. pagination parameters. All filter fields are optional — omit a field to skip that filter. Provide at least `page` and `pageSize` for pagination.

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/tql_otr_factoring_data_exchange/apis/invoices_api.rb', line 92

def search_invoices(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/invoices/search',
                                 Server::DEFAULT)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('bearerAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(InvoiceSearchResponse.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             "Validation error — invalid filter criteria or pagination'\
                              ' parameters.\n",
                             ProblemDetailsErrorException))
    .execute
end

#submit_invoice(body) ⇒ ApiResponse

Submit a factoring company invoice against a TQL load. The request must include the TQL load number, the factoring company’s invoice number, carrier details, at least two stops (origin and destination), one or more charges, and at least one reference number. The invoice is accepted asynchronously — a ‘202 Accepted` response is returned immediately with the generated invoice ID. Use `GET /api/invoices/invoiceNumber` to poll for processing completion and to retrieve any exceptions. company invoice payload including TQL load number, factoring company invoice number, carrier information, stops, charges, reference numbers, and operational dates.

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/tql_otr_factoring_data_exchange/apis/invoices_api.rb', line 22

def submit_invoice(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/invoices',
                                 Server::DEFAULT)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('bearerAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubmitInvoiceResponse.method(:from_hash))
                .is_api_response(true)
                .local_error('400',
                             "Validation error — the request body is missing required fields'\
                              ' or contains invalid data. Review the `detail` field for'\
                              ' specifics.\n",
                             ProblemDetailsErrorException))
    .execute
end