Sign in

v1

latestOpenAPI 3.0.02026-07-2422987517.5 KB
Bill

List bills

Returns a paginated list of the company's bills ("boletas/facturas de Cardda"): the monthly billing documents that aggregate Cardda's commission charges.

Scope

Company users only see bills for companies they are a member of (via their company memberships). Cardda staff see all bills.

Filtering, sorting, pagination

Supports the standard list controls: _start/_end for pagination, _field/_order for sorting, and per-field filters. A filter value can be a plain value (exact match) or a JSON string with an operator, e.g. status={"$in":["issued","preissued"]}.

Response

Each bill includes charges_with_descriptions, a human-readable breakdown of the per-product charges.

get/v1/bills

Query parameters

_startinteger

If all the transactions where in an array, this would represent the index of the first item returned in the response

_endinteger

If all the transactions where in an array, this would represent the index of the last item returned in the response

_order'asc' | 'desc'

The order method, which can be ascending or descending

_fieldstring
Example:created_at

The field used to sort, the example illustrates a response that would be sorted by the creation date

company_idstring

Filter by company UUID. Supports {"$in":[...]} for batch lookups.

statusstring

Filter by bill status (e.g. draft, preissued, issued).

monthinteger

Filter by billing month (1-12).

yearinteger

Filter by billing year.

Headers

company-idstring uuid required

UUID of the company on whose behalf the request is made. Required for every Finance endpoint. See The company-id header for details on how to obtain a value for this header and the error responses to expect when it is missing or invalid.

Response

Paginated list of bills.

idstring uuid required
company_idstring uuid required

Company the bill belongs to.

monthinteger nullable
yearinteger nullable
statusstring nullable

Lifecycle state of the bill.

  • draft - being assembled, not yet issued
  • preissued - pre-issued at the tax authority
  • issued - final tax document emitted
transitionstring nullable

In-flight state transition, when a status change is being processed.

external_idstring nullable

Identifier of the emitted document at the external billing provider.

total_amountinteger nullable

Total amount of the bill, in the smallest currency unit.

datestring date nullable

Issue date of the bill.

fiscal_invoice_idstring nullable

Identifier of the associated fiscal (SII) invoice, when emitted.

chargesobject nullable

Raw per-product charge map ({ "<product>": <amount_cents> }) accumulated from the underlying commissions.

created_atstring date-time
updated_atstring date-time

Example response

[
  {
    "month": 6,
    "year": 2024,
    "status": "issued",
    "total_amount": 119000,
    "charges_with_descriptions": [
      {
        "amount": 100000,
        "description": "Comisión transferencias"
      }
    ]
  }
]