Sibill Integration API (1.0.0)

API reference

The Sibill API is organized around REST. Our API has predictable resource-oriented URLs, accepts multiple encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

The Sibill API uses API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. All API requests must be made over HTTPS. API requests without authentication will fail.

Errors

Sibill uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Sibill’s servers. Some 4xx errors that could be handled programmatically (e.g., an invoice is declined) include an error code that briefly explains the error reported.

HTTP Status Code	Meaning	Description
200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid API key provided.
402	Request Failed	The parameters were valid but the request failed.
403	Forbidden	The API key doesn’t have permissions to perform the request.
404	Not Found	The requested resource doesn’t exist.
422	Unprocessable entity	The server understood the content type of the request content, and the syntax of the request content was correct, but it was unable to process the contained instructions.
429	Too Many Requests	The client has sent too many requests in a given amount of time. This mechanism of asking the client to slow down the rate of requests, that is of 10 requests per second.
500, 502, 503, 504	Server Errors	Something went wrong on Sibill’s end.

Environments

There are two available environments: Development and Production. The base_url will change depending on the selected environment:

Development: https://integration.dev.sibill.com
Production: https://integration.sibill.com

Webhook

Document updated event Webhook

Triggered when a Document has successfully been updated.

Request Body schema: application/json
required

company_id required	string <uuid> Company identifier
required	object (DocumentSchema) Document data representation
id required	string <uuid> The id of the event
event required	string Value: "document.updated" The type of the event that happend to the resource

Responses

Request samples

Payload

Content type

application/json

{"company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
"data": {"category": {"id": "01a09ff1-9ad8-7024-b102-e44db79ec2ff",
"name": "string"
},
"counterpart": {"address": "string",
"bank_identifier": "string",
"city": "string",
"company_name": "string",
"country": "string",
"destination_code": "string",
"id": "01a09ff1-9bb4-76fa-988d-53f2d30cb566",
"identity_type": "COMPANY",
"issued_category": {"color": "string",
"id": "01a09ff1-9bb4-720f-9e78-dc26cb46b800",
"name": "string"
},
"issued_subcategory": {"category_id": "01a09ff1-9bb4-76df-b93b-e4e0f10dd800",
"id": "01a09ff1-9bb4-7a18-9fd3-c70e83ef6368",
"name": "string"
},
"payment_date": "15",
"payment_method": "CARD",
"postal_code": "string",
"province_code": "string",
"received_category": {"color": "string",
"id": "01a09ff1-9bb4-7762-8a33-9add66223f9e",
"name": "string"
},
"received_subcategory": {"category_id": "01a09ff1-9bb4-7e5a-b733-244ffca0e80e",
"id": "01a09ff1-9bb4-7e5d-a215-40a56bfea4f6",
"name": "string"
},
"tax_number": "string",
"vat_number": "string"
},
"created_at": "2019-08-24T14:15:22Z",
"creation_date": "2019-08-24",
"delivery_date": "string",
"delivery_status": "string",
"direction": "ISSUED",
"external_id": "string",
"file_name": "string",
"flows": [{"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
}
],
"format": "FPA12",
"gross_amount": {"amount": "12.3",
"currency": "EUR"
},
"id": "01a09ff1-9ad8-7fb5-9ff7-8528672ddee7",
"is_e_invoice": true,
"notes": "string",
"number": "NC/12345/2026",
"progressive": "12345",
"reasons_and_remarks": ["string"
],
"sectional": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"minimum_digits": 0,
"prefix": "NC/",
"suffix": "/2026"
},
"status": "DRAFT",
"subcategory": {"id": "01a09ff1-9ad8-7489-a0af-4a59153b1e47",
"name": "string"
},
"type": "BILL",
"updated_at": "2019-08-24T14:15:22Z",
"vat_amount": {"amount": "12.3",
"currency": "EUR"
}
},
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"event": "document.updated"
}

Flow updated event Webhook

Triggered when a Flow has successfully been updated.

Request Body schema: application/json
required

company_id required	string <uuid> Company identifier
required	object (FlowSchema) Flow data representation
id required	string <uuid> The id of the event
event required	string Value: "flow.updated" The type of the event that happened to the resource

Responses

Request samples

Payload

Content type

application/json

{"company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
"data": {"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
},
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"event": "flow.updated"
}

Company

List all the available companies

List all the companies for the current integrator

Authorizations:

None

query Parameters

expand

string

Fields that will be expanded. Expandable fields: company_identity, subscriptions

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

200
401
403
429
500

Content type

application/json

{"data": [{"company_identity": {"address": "string",
"city": "string",
"country": "string",
"postal_code": "string",
"province_code": "string"
},
"country": "string",
"fiscal_regime": "string",
"id": "01a09ff1-9e29-7cb3-892c-4833bac52d47",
"name": "string",
"subscriptions": [{"created_at": "2019-08-24T14:15:22Z",
"status": "PRE_TRIAL"
}
],
"vat_number": "string"
}
]
}

Account

List all accounts for the company

The return value is paginated. By default the response contains 25 elements per page but can be instructed to return more elements per page. A cursor is needed to traverse the results.

Authorizations:

None

path Parameters

company_id

required

string

The company the accounts belong to

query Parameters

page_size	integer The page size
cursor	string The pagination cursor. A cursor is used to paginate through a large set of data. It is a unique identifier that represents a specific position in the dataset.
filter	object List of filters on the resource. Currently the fields that allow to be filtered are: `id`
sort	string Fields for which we can order the results. Sortable fields: `created_at`

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/accounts \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": [{"available_balance": {"amount": "12.3",
"currency": "EUR"
},
"balance_date": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"credit_limit": {"amount": "12.3",
"currency": "EUR"
},
"currency": "AED",
"current_balance": {"amount": "12.3",
"currency": "EUR"
},
"id": "01a09ff1-a1c3-776e-b51c-38a0aa0c192f",
"nickname": "string"
}
],
"page": {"cursor": "string",
"size": 0
}
}

Get a account

Returns all the information for a specific account from its identifier

Authorizations:

None

path Parameters

company_id required	string The company the account belongs to
id required	string The account identifier

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/accounts/:account_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": {"available_balance": {"amount": "12.3",
"currency": "EUR"
},
"balance_date": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"credit_limit": {"amount": "12.3",
"currency": "EUR"
},
"currency": "AED",
"current_balance": {"amount": "12.3",
"currency": "EUR"
},
"id": "01a09ff1-a1c3-776e-b51c-38a0aa0c192f",
"nickname": "string"
}
}

List all categories for the company

The return value is paginated. By default the response contains 25 elements per page but can be instructed to return more elements per page. A cursor is needed to traverse the results.

Authorizations:

None

path Parameters

company_id

required

string

The company the categories belong to

query Parameters

page_size	integer The page size
cursor	string The pagination cursor. A cursor is used to paginate through a large set of data. It is a unique identifier that represents a specific position in the dataset.
filter	object List of filters on the resource. Currently the fields that allow to be filtered are: `id`, `name`
sort	string Fields for which we can order the results. Sortable fields: `name`

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/categories \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": [{"color": "string",
"id": "01a09ff1-a1c7-7b73-b901-24367a1fc5b7",
"name": "string"
}
],
"page": {"cursor": "string",
"size": 0
}
}

Create a new category

Authorizations:

None

path Parameters

company_id

required

string

The company the category belongs to

Request Body schema: application/json
optional

Responses

Request samples

Content type

application/json

{"color": "string",
"name": "string"
}

Response samples

Content type

application/json

{"data": {"color": "string",
"id": "01a09ff1-a1c7-7b73-b901-24367a1fc5b7",
"name": "string"
}
}

Delete a category

Deletes the category and clears its reference from associated transactions, recurrences and counterparts.

Authorizations:

None

path Parameters

company_id required	string The company the category belongs to
id required	string The category identifier

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request DELETE \
     --url ${base_url}/api/v1/companies/:company_id/categories/:category_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

401
403
404
429
500

Content type

application/json

{"errors": [{"code": "bad_request",
"detail": "null value where string expected",
"source": {"pointer": "/data/attributes/name"
},
"title": "Invalid value"
}
]
}

Get a category

Returns all the information for a specific category from its identifier

Authorizations:

None

path Parameters

company_id required	string The company the category belongs to
id required	string The category identifier

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/categories/:category_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": {"color": "string",
"id": "01a09ff1-a1c7-7b73-b901-24367a1fc5b7",
"name": "string"
}
}

Update an existing category

Authorizations:

None

path Parameters

company_id required	string The company the category belongs to
id required	string The category identifier

Request Body schema: application/json
optional

Responses

Request samples

Content type

application/json

{"color": "string",
"name": "string"
}

Response samples

Content type

application/json

{"data": {"color": "string",
"id": "01a09ff1-a1c7-7b73-b901-24367a1fc5b7",
"name": "string"
}
}

Counterpart

Get the list of counterparts

The return value is paginated. By default the response contains 25 elements per page but can be instructed to return more elements per page. A cursor is needed to traverse the results.

Authorizations:

None

path Parameters

company_id

required

string

The company the counterparts belongs to

query Parameters

page_size	integer The page size
cursor	string The pagination cursor. A cursor is used to paginate through a large set of data. It is a unique identifier that represents a specific position in the dataset.
filter	object List of filters on the resource. Currently the fields that allow to be filtered are: `vat_number`, `tax_number`, `company_name`
sort	string Fields for which we can order the results. Sortable fields: `company_name`
expand	string Fields that will be expanded. Expandable fields: `issued_category`, `issued_subcategory`, `received_category`, `received_subcategory`

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/counterparts \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

200
401
403
404

Content type

application/json

{"data": [{"address": "string",
"bank_identifier": "string",
"city": "string",
"company_name": "string",
"country": "string",
"destination_code": "string",
"id": "01a09ff1-9bb4-76fa-988d-53f2d30cb566",
"identity_type": "COMPANY",
"issued_category": {"color": "string",
"id": "01a09ff1-9bb4-720f-9e78-dc26cb46b800",
"name": "string"
},
"issued_subcategory": {"category_id": "01a09ff1-9bb4-76df-b93b-e4e0f10dd800",
"id": "01a09ff1-9bb4-7a18-9fd3-c70e83ef6368",
"name": "string"
},
"payment_date": "15",
"payment_method": "CARD",
"postal_code": "string",
"province_code": "string",
"received_category": {"color": "string",
"id": "01a09ff1-9bb4-7762-8a33-9add66223f9e",
"name": "string"
},
"received_subcategory": {"category_id": "01a09ff1-9bb4-7e5a-b733-244ffca0e80e",
"id": "01a09ff1-9bb4-7e5d-a215-40a56bfea4f6",
"name": "string"
},
"tax_number": "string",
"vat_number": "string"
}
],
"page": {"cursor": "string",
"size": 0
}
}

Create a new counterpart

Authorizations:

None

path Parameters

company_id

required

string

The company the counterpart belongs to

query Parameters

expand

string

Fields that will be expanded. Expandable fields: issued_category, issued_subcategory, received_category, received_subcategory

Request Body schema: application/json
optional

Counterpart

address	string or null The address
bank_identifier	string or null The bank coordinates (e.g. IBAN) used for payments to this counterpart
city	string or null The city
company_name	string or null The company name of the counterpart
country required	string The country (ISO code)
destination_code	string or null The destination code (if applicable) for the Italian Electronic system (SDI).
identity_type	string or null Enum: "COMPANY" "PA" "PERSON" "CONTRACTOR" The type of the counterpart. Possible values are: `COMPANY`: a company `PA`: a public authority `PERSON`: a person `CONTRACTOR`: a contractor
issued_category_id	string or null <uuid> The identifier of the category applied to documents issued to this counterpart
issued_subcategory_id	string or null <uuid> The identifier of the subcategory applied to documents issued to this counterpart. Must belong to issued_category_id.
payment_date	string or null Enum: "15" "30" "60" "90" "120" "150" "EOM" "30EOM" "60EOM" "90EOM" "120EOM" "150EOM" "EOMPLUS15" "30EOMPLUS15" "60EOMPLUS15" "90EOMPLUS15" "120EOMPLUS15" Configurable payment date interval for received invoices
payment_method	string or null Enum: "CARD" "CASH" "CHECK" "DEFERRED" "TAX_FORM" "FISCAL_CREDIT" "OTHER" "POSTAL" "RIBA" "SDD" "TRANSFER" Expected method of payment for the counterpart
postal_code	string or null The postal code (if applicable)
province_code	string or null The province code (if applicable)
received_category_id	string or null <uuid> The identifier of the category applied to documents received from this counterpart
received_subcategory_id	string or null <uuid> The identifier of the subcategory applied to documents received from this counterpart. Must belong to received_category_id.
tax_number	string or null The tax number
vat_number	string or null The VAT number

Responses

Request samples

Content type

application/json

