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:



8106
8107
8108
 
# File 'lib/infrawrench/client.rb', line 8106

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:



8144
8145
8146
8147
8148
8149
8150
8151
 
# File 'lib/infrawrench/client.rb', line 8144

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:



8175
8176
8177
8178
8179
8180
8181
8182
8183
 
# File 'lib/infrawrench/client.rb', line 8175

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:



8204
8205
8206
8207
8208
8209
8210
8211
 
# File 'lib/infrawrench/client.rb', line 8204

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:



8232
8233
8234
8235
8236
8237
8238
8239
8240
 
# File 'lib/infrawrench/client.rb', line 8232

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:



8260
8261
8262
8263
8264
8265
8266
8267
 
# File 'lib/infrawrench/client.rb', line 8260

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:



8290
8291
8292
8293
8294
8295
8296
8297
8298
 
# File 'lib/infrawrench/client.rb', line 8290

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:



8333
8334
8335
8336
8337
8338
8339
8340
8341
 
# File 'lib/infrawrench/client.rb', line 8333

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:



8367
8368
8369
8370
8371
8372
8373
8374
8375
 
# File 'lib/infrawrench/client.rb', line 8367

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:



8406
8407
8408
8409
8410
8411
8412
8413
8414
 
# File 'lib/infrawrench/client.rb', line 8406

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