Class: Infrawrench::InvoicesNamespace

Inherits:
Object
  • Object
show all
Defined in:
lib/infrawrench/client.rb,
sig/infrawrench/sdk.rbs

Overview

client.invoices

Instance Method Summary collapse

Constructor Details

#initialize(transport) ⇒ InvoicesNamespace

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of InvoicesNamespace.

Parameters:



8754
8755
8756
 
# File 'lib/infrawrench/client.rb', line 8754

def initialize(transport)
  @transport = transport
end

Instance Method Details

#approve(id:, org_id: nil, request_options: nil) ⇒ Hash

Approve an invoice — freeze its figures

Computes the figures one last time and writes them onto the invoice together with the exchange rates, the day they were read, the billing rules in force and the names everything in scope had. From here the invoice is a document, not a query.

A distinct act from generation, on a distinct permission (invoices:issue), with its own audit entry recording who approved what.

Refused with 409 when a currency in the invoice has no stated exchange rate: an approved invoice has to be quotable as one number in the customer's currency.

Refused with 409, too, when the draft or its customer changed while the figures were being computed — a different period, scope, currency, cost basis or billing-rules setting. Nothing is approved in that case: freezing figures that describe a different question would be worse than making the caller look again.

Requires permission: invoices:issue.

POST /api/org/orgId/invoices/id/approve

Raises on 404: Not found