{"address": "string",
"bank_identifier": "string",
"city": "string",
"company_name": "string",
"country": "string",
"destination_code": "string",
"identity_type": "COMPANY",
"issued_category_id": "01a09ff1-9c4c-7e52-9beb-8cd34ae68ef9",
"issued_subcategory_id": "01a09ff1-9c4c-7f8f-b5a7-113e6f2670a8",
"payment_date": "15",
"payment_method": "CARD",
"postal_code": "string",
"province_code": "string",
"received_category_id": "01a09ff1-9c4c-72bc-a6f8-8c551b28fab7",
"received_subcategory_id": "01a09ff1-9c4c-7a02-8988-bfcf898c1b1c",
"tax_number": "string",
"vat_number": "string"
}

Response samples

Content type

application/json

{"data": {"address": "string",
"bank_identifier": "string",
"city": "string",
"company_name": "string",
"country": "string",
"destination_code": "string",
"id": "01a09ff1-9bb4-76fa-988d-53f2d30cb566",
"identity_type": "COMPANY",
"issued_category": {"color": "string",
"id": "01a09ff1-9bb4-720f-9e78-dc26cb46b800",
"name": "string"
},
"issued_subcategory": {"category_id": "01a09ff1-9bb4-76df-b93b-e4e0f10dd800",
"id": "01a09ff1-9bb4-7a18-9fd3-c70e83ef6368",
"name": "string"
},
"payment_date": "15",
"payment_method": "CARD",
"postal_code": "string",
"province_code": "string",
"received_category": {"color": "string",
"id": "01a09ff1-9bb4-7762-8a33-9add66223f9e",
"name": "string"
},
"received_subcategory": {"category_id": "01a09ff1-9bb4-7e5a-b733-244ffca0e80e",
"id": "01a09ff1-9bb4-7e5d-a215-40a56bfea4f6",
"name": "string"
},
"tax_number": "string",
"vat_number": "string"
}
}

Get a specific counterpart

Authorizations:

None

path Parameters

company_id required	string The company the counterpart belongs to
id required	string The counterpart identifier

query Parameters

expand

string

Fields that will be expanded. Expandable fields: issued_category, issued_subcategory, received_category, received_subcategory

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/counterparts/:counterpart_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

200
401
403
404

Content type

application/json

{"data": {"address": "string",
"bank_identifier": "string",
"city": "string",
"company_name": "string",
"country": "string",
"destination_code": "string",
"id": "01a09ff1-9bb4-76fa-988d-53f2d30cb566",
"identity_type": "COMPANY",
"issued_category": {"color": "string",
"id": "01a09ff1-9bb4-720f-9e78-dc26cb46b800",
"name": "string"
},
"issued_subcategory": {"category_id": "01a09ff1-9bb4-76df-b93b-e4e0f10dd800",
"id": "01a09ff1-9bb4-7a18-9fd3-c70e83ef6368",
"name": "string"
},
"payment_date": "15",
"payment_method": "CARD",
"postal_code": "string",
"province_code": "string",
"received_category": {"color": "string",
"id": "01a09ff1-9bb4-7762-8a33-9add66223f9e",
"name": "string"
},
"received_subcategory": {"category_id": "01a09ff1-9bb4-7e5a-b733-244ffca0e80e",
"id": "01a09ff1-9bb4-7e5d-a215-40a56bfea4f6",
"name": "string"
},
"tax_number": "string",
"vat_number": "string"
}
}

Update an existing counterpart

Authorizations:

None

path Parameters

company_id required	string The company the counterpart belongs to
id required	string The counterpart identifier

query Parameters

expand

string

Fields that will be expanded. Expandable fields: issued_category, issued_subcategory, received_category, received_subcategory

Request Body schema: application/json
optional

Counterpart

address	string or null The address
bank_identifier	string or null The bank coordinates (e.g. IBAN) used for payments to this counterpart
city	string or null The city
company_name	string or null The company name of the counterpart
country	string or null The country (ISO code)
destination_code	string or null The destination code (if applicable) for the Italian Electronic system (SDI).
issued_category_id	string or null <uuid> The identifier of the category applied to documents issued to this counterpart
issued_subcategory_id	string or null <uuid> The identifier of the subcategory applied to documents issued to this counterpart. Must belong to issued_category_id.
payment_date	string or null Enum: "15" "30" "60" "90" "120" "150" "EOM" "30EOM" "60EOM" "90EOM" "120EOM" "150EOM" "EOMPLUS15" "30EOMPLUS15" "60EOMPLUS15" "90EOMPLUS15" "120EOMPLUS15" Configurable payment date interval for received invoices
payment_method	string or null Enum: "CARD" "CASH" "CHECK" "DEFERRED" "TAX_FORM" "FISCAL_CREDIT" "OTHER" "POSTAL" "RIBA" "SDD" "TRANSFER" Expected method of payment for the counterpart
postal_code	string or null The postal code (if applicable)
province_code	string or null The province code (if applicable)
received_category_id	string or null <uuid> The identifier of the category applied to documents received from this counterpart
received_subcategory_id	string or null <uuid> The identifier of the subcategory applied to documents received from this counterpart. Must belong to received_category_id.

Responses

Request samples

Content type

application/json

{"address": "string",
"bank_identifier": "string",
"city": "string",
"company_name": "string",
"country": "string",
"destination_code": "string",
"issued_category_id": "01a09ff1-9c74-7caa-a946-a84052b9322b",
"issued_subcategory_id": "01a09ff1-9c74-702a-b484-37e6842d29da",
"payment_date": "15",
"payment_method": "CARD",
"postal_code": "string",
"province_code": "string",
"received_category_id": "01a09ff1-9c74-7fd8-94bc-d25651779ba7",
"received_subcategory_id": "01a09ff1-9c74-77df-9899-35fbe9999308"
}

Response samples

Content type

application/json

{"data": {"address": "string",
"bank_identifier": "string",
"city": "string",
"company_name": "string",
"country": "string",
"destination_code": "string",
"id": "01a09ff1-9bb4-76fa-988d-53f2d30cb566",
"identity_type": "COMPANY",
"issued_category": {"color": "string",
"id": "01a09ff1-9bb4-720f-9e78-dc26cb46b800",
"name": "string"
},
"issued_subcategory": {"category_id": "01a09ff1-9bb4-76df-b93b-e4e0f10dd800",
"id": "01a09ff1-9bb4-7a18-9fd3-c70e83ef6368",
"name": "string"
},
"payment_date": "15",
"payment_method": "CARD",
"postal_code": "string",
"province_code": "string",
"received_category": {"color": "string",
"id": "01a09ff1-9bb4-7762-8a33-9add66223f9e",
"name": "string"
},
"received_subcategory": {"category_id": "01a09ff1-9bb4-7e5a-b733-244ffca0e80e",
"id": "01a09ff1-9bb4-7e5d-a215-40a56bfea4f6",
"name": "string"
},
"tax_number": "string",
"vat_number": "string"
}
}

Search counterpart informations

Search for counterpart information from a third-party system.

Authorizations:

None

query Parameters

vat_number

required

string

The VAT number of the counterpart to search

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/counterparts/search \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": {"address": "string",
"city": "string",
"company_name": "string",
"country": "string",
"postal_code": "string",
"province_code": "string",
"tax_number": "string",
"vat_number": "string"
}
}

DocumentSectional

List all document sectionals for the company

The return value is paginated. By default the response contains 25 elements per page but can be instructed to return more elements per page. A cursor is needed to traverse the results.

Authorizations:

None

path Parameters

company_id

required

string

The company the document sectionals belong to

query Parameters

page_size	integer The page size
cursor	string The pagination cursor. A cursor is used to paginate through a large set of data. It is a unique identifier that represents a specific position in the dataset.
filter	object List of filters on the resource. Currently the fields that allow to be filtered are: `id`, `prefix`, `suffix`, `year`
sort	string Fields for which we can order the results. Sortable fields: `created_at`

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/document-sectionals \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": [{"id": "01a09ff1-a14a-775d-ba55-4aaba3fca62d",
"minimum_digits": 0,
"prefix": "NC/",
"suffix": "/2026",
"year": 2026
}
],
"page": {"cursor": "string",
"size": 0
}
}

Create a new document sectional

Authorizations:

None

path Parameters

company_id

required

string

The company the document sectional belongs to

Request Body schema: application/json
optional

DocumentSectional

minimum_digits	integer or null The minimum number of digits used to pad the progressive number
prefix	string or null The prefix prepended to the progressive number to form the document number. Either `prefix` or `suffix` must be provided.
suffix	string or null The suffix appended to the progressive number to form the document number. Either `prefix` or `suffix` must be provided.
year required	integer The year the sectional applies to

Responses

Request samples

Content type

application/json

{"minimum_digits": 0,
"prefix": "string",
"suffix": "string",
"year": 0
}

Response samples

Content type

application/json

{"data": {"id": "01a09ff1-a14a-775d-ba55-4aaba3fca62d",
"minimum_digits": 0,
"prefix": "NC/",
"suffix": "/2026",
"year": 2026
}
}

Get a document sectional

Returns all the information for a specific document sectional from its identifier

Authorizations:

None

path Parameters

company_id required	string The company the document sectional belongs to
id required	string The document sectional identifier

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/document-sectionals/:document_sectional_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": {"id": "01a09ff1-a14a-775d-ba55-4aaba3fca62d",
"minimum_digits": 0,
"prefix": "NC/",
"suffix": "/2026",
"year": 2026
}
}

Update an existing document sectional

Authorizations:

None

path Parameters

company_id required	string The company the document sectional belongs to
id required	string The document sectional identifier

Request Body schema: application/json
optional

DocumentSectional

minimum_digits	integer or null The minimum number of digits used to pad the progressive number
prefix	string or null The prefix prepended to the progressive number to form the document number
suffix	string or null The suffix appended to the progressive number to form the document number
year	integer The year the sectional applies to

Responses

Request samples

Content type

application/json

{"minimum_digits": 0,
"prefix": "string",
"suffix": "string",
"year": 0
}

Response samples

Content type

application/json

{"data": {"id": "01a09ff1-a14a-775d-ba55-4aaba3fca62d",
"minimum_digits": 0,
"prefix": "NC/",
"suffix": "/2026",
"year": 2026
}
}

Document

List all the company's documents

The return value is paginated. By default the response contains 25 elements per page but can be instructed to return more elements per page. A cursor is needed to traverse the results.

Authorizations:

None

path Parameters

company_id

required

string

The company the documents belong to

query Parameters

page_size	integer The page size
cursor	string The pagination cursor. A cursor is used to paginate through a large set of data. It is a unique identifier that represents a specific position in the dataset.
expand	string Fields that will be expanded. Expandable fields: `category`, `counterpart`, `flows`, `subcategory`
filter	object List of filters on the resource. Currently the fields that allow to be filtered are: `creation_date`, `delivery_date`, `direction`, `status`, `type`, `number`,`counterpart_company_name`, `notes`, `progressive`, `sectional_id`, `source_id`, `external_id`
sort	string Fields for which we can order the results. Sortable fields: `created_at`, `creation_date`, `delivery_date`, `number`, `progressive`

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/documents \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": [{"category": {"id": "01a09ff1-9ad8-7024-b102-e44db79ec2ff",
"name": "string"
},
"counterpart": {"address": "string",
"bank_identifier": "string",
"city": "string",
"company_name": "string",
"country": "string",
"destination_code": "string",
"id": "01a09ff1-9bb4-76fa-988d-53f2d30cb566",
"identity_type": "COMPANY",
"issued_category": {"color": "string",
"id": "01a09ff1-9bb4-720f-9e78-dc26cb46b800",
"name": "string"
},
"issued_subcategory": {"category_id": "01a09ff1-9bb4-76df-b93b-e4e0f10dd800",
"id": "01a09ff1-9bb4-7a18-9fd3-c70e83ef6368",
"name": "string"
},
"payment_date": "15",
"payment_method": "CARD",
"postal_code": "string",
"province_code": "string",
"received_category": {"color": "string",
"id": "01a09ff1-9bb4-7762-8a33-9add66223f9e",
"name": "string"
},
"received_subcategory": {"category_id": "01a09ff1-9bb4-7e5a-b733-244ffca0e80e",
"id": "01a09ff1-9bb4-7e5d-a215-40a56bfea4f6",
"name": "string"
},
"tax_number": "string",
"vat_number": "string"
},
"created_at": "2019-08-24T14:15:22Z",
"creation_date": "2019-08-24",
"delivery_date": "string",
"delivery_status": "string",
"direction": "ISSUED",
"external_id": "string",
"file_name": "string",
"flows": [{"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
}
],
"format": "FPA12",
"gross_amount": {"amount": "12.3",
"currency": "EUR"
},
"id": "01a09ff1-9ad8-7fb5-9ff7-8528672ddee7",
"is_e_invoice": true,
"notes": "string",
"number": "NC/12345/2026",
"progressive": "12345",
"reasons_and_remarks": ["string"
],
"sectional": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"minimum_digits": 0,
"prefix": "NC/",
"suffix": "/2026"
},
"status": "DRAFT",
"subcategory": {"id": "01a09ff1-9ad8-7489-a0af-4a59153b1e47",
"name": "string"
},
"type": "BILL",
"updated_at": "2019-08-24T14:15:22Z",
"vat_amount": {"amount": "12.3",
"currency": "EUR"
}
}
],
"page": {"cursor": "string",
"size": 0
}
}

