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:



8160
8161
8162
 
# File 'lib/infrawrench/client.rb', line 8160

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:



8198
8199
8200
8201
8202
8203
8204
8205
 
# File 'lib/infrawrench/client.rb', line 8198

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:



8229
8230
8231
8232
8233
8234
8235
8236
8237
 
# File 'lib/infrawrench/client.rb', line 8229

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:



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

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:



8286
8287
8288
8289
8290
8291
8292
8293
8294
 
# File 'lib/infrawrench/client.rb', line 8286

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:



8314
8315
8316
8317
8318
8319
8320
8321
 
# File 'lib/infrawrench/client.rb', line 8314

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:



8344
8345
8346
8347
8348
8349
8350
8351
8352
 
# File 'lib/infrawrench/client.rb', line 8344

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:



8387
8388
8389
8390
8391
8392
8393
8394
8395
 
# File 'lib/infrawrench/client.rb', line 8387

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:



8421
8422
8423
8424
8425
8426
8427
8428
8429
 
# File 'lib/infrawrench/client.rb', line 8421

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:



8460
8461
8462
8463
8464
8465
8466
8467
8468
 
# File 'lib/infrawrench/client.rb', line 8460

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