cargos-api

A small Python library to build and submit rental booking records to the Italian Police Ca.R.G.O.S. API.

Table of Contents

• cargos-api
• Table of Contents
• Install
• Quick start
• Formatting the data
  • Required fields
  • Optional fields
  • Lookup tables (locations, documents, payments, vehicles)
• API usage notes
• Inspecting the record as a mapping

This repository was created to interact with the Ca.R.G.O.S. APIs for a client who needed to automate the submission of rental booking details to the Italian Police.

The official documentation (see docs.pdf) is difficult to follow and sparse on examples. The goal of this project is to provide a clean, documented Python module that makes the integration straightforward and consistent.

This module handles all the location -> id conversions, data formatting and submission to the Ca.R.G.O.S. API.

Install

pip install cargos-api

Quick start

from cargos_api import CargosAPI, CargosRecordMapper, models as m

# Credentials
api = CargosAPI(username="...", password="...", api_key="...48-chars...")

# Build a booking using codes from your catalogs (examples below use placeholder codes)
booking = m.BookingData(
    contract_id="CONTR-001",
    contract_datetime="2025-01-01T10:00:00",   # ISO-like; mapper outputs dd/mm/YYYY HH:MM
    payment_type_code="1",                     # per Ca.R.G.O.S. table
    checkout_datetime="2025-01-01T11:00:00",
    checkout_place=m.Address(location_code=403015146, street="Via X 1"),  # Roma (example)
    checkin_datetime="2025-01-02T11:00:00",
    checkin_place=m.Address(location_code=402020327, street="Via Y 2"),    # Verona (example)
    operator=m.Operator(
        id="SYSTEM",
        agency_id="1",
        agency_name="ACME",
        agency_place_code=403015146,
        agency_address="Via Z 3",
        agency_phone="0000",
    ),
    car=m.Car(
        type_code="A",  # vehicle type code (per table)
        brand="Fiat",
        model="Panda",
        plate="AB123CD",
        color="Bianco",
    ),
    customer=m.Customer(
        surname="Rossi",
        name="Mario",
        birth_date="1990-01-01",
        birth_place_code=401028044,           # Genova (example)
        citizenship_code=100000001,           # Italia (example)
        id_doc_type_code="CI",
        id_doc_number="XYZ12345",
        id_doc_issuing_place_code=401028044,
        driver_licence_number="LIC123456",
        driver_licence_issuing_place_code=401028044,
        contact="0000000000",
    ),
)

# Map to Ca.R.G.O.S. fixed-width record (1505 chars)
record = CargosRecordMapper().build_record(booking)

# Validate or send
api.check_contracts([record])
# api.send_contracts([record])

Formatting the data

This library exposes typed dataclasses in cargos_api.models that you fill with your normalized data and pass to the mapper.

• BookingData: contract_id, contract_datetime, payment_type_code, checkout_datetime, checkout_place (Address), checkin_datetime, checkin_place (Address), operator (Operator), car (Car), customer (Customer), second_driver (optional)
• Customer: surname, name, birth_date, birth_place_code, citizenship_code, residence (Address, optional), id_doc_type_code, id_doc_number, id_doc_issuing_place_code, driver_licence_number, driver_licence_issuing_place_code, contact
• SecondDriver: same as Customer (without residence); if present, all fields are mandatory
• Car: type_code, brand, model, plate, color (optional), has_gps (optional), has_immobilizer (optional)
• Address: location_code, street
• Operator: id, agency_id, agency_name, agency_place_code, agency_address, agency_phone

Ca.R.G.O.S. Tracciato Record Parameters

Notes

• * → Both residence fields (LUOGO_COD and INDIRIZZO) must be filled together, otherwise the data is rejected.
• ** → If a second driver is present, all fields under CONDUCENTE2_ become mandatory.
• Each block of records must not contain more than 100 contracts (rows).

Required fields

The mapper validates inputs and raises InvalidInput if anything is missing:

• booking: id, creation_date, from_date, to_date
• customer: birth_date, firstname, lastname, birth_place, citizenship, and one of (document_id, driver_licence_number) and one of (cellphone, email)
• car: brand, model, plate, color
• delivery_place: address_city, address
• return_place: address_city, address
• operator: id, agency_id, agency_name, city, address, phone

Optional fields