Create a new document

Creates a document for the company from structured fields.

The counterpart is referenced by counterpart_id (create or retrieve it first via the counterparts API); its identity and default categories are copied onto the document. Payment flows are managed through the flows API.

An optional external_id correlates the document with your system and acts as an idempotency key: reusing an external_id that already maps to a document returns 422.

Authorizations:

None

path Parameters

company_id

required

string

The company where to create the document

Request Body schema: application/json
optional

Document

counterpart_id required	string <uuid> The identifier of an existing counterpart (created or retrieved via the counterparts API) the document belongs to
creation_date required	string <date> The date of the document
direction required	string Enum: "ISSUED" "RECEIVED" Whether the document is issued by (`ISSUED`) or received by (`RECEIVED`) the company
external_id	string or null An optional identifier of the document on your system. Used as an idempotency key: reusing it for the same company returns `422`.
required	object Money representation through amount and currency properties
notes	string or null <= 1000 characters Document notes (max 1000 characters)
number required	string non-empty The document number
type required	string Enum: "INVOICE" "CREDIT_NOTE" "DEBIT_NOTE" "PARCEL" "SELF_INVOICE" The document type.
required	object Money representation through amount and currency properties
	object or null Money representation through amount and currency properties

Responses

Request samples

Content type

application/json

{"counterpart_id": "01a09ff1-9bd9-7e70-a00d-3444e6111106",
"creation_date": "2019-08-24",
"direction": "ISSUED",
"external_id": "string",
"gross_amount": {"amount": "12.3",
"currency": "EUR"
},
"notes": "string",
"number": "NC/12345/2026",
"type": "INVOICE",
"vat_amount": {"amount": "12.3",
"currency": "EUR"
},
"withholding_tax": {"amount": "12.3",
"currency": "EUR"
}
}

Response samples

Content type

application/json

{"data": {"category": {"id": "01a09ff1-9ad8-7024-b102-e44db79ec2ff",
"name": "string"
},
"counterpart": {"address": "string",
"bank_identifier": "string",
"city": "string",
"company_name": "string",
"country": "string",
"destination_code": "string",
"id": "01a09ff1-9bb4-76fa-988d-53f2d30cb566",
"identity_type": "COMPANY",
"issued_category": {"color": "string",
"id": "01a09ff1-9bb4-720f-9e78-dc26cb46b800",
"name": "string"
},
"issued_subcategory": {"category_id": "01a09ff1-9bb4-76df-b93b-e4e0f10dd800",
"id": "01a09ff1-9bb4-7a18-9fd3-c70e83ef6368",
"name": "string"
},
"payment_date": "15",
"payment_method": "CARD",
"postal_code": "string",
"province_code": "string",
"received_category": {"color": "string",
"id": "01a09ff1-9bb4-7762-8a33-9add66223f9e",
"name": "string"
},
"received_subcategory": {"category_id": "01a09ff1-9bb4-7e5a-b733-244ffca0e80e",
"id": "01a09ff1-9bb4-7e5d-a215-40a56bfea4f6",
"name": "string"
},
"tax_number": "string",
"vat_number": "string"
},
"created_at": "2019-08-24T14:15:22Z",
"creation_date": "2019-08-24",
"delivery_date": "string",
"delivery_status": "string",
"direction": "ISSUED",
"external_id": "string",
"file_name": "string",
"flows": [{"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
}
],
"format": "FPA12",
"gross_amount": {"amount": "12.3",
"currency": "EUR"
},
"id": "01a09ff1-9ad8-7fb5-9ff7-8528672ddee7",
"is_e_invoice": true,
"notes": "string",
"number": "NC/12345/2026",
"progressive": "12345",
"reasons_and_remarks": ["string"
],
"sectional": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"minimum_digits": 0,
"prefix": "NC/",
"suffix": "/2026"
},
"status": "DRAFT",
"subcategory": {"id": "01a09ff1-9ad8-7489-a0af-4a59153b1e47",
"name": "string"
},
"type": "BILL",
"updated_at": "2019-08-24T14:15:22Z",
"vat_amount": {"amount": "12.3",
"currency": "EUR"
}
}
}

Import an invoice issued outside Sibill

Import an electronic invoice that has already been issued elsewhere.

The request body is the Italian Electronic invoice format file content, as application/xml. Plain XML, base64 encoded XML and signed .p7m payloads are all accepted; the original file is stored as-is and served back as the document e-invoice.

The document is registered with status CREATED and is never transmitted to SDI: use POST /documents/invoice instead to create and issue an invoice through Sibill.

The content should represent only one invoice; content with multiple invoices is not supported yet.

Authorizations:

None

path Parameters

company_id

required

string

The company where to import the invoice

query Parameters

filename required	string The original file name of the invoice. It is stored alongside the document and identifies it, so importing the same file name twice returns `400`
direction	string Enum: "ISSUED" "RECEIVED" Whether the invoice is issued by (`ISSUED`) or received by (`RECEIVED`) the company. When omitted it is derived from the invoice itself

header Parameters

content-type

required

string

Indicate the original mime type of the resource. It must be application/xml

Request Body schema: application/xml
required

The invoice file content

	Array of objects (Body)
	object
namespace	string
sistema_emittente	string
versione	string Enum: "FPA12" "FPR12"

Responses

Request samples

Content type

application/xml

<?xml version="1.0" encoding="utf-8"?>
<FatturaElettronica xmlns="http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2"
  xsi:schemaLocation="http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2 schema.xsd"
  versione="FPA12"
  SistemaEmittente="{L}LapLI{s" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <FatturaElettronicaHeader xmlns="">
    <DatiTrasmissione>
      <IdTrasmittente>
        <IdPaese>KO</IdPaese>
        <IdCodice>string</IdCodice>
      </IdTrasmittente>
      <ProgressivoInvio>IIs{{s</ProgressivoInvio>
      <FormatoTrasmissione>FPA12</FormatoTrasmissione>
      <CodiceDestinatario>EM1A07</CodiceDestinatario>
      <ContattiTrasmittente />
      <PECDestinatario>%+R--}--.#V!=@+?=?yUK?*3A?yj++?+--.Z.*!-=fmuh</PECDestinatario>
    </DatiTrasmissione>
    <CedentePrestatore>
      <DatiAnagrafici>
        <IdFiscaleIVA>
          <IdPaese>WX</IdPaese>
          <IdCodice>string</IdCodice>
        </IdFiscaleIVA>
        <Anagrafica>
          <Nome>BBpuIutaaIScBBII</Nome>
          <Cognome>a</Cognome>
        </Anagrafica>
        <RegimeFiscale>RF01</RegimeFiscale>
      </DatiAnagrafici>
      <Sede>
        <Indirizzo>ea</Indirizzo>
        <CAP>37675</CAP>
        <Comune>Lue</Comune>
        <Nazione>IT</Nazione>
      </Sede>
      <StabileOrganizzazione>
        <Indirizzo>aiu</Indirizzo>
        <CAP>66435</CAP>
        <Comune>{ceSaBpiBmep</Comune>
        <Nazione>IT</Nazione>
      </StabileOrganizzazione>
      <IscrizioneREA>
        <Ufficio>FT</Ufficio>
        <NumeroREA>tLIa}pp{}apsan]c{]a]</NumeroREA>
        <StatoLiquidazione>LN</StatoLiquidazione>
      </IscrizioneREA>
      <Contatti />
      <RiferimentoAmministrazione>ns{IiicpaaIip}IiaLa{</RiferimentoAmministrazione>
    </CedentePrestatore>
    <RappresentanteFiscale>
      <DatiAnagrafici>
        <IdFiscaleIVA>
          <IdPaese>MK</IdPaese>
          <IdCodice>string</IdCodice>
        </IdFiscaleIVA>
        <Anagrafica>
          <Denominazione>I{BipIs{a}ap{LucBiu</Denominazione>
        </Anagrafica>
      </DatiAnagrafici>
    </RappresentanteFiscale>
    <CessionarioCommittente>
      <DatiAnagrafici>
        <Anagrafica>
          <Denominazione>em</Denominazione>
        </Anagrafica>
      </DatiAnagrafici>
      <Sede>
        <Indirizzo>BmeiSp{eu}eLSL</Indirizzo>
        <CAP>65255</CAP>
        <Comune>ippea}ntBSLIu{IBplSce}{SmB}{{{LL</Comune>
        <Nazione>IT</Nazione>
      </Sede>
      <StabileOrganizzazione>
        <Indirizzo>{B{}eaeniLp{aBlpaa{p{LBLincpLI}{SBc{SeS}}}ae{e</Indirizzo>
        <CAP>48679</CAP>
        <Comune>lLtBpa</Comune>
        <Nazione>IT</Nazione>
      </StabileOrganizzazione>
      <RappresentanteFiscale>
        <IdFiscaleIVA>
          <IdPaese>ZO</IdPaese>
          <IdCodice>string</IdCodice>
        </IdFiscaleIVA>
        <Denominazione>LBcc}e}aLBcsSLS{BI}aeapcce}n</Denominazione>
      </RappresentanteFiscale>
    </CessionarioCommittente>
    <TerzoIntermediarioOSoggettoEmittente>
      <DatiAnagrafici>
        <Anagrafica>
          <Nome>t}iaScccpa{ieLnSLp}BncieSci{uI{i{pce}cScSSaLBBcpIlSa}Bnpcac</Nome>
          <Cognome>aaSm}{LI{BBc}i}a{nncms}eelSeBpuiBapi}ciLpLeaci{n}</Cognome>
        </Anagrafica>
      </DatiAnagrafici>
    </TerzoIntermediarioOSoggettoEmittente>
    <SoggettoEmittente>CC</SoggettoEmittente>
  </FatturaElettronicaHeader>
  <FatturaElettronicaBody xmlns="">
    <DatiGenerali>
      <DatiGeneraliDocumento>
        <TipoDocumento>TD16</TipoDocumento>
        <Divisa>TUL</Divisa>
        <Data>2017-10-03</Data>
        <Numero>iniaaB</Numero>
      </DatiGeneraliDocumento>
      <DatiOrdineAcquisto>
        <IdDocumento>Li]ci{pc}iII]</IdDocumento>
      </DatiOrdineAcquisto>
      <DatiContratto>
        <IdDocumento>tp{t}IBippn{}B]</IdDocumento>
      </DatiContratto>
      <DatiConvenzione>
        <IdDocumento>ap]L}BniaLa{pcn</IdDocumento>
      </DatiConvenzione>
      <DatiRicezione>
        <IdDocumento>ccILstLB</IdDocumento>
      </DatiRicezione>
      <DatiFattureCollegate>
        <IdDocumento>I}Ip{tpa]]ac]IL}pBsn</IdDocumento>
      </DatiFattureCollegate>
      <DatiSAL>
        <RiferimentoFase>361</RiferimentoFase>
      </DatiSAL>
      <DatiDDT>
        <NumeroDDT>sBi}nat</NumeroDDT>
        <DataDDT>1972-12-17</DataDDT>
      </DatiDDT>
      <DatiTrasporto />
      <FatturaPrincipale>
        <NumeroFatturaPrincipale>{]nppLpiB</NumeroFatturaPrincipale>
        <DataFatturaPrincipale>1970-08-14</DataFatturaPrincipale>
      </FatturaPrincipale>
    </DatiGenerali>
    <DatiBeniServizi>
      <DettaglioLinee>
        <NumeroLinea>8284</NumeroLinea>
        <Descrizione>n</Descrizione>
        <PrezzoUnitario>1369450.2349058</PrezzoUnitario>
        <PrezzoTotale>-805869.765094196</PrezzoTotale>
        <AliquotaIVA>4402260</AliquotaIVA>
      </DettaglioLinee>
      <DatiRiepilogo>
        <AliquotaIVA>3148340</AliquotaIVA>
        <ImponibileImporto>4413100.2349058</ImponibileImporto>
        <Imposta>3371250.2349058</Imposta>
      </DatiRiepilogo>
    </DatiBeniServizi>
    <DatiVeicoli>
      <Data>2012-11-25</Data>
      <TotalePercorso>}BtL{L</TotalePercorso>
    </DatiVeicoli>
    <DatiPagamento>
      <CondizioniPagamento>TP01</CondizioniPagamento>
      <DettaglioPagamento>
        <ModalitaPagamento>MP17</ModalitaPagamento>
        <ImportoPagamento>-3583049.7650942</ImportoPagamento>
      </DettaglioPagamento>
    </DatiPagamento>
    <Allegati>
      <NomeAttachment>pel</NomeAttachment>
      <AlgoritmoCompressione>pctaaL}LIa</AlgoritmoCompressione>
      <FormatoAttachment>{cIsIpaIIi</FormatoAttachment>
      <DescrizioneAttachment>SsLcp</DescrizioneAttachment>
      <Attachment>YTM0NZomIzI2OTsmIzM0NTueYQ==</Attachment>
    </Allegati>
  </FatturaElettronicaBody>
  <FatturaElettronicaBody xmlns="">
    <DatiGenerali>
      <DatiGeneraliDocumento>
        <TipoDocumento>TD05</TipoDocumento>
        <Divisa>MWH</Divisa>
        <Data>1996-10-28</Data>
        <Numero>aBt{i}{tiIptpnac]</Numero>
      </DatiGeneraliDocumento>
      <DatiOrdineAcquisto>
        <IdDocumento>{cnIpc}i]Is]c</IdDocumento>
      </DatiOrdineAcquisto>
      <DatiContratto>
        <IdDocumento>n]i}</IdDocumento>
      </DatiContratto>
      <DatiConvenzione>
        <IdDocumento>]a}I}}c}aa</IdDocumento>
      </DatiConvenzione>
      <DatiRicezione>
        <IdDocumento>a{}s}</IdDocumento>
      </DatiRicezione>
      <DatiFattureCollegate>
        <IdDocumento>ct}LI</IdDocumento>
      </DatiFattureCollegate>
      <DatiSAL>
        <RiferimentoFase>369</RiferimentoFase>
      </DatiSAL>
      <DatiDDT>
        <NumeroDDT>Ban</NumeroDDT>
        <DataDDT>1972-11-14</DataDDT>
      </DatiDDT>
      <DatiTrasporto />
      <FatturaPrincipale>
        <NumeroFatturaPrincipale>t}{i}napBic</NumeroFatturaPrincipale>
        <DataFatturaPrincipale>2016-12-16</DataFatturaPrincipale>
      </FatturaPrincipale>
    </DatiGenerali>
    <DatiBeniServizi>
      <DettaglioLinee>
        <NumeroLinea>2867</NumeroLinea>
        <Descrizione>pL</Descrizione>
        <PrezzoUnitario>-2058329.7650942</PrezzoUnitario>
        <PrezzoTotale>3961400.2349058</PrezzoTotale>
        <AliquotaIVA>-1219789.7650942</AliquotaIVA>
      </DettaglioLinee>
      <DatiRiepilogo>
        <AliquotaIVA>2690430</AliquotaIVA>
        <ImponibileImporto>-4257529.7650942</ImponibileImporto>
        <Imposta>2794280.2349058</Imposta>
      </DatiRiepilogo>
    </DatiBeniServizi>
    <DatiVeicoli>
      <Data>1996-12-06</Data>
      <TotalePercorso>aBcpcBLtc{tBi}s</TotalePercorso>
    </DatiVeicoli>
    <DatiPagamento>
      <CondizioniPagamento>TP03</CondizioniPagamento>
      <DettaglioPagamento>
        <ModalitaPagamento>MP18</ModalitaPagamento>
        <ImportoPagamento>-4401059.7650942</ImportoPagamento>
      </DettaglioPagamento>
    </DatiPagamento>
    <Allegati>
      <NomeAttachment>t}ae</NomeAttachment>
      <AlgoritmoCompressione>snn}Bt}n{</AlgoritmoCompressione>
      <FormatoAttachment>iLBnsnLanc</FormatoAttachment>
      <DescrizioneAttachment>}spLLILSeSaBlSLiiiinSIc}ptBI{SccasstI</DescrizioneAttachment>
      <Attachment>YTM0NZomIzI2OTsmIzM0NTueYQ==</Attachment>
    </Allegati>
  </FatturaElettronicaBody>
  <FatturaElettronicaBody xmlns="">
    <DatiGenerali>
      <DatiGeneraliDocumento>
        <TipoDocumento>TD18</TipoDocumento>
        <Divisa>FAB</Divisa>
        <Data>1970-08-27</Data>
        <Numero>snpan{acB]aantB</Numero>
      </DatiGeneraliDocumento>
      <DatiOrdineAcquisto>
        <IdDocumento>s</IdDocumento>
      </DatiOrdineAcquisto>
      <DatiContratto>
        <IdDocumento>B</IdDocumento>
      </DatiContratto>
      <DatiConvenzione>
        <IdDocumento>InIasi]p]a</IdDocumento>
      </DatiConvenzione>
      <DatiRicezione>
        <IdDocumento>{capBc</IdDocumento>
      </DatiRicezione>
      <DatiFattureCollegate>
        <IdDocumento>pIL]}tLL}n]B}n]iBtLc</IdDocumento>
      </DatiFattureCollegate>
      <DatiSAL>
        <RiferimentoFase>519</RiferimentoFase>
      </DatiSAL>
      <DatiDDT>
        <NumeroDDT>BnLc{ni</NumeroDDT>
        <DataDDT>1973-11-05</DataDDT>
      </DatiDDT>
      <DatiTrasporto />
      <FatturaPrincipale>
        <NumeroFatturaPrincipale>L</NumeroFatturaPrincipale>
        <DataFatturaPrincipale>1991-11-06</DataFatturaPrincipale>
      </FatturaPrincipale>
    </DatiGenerali>
    <DatiBeniServizi>
      <DettaglioLinee>
        <NumeroLinea>8217</NumeroLinea>
        <Descrizione>I{SlLceItci</Descrizione>
        <PrezzoUnitario>-3196579.7650942</PrezzoUnitario>
        <PrezzoTotale>-2138439.7650942</PrezzoTotale>
        <AliquotaIVA>-869189.765094196</AliquotaIVA>
      </DettaglioLinee>
      <DatiRiepilogo>
        <AliquotaIVA>1031150</AliquotaIVA>
        <ImponibileImporto>-3900039.7650942</ImponibileImporto>
        <Imposta>1213930.2349058</Imposta>
      </DatiRiepilogo>
    </DatiBeniServizi>
    <DatiVeicoli>
      <Data>1981-10-23</Data>
      <TotalePercorso>I}pptsL}{I</TotalePercorso>
    </DatiVeicoli>
    <DatiPagamento>
      <CondizioniPagamento>TP02</CondizioniPagamento>
      <DettaglioPagamento>
        <ModalitaPagamento>MP08</ModalitaPagamento>
        <ImportoPagamento>1109440.2349058</ImportoPagamento>
      </DettaglioPagamento>
    </DatiPagamento>
    <Allegati>
      <NomeAttachment>Bpl{BeL{tmIaeIStaic{pe}Bec{Ic}</NomeAttachment>
      <AlgoritmoCompressione>IB</AlgoritmoCompressione>
      <FormatoAttachment>nnn}}IBic}</FormatoAttachment>
      <DescrizioneAttachment>}e</DescrizioneAttachment>
      <Attachment>YTM0NZomIzI2OTsmIzM0NTueYQ==</Attachment>
    </Allegati>
  </FatturaElettronicaBody>
