Bancomail Web API - Integration Guide

Setup

To activate the integration and start using Bancomail datasets within your platform:

• Join the Bancomail Partner Program
• Provide the authorized IP addresses for API calls
• Request your access credentials from our team

Authentication

Authentication is handled through an access token.

To obtain the access token, provide username:password in the request headers, encoded in Base64. Example: Authorization: Basic dGVzdDpibWwyYVRwRg==.

The access token must be included in the headers of all subsequent calls using Authorization: Bearer {{token}}. The token remains valid until logout or for 15 minutes after the last request in which it was included. While the token is valid, every request that uses it resets the session timeout counter.

{
  "response": {
    "token": "536076f226e28b2a2bd0e4bbc3de6add6927e778a8819882628"
  },
  "messages": [
    {
      "code": "0",
      "message": "OK"
    }
  ]
}

Search

The main search layout is result. For each query, the returned value is the total number of available records. Queries must use only the parameters defined below.

To retrieve the valid references for these parameters, use the layouts described in the next section (Reference Layout).

{
  "query": [
    {"macro_id": "40", "country_code": "IT"}
  ],
  "limit": "1"
}

Reference Layout

Dedicated layouts have been created to define search parameters and provide the nomenclatures needed to populate dropdown menus or search interfaces.

Fields

If you need to query one of these layouts and return more than 100 records, such as retrieving the full list of macro categories, you must set the limit parameter to the maximum number of records available in that layout.

{
  "query": [
    {"id": ">0"}
  ],
  "limit": "300"
}

Purchases

To complete a purchase, the order information must be inserted into the acquisti layout.

The required information is listed below:

{
  "fieldData": {
    "query": "{\"country_code\":\"AL\",\"macro_id\":\"180\"},{\"admin1_code\":\"IT.02\",\"country_code\":\"IT\",\"macro_id\":\"180\"},{\"admin2_code\":\"DE.02.094\",\"admin1_code\":\"DE.02\",\"country_code\":\"DE\",\"macro_id\":\"180\"},{\"admin2_code\":\"IT.01.AQ\",\"admin1_code\":\"IT.01\",\"country_code\":\"IT\",\"macro_id\":\"180\"}",
    "numero_anagrafiche": "51",
    "user": "test",
    "order_user_id": "FD459",
    "est_garanzia": "Bancomail S.p.A., Genova, GE, Italia"
  },
  "script": "notifica_ordine"
}

Once the order has been registered and completed, the databases will be made available via FTP within a maximum of 3 working days.

Check Purchase Status

You can query the same layout to verify the purchase status using the following parameters:

{
  "query": [
    {"order_user_id": "FD459"}
  ]
}

Retrieve Purchased Packages via FTP

After the order is completed, the Database department will prepare the requested databases and make them available for download. The partner must retrieve the data through an FTP connection.

• Host name: takoaka.com (standard port)
• Access credentials are communicated to the partner when the service is enabled.
• For each order, within 3 working days, the partner will find a ZIP file, typically named user_orderid.zip.
• The ZIP file contains two files with the same filename, in .xlsx and .csv format.
• As soon as the package is available, the order status is updated to fulfilled.

Credits

The payment model for orders placed through the Bancomail Web Service is based on purchasing credits in advance. Credit top-ups are handled through an external Bancomail procedure that is communicated to each service user.

To verify the available credit balance, query the credits layout using the parameter name (user name).

The remaining credit balance is not updated in real time because it depends on an administrative check. Updates may take from one hour up to one working day. Orders are still recorded immediately, and the related credits are deducted during the update process.

Examples

Using cURL

curl \
-X <HTTP METHOD> \
-H 'authorization: Bearer <TOKEN>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '<BODY>' \
<URL>

Example Search Call via cURL

curl \
-H 'authorization: Bearer 536076f226e28b2a2bd0e4bbc3de6add6927e778a8819882628' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
  "query": [
    {"macro_id": "40", "country_code":"IT"}
  ],
  "limit":"1"
}' \
https://api.neosoft.it/fmi/data/v1/databases/BM_WS_TEST/layouts/result/_find

Example Query Collections

Postman documentation links:

• Test Environment: Open Postman documentation
• Production Environment: Open Postman documentation

Recommended next steps

Partner application

Integration is available to Bancomail partners. Apply to the Partner Program and activate your setup with direct support from our team.