Selezione Risultati

Le API di Sibill permettono di selezionare i risultati per aiutare il cliente a fare ricerche più precise. Non esiste un ordinamento predefinito, ma è possibile ordinare i risultati utilizzando il parametro sort.

Ogni risorsa ammette un insieme di campi su cui si possono applicare dei filtri e si trovano nella API reference di ciascuna risorsa e chiamata.

Come si fa

I filtri devono essere passati come parametri in query string nella seguente forma: filter[campo__operatore]=valore Dove campo è il nome del campo che si vuole filtrare seguito da __ (2 underscore) e poi da operatore che rappresenta l'operatore di filtro, infine c'è il valore.

Questo è un esempio di come utilizzare le api con i filtri GET /api/v1/companies/:company_id/documents?filter[status__eq]=DRAFT

La chiamata precedente recupererà tutti i documenti che hanno status uguale a DRAFT.

Lista operatori

Segue una tabella con gli operatori che è possibile usare nei filtri. Alcuni operatori possono essere usati solo con alcuni tipi di campi.

Operatore	Descrizione	Esempio
eq	{'=='}	filter[status__eq]=DRAFT
neq	{'!='}	filter[status__neq]=DRAFT
gt	{'>'}	filter[amount__gt]=10
gte	{'>='}	filter[amount__gte]=10
lt	{'<'}	filter[amount__lt]=10
lte	{'<='}	filter[amount__lte]=10
in	in	filter[status__in]=DRAFT,CREATED
notIn	!in	filter[status__notIn]=DRAFT,CREATED
empty	campo valorizzato o meno	filter[delivery_status__empty]=true / filter[delivery_status__empty]=false
ilike	ricerca testuale sul campo case insensitive	filter[description__ilike]=fatt

warning

I valori dei filtri di tipo Enum (o comunque con un set di valori limitati) devono essere passati in come stringa in uppercase.

GET /api/v1/companies/:company_id/documents?filter[creation_date__gte]=2025-02-01&filter[creation_date__lte]=2025-02-28&filter[status__eq]=DRAFT

HTTP/1.1 200 Ok
Content-Type: application/json

{
   "data":[
      {
         "created_at":"2025-02-06T08:21:37.999777Z",
         "creation_date":"2025-02-07",
         "delivery_date":null,
         "delivery_status":null,
         "format":"FPR12",
         "id":"aa5d3bb5-a8b8-4124-9ce1-47963b56c260",
         "number":"document-number-ddonp",
         "status":"DRAFT",
         "updated_at":"2025-03-06T08:21:37.999777Z"
      },
      ...
   ],
   "page":{
      "cursor":"g3QAAAACdwJpZG0AAAAkYzg3ZTNiYmMtYzNhZi00ZmFjLThkNzYtNmE1MTgzMDRhYdw1pY3JvkYXJ3E0NQRjEyAA==",
      "size":25
   }
}

Recupera i documenti che sono in stato DRAFT oppure CREATED

Da notare che gli operatori in e notIn si aspettano una lista separata da virgole

GET /api/v1/companies/:company_id/documents?filter[status__in]=DRAFT,CREATED

HTTP/1.1 200 Ok
Content-Type: application/json

{
   "data":[
      {
         "created_at":"2025-02-06T08:21:37.999777Z",
         "creation_date":"2025-02-07",
         "delivery_date":null,
         "delivery_status":null,
         "format":"FPR12",
         "id":"aa5d3bb5-a8b8-4124-9ce1-47963b56c260",
         "number":"document-number-ddonp",
         "status":"DRAFT",
         "updated_at":"2025-03-06T08:21:37.999777Z"
      },
      ...
   ],
   "page":{
      "cursor":"g3QAAAACdwJpZG0AAAAkYzg3ZTNiYmMtYzNhZi00ZmFjLThkNzYtNmE1MTgzMDRhYdw1pY3JvkYXJ3E0NQRjEyAA==",
      "size":25
   }
}

Esempio con l'operatore ilike

L'operatore ilike è molto simile all'operatore ilike che si trova nella maggior parte dei database, nel caso che segue verranno restituite tutte le transazioni che hanno nel campo clean_description la stringa stipendi ignorando il case.

GET /api/v1/companies/:company_id/transactions?filter[clean_description__ilike]=stipendi

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": [
    {
      "booking_date_time": "2019-08-24T14:15:22Z",
      "amount": {
        "amount": 1000,
        "currency": "EUR"
      },
      "clean_description": "stipendio marzo",
      "counterpart_name": "counterpat name",
      "created_at": "2019-08-24T14:15:22Z",
      "date": "2019-08-24T14:15:22Z",
      "description": "StipEndio Marzo ",
      "id": "06a5b150-2c10-4127-ab4c-dcab46029910",
      "value_date_time": "2019-08-24T14:15:22Z"
    },
    ...
  ],
  "page": {
    "cursor": "g3QAAAACdwJpZG0AAAAkYzg3ZTNiYmMtYzNhZi00ZmFjLThkNzYtNmE1MTgzMDRhYdw1pY3JvkYXJ3E0NQRjEyAA==",
    "size": 25
  }
}