</FatturaElettronica>

Response samples

Content type

application/json

{"data": [{"category": {"id": "01a09ff1-9ad8-7024-b102-e44db79ec2ff",
"name": "string"
},
"counterpart": {"address": "string",
"bank_identifier": "string",
"city": "string",
"company_name": "string",
"country": "string",
"destination_code": "string",
"id": "01a09ff1-9bb4-76fa-988d-53f2d30cb566",
"identity_type": "COMPANY",
"issued_category": {"color": "string",
"id": "01a09ff1-9bb4-720f-9e78-dc26cb46b800",
"name": "string"
},
"issued_subcategory": {"category_id": "01a09ff1-9bb4-76df-b93b-e4e0f10dd800",
"id": "01a09ff1-9bb4-7a18-9fd3-c70e83ef6368",
"name": "string"
},
"payment_date": "15",
"payment_method": "CARD",
"postal_code": "string",
"province_code": "string",
"received_category": {"color": "string",
"id": "01a09ff1-9bb4-7762-8a33-9add66223f9e",
"name": "string"
},
"received_subcategory": {"category_id": "01a09ff1-9bb4-7e5a-b733-244ffca0e80e",
"id": "01a09ff1-9bb4-7e5d-a215-40a56bfea4f6",
"name": "string"
},
"tax_number": "string",
"vat_number": "string"
},
"created_at": "2019-08-24T14:15:22Z",
"creation_date": "2019-08-24",
"delivery_date": "string",
"delivery_status": "string",
"direction": "ISSUED",
"external_id": "string",
"file_name": "string",
"flows": [{"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
}
],
"format": "FPA12",
"gross_amount": {"amount": "12.3",
"currency": "EUR"
},
"id": "01a09ff1-9ad8-7fb5-9ff7-8528672ddee7",
"is_e_invoice": true,
"notes": "string",
"number": "NC/12345/2026",
"progressive": "12345",
"reasons_and_remarks": ["string"
],
"sectional": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"minimum_digits": 0,
"prefix": "NC/",
"suffix": "/2026"
},
"status": "DRAFT",
"subcategory": {"id": "01a09ff1-9ad8-7489-a0af-4a59153b1e47",
"name": "string"
},
"type": "BILL",
"updated_at": "2019-08-24T14:15:22Z",
"vat_amount": {"amount": "12.3",
"currency": "EUR"
}
}
]
}

Create an invoice and issue it

Create an invoice. By default will be created as draft and not issued.

The company must have the invoicing module enabled, otherwise the request fails with 403 invoicing_not_enabled.

The request body (that could be application/xml or application/json) represent the Italian Electronic invoice format. For example, if the XML content comes from another system — perhaps as a file — the request body will contain the file's content. The content should represent only one invoice; content with multiple invoices is not supported yet.

The invoice numero is under customer control (i.e. customer must choose it), while the file name and the progressivo invio are automatically generated by the system.

Authorizations:

None

path Parameters

company_id

required

string

The company where to execute the operation

query Parameters

issue	boolean Issue the invoice after creating it. If true, the invoice is issued. Default value is false. In this case, the invoice is created as a draft and not issued.
reconciliation_identifier	string A unique identifier used to match an invoice with its corresponding transaction. This can be, for example, an ID coming from your collection system (ex. Transaction ID on Stripe or Paypal) that you want to pass when issuing the invoice to be able to reconcile the movement and the invoice automatically
sectional_id	string The sectional identifier to associate with the document
automatic_number	boolean Automatically populate/override invoice number with the next number of `sectional_id`. If `sectional_id` is null, it generates a number without sectional

header Parameters

content-type

required

string

Indicate the original mime type of the resource. It could be application/xml or application/json

Request Body schema:
application/json
required

The user attributes

	Array of objects (Body)
	object
namespace	string
sistema_emittente	string
versione	string Enum: "FPA12" "FPR12"

Responses

Request samples

Content type

application/json

