# Implementation example

This section gives a step-by-step example for fetching bookkeeping data and optionally marking verifications as synced. It assumes activation level [organization.company](/apis/organization) (API calls are then scoped to that company).

### Step 1: Confirmed verification groups

Fetch confirmed verification groups after a given date (e.g. 30 days before the run).

- Unconfirmed groups have no `confirmation_date` and are excluded.
- For minimal payload, add `_slim=true` to return only `id`.


**Endpoint:** [GET /accounting/bookkeeping/verificationgroup/list/](/apis/accounting)


```
GET .../accounting/bookkeeping/verificationgroup/list/?_page=1&_page_size=500&confirmation_date__gte=2024-01-15
```

**Query parameters:**

- **_page** — Page number (e.g. 1)
- **_page_size** — Page size (e.g. 500)
- **confirmation_date__gte** — Only groups confirmed on or after this date (e.g. 2024-01-15)


### Step 2: Verifications in those groups

Fetch [accounting.verification](/apis/accounting) items in the groups from step 1, with a registration date filter (e.g. same 30-day window) to avoid re-syncing old data.

- Filtering on `registration_date` is recommended to avoid duplicate syncs.


**Endpoint:** [GET /accounting/bookkeeping/verification/list/](/apis/accounting)


```
GET .../accounting/bookkeeping/verification/list/?_page=1&_page_size=500&registration_date__gte=2024-01-15&verification_group__in=<group-id-1>,<group-id-2>
```

**Query parameters:**

- **_page** — Page number (e.g. 1)
- **_page_size** — Page size (e.g. 500)
- **registration_date__gte** — Only verifications registered on or after this date (e.g. 2024-01-15)
- **verification_group__in** — Comma-separated IDs from step 1


### Step 3: Transactions for those verifications

Fetch [accounting.transaction](/apis/accounting) items for the verifications from step 2.

**Endpoint:** [GET /accounting/bookkeeping/transaction/list/](/apis/accounting) (or equivalent transaction list in the API)


```
GET .../accounting/bookkeeping/transaction/list/?_page=1&_page_size=500&verification__in=<verification-id-1>,<verification-id-2>
```

**Query parameters:**

- **_page** — Page number (e.g. 1)
- **_page_size** — Page size (e.g. 500)
- **verification__in** — Comma-separated verification IDs from step 2


### Step 4 (optional): Invoice PDF files

1. Collect the set of invoice IDs from the `invoice` field on the verifications from step 2.
2. Fetch [accounting.invoicerelatedpdffile](/apis/accounting) items.


**Endpoint:** List endpoint for invoice-related PDF files (see API Reference).


```
GET .../accounting/invoicerelatedpdffile/list/?_page=1&_page_size=500&invoice__in=<invoice-id-1>,<invoice-id-2>
```

**Query parameters:**

- **_page** — Page number (e.g. 1)
- **_page_size** — Page size (e.g. 500)
- **invoice__in** — Comma-separated invoice IDs from verifications (step 2)


### Step 5 (optional): Mark verifications as synced

You can record that a verification has been synced/processed. This reduces duplicate syncs and allows Pigello UI to show sync status.

- **POST** to the list endpoint for [integrations.integrationserviceidconnection](/apis/integrations) with a list of items.
- Set `content_type` to `{"id":"accounting.verification"}` and `object_id` to the verification ID.
- Set `external_id` to the ID in your external system.


**Endpoint:** List endpoint for [integrations.integrationserviceidconnection](/apis/integrations).

To list connections for verifications:


```
GET .../integrations/integrationserviceidconnection/list/accounting.verification/?_page=1&_page_size=500
```

**Query parameters:**

- **_page** — Page number (e.g. 1)
- **_page_size** — Page size (e.g. 500)


**Notes:**

- All activations of your integration can read each other's integration-service-id connections (e.g. Company A can see connections for Company B).


This section gives the same bookkeeping flow using the **Pigello Python SDK**. It assumes activation level [organization.company](/apis/organization) (list calls are then scoped to that company).