• Customer.address is emitted as free-text in the record when provided
• Address.address_country is currently not mapped to a dedicated field

Lookup tables (locations, documents, payments, vehicles)

• Packaged CSV catalogs under cargos_api/data/ are used at runtime:
  • luoghi.csv (location/country codes)
  • tipo_documento.csv (document types)
  • tipo_pagamento.csv (payment types)
  • tipo_veicolo.csv (vehicle types)
• Lookups are case-insensitive; expired locations (rows with DataFineVal) are ignored
• Use CatalogLoader if you need to resolve human-readable labels to Ca.R.G.O.S. codes in your app:

  from cargos_api.locations_loader import CatalogLoader
  code = CatalogLoader().document_type_code('CI')
  

• If a required code is not found, the mapper raises a ValueError

Inspecting the record as a mapping

Sometimes you want to verify exactly what each field contains after padding/truncation. You can ask the mapper to return both the fixed-width string and a JSON-like mapping of field names to their exact slices by passing with_map=True:

from cargos_api import CargosRecordMapper, models as m

booking = m.BookingData(
    contract_id="123", contract_datetime="2025-01-05T09:00:00", payment_type_code="1",
    checkout_datetime="2025-01-06T10:00:00", checkout_place=m.Address(location_code=403015146, street="Via A 10"),
    checkin_datetime="2025-01-07T10:00:00", checkin_place=m.Address(location_code=403015146, street="Via B 20"),
    operator=m.Operator(id="SYS", agency_id="AG1", agency_name="ACME", agency_place_code=403015146, agency_address="Via C 30", agency_phone="06..."),
    car=m.Car(type_code="A", brand="VW", model="Golf", plate="ZZ999ZZ"),
    customer=m.Customer(
        surname="Bianchi", name="Anna", birth_date="1985-05-20",
        birth_place_code=403015146, citizenship_code=100000001,
        id_doc_type_code="CI", id_doc_number="X1", id_doc_issuing_place_code=403015146,
        driver_licence_number="L1", driver_licence_issuing_place_code=403015146,
    ),
)
record, mapping = CargosRecordMapper().build_record(booking, with_map=True)
print(len(record))              # 1505
print(mapping["CONTRATTO_ID"])  # 50-char padded slice for the contract ID

API usage notes

• CargosAPI.get_token() fetches the token using HTTP Basic auth
• The api_key must be exactly 48 characters: first 32 chars are the AES key and the last 16 chars are the IV used to encrypt the bearer token
• Use check_contracts(records) to validate records before submission; use send_contracts(records) to submit them

Example: minimal end-to-end flow

from cargos_api import CargosAPI, CargosRecordMapper, models as m

api = CargosAPI(username="ORG", password="PASS", api_key="...48-chars...")
booking = m.BookingData(
    contract_id="123",
    contract_datetime="2025-01-05T09:00:00",
    payment_type_code="1",
    checkout_datetime="2025-01-06T10:00:00",
    checkout_place=m.Address(location_code=403015146, street="Via A 10"),
    checkin_datetime="2025-01-07T10:00:00",
    checkin_place=m.Address(location_code=403015146, street="Via B 20"),
    operator=m.Operator(id="SYS", agency_id="AG1", agency_name="ACME", agency_place_code=403015146, agency_address="Via C 30", agency_phone="06..."),
    car=m.Car(type_code="A", brand="VW", model="Golf", plate="ZZ999ZZ", color="Nero"),
    customer=m.Customer(
        surname="Bianchi", name="Anna", birth_date="1985-05-20",
        birth_place_code=403015146, citizenship_code=100000001,
        id_doc_type_code="CI", id_doc_number="DOC1", id_doc_issuing_place_code=403015146,
        driver_licence_number="LIC1", driver_licence_issuing_place_code=403015146,
        contact="333...",
    ),
)
record = CargosRecordMapper().build_record(booking)
api.check_contracts([record])

Troubleshooting

• ValueError: location not found → check the spelling of city/country names
• InvalidInput: missing fields → read the error message for which fields are missing
• InvalidResponse: HTTP errors → network issues or server response with errore field

Building something with it?

If you nee dhelp implementing this in your project, please reach out.

Author

If you found this project helpful or interesting, consider starring the repo and following me for more security research and tools, or buy me a coffee to keep me up