{"fattura_elettronica_body": [{"allegati": [{"algoritmo_compressione": "string",
"attachment": "string",
"descrizione_attachment": "string",
"formato_attachment": "string",
"nome_attachment": "string"
}
],
"dati_beni_servizi": {"dati_riepilogo": [{"aliquota_iva": "string",
"arrotondamento": "string",
"esigibilita_iva": "string",
"imponibile_importo": "string",
"imposta": "string",
"natura": "N1",
"riferimento_normativo": "string",
"spese_accessorie": "string"
}
],
"dettaglio_linee": [{"aliquota_iva": "string",
"altri_dati_gestionali": [{"riferimento_data": "string",
"riferimento_numero": "string",
"riferimento_testo": "string",
"tipo_dato": "string"
}
],
"codice_articolo": [{"codice_tipo": "string",
"codice_valore": "string"
}
],
"data_fine_periodo": "string",
"data_inizio_periodo": "string",
"descrizione": "string",
"natura": "N1",
"numero_linea": "string",
"prezzo_totale": "string",
"prezzo_unitario": "string",
"quantita": "string",
"riferimento_amministrazione": "string",
"ritenuta": "string",
"sconto_maggiorazione": [{"importo": "string",
"percentuale": "string",
"tipo": "string"
}
],
"tipo_cessione_prestazione": "SC",
"unita_misura": "string"
}
]
},
"dati_generali": {"dati_contratto": [{"codice_cig": "string",
"codice_commessa_convenzione": "string",
"codice_cup": "string",
"data": "string",
"id_documento": "string",
"num_item": "string",
"riferimento_numero_linea": [0
]
}
],
"dati_convenzione": [{"codice_cig": "string",
"codice_commessa_convenzione": "string",
"codice_cup": "string",
"data": "string",
"id_documento": "string",
"num_item": "string",
"riferimento_numero_linea": [0
]
}
],
"dati_ddt": [{"data_ddt": "string",
"numero_ddt": "string",
"riferimento_numero_linea": ["string"
]
}
],
"dati_fatture_collegate": [{"codice_cig": "string",
"codice_commessa_convenzione": "string",
"codice_cup": "string",
"data": "string",
"id_documento": "string",
"num_item": "string",
"riferimento_numero_linea": [0
]
}
],
"dati_generali_documento": {"arrotondamento": "string",
"art_73": "SI",
"causale": ["string"
],
"data": "string",
"dati_bollo": {"bollo_virtuale": "string",
"importo_bollo": "string"
},
"dati_cassa_previdenziale": [{"al_cassa": "string",
"aliquota_iva": "string",
"imponibile_cassa": "string",
"importo_contributo_cassa": "string",
"natura": "N1",
"riferimento_amministrazione": "string",
"ritenuta": "string",
"tipo_cassa": "TC01"
}
],
"dati_ritenuta": [{"aliquota_ritenuta": "string",
"causale_pagamento": "A",
"importo_ritenuta": "string",
"tipo_ritenuta": "RT01"
}
],
"divisa": "string",
"importo_totale_documento": "string",
"numero": "string",
"sconto_maggiorazione": [{"importo": "string",
"percentuale": "string",
"tipo": "MG"
}
],
"tipo_documento": "TD01"
},
"dati_ordine_acquisto": [{"codice_cig": "string",
"codice_commessa_convenzione": "string",
"codice_cup": "string",
"data": "string",
"id_documento": "string",
"num_item": "string",
"riferimento_numero_linea": [0
]
}
],
"dati_ricezione": [{"codice_cig": "string",
"codice_commessa_convenzione": "string",
"codice_cup": "string",
"data": "string",
"id_documento": "string",
"num_item": "string",
"riferimento_numero_linea": [0
]
}
],
"dati_sal": [{"riferimento_fase": "string"
}
],
"dati_trasporto": {"causale_trasporto": "string",
"data_inizio_trasporto": "string",
"data_ora_consegna": "string",
"data_ora_ritiro": "string",
"dati_anagrafici_vettore": {"anagrafica": {"cod_eori": "string",
"cognome": "string",
"denominazione": "string",
"nome": "string",
"titolo": "string"
},
"codice_fiscale": "string",
"id_fiscale_iva": {"id_codice": "string",
"id_paese": "string"
},
"numero_licenza_guida": "string"
},
"descrizione": "string",
"indirizzo_resa": {"cap": "string",
"comune": "string",
"indirizzo": "string",
"nazione": "string",
"numero_civico": "string",
"provincia": "string"
},
"mezzo_trasporto": "string",
"numero_colli": 0,
"peso_lordo": "string",
"peso_netto": "string",
"tipo_resa": "string",
"unita_misura_peso": "string"
},
"fattura_principale": {"data_fattura_principale": "string",
"numero_fattura_principale": "string"
}
},
"dati_pagamento": [{"condizioni_pagamento": "TP01",
"dettaglio_pagamento": [{"abi": "string",
"beneficiario": "string",
"bic": "string",
"cab": "string",
"cf_quietanzante": "string",
"cod_ufficio_postale": "string",
"codice_pagamento": "string",
"cognome_quietanzante": "string",
"data_decorrenza_penale": "string",
"data_limite_pagamento_anticipato": "string",
"data_riferimento_termini_pagamento": "string",
"data_scadenza_pagamento": "string",
"giorni_termini_pagamento": 0,
"iban": "string",
"importo_pagamento": "string",
"istituto_finanziario": "string",
"modalita_pagamento": "MP01",
"nome_quietanzante": "string",
"penalita_pagamenti_ritardati": "string",
"sconto_pagamento_anticipato": "string",
"titolo_quietanzante": "string"
}
]
}
],
"dati_veicoli": {"data": "string",
"totale_percorso": "string"
}
}
],
"fattura_elettronica_header": {"cedente_prestatore": {"contatti": {"email": "string",
"fax": "string",
"telefono": "string"
},
"dati_anagrafici": {"albo_professionale": "string",
"anagrafica": {"cod_eori": "string",
"cognome": "string",
"denominazione": "string",
"nome": "string",
"titolo": "string"
},
"codice_fiscale": "string",
"data_iscrizione_albo": "string",
"id_fiscale_iva": {"id_codice": "string",
"id_paese": "string"
},
"numero_iscrizione_albo": "string",
"provincia_albo": "string",
"regime_fiscale": "RF01"
},
"iscrizione_rea": {"capitale_sociale": "string",
"numero_rea": "string",
"socio_unico": "SU",
"stato_liquidazione": "LS",
"ufficio": "string"
},
"riferimento_amministrazione": "string",
"sede": {"cap": "string",
"comune": "string",
"indirizzo": "string",
"nazione": "string",
"numero_civico": "string",
"provincia": "string"
},
"stabile_organizzazione": {"cap": "string",
"comune": "string",
"indirizzo": "string",
"nazione": "string",
"numero_civico": "string",
"provincia": "string"
}
},
"cessionario_committente": {"dati_anagrafici": {"anagrafica": {"cod_eori": "string",
"cognome": "string",
"denominazione": "string",
"nome": "string",
"titolo": "string"
},
"codice_fiscale": "string",
"id_fiscale_iva": {"id_codice": "string",
"id_paese": "string"
}
},
"rappresentante_fiscale": {"cognome": "string",
"denominazione": "string",
"id_fiscale_iva": {"id_codice": "string",
"id_paese": "string"
},
"nome": "string"
},
"sede": {"cap": "string",
"comune": "string",
"indirizzo": "string",
"nazione": "string",
"numero_civico": "string",
"provincia": "string"
},
"stabile_organizzazione": {"cap": "string",
"comune": "string",
"indirizzo": "string",
"nazione": "string",
"numero_civico": "string",
"provincia": "string"
}
},
"dati_trasmissione": {"codice_destinatario": "string",
"contatti_trasmittente": {"email": "string",
"telefono": "string"
},
"formato_trasmissione": "FPA12",
"id_trasmittente": {"id_codice": "string",
"id_paese": "string"
},
"pec_destinatario": "string",
"progressivo_invio": "string"
},
"rappresentante_fiscale": {"dati_anagrafici": {"anagrafica": {"cod_eori": "string",
"cognome": "string",
"denominazione": "string",
"nome": "string",
"titolo": "string"
},
"codice_fiscale": "string",
"id_fiscale_iva": {"id_codice": "string",
"id_paese": "string"
}
}
},
"soggetto_emittente": "CC",
"terzo_intermediario_o_soggetto_emittente": {"dati_anagrafici": {"anagrafica": {"cod_eori": "string",
"cognome": "string",
"denominazione": "string",
"nome": "string",
"titolo": "string"
},
"codice_fiscale": "string",
"id_fiscale_iva": {"id_codice": "string",
"id_paese": "string"
}
}
}
},
"namespace": "string",
"sistema_emittente": "string",
"versione": "FPA12"
}

Response samples

Content type

application/json

{"data": [{"category": {"id": "01a09ff1-9ad8-7024-b102-e44db79ec2ff",
"name": "string"
},
"counterpart": {"address": "string",
"bank_identifier": "string",
"city": "string",
"company_name": "string",
"country": "string",
"destination_code": "string",
"id": "01a09ff1-9bb4-76fa-988d-53f2d30cb566",
"identity_type": "COMPANY",
"issued_category": {"color": "string",
"id": "01a09ff1-9bb4-720f-9e78-dc26cb46b800",
"name": "string"
},
"issued_subcategory": {"category_id": "01a09ff1-9bb4-76df-b93b-e4e0f10dd800",
"id": "01a09ff1-9bb4-7a18-9fd3-c70e83ef6368",
"name": "string"
},
"payment_date": "15",
"payment_method": "CARD",
"postal_code": "string",
"province_code": "string",
"received_category": {"color": "string",
"id": "01a09ff1-9bb4-7762-8a33-9add66223f9e",
"name": "string"
},
"received_subcategory": {"category_id": "01a09ff1-9bb4-7e5a-b733-244ffca0e80e",
"id": "01a09ff1-9bb4-7e5d-a215-40a56bfea4f6",
"name": "string"
},
"tax_number": "string",
"vat_number": "string"
},
"created_at": "2019-08-24T14:15:22Z",
"creation_date": "2019-08-24",
"delivery_date": "string",
"delivery_status": "string",
"direction": "ISSUED",
"external_id": "string",
"file_name": "string",
"flows": [{"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
}
],
"format": "FPA12",
"gross_amount": {"amount": "12.3",
"currency": "EUR"
},
"id": "01a09ff1-9ad8-7fb5-9ff7-8528672ddee7",
"is_e_invoice": true,
"notes": "string",
"number": "NC/12345/2026",
"progressive": "12345",
"reasons_and_remarks": ["string"
],
"sectional": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"minimum_digits": 0,
"prefix": "NC/",
"suffix": "/2026"
},
"status": "DRAFT",
"subcategory": {"id": "01a09ff1-9ad8-7489-a0af-4a59153b1e47",
"name": "string"
},
"type": "BILL",
"updated_at": "2019-08-24T14:15:22Z",
"vat_amount": {"amount": "12.3",
"currency": "EUR"
}
}
]
}

Get a document invoice by its identifier

Retrieve a specific document invoice along with a signed url to the xml representation of the invoice. The signed url provides a secure and temporary access to the xml data.

Authorizations:

None

path Parameters

company_id required	string The company the document invoice belongs to
document_id required	string The document identifier

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/documents/:document_id/invoice \
     --header "Authorization: Bearer ${authorization_token}" \
     --header "Content-Type: application/json"

Response samples

Content type

application/json

