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:



8632
8633
8634
 
# File 'lib/infrawrench/client.rb', line 8632

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:



8670
8671
8672
8673
8674
8675
8676
8677
 
# File 'lib/infrawrench/client.rb', line 8670

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:



8701
8702
8703
8704
8705
8706
8707
8708
8709
 
# File 'lib/infrawrench/client.rb', line 8701

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:



8730
8731
8732
8733
8734
8735
8736
8737
 
# File 'lib/infrawrench/client.rb', line 8730

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:



8758
8759
8760
8761
8762
8763
8764
8765
8766
 
# File 'lib/infrawrench/client.rb', line 8758

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:



8786
8787
8788
8789
8790
8791
8792
8793
 
# File 'lib/infrawrench/client.rb', line 8786

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:



8816
8817
8818
8819
8820
8821
8822
8823
8824
 
# File 'lib/infrawrench/client.rb', line 8816

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:



8859
8860
8861
8862
8863
8864
8865
8866
8867
 
# File 'lib/infrawrench/client.rb', line 8859

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:



8893
8894
8895
8896
8897
8898
8899
8900
8901
 
# File 'lib/infrawrench/client.rb', line 8893

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:



8932
8933
8934
8935
8936
8937
8938
8939
8940
 
# File 'lib/infrawrench/client.rb', line 8932

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