Skip to main content

Query Filters

Our APIs have a filtering system that allows querying for a resource by many different attributes and operations.

List Allowed Filters [GET]

BASE URL
https://api-b2b-hml.carbonext.com.br/v1/allowed-filters/:resource

Request Parameter

ParameterDescription
resourceIt could be any feedback we saw on the [Resources] page (/docs/core-concepts/resources)

Response Parameters

ParameterDescription
filtersAn array of available filters
sortAn array of available sorts
aggregatePerforms math operations for the filter

This endpoint returns the fields accepted for filtering and sorting. It is important to mention that sort has the createdAt_desc filter by default.

Example Request

var axios = require('axios');

var config = {
method: 'get',
url: 'https://api-b2b-hml.carbonext.com.br/v1/allowed-filters/orders',
headers: { }
};

axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

Example Response

{
"filters": [
"status_eq",
"status_ne",
"status_in",
"vcuUnitPrice_ge",
"vcuUnitPrice_le",
"vcuUnitPrice_gt",
"vcuUnitPrice_lt",
"vcuAmount_eq",
"vcuAmount_ge",
"vcuAmount_le",
"vcuAmount_gt",
"vcuAmount_lt",
"invoiceId_eq",
"createdAt_eq",
"createdAt_ge",
"createdAt_le",
"createdAt_gt",
"createdAt_lt",
"totalPrice_eq",
"totalPrice_ge",
"totalPrice_le",
"totalPrice_gt",
"totalPrice_lt",
"type_eq",
"type_ne",
"type_in",
"retireForRecipient_eq",
"thirdPartyTaxId_eq",
"invoiceId_eq",
"subscriptionId_eq"
],
"sort": ["createdAt", "vcuAmount", "status", "vcuUnitPrice"],
"aggregate": {
"columns": ["vcuAmount", "vcuUnitPrice", "totalPrice"],
"operations": ["sum", "avg", "min", "max", "count"]
}
}

Let's see how many filter operations we have and what they mean.

Available Filters Operations

FilterValueDescription
eq=Returns fields with values equal then what was passed in the filter
ne!=Returns fields with different values than what was passed in the filter
ge>=Returns fields with values greater than or equal to what was passed in the filter
le<=Returns fields with values less than or equal to what was passed in the filter. For createdAt, at 23:59:59pm before the date chosen in the YYYY-MM-DD format
gt>Returns fields with values greater than what was passed in the filter
lt<Returns fields with values less than what was passed in the filter. For createdAt, at 00:00 am before the date chosen in the YYYY-MM-DD format
FilterDescription
instatus in (1,2,3) returns records with status equal to 1 or 2 or 3 (status here is the field with filter type _in)
likeReturns records that contain the value sought in the filter (case insensitive).

List Invoices by Filter [GET]

BASE URL
https://api-b2b.carbonext.com.br/v1/invoices

Let's see a practical example of the query filters applied to invoices, in this example, we will return a list of invoices filtered by totalVcuAmount and status. To use more than one filter on the same query, they must be separated by a tilde (~).

The filter syntax is ?filter-by=filter1:value2~filter2:value2, as for the filters with the in operator, the values must be separated by a hyphen -.

The following example will illustrate querying invoices with totalVcuAmount greater or equal to 30, that have a status of either Paid or Pending (enum status names are case insensitive)

Response Parameters

ParameterDescription
itemsAn array of filtered invoices

Request Example

var axios = require('axios');

var config = {
method: 'get',
url: 'https://api-b2b-hml.carbonext.com.br/v1/invoices/invoices?sort-by=totalVcuAmount_asc&filter-by=totalVcuAmount_ge:30~status_in:Paid-pending',
headers: { }
};

axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});

Response Example

{
"items": [
{
"id": "8b864cbf-c181-4405-b119-91b2f63b1954",
"status": "Pending",
"totalVcuAmount": 30,
"totalPrice": 2310,
"currency": "BRL",
"customerId": "a2170dcf-a87f-4fdb-b4e6-54e4f0889324",
"createdAt": "2022-01-05T22:20:57.378254",
"paidAt": null,
"dueDate": null
},
{
"id": "5a8ff819-f60b-450b-9efb-f62c1445d511",
"status": "Pending",
"totalVcuAmount": 45,
"totalPrice": 3465,
"currency": "BRL",
"customerId": "a2170dcf-a87f-4fdb-b4e6-54e4f0889324",
"createdAt": "2022-01-05T22:09:21.372156",
"paidAt": null,
"dueDate": null
},
{
"id": "5e27bd46-95ce-4fd1-86c6-04fbd18e45bb",
"status": "Pending",
"totalVcuAmount": 45,
"totalPrice": 3465,
"currency": "BRL",
"customerId": "a2170dcf-a87f-4fdb-b4e6-54e4f0889324",
"createdAt": "2022-01-05T22:20:08.853038",
"paidAt": null,
"dueDate": null
},
{
"id": "3951ae7b-2c3d-4bd8-a05c-7755328413b5",
"status": "Pending",
"totalVcuAmount": 60,
"totalPrice": 4620,
"currency": "BRL",
"customerId": "a2170dcf-a87f-4fdb-b4e6-54e4f0889324",
"createdAt": "2022-01-05T22:15:43.037432",
"paidAt": null,
"dueDate": null
},
{
"id": "b92c0e55-45b0-4be2-9b85-c28d834137eb",
"status": "Pending",
"totalVcuAmount": 100,
"totalPrice": 7700,
"currency": "BRL",
"customerId": "a2170dcf-a87f-4fdb-b4e6-54e4f0889324",
"createdAt": "2021-12-10T20:47:11.424205",
"paidAt": null,
"dueDate": null
},
{
"id": "117f2fd6-953d-42d0-895d-31abc809af88",
"status": "Paid",
"totalVcuAmount": 10000,
"totalPrice": 770000,
"currency": "BRL",
"customerId": "a2170dcf-a87f-4fdb-b4e6-54e4f0889324",
"createdAt": "2021-12-09T19:49:43.112941",
"paidAt": "2021-12-10T20:12:09.154332",
"dueDate": null
},
{
"id": "71050ef4-ae2a-4966-beaf-603d75b3f8c2",
"status": "Paid",
"totalVcuAmount": 10000,
"totalPrice": 770000,
"currency": "BRL",
"customerId": "a2170dcf-a87f-4fdb-b4e6-54e4f0889324",
"createdAt": "2021-12-06T13:54:13.56172",
"paidAt": "2021-12-06T14:06:19.755607",
"dueDate": null
}
],
"pageIndex": 1,
"totalPages": 1,
"totalCount": 7,
"hasPreviousPage": false,
"hasNextPage": false
}