{"data": {"invoice": {"fattura_elettronica_body": [{"allegati": [{"algoritmo_compressione": "string",
"attachment": "string",
"descrizione_attachment": "string",
"formato_attachment": "string",
"nome_attachment": "string"
}
],
"dati_beni_servizi": {"dati_riepilogo": [{"aliquota_iva": "string",
"arrotondamento": "string",
"esigibilita_iva": "string",
"imponibile_importo": "string",
"imposta": "string",
"natura": "N1",
"riferimento_normativo": "string",
"spese_accessorie": "string"
}
],
"dettaglio_linee": [{"aliquota_iva": "string",
"altri_dati_gestionali": [{"riferimento_data": null,
"riferimento_numero": null,
"riferimento_testo": null,
"tipo_dato": null
}
],
"codice_articolo": [{"codice_tipo": null,
"codice_valore": null
}
],
"data_fine_periodo": "string",
"data_inizio_periodo": "string",
"descrizione": "string",
"natura": "N1",
"numero_linea": "string",
"prezzo_totale": "string",
"prezzo_unitario": "string",
"quantita": "string",
"riferimento_amministrazione": "string",
"ritenuta": "string",
"sconto_maggiorazione": [{"importo": null,
"percentuale": null,
"tipo": null
}
],
"tipo_cessione_prestazione": "SC",
"unita_misura": "string"
}
]
},
"dati_generali": {"dati_contratto": [{"codice_cig": "string",
"codice_commessa_convenzione": "string",
"codice_cup": "string",
"data": "string",
"id_documento": "string",
"num_item": "string",
"riferimento_numero_linea": [0
]
}
],
"dati_convenzione": [{"codice_cig": "string",
"codice_commessa_convenzione": "string",
"codice_cup": "string",
"data": "string",
"id_documento": "string",
"num_item": "string",
"riferimento_numero_linea": [0
]
}
],
"dati_ddt": [{"data_ddt": "string",
"numero_ddt": "string",
"riferimento_numero_linea": ["string"
]
}
],
"dati_fatture_collegate": [{"codice_cig": "string",
"codice_commessa_convenzione": "string",
"codice_cup": "string",
"data": "string",
"id_documento": "string",
"num_item": "string",
"riferimento_numero_linea": [0
]
}
],
"dati_generali_documento": {"arrotondamento": "string",
"art_73": "SI",
"causale": ["string"
],
"data": "string",
"dati_bollo": {"bollo_virtuale": "string",
"importo_bollo": "string"
},
"dati_cassa_previdenziale": [{"al_cassa": "string",
"aliquota_iva": "string",
"imponibile_cassa": "string",
"importo_contributo_cassa": "string",
"natura": "N1",
"riferimento_amministrazione": "string",
"ritenuta": "string",
"tipo_cassa": "TC01"
}
],
"dati_ritenuta": [{"aliquota_ritenuta": "string",
"causale_pagamento": "A",
"importo_ritenuta": "string",
"tipo_ritenuta": "RT01"
}
],
"divisa": "string",
"importo_totale_documento": "string",
"numero": "string",
"sconto_maggiorazione": [{"importo": "string",
"percentuale": "string",
"tipo": "MG"
}
],
"tipo_documento": "TD01"
},
"dati_ordine_acquisto": [{"codice_cig": "string",
"codice_commessa_convenzione": "string",
"codice_cup": "string",
"data": "string",
"id_documento": "string",
"num_item": "string",
"riferimento_numero_linea": [0
]
}
],
"dati_ricezione": [{"codice_cig": "string",
"codice_commessa_convenzione": "string",
"codice_cup": "string",
"data": "string",
"id_documento": "string",
"num_item": "string",
"riferimento_numero_linea": [0
]
}
],
"dati_sal": [{"riferimento_fase": "string"
}
],
"dati_trasporto": {"causale_trasporto": "string",
"data_inizio_trasporto": "string",
"data_ora_consegna": "string",
"data_ora_ritiro": "string",
"dati_anagrafici_vettore": {"anagrafica": {"cod_eori": "string",
"cognome": "string",
"denominazione": "string",
"nome": "string",
"titolo": "string"
},
"codice_fiscale": "string",
"id_fiscale_iva": {"id_codice": "string",
"id_paese": "string"
},
"numero_licenza_guida": "string"
},
"descrizione": "string",
"indirizzo_resa": {"cap": "string",
"comune": "string",
"indirizzo": "string",
"nazione": "string",
"numero_civico": "string",
"provincia": "string"
},
"mezzo_trasporto": "string",
"numero_colli": 0,
"peso_lordo": "string",
"peso_netto": "string",
"tipo_resa": "string",
"unita_misura_peso": "string"
},
"fattura_principale": {"data_fattura_principale": "string",
"numero_fattura_principale": "string"
}
},
"dati_pagamento": [{"condizioni_pagamento": "TP01",
"dettaglio_pagamento": [{"abi": "string",
"beneficiario": "string",
"bic": "string",
"cab": "string",
"cf_quietanzante": "string",
"cod_ufficio_postale": "string",
"codice_pagamento": "string",
"cognome_quietanzante": "string",
"data_decorrenza_penale": "string",
"data_limite_pagamento_anticipato": "string",
"data_riferimento_termini_pagamento": "string",
"data_scadenza_pagamento": "string",
"giorni_termini_pagamento": 0,
"iban": "string",
"importo_pagamento": "string",
"istituto_finanziario": "string",
"modalita_pagamento": "MP01",
"nome_quietanzante": "string",
"penalita_pagamenti_ritardati": "string",
"sconto_pagamento_anticipato": "string",
"titolo_quietanzante": "string"
}
]
}
],
"dati_veicoli": {"data": "string",
"totale_percorso": "string"
}
}
],
"fattura_elettronica_header": {"cedente_prestatore": {"contatti": {"email": "string",
"fax": "string",
"telefono": "string"
},
"dati_anagrafici": {"albo_professionale": "string",
"anagrafica": {"cod_eori": "string",
"cognome": "string",
"denominazione": "string",
"nome": "string",
"titolo": "string"
},
"codice_fiscale": "string",
"data_iscrizione_albo": "string",
"id_fiscale_iva": {"id_codice": "string",
"id_paese": "string"
},
"numero_iscrizione_albo": "string",
"provincia_albo": "string",
"regime_fiscale": "RF01"
},
"iscrizione_rea": {"capitale_sociale": "string",
"numero_rea": "string",
"socio_unico": "SU",
"stato_liquidazione": "LS",
"ufficio": "string"
},
"riferimento_amministrazione": "string",
"sede": {"cap": "string",
"comune": "string",
"indirizzo": "string",
"nazione": "string",
"numero_civico": "string",
"provincia": "string"
},
"stabile_organizzazione": {"cap": "string",
"comune": "string",
"indirizzo": "string",
"nazione": "string",
"numero_civico": "string",
"provincia": "string"
}
},
"cessionario_committente": {"dati_anagrafici": {"anagrafica": {"cod_eori": "string",
"cognome": "string",
"denominazione": "string",
"nome": "string",
"titolo": "string"
},
"codice_fiscale": "string",
"id_fiscale_iva": {"id_codice": "string",
"id_paese": "string"
}
},
"rappresentante_fiscale": {"cognome": "string",
"denominazione": "string",
"id_fiscale_iva": {"id_codice": "string",
"id_paese": "string"
},
"nome": "string"
},
"sede": {"cap": "string",
"comune": "string",
"indirizzo": "string",
"nazione": "string",
"numero_civico": "string",
"provincia": "string"
},
"stabile_organizzazione": {"cap": "string",
"comune": "string",
"indirizzo": "string",
"nazione": "string",
"numero_civico": "string",
"provincia": "string"
}
},
"dati_trasmissione": {"codice_destinatario": "string",
"contatti_trasmittente": {"email": "string",
"telefono": "string"
},
"formato_trasmissione": "FPA12",
"id_trasmittente": {"id_codice": "string",
"id_paese": "string"
},
"pec_destinatario": "string",
"progressivo_invio": "string"
},
"rappresentante_fiscale": {"dati_anagrafici": {"anagrafica": {"cod_eori": "string",
"cognome": "string",
"denominazione": "string",
"nome": "string",
"titolo": "string"
},
"codice_fiscale": "string",
"id_fiscale_iva": {"id_codice": "string",
"id_paese": "string"
}
}
},
"soggetto_emittente": "CC",
"terzo_intermediario_o_soggetto_emittente": {"dati_anagrafici": {"anagrafica": {"cod_eori": "string",
"cognome": "string",
"denominazione": "string",
"nome": "string",
"titolo": "string"
},
"codice_fiscale": "string",
"id_fiscale_iva": {"id_codice": "string",
"id_paese": "string"
}
}
}
},
"namespace": "string",
"sistema_emittente": "string",
"versione": "FPA12"
},
"xml_url": "string"
}
}

Send an invoice courtesy copy through email

Send an invoice courtesy copy through email to some recipient provided in the request body.

The email will contain a link to the actual invoice and maybe contain a personalized body and subject. If these are not provided, the email will contain a default body and subject.

If the response is successful, the email will be sent to the recipient but we do not guarantee that the email will be delivered successfully. The success of the response means that the system has accepted the request and will attempt to send the email.

Authorizations:

None

path Parameters

company_id required	string The company where to execute the operation
document_id required	string The document identifier

Request Body schema: application/json
optional

Request

body	string The body of the email. If not provided, a default body will be used: in Italian: Buongiorno, abbiamo provveduto all'invio della {INVOICE_TYPE} n. {INVOICE_NUMBER}. È possibile visualizzarla o scaricarne una copia in versione PDF cliccando sul bottone sottostante. Grazie e buon lavoro
reply_to required	string <email> non-empty
subject	string The subject of the email. If not provided, a default subject will be used: in Italian: Nostra {INVOICE_TYPE} n. {INVOICE_NUMBER}
required	string or Array of strings

Responses

Request samples

Content type

application/json

{"body": "string",
"reply_to": "[email protected]",
"subject": "string",
"to": "[email protected]"
}

Response samples

Content type

application/json

{"errors": [{"code": "bad_request",
"detail": "null value where string expected",
"source": {"pointer": "/data/attributes/name"
},
"title": "Invalid value"
}
]
}

Delete an existing document

Authorizations:

None

path Parameters

company_id required	string The company where to execute the operation
id required	string The document identifier

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request DELETE \
     --url ${base_url}/api/v1/companies/:company_id/documents/:document_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"errors": [{"code": "bad_request",
"detail": "null value where string expected",
"source": {"pointer": "/data/attributes/name"
},
"title": "Invalid value"
}
]
}

Get a document

Returns all the information for a specific document from its identifier

Authorizations:

None

path Parameters

company_id required	string The company the document belongs to
id required	string The document identifier

query Parameters

expand

string

Fields that will be expanded. Expandable fields: category, counterpart, flows, sectional, subcategory

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/documents/:document_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": {"category": {"id": "01a09ff1-9ad8-7024-b102-e44db79ec2ff",
"name": "string"
},
"counterpart": {"address": "string",
"bank_identifier": "string",
"city": "string",
"company_name": "string",
"country": "string",
"destination_code": "string",
"id": "01a09ff1-9bb4-76fa-988d-53f2d30cb566",
"identity_type": "COMPANY",
"issued_category": {"color": "string",
"id": "01a09ff1-9bb4-720f-9e78-dc26cb46b800",
"name": "string"
},
"issued_subcategory": {"category_id": "01a09ff1-9bb4-76df-b93b-e4e0f10dd800",
"id": "01a09ff1-9bb4-7a18-9fd3-c70e83ef6368",
"name": "string"
},
"payment_date": "15",
"payment_method": "CARD",
"postal_code": "string",
"province_code": "string",
"received_category": {"color": "string",
"id": "01a09ff1-9bb4-7762-8a33-9add66223f9e",
"name": "string"
},
"received_subcategory": {"category_id": "01a09ff1-9bb4-7e5a-b733-244ffca0e80e",
"id": "01a09ff1-9bb4-7e5d-a215-40a56bfea4f6",
"name": "string"
},
"tax_number": "string",
"vat_number": "string"
},
"created_at": "2019-08-24T14:15:22Z",
"creation_date": "2019-08-24",
"delivery_date": "string",
"delivery_status": "string",
"direction": "ISSUED",
"external_id": "string",
"file_name": "string",
"flows": [{"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
}
],
"format": "FPA12",
"gross_amount": {"amount": "12.3",
"currency": "EUR"
},
"id": "01a09ff1-9ad8-7fb5-9ff7-8528672ddee7",
"is_e_invoice": true,
"notes": "string",
"number": "NC/12345/2026",
"progressive": "12345",
"reasons_and_remarks": ["string"
],
"sectional": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"minimum_digits": 0,
"prefix": "NC/",
"suffix": "/2026"
},
"status": "DRAFT",
"subcategory": {"id": "01a09ff1-9ad8-7489-a0af-4a59153b1e47",
"name": "string"
},
"type": "BILL",
"updated_at": "2019-08-24T14:15:22Z",
"vat_amount": {"amount": "12.3",
"currency": "EUR"
}
}
}

Update an existing document

Authorizations:

None

path Parameters

company_id required	string The company where to execute the operation
id required	string The document identifier

query Parameters

expand

string

Fields that will be expanded. Expandable fields: category, counterpart, flows, subcategory

Request Body schema: application/json
optional

Document

category_id	string or null <uuid> The category identifier. Pass `null` to clear the category and the subcategory.
notes	string or null <= 1000 characters Document notes (max 1000 characters)
subcategory_id	string or null <uuid> The subcategory identifier. Must belong to the category_id set in the same request, or to the current category if category_id is not provided, otherwise the request returns `422 Unprocessable Entity`.

Responses

Request samples

Content type

application/json

{"category_id": "01a09ff1-9c09-7c6f-9af0-b4945b63bc52",
"notes": "string",
"subcategory_id": "01a09ff1-9c09-7e42-9e1d-4e791f29f4c9"
}

Response samples

Content type

application/json

{"data": {"category": {"id": "01a09ff1-9ad8-7024-b102-e44db79ec2ff",
"name": "string"
},
"counterpart": {"address": "string",
"bank_identifier": "string",
"city": "string",
"company_name": "string",
"country": "string",
"destination_code": "string",
"id": "01a09ff1-9bb4-76fa-988d-53f2d30cb566",
"identity_type": "COMPANY",
"issued_category": {"color": "string",
"id": "01a09ff1-9bb4-720f-9e78-dc26cb46b800",
"name": "string"
},
"issued_subcategory": {"category_id": "01a09ff1-9bb4-76df-b93b-e4e0f10dd800",
"id": "01a09ff1-9bb4-7a18-9fd3-c70e83ef6368",
"name": "string"
},
"payment_date": "15",
"payment_method": "CARD",
"postal_code": "string",
"province_code": "string",
"received_category": {"color": "string",
"id": "01a09ff1-9bb4-7762-8a33-9add66223f9e",
"name": "string"
},
"received_subcategory": {"category_id": "01a09ff1-9bb4-7e5a-b733-244ffca0e80e",
"id": "01a09ff1-9bb4-7e5d-a215-40a56bfea4f6",
"name": "string"
},
"tax_number": "string",
"vat_number": "string"
},
"created_at": "2019-08-24T14:15:22Z",
"creation_date": "2019-08-24",
"delivery_date": "string",
"delivery_status": "string",
"direction": "ISSUED",
"external_id": "string",
"file_name": "string",
"flows": [{"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
}
],
"format": "FPA12",
"gross_amount": {"amount": "12.3",
"currency": "EUR"
},
"id": "01a09ff1-9ad8-7fb5-9ff7-8528672ddee7",
"is_e_invoice": true,
"notes": "string",
"number": "NC/12345/2026",
"progressive": "12345",
"reasons_and_remarks": ["string"
],
"sectional": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"minimum_digits": 0,
"prefix": "NC/",
"suffix": "/2026"
},
"status": "DRAFT",
"subcategory": {"id": "01a09ff1-9ad8-7489-a0af-4a59153b1e47",
"name": "string"
},
"type": "BILL",
"updated_at": "2019-08-24T14:15:22Z",
"vat_amount": {"amount": "12.3",
"currency": "EUR"
}
}
}

Flow

Get the list of flows for the given document

The return value is paginated. By default the response contains 25 elements per page but can be instructed to return more elements per page. A cursor is needed to traverse the results.

Authorizations:

None

path Parameters

company_id required	string The company the flows belongs to
document_id required	string The document identifier

query Parameters

page_size	integer The page size
cursor	string The pagination cursor. A cursor is used to paginate through a large set of data. It is a unique identifier that represents a specific position in the dataset.
filter	object List of filters on the resource. Currently the only filterable field is `external_id`.

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/documents/:document_id/flows \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": [{"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
}
],
"page": {"cursor": "string",
"size": 0
}
}

Create a new flow for the given document

Authorizations:

None

path Parameters

company_id required	string The company the flow belongs to
document_id required	string The document identifier

Request Body schema: application/json
optional

Flow