You need a session for integration (user-agent) access. Use **`APIUserAgentSession`** from `pigello_sdk.session` with your application ID, service ID, target customer, content type, target object ID, client secret, and optionally service version ID. See [Python SDK — Session](/tools/sdks/#session-authentication) for details.

### Step 1: Confirmed verification groups

Fetch confirmed verification groups after a given date (e.g. 30 days before the run). Unconfirmed groups have no `confirmation_date` and are excluded by the filter.


```python
from pigello_sdk.entities.accounting.verificationgroup import Verificationgroup

since_date = date.today() - timedelta(days=30)

vg_query = Verificationgroup.get_query_helper(session)
vg_query.add_filters([
    FilterInstruction("confirmation_date", FILTER_OPERATIONS.GTE, since_date),
    FilterInstruction("_slim", FILTER_OPERATIONS.EQ, True), # if you don't need the rest of the attributes for the verification-groups
])
vg_query.set_pagination(page_size=500, page=1)

vg_result = vg_query.collect_query()
verification_groups = vg_result.instances  # EntitiesList[Verificationgroup]

group_ids = [vg.id for vg in verification_groups if vg.id]
```

### Step 2: Verifications in those groups

Fetch [accounting.verification](/apis/accounting) items in the groups from step 1, with a registration date filter (e.g. same 30-day window) to avoid re-syncing old data.


```python
from pigello_sdk.entities.accounting.verification import Verification

v_query = Verification.get_query_helper(session)
v_query.add_filters([
    FilterInstruction("registration_date", FILTER_OPERATIONS.GTE, since_date),
    FilterInstruction("verification_group", FILTER_OPERATIONS.IN, group_ids),
])
v_query.set_pagination(page_size=500, page=1)

v_result = v_query.collect_query()
verifications = v_result.instances  # EntitiesList[Verification]

verification_ids = [v.id for v in verifications if v.id]
```

### Step 3: Transactions for those verifications

Fetch [accounting.transaction](/apis/accounting) items for the verifications from step 2.


```python
from pigello_sdk.entities.accounting.transaction import Transaction

t_query = Transaction.get_query_helper(session)
t_query.add_filters([
    FilterInstruction("verification", FILTER_OPERATIONS.IN, verification_ids),
])
t_query.set_pagination(page_size=500, page=1)

t_result = t_query.collect_query()
transactions = t_result.instances  # EntitiesList[Transaction]
```

### Step 4 (optional): Invoice PDF files

Collect the set of invoice IDs from the `invoice` field on the verifications from step 2, then fetch [accounting.invoicerelatedpdffile](/apis/accounting) items.


```python
from pigello_sdk.entities.accounting.invoicerelatedpdffile import Invoicerelatedpdffile

# Collect invoice IDs from verifications (resolve invoice if needed)
invoice_ids = list({v.invoice.id for v in verifications if v.invoice and v.invoice.id})

if invoice_ids:
    pdf_query = Invoicerelatedpdffile.get_query_helper(session)
    pdf_query.add_filters([
        FilterInstruction("invoice", FILTER_OPERATIONS.IN, invoice_ids),
    ])
    pdf_query.set_pagination(page_size=500, page=1)
    pdf_result = pdf_query.collect_query()
    pdf_files = pdf_result.instances  # EntitiesList[Invoicerelatedpdffile]
```

### Step 5 (optional): Mark verifications as synced

Record that a verification has been synced/processed by creating [integrations.integrationserviceidconnection](/apis/integrations) rows. Set `content_type` to the content type for verification, `object_id` to the verification ID, and `external_id` to the ID in your external system.

**Notes:**

- All activations of your integration can read each other's integration-service-id connections (e.g. Company A can see connections for Company B).



```python
from pigello_sdk.entities.integrations.integrationserviceidconnection import Integrationserviceidconnection
from pigello_sdk.entities.contenttypes.contenttype import Contenttype

VERIFICATION_CONTENT_TYPE = "accounting.verification"

# Example: (verification_id, external_system_id) for each synced verification
sync_map = [
    (some_verification_id, "external-id-1"),
    (another_verification_id, "external-id-2"),
]

connections = []
for object_id, external_id in sync_map:
    conn = Integrationserviceidconnection(
        session=session,
        content_type=Contenttype(id=VERIFICATION_CONTENT_TYPE),
        object_id=object_id,
        external_id=external_id,
    )
    connections.append(conn)

if connections:
    list_to_save = bulk.EntitiesList(session, connections)
    list_to_save.save()
```

## Summary

| Step | SDK entities | Action |
|  --- | --- | --- |
| 1 | `Verificationgroup` | Filter `confirmation_date__gte`, `collect_query()`, collect group IDs. |
| 2 | `Verification` | Filter `registration_date__gte`, `verification_group__in`, collect verification IDs. |
| 3 | `Transaction` | Filter `verification__in`. |
| 4 (optional) | `Invoicerelatedpdffile` | Filter `invoice__in`. |
| 5 (optional) | `Integrationserviceidconnection` | Build instances with `Contenttype(id="accounting.verification")`, `object_id`, `external_id`; put in `EntitiesList(session, list)` and `.save()`. |


For more on the SDK (session types, filters, resolving relations), see the [Python SDK](/tools/sdks/) documentation.