Raises on 409: Conflict

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • id (String)
  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • id: (String)
  • org_id: (String, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as Invoice — see sig/infrawrench/sdk.rbs.

Raises:



8792
8793
8794
8795
8796
8797
8798
8799
 
# File 'lib/infrawrench/client.rb', line 8792

def approve(id:, org_id: nil, request_options: nil)
  @transport.request(
    http_method: "POST",
    path: "/api/org/{orgId}/invoices/{id}/approve",
    path_params: { "orgId" => org_id, "id" => id },
    request_options: request_options
  )
end

#create(body:, org_id: nil, request_options: nil) ⇒ Hash

Raise a draft invoice

Always lands in draft. Generating and issuing are two acts on two permissions: a mistyped period must not be able to reach a customer without anyone having read the numbers.

Requires permission: invoices:write.

POST /api/org/orgId/invoices

Raises on 400: Bad request

Raises on 404: Not found

Raises on 409: Conflict

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • body (Hash) —

    Request body, shaped as InvoiceInput.

  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • body: (invoice_input)
  • org_id: (String, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as Invoice — see sig/infrawrench/sdk.rbs.

Raises:



8823
8824
8825
8826
8827
8828
8829
8830
8831
 
# File 'lib/infrawrench/client.rb', line 8823

def create(body:, org_id: nil, request_options: nil)
  @transport.request(
    http_method: "POST",
    path: "/api/org/{orgId}/invoices",
    path_params: { "orgId" => org_id },
    body: body,
    request_options: request_options
  )
end

#delete(id:, org_id: nil, request_options: nil) ⇒ Hash

Delete a draft invoice

Draft only, and refused with 409 otherwise. An issued invoice is voided; deleting one would erase a document a customer holds a copy of.

Requires permission: invoices:write.

DELETE /api/org/orgId/invoices/id

Raises on 404: Not found

Raises on 409: Conflict

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • id (String)
  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • id: (String)
  • org_id: (String, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as Ok — see sig/infrawrench/sdk.rbs.

Raises:



8852
8853
8854
8855
8856
8857
8858
8859
 
# File 'lib/infrawrench/client.rb', line 8852

def delete(id:, org_id: nil, request_options: nil)
  @transport.request(
    http_method: "DELETE",
    path: "/api/org/{orgId}/invoices/{id}",
    path_params: { "orgId" => org_id, "id" => id },
    request_options: request_options
  )
end

#export(id:, org_id: nil, request_options: nil) ⇒ String

Download an invoice as CSV

The derivation, not a rendered document: what was collected, what the rules added, the rate and the day it was read, and the final figure — every column an accounts-payable clerk needs to check the arithmetic. Same RFC 4180 quoting as the scheduled cost exports.

Requires permission: invoices:read.

GET /api/org/orgId/invoices/id/export

Raises on 404: Not found

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • id (String)
  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • id: (String)
  • org_id: (String, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (String) —

    Raw response bytes.

Raises:



8880
8881
8882
8883
8884
8885
8886
8887
8888
 
# File 'lib/infrawrench/client.rb', line 8880

def export(id:, org_id: nil, request_options: nil)
  @transport.request(
    http_method: "GET",
    path: "/api/org/{orgId}/invoices/{id}/export",
    path_params: { "orgId" => org_id, "id" => id },
    accept: :binary,
    request_options: request_options
  )
end

#get(id:, org_id: nil, request_options: nil) ⇒ Hash

Get an invoice

A draft recomputes from live spend; an approved, sent or void invoice does not. live says which happened. A frozen invoice returns the figures written at approval and does not read cost data at all.

Requires permission: invoices:read.

GET /api/org/orgId/invoices/id

Raises on 404: Not found

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • id (String)
  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • id: (String)
  • org_id: (String, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as Invoice — see sig/infrawrench/sdk.rbs.

Raises:



8908
8909
8910
8911
8912
8913
8914
8915
 
# File 'lib/infrawrench/client.rb', line 8908

def get(id:, org_id: nil, request_options: nil)
  @transport.request(
    http_method: "GET",
    path: "/api/org/{orgId}/invoices/{id}",
    path_params: { "orgId" => org_id, "id" => id },
    request_options: request_options
  )
end

#list(org_id: nil, managed_account_id: nil, status: nil, request_options: nil) ⇒ Array<Hash>

List invoices

Summaries, newest period first. A draft's totals is null here rather than recomputed — recomputing every draft would make opening the list one cost-data scan per draft, and zero would be a lie the reader cannot detect.

Requires permission: invoices:read.

GET /api/org/orgId/invoices

Raises on 400: Bad request

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • managed_account_id (String, nil) (defaults to: nil)
  • status (String, nil) (defaults to: nil)
  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • org_id: (String, nil) (defaults to: nil)
  • managed_account_id: (String, nil) (defaults to: nil)
  • status: (invoice_status, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Array<Hash>) —

    Parsed JSON, shaped as Array<InvoiceSummary> — see sig/infrawrench/sdk.rbs.

Raises:



8938
8939
8940
8941
8942
8943
8944
8945
8946
 
# File 'lib/infrawrench/client.rb', line 8938

def list(org_id: nil, managed_account_id: nil, status: nil, request_options: nil)
  @transport.request(
    http_method: "GET",
    path: "/api/org/{orgId}/invoices",
    path_params: { "orgId" => org_id },
    query: { "managedAccountId" => , "status" => status },
    request_options: request_options
  )
end

#post_org_org_id_invoices_id_send(id:, org_id: nil, body: nil, request_options: nil) ⇒ Hash

Send an invoice to its customer

Changes no figure — the document was frozen at approval. It records the release (this may go to the customer, and this person said so), then emails the invoice to the customer's contact addresses with the CSV attached.

200 even when delivery failed. The release happened and is recorded either way; delivery says what became of the transport. An error status would leave the caller unable to tell which of the two failed. A failed delivery is visible, and re-sending retries it.

Sending again needs resend: true only when the last attempt reached somebody — see InvoiceSendRequest. The body may be omitted entirely for a first send.

Requires permission: invoices:issue.

POST /api/org/orgId/invoices/id/send

Raises on 400: Bad request

Raises on 404: Not found

Raises on 409: Conflict

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • id (String)
  • body (Hash, nil) (defaults to: nil) —

    Request body, shaped as InvoiceSendRequest.

  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • id: (String)
  • org_id: (String, nil) (defaults to: nil)
  • body: (invoice_send_request, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as Invoice — see sig/infrawrench/sdk.rbs.

Raises:



8981
8982
8983
8984
8985
8986
8987
8988
8989
 
# File 'lib/infrawrench/client.rb', line 8981

def post_org_org_id_invoices_id_send(id:, org_id: nil, body: nil, request_options: nil)
  @transport.request(
    http_method: "POST",
    path: "/api/org/{orgId}/invoices/{id}/send",
    path_params: { "orgId" => org_id, "id" => id },
    body: body,
    request_options: request_options
  )
end

#update(id:, body:, org_id: nil, request_options: nil) ⇒ Hash

Edit a draft invoice

Draft only. An approved, sent or void invoice is refused with 409 by the service, not merely hidden by the UI — an issued invoice that silently changed after the customer received it is the worst outcome this feature could produce.

Requires permission: invoices:write.

PUT /api/org/orgId/invoices/id

Raises on 400: Bad request

Raises on 404: Not found

Raises on 409: Conflict

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • id (String)
  • body (Hash) —

    Request body, shaped as InvoiceUpdate.

  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • id: (String)
  • body: (invoice_update)
  • org_id: (String, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as Invoice — see sig/infrawrench/sdk.rbs.

Raises:



9015
9016
9017
9018
9019
9020
9021
9022
9023
 
# File 'lib/infrawrench/client.rb', line 9015

def update(id:, body:, org_id: nil, request_options: nil)
  @transport.request(
    http_method: "PUT",
    path: "/api/org/{orgId}/invoices/{id}",
    path_params: { "orgId" => org_id, "id" => id },
    body: body,
    request_options: request_options
  )
end

#void(id:, body:, org_id: nil, request_options: nil) ⇒ Hash

Void an issued invoice

The only correction there is. The original keeps every figure it was sent with — “we billed you this, it was wrong, here is the corrected one” is a story a customer can follow, and “we changed the invoice” is not.

With supersede, the void, the corrective draft and both directions of the link between them are one transaction. Void is irreversible, so a half-applied correction would leave a withdrawn invoice with no way forward; this call either applies whole or not at all.

Requires permission: invoices:issue.

POST /api/org/orgId/invoices/id/void

Raises on 400: Bad request

Raises on 404: Not found

Raises on 409: Conflict

Parameters:

  • org_id (String, nil) (defaults to: nil) —

    Organization id. Defaults to the org_id the client was constructed with.

  • id (String)
  • body (Hash) —

    Request body, shaped as InvoiceVoidRequest.

  • request_options (Hash, nil) (defaults to: nil) —

    Per-call :headers, :timeout and :open_timeout.

  • id: (String)
  • body: (invoice_void_request)
  • org_id: (String, nil) (defaults to: nil)
  • request_options: (Hash[Symbol, untyped], nil) (defaults to: nil)

Returns:

  • (Hash) —

    Parsed JSON, shaped as InvoiceVoidResponse — see sig/infrawrench/sdk.rbs.

Raises:



9054
9055
9056
9057
9058
9059
9060
9061
9062
 
# File 'lib/infrawrench/client.rb', line 9054

def void(id:, body:, org_id: nil, request_options: nil)
  @transport.request(
    http_method: "POST",
    path: "/api/org/{orgId}/invoices/{id}/void",
    path_params: { "orgId" => org_id, "id" => id },
    body: body,
    request_options: request_options
  )
end