account_id	string or null <uuid> The id of the account
required	object Money representation through amount and currency properties
expected_payment_date required	string <date> The date when the flow is due
external_id	string or null An optional identifier of the flow on your system. Used as an idempotency key: reusing it for the same company returns `422`.
payment_date required	string <date> The date when the flow was paid
payment_method	string or null Enum: "CARD" "CASH" "CHECK" "DEFERRED" "TAX_FORM" "FISCAL_CREDIT" "OTHER" "POSTAL" "RIBA" "SDD" "TRANSFER" The payment method. Possible values are: `CARD`: Payment by debit or credit card. `CASH`: Payment in cash. `CHECK`: Payment by bank check. `DEFERRED`: Amount not collected at the time of sale (e.g. ticket, corrispettivo). `TAX_FORM`: Payment via tax withholding form (e.g. F24 ritenute d'acconto). `FISCAL_CREDIT`: Payment offset by a fiscal/tax credit. `OTHER`: Any payment method not covered by the other values. `POSTAL`: Payment via postal order or postal current account (bollettino postale). `RIBA`: Ricevuta Bancaria — Italian bank receipt collection instrument. `SDD`: SEPA Direct Debit — recurring bank debit authorised by the payer. `TRANSFER`: Bank wire transfer (bonifico bancario).
payment_status required	string Enum: "PAID" "TO_PAY" The payment status. Possible values are: `PAID`: The flow has been paid. `TO_PAY`: The flow is to be paid.

Responses

Request samples

Content type

application/json

{"account_id": "01a09ff1-9d07-7b8c-803f-553007762088",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"expected_payment_date": "2019-08-24",
"external_id": "string",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
}

Response samples

Content type

application/json

{"data": {"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
}
}

Delete a flow for the given document

Authorizations:

None

path Parameters

company_id required	string The company the flow belongs to
document_id required	string The document identifier
id required	string The flow identifier

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request DELETE \
     --url ${base_url}/api/v1/companies/:company_id/documents/:document_id/flows/:flow_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"errors": [{"code": "bad_request",
"detail": "null value where string expected",
"source": {"pointer": "/data/attributes/name"
},
"title": "Invalid value"
}
]
}

Get a specific flow for the document

Authorizations:

None

path Parameters

company_id required	string The company the flow belongs to
document_id required	string The document identifier
id required	string The flow identifier

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/documents/:document_id/flows/:flow_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": {"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
}
}

Update an existing flow

Authorizations:

None

path Parameters

company_id required	string The company where to execute the operation
document_id required	string The document identifier
id required	string The flow identifier

Request Body schema: application/json
optional

Flow

	object Money representation through amount and currency properties
expected_payment_date	string <date> The date when the flow is due
payment_date	string <date> The date when the flow was paid
payment_method	string or null Enum: "CARD" "CASH" "CHECK" "DEFERRED" "TAX_FORM" "FISCAL_CREDIT" "OTHER" "POSTAL" "RIBA" "SDD" "TRANSFER" The payment method
payment_status	string Enum: "PAID" "TO_PAY" The payment status

Responses

Request samples

Content type

application/json

{"amount": {"amount": "12.3",
"currency": "EUR"
},
"expected_payment_date": "2019-08-24",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
}

Response samples

Content type

application/json

{"data": {"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
}
}

Product

Get the list of products

The return value is paginated. By default the response contains 25 elements per page but can be instructed to return more elements per page. A cursor is needed to traverse the results.

Authorizations:

None

path Parameters

company_id

required

string

The company the products belong to

query Parameters

page_size	integer The page size
cursor	string The pagination cursor. A cursor is used to paginate through a large set of data. It is a unique identifier that represents a specific position in the dataset.
filter	object List of filters on the resource. Currently the fields that allow to be filtered are: `code`, `description`, `search`
sort	string Fields for which we can order the results. Sortable fields: `code`, `description`

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/products \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": [{"code": "string",
"description": "string",
"id": "01a09ff1-a206-7e5a-be7b-734479260de0",
"tax_exemption": "string",
"unit_of_measure": "string",
"unit_price": {"amount": "12.3",
"currency": "EUR"
},
"vat_percentage": 0.1
}
],
"page": {"cursor": "string",
"size": 0
}
}

Create a new product

Authorizations:

None

path Parameters

company_id

required

string

The company the product belongs to

Request Body schema: application/json
optional

Product

code	string or null The internal code that identifies the product
description required	string The description of the product
tax_exemption	string or null The tax exemption code, required when `vat_percentage` is `0`
unit_of_measure	string or null The unit of measure of the product (e.g. `pcs`, `kg`, `h`)
required	object Money representation through amount and currency properties
vat_percentage required	number <float> The VAT percentage applied to the product

Responses

Request samples

Content type

application/json

{"code": "string",
"description": "string",
"tax_exemption": "string",
"unit_of_measure": "string",
"unit_price": {"amount": "12.3",
"currency": "EUR"
},
"vat_percentage": 0.1
}

Response samples

Content type

application/json

{"data": {"code": "string",
"description": "string",
"id": "01a09ff1-a206-7e5a-be7b-734479260de0",
"tax_exemption": "string",
"unit_of_measure": "string",
"unit_price": {"amount": "12.3",
"currency": "EUR"
},
"vat_percentage": 0.1
}
}

Delete a product

Authorizations:

None

path Parameters

company_id required	string The company the product belongs to
id required	string The product identifier

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request DELETE \
     --url ${base_url}/api/v1/companies/:company_id/products/:product_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

401
403
404
429
500

Content type

application/json

{"errors": [{"code": "bad_request",
"detail": "null value where string expected",
"source": {"pointer": "/data/attributes/name"
},
"title": "Invalid value"
}
]
}

Get a specific product

Authorizations:

None

path Parameters

company_id required	string The company the product belongs to
id required	string The product identifier

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/products/:product_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": {"code": "string",
"description": "string",
"id": "01a09ff1-a206-7e5a-be7b-734479260de0",
"tax_exemption": "string",
"unit_of_measure": "string",
"unit_price": {"amount": "12.3",
"currency": "EUR"
},
"vat_percentage": 0.1
}
}

Update an existing product

Authorizations:

None

path Parameters

company_id required	string The company the product belongs to
id required	string The product identifier

Request Body schema: application/json
optional

Product

code	string or null The internal code that identifies the product
description	string The description of the product
tax_exemption	string or null The tax exemption code, required when `vat_percentage` is `0`
unit_of_measure	string or null The unit of measure of the product (e.g. `pcs`, `kg`, `h`)
	object Money representation through amount and currency properties
vat_percentage	number <float> The VAT percentage applied to the product

Responses

Request samples

Content type

application/json

{"code": "string",
"description": "string",
"tax_exemption": "string",
"unit_of_measure": "string",
"unit_price": {"amount": "12.3",
"currency": "EUR"
},
"vat_percentage": 0.1
}

Response samples

Content type

application/json

{"data": {"code": "string",
"description": "string",
"id": "01a09ff1-a206-7e5a-be7b-734479260de0",
"tax_exemption": "string",
"unit_of_measure": "string",
"unit_price": {"amount": "12.3",
"currency": "EUR"
},
"vat_percentage": 0.1
}
}

Reconciliation

List all the company's reconciliations

The return value is paginated. By default the response contains 25 elements per page but can be instructed to return more elements per page. A cursor is needed to traverse the results.

Authorizations:

None

path Parameters

company_id

required

string

The company the reconciliations belong to

query Parameters

page_size	integer The page size
cursor	string The pagination cursor. A cursor is used to paginate through a large set of data. It is a unique identifier that represents a specific position in the dataset.
expand	string Fields that will be expanded. Expandable fields: `flow`, `transaction`, `transaction.category`, `transaction.subcategory`
filter	object List of filters on the resource. Currently the fields that allow to be filtered are: `transaction_id`, `flow_id`, `created_at`
sort	string Fields for which we can order the results. Sortable fields: `created_at`

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/reconciliations \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": [{"created_at": "2019-08-24T14:15:22Z",
"flow": {"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
},
"flow_id": "01a09ff1-a101-71ef-b121-2d02dc814e76",
"id": "01a09ff1-a101-7562-81f8-67f19c144af1",
"transaction": {"account_id": "01a09ff1-9e1c-7221-ad86-0ab4b8c2ab57",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"bank_code": "string",
"booking_date_time": "2019-08-24T14:15:22Z",
"category": {"id": "01a09ff1-9e1c-7ad4-ab8d-f42a417aaa9d",
"name": "string"
},
"clean_description": "string",
"counterpart_name": "string",
"created_at": "2019-08-24T14:15:22Z",
"date": "2019-08-24T14:15:22Z",
"description": "string",
"id": "01a09ff1-9e1c-7f3d-b76a-c7ad86380162",
"reconciliations": [{ }
],
"subcategory": {"id": "01a09ff1-9e1c-775a-aca5-d2977a048fed",
"name": "string"
},
"type": "CARDS",
"value_date_time": "2019-08-24T14:15:22Z"
},
"transaction_id": "01a09ff1-a101-7e0c-8863-c7b0ecfe4412"
}
],
"page": {"cursor": "string",
"size": 0
}
}

Create a new reconciliation

Create a new reconciliation between a flow and a bank transaction.

Authorizations:

None

path Parameters

company_id

required

string

The company where to execute the operation

query Parameters

expand

string

Fields that will be expanded. Expandable fields: flow, transaction, transaction.category, transaction.subcategory

Request Body schema: application/json
optional

Reconciliation

flow_id required	string <uuid> The ID of the relative flow
transaction_id required	string <uuid> The ID of the relative transaction

Responses

Request samples

Content type

application/json

{"flow_id": "01a09ff1-a17d-79c7-82f8-48363ece53eb",
"transaction_id": "01a09ff1-a17d-7ade-a21c-e19a91973139"
}

Response samples

Content type

application/json

{"data": {"created_at": "2019-08-24T14:15:22Z",
"flow": {"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
},
"flow_id": "01a09ff1-a101-71ef-b121-2d02dc814e76",
"id": "01a09ff1-a101-7562-81f8-67f19c144af1",
"transaction": {"account_id": "01a09ff1-9e1c-7221-ad86-0ab4b8c2ab57",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"bank_code": "string",
"booking_date_time": "2019-08-24T14:15:22Z",
"category": {"id": "01a09ff1-9e1c-7ad4-ab8d-f42a417aaa9d",
"name": "string"
},
"clean_description": "string",
"counterpart_name": "string",
"created_at": "2019-08-24T14:15:22Z",
"date": "2019-08-24T14:15:22Z",
"description": "string",
"id": "01a09ff1-9e1c-7f3d-b76a-c7ad86380162",
"reconciliations": [{ }
],
"subcategory": {"id": "01a09ff1-9e1c-775a-aca5-d2977a048fed",
"name": "string"
},
"type": "CARDS",
"value_date_time": "2019-08-24T14:15:22Z"
},
"transaction_id": "01a09ff1-a101-7e0c-8863-c7b0ecfe4412"
}
}

Delete an existing reconciliation

Authorizations:

None

path Parameters

company_id required	string The company where to execute the operation
id required	string The reconciliation identifier

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request DELETE \
     --url ${base_url}/api/v1/companies/:company_id/reconciliations/:id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

401
403
404
429
500

Content type

application/json

{"errors": [{"code": "bad_request",
"detail": "null value where string expected",
"source": {"pointer": "/data/attributes/name"
},
"title": "Invalid value"
}
]
}

Get a specific reconciliation

Authorizations:

None

path Parameters

company_id required	string The company the reconciliation belongs to
id required	string The reconciliation identifier

query Parameters

expand

string

Fields that will be expanded. Expandable fields: flow, transaction, transaction.category, transaction.subcategory

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/reconciliations/:id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": {"created_at": "2019-08-24T14:15:22Z",
"flow": {"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
},
"flow_id": "01a09ff1-a101-71ef-b121-2d02dc814e76",
"id": "01a09ff1-a101-7562-81f8-67f19c144af1",
"transaction": {"account_id": "01a09ff1-9e1c-7221-ad86-0ab4b8c2ab57",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"bank_code": "string",
"booking_date_time": "2019-08-24T14:15:22Z",
"category": {"id": "01a09ff1-9e1c-7ad4-ab8d-f42a417aaa9d",
"name": "string"
},
"clean_description": "string",
"counterpart_name": "string",
"created_at": "2019-08-24T14:15:22Z",
"date": "2019-08-24T14:15:22Z",
"description": "string",
"id": "01a09ff1-9e1c-7f3d-b76a-c7ad86380162",
"reconciliations": [{ }
],
"subcategory": {"id": "01a09ff1-9e1c-775a-aca5-d2977a048fed",
"name": "string"
},
"type": "CARDS",
"value_date_time": "2019-08-24T14:15:22Z"
},
"transaction_id": "01a09ff1-a101-7e0c-8863-c7b0ecfe4412"
}
}

Payment

Create a draft bulk payment request

Creates a draft payment operation from bulk-payment rows and returns the Sibill app redirect URL.

Authorizations:

None

path Parameters

company_id

required

string

The company where to create the draft payment operation

