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:



8415
8416
8417
 
# File 'lib/infrawrench/client.rb', line 8415

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:



8453
8454
8455
8456
8457
8458
8459
8460
 
# File 'lib/infrawrench/client.rb', line 8453

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:



8484
8485
8486
8487
8488
8489
8490
8491
8492
 
# File 'lib/infrawrench/client.rb', line 8484

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:



8513
8514
8515
8516
8517
8518
8519
8520
 
# File 'lib/infrawrench/client.rb', line 8513

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:



8541
8542
8543
8544
8545
8546
8547
8548
8549
 
# File 'lib/infrawrench/client.rb', line 8541

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:



8569
8570
8571
8572
8573
8574
8575
8576
 
# File 'lib/infrawrench/client.rb', line 8569

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:



8599
8600
8601
8602
8603
8604
8605
8606
8607
 
# File 'lib/infrawrench/client.rb', line 8599

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:



8642
8643
8644
8645
8646
8647
8648
8649
8650
 
# File 'lib/infrawrench/client.rb', line 8642

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:



8676
8677
8678
8679
8680
8681
8682
8683
8684
 
# File 'lib/infrawrench/client.rb', line 8676

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:



8715
8716
8717
8718
8719
8720
8721
8722
8723
 
# File 'lib/infrawrench/client.rb', line 8715

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