Request Body schema: application/json
optional

Bulk payment request

required

Array of objects non-empty

Array (non-empty)

required	object
payee_identifier required	string
payee_name required	string
reason required	string

Responses

Request samples

Content type

application/json

{"payments": [{"amount": {"amount": "2500.00",
"currency": "EUR"
},
"payee_identifier": "IT60X0542811101000000123456",
"payee_name": "Mario Rossi",
"reason": "Stipendio maggio 2026"
}
]
}

Response samples

Content type

application/json

{"data": {"request_id": "266ea41d-adf5-480b-af50-15b940c2b846"
},
"links": [{"href": "http://example.com",
"rel": "externalLink"
}
]
}

Submit an F24 PDF for OCR processing

Upload a raw F24 PDF for asynchronous OCR processing.

The PDF is stored in S3 under a company-scoped path and an F24Upload record is created with status WAITING_OCR. The response contains a request_id that uniquely identifies the processing job — use it to correlate the OCR result delivered later via webhook.

The request body must be the raw binary content of the PDF file with Content-Type: application/pdf. The file_name query parameter is required and should reflect the original file name; label is optional and can be used to attach a human-readable description to the upload.

Requires the * wildcard permission or the payments:f24:write permission.

Authorizations:

None

path Parameters

company_id

required

string

The company where to execute the operation

query Parameters

file_name required	string User-provided file_name for the operation
label required	string User-provided label for the operation

header Parameters

content-type

required

string

Indicate the original mime type of the resource. It could be application/pdf

Request Body schema: application/pdf
optional

PDF file

object <binary>

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request POST \
     --url ${base_url}/api/v1/companies/:company_id/requests/f24/ocr?file_name=:file_name&label=:label \
     --header "Authorization: Bearer ${authorization_token}" \
     --header "Content-Type: application/pdf" \
     --data '${your payload here}'

Response samples

Content type

application/json

{"data": {"request_id": "string"
},
"links": [{"href": "http://example.com",
"rel": "externalLink"
}
]
}

Subcategory

List all subcategories for the company

The return value is paginated. By default the response contains 25 elements per page but can be instructed to return more elements per page. A cursor is needed to traverse the results.

Authorizations:

None

path Parameters

company_id

required

string

The company the subcategories belong to

query Parameters

page_size	integer The page size
cursor	string The pagination cursor. A cursor is used to paginate through a large set of data. It is a unique identifier that represents a specific position in the dataset.
filter	object List of filters on the resource. Currently the fields that allow to be filtered are: `id`, `category_id`, `name`
sort	string Fields for which we can order the results. Sortable fields: `category_id`, `name`

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/subcategories \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": [{"category_id": "8de4c9fd-61a4-4c0b-bf88-0ed3a0fe3fa2",
"id": "01a09ff1-a220-753a-9ba1-73f2ac942972",
"name": "string"
}
],
"page": {"cursor": "string",
"size": 0
}
}

Create a new subcategory

Creates a new subcategory under a parent category. The parent category must belong to the same company; otherwise the request returns 404 Not Found.

Authorizations:

None

path Parameters

company_id

required

string

The company the subcategory belongs to

Request Body schema: application/json
optional

Subcategory

category_id required	string <uuid> The id of the parent category
name required	string The name of the subcategory

Responses

Request samples

Content type

application/json

{"category_id": "8de4c9fd-61a4-4c0b-bf88-0ed3a0fe3fa2",
"name": "string"
}

Response samples

Content type

application/json

{"data": {"category_id": "8de4c9fd-61a4-4c0b-bf88-0ed3a0fe3fa2",
"id": "01a09ff1-a220-753a-9ba1-73f2ac942972",
"name": "string"
}
}

Delete a subcategory

Deletes the subcategory and clears its reference from associated transactions.

Authorizations:

None

path Parameters

company_id required	string The company the subcategory belongs to
id required	string The subcategory identifier

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request DELETE \
     --url ${base_url}/api/v1/companies/:company_id/subcategories/:subcategory_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

401
403
404
429
500

Content type

application/json

{"errors": [{"code": "bad_request",
"detail": "null value where string expected",
"source": {"pointer": "/data/attributes/name"
},
"title": "Invalid value"
}
]
}

Get a subcategory

Returns all the information for a specific subcategory from its identifier

Authorizations:

None

path Parameters

company_id required	string The company the subcategory belongs to
id required	string The subcategory identifier

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/subcategories/:subcategory_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": {"category_id": "8de4c9fd-61a4-4c0b-bf88-0ed3a0fe3fa2",
"id": "01a09ff1-a220-753a-9ba1-73f2ac942972",
"name": "string"
}
}

Update an existing subcategory

Authorizations:

None

path Parameters

company_id required	string The company the subcategory belongs to
id required	string The subcategory identifier

Request Body schema: application/json
optional

Subcategory

name	string The name of the subcategory

Responses

Request samples

Content type

application/json

{"name": "string"
}

Response samples

Content type

application/json

{"data": {"category_id": "8de4c9fd-61a4-4c0b-bf88-0ed3a0fe3fa2",
"id": "01a09ff1-a220-753a-9ba1-73f2ac942972",
"name": "string"
}
}

Transaction

List all transactions for the company

The return value is paginated. By default the response contains 25 elements per page but can be instructed to return more elements per page. A cursor is needed to traverse the results.

Authorizations:

None

path Parameters

company_id

required

string

The company the transactions belong to

query Parameters

page_size	integer The page size
cursor	string The pagination cursor. A cursor is used to paginate through a large set of data. It is a unique identifier that represents a specific position in the dataset.
expand	string Fields that will be expanded. Expandable fields: `category`, `subcategory`, `reconciliations`, `reconciliations.flow`
filter	object List of filters on the resource. Currently the fields that allow to be filtered are: `account_id`, `booking_date_time`, `clean_description`, `counterpart_name`, `date`, `type`
sort	string Fields for which we can order the results. Sortable fields: `amount`, `created_at`, `date`

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/transactions \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": [{"account_id": "01a09ff1-9e1c-7221-ad86-0ab4b8c2ab57",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"bank_code": "string",
"booking_date_time": "2019-08-24T14:15:22Z",
"category": {"id": "01a09ff1-9e1c-7ad4-ab8d-f42a417aaa9d",
"name": "string"
},
"clean_description": "string",
"counterpart_name": "string",
"created_at": "2019-08-24T14:15:22Z",
"date": "2019-08-24T14:15:22Z",
"description": "string",
"id": "01a09ff1-9e1c-7f3d-b76a-c7ad86380162",
"reconciliations": [{"created_at": "2019-08-24T14:15:22Z",
"flow": {"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
},
"flow_id": "01a09ff1-a101-71ef-b121-2d02dc814e76",
"id": "01a09ff1-a101-7562-81f8-67f19c144af1",
"transaction": { },
"transaction_id": "01a09ff1-a101-7e0c-8863-c7b0ecfe4412"
}
],
"subcategory": {"id": "01a09ff1-9e1c-775a-aca5-d2977a048fed",
"name": "string"
},
"type": "CARDS",
"value_date_time": "2019-08-24T14:15:22Z"
}
],
"page": {"cursor": "string",
"size": 0
}
}

Get a transaction

Returns all the information for a specific transaction from its identifier

Authorizations:

None

path Parameters

company_id required	string The company the transaction belongs to
id required	string The transaction identifier

query Parameters

expand

string

Fields that will be expanded. Expandable fields: category, subcategory, reconciliations, reconciliations.flow

Responses

Request samples

base_url="http://example.com" # Replace with the correct Sibill integration API host

curl --request GET \
     --url ${base_url}/api/v1/companies/:company_id/transactions/:transaction_id \
     --header "Authorization: Bearer ${authorization_token}"

Response samples

Content type

application/json

{"data": {"account_id": "01a09ff1-9e1c-7221-ad86-0ab4b8c2ab57",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"bank_code": "string",
"booking_date_time": "2019-08-24T14:15:22Z",
"category": {"id": "01a09ff1-9e1c-7ad4-ab8d-f42a417aaa9d",
"name": "string"
},
"clean_description": "string",
"counterpart_name": "string",
"created_at": "2019-08-24T14:15:22Z",
"date": "2019-08-24T14:15:22Z",
"description": "string",
"id": "01a09ff1-9e1c-7f3d-b76a-c7ad86380162",
"reconciliations": [{"created_at": "2019-08-24T14:15:22Z",
"flow": {"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
},
"flow_id": "01a09ff1-a101-71ef-b121-2d02dc814e76",
"id": "01a09ff1-a101-7562-81f8-67f19c144af1",
"transaction": { },
"transaction_id": "01a09ff1-a101-7e0c-8863-c7b0ecfe4412"
}
],
"subcategory": {"id": "01a09ff1-9e1c-775a-aca5-d2977a048fed",
"name": "string"
},
"type": "CARDS",
"value_date_time": "2019-08-24T14:15:22Z"
}
}

Update an existing transaction

Authorizations:

None

path Parameters

company_id required	string The company where to execute the operation
id required	string The transaction identifier

query Parameters

expand

string

Fields that will be expanded. Expandable fields: category, subcategory, reconciliations, reconciliations.flow

Request Body schema: application/json
optional

Transaction

category_id	string or null <uuid> The category identifier. Pass `null` to clear the category and the subcategory.
subcategory_id	string or null <uuid> The subcategory identifier. Must belong to the category_id set in the same request, or to the current category if category_id is not provided, otherwise the request returns `422 Unprocessable Entity`.

Responses

Request samples

Content type

application/json

{"category_id": "01a09ff1-9ea1-7cf9-9203-9c65313595cb",
"subcategory_id": "01a09ff1-9ea1-7ce3-9d1b-748e0343cfbf"
}

Response samples

Content type

application/json

{"data": {"account_id": "01a09ff1-9e1c-7221-ad86-0ab4b8c2ab57",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"bank_code": "string",
"booking_date_time": "2019-08-24T14:15:22Z",
"category": {"id": "01a09ff1-9e1c-7ad4-ab8d-f42a417aaa9d",
"name": "string"
},
"clean_description": "string",
"counterpart_name": "string",
"created_at": "2019-08-24T14:15:22Z",
"date": "2019-08-24T14:15:22Z",
"description": "string",
"id": "01a09ff1-9e1c-7f3d-b76a-c7ad86380162",
"reconciliations": [{"created_at": "2019-08-24T14:15:22Z",
"flow": {"account_id": "01a09ff1-9c9d-7123-86ad-5438c3da793b",
"amount": {"amount": "12.3",
"currency": "EUR"
},
"created_at": "2019-08-24T14:15:22Z",
"document_id": "01a09ff1-9c9d-7a57-8e11-a15c463704e4",
"expected_payment_date": "2019-08-24",
"external_id": "string",
"id": "01a09ff1-9c9d-7c57-aa41-c72cac8d7466",
"payment_date": "2019-08-24",
"payment_method": "CARD",
"payment_status": "PAID"
},
"flow_id": "01a09ff1-a101-71ef-b121-2d02dc814e76",
"id": "01a09ff1-a101-7562-81f8-67f19c144af1",
"transaction": { },
"transaction_id": "01a09ff1-a101-7e0c-8863-c7b0ecfe4412"
}
],
"subcategory": {"id": "01a09ff1-9e1c-775a-aca5-d2977a048fed",
"name": "string"
},
"type": "CARDS",
"value_date_time": "2019-08-24T14:15:22Z"
}
}

color	string The color used to visually represent the category, encoded as a hex string (e.g. `#ff0000`). Defaults to `#ffffff` if not provided.
name required	string The name of the category

Sibill Integration API (1.0.0)

API reference

Webhook

Document updated event Webhook

Request Body schema: application/jsonrequired

Responses

Request samples

Flow updated event Webhook

Request Body schema: application/jsonrequired

Responses

Request samples

Company

List all the available companies

Authorizations:

query Parameters

Responses

Request samples

Response samples

Account

List all accounts for the company

Authorizations:

path Parameters

query Parameters

Responses

Request samples

Response samples

Get a account

Authorizations:

path Parameters

Responses

Request samples

Response samples

Category

List all categories for the company

Authorizations:

path Parameters

query Parameters

Responses

Request samples

Response samples

Create a new category

Authorizations:

path Parameters

Request Body schema: application/jsonoptional

Responses

Request samples

Response samples

Delete a category

Authorizations:

path Parameters

Responses

Request samples

Response samples

Get a category

Authorizations:

path Parameters

Responses

Request samples

Response samples

Update an existing category

Authorizations:

path Parameters

Request Body schema: application/jsonoptional

Responses

Request samples

Response samples

Counterpart

Get the list of counterparts

Authorizations:

path Parameters

query Parameters

Responses

Request samples

Response samples

Create a new counterpart

Authorizations:

path Parameters

query Parameters

Request Body schema: application/jsonoptional

Responses

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
optional

Request Body schema: application/json
optional

Request Body schema: application/json
optional

Request Body schema: application/json
optional

Request Body schema: application/json
optional

Request Body schema: application/json
optional

Request Body schema: application/json
optional