API Documentation

Smart API Overview

The CRIF API endpoints feature intelligent database caching with UUID-based tracking that allows multiple clients to request the same tax_id independently while avoiding duplicate processing.

Key Features

Smart caching - returns existing data when available
UUID tracking - multiple clients can track same tax_id independently
Real-time status tracking for processing reports
PDF and JSON data included in responses
Input validation and comprehensive error handling
Automatic deduplication prevents unnecessary external API calls

UUID Workflow

How UUID Tracking Works

New Request: Send tax_id with optional uuid to create a new request
Status Check: Send only uuid to check the status of an existing request
Multiple Clients: Different UUIDs allow multiple clients to request the same tax_id
Smart Caching: System checks database first before making external API calls

Response Status Codes

Status Code	Meaning	Description
200	Completed	Existing completed report returned with PDF and JSON data
202	Processing	Report is being processed or new request created
400	Bad Request	Missing or invalid request data
404	Not Found	UUID not found in database
500	Server Error	Internal server error occurred

Base URL

http://localhost:5000

Content Type

application/json

Supported Methods

POST

Quick Tip

Use UUIDs to track multiple requests for the same tax_id. This allows different clients to monitor their specific requests independently.

Company Reports API

Retrieve credit reports for Italian companies using their VAT number (Partita IVA) with smart UUID-based tracking.

POST /api/crif/company

Request Fields

Field	Type	Required	Description
`tax_id`	String	New Requests	Italian VAT number (Partita IVA) - 11 digits
`uuid`	String	Optional	Client-provided UUID for tracking multiple requests

Usage Patterns

New Request

{
  "tax_id": "11423251005",
  "uuid": "my-unique-id-123"
}

Creates new request with optional UUID tracking

Status Check

{
  "uuid": "my-unique-id-123"
}

Check status of existing request using UUID only

Validation Rules

tax_id: Must be exactly 11 digits
uuid: Optional for new requests, required for status checks
Multiple requests for same tax_id with different UUIDs are allowed
UUID format: Any string, recommend using UUID4 format

Response Structure

Completed Report (200)

{
  "success": true,
  "report_id": 18,
  "uuid": "my-unique-id-123",
  "status": "completed",
  "message": "Report completed - returning data",
  "data": {
    "pdf_available": true,
    "json_data": "...",
    "pdf_url": "/serve_pdf/18",
    "created_at": "2025-08-12T18:24:42.850040",
    "completed_at": "2025-08-12T18:26:20.989681"
  }
}

Processing Report (202)

{
  "success": true,
  "report_id": 19,
  "uuid": "my-unique-id-123", 
  "status": "processing",
  "message": "Report is currently being processed",
  "data": {
    "pdf_available": false,
    "external_request_id": "4983a0be-9e24-41d2-b2b3-f4d2b6ea14f4",
    "created_at": "2025-08-13T12:21:28.394956"
  }
}

UUID Not Found (404)

{
  "error": "No request found for provided UUID"
}

Individual Reports API

Retrieve credit reports for Italian individuals using their fiscal code (Codice Fiscale) with smart UUID-based tracking.

POST /api/crif/individual

Request Fields

Field	Type	Required	Description
`tax_id`	String	New Requests	Italian fiscal code (Codice Fiscale) - 16 characters
`uuid`	String	Optional	Client-provided UUID for tracking multiple requests

Usage Patterns

New Request

{
  "tax_id": "RSSMRA85M01H501Z",
  "uuid": "client-tracking-456"
}

Creates new request with optional UUID tracking

Status Check

{
  "uuid": "client-tracking-456"
}

Check status of existing request using UUID only

Fiscal Code Format

16 characters total
First 6: Last name (3) + First name (3)
Next 5: Birth year (2) + Month (1) + Day (2)
Next 4: Birth municipality code
Last 1: Control character

Validation Rules

Must be exactly 16 characters
Cannot be empty or whitespace only
Automatically trimmed and converted to uppercase
Must follow Italian fiscal code format
uuid: Optional for new requests, required for status checks

Response Structure

Completed Report (200)

{
  "success": true,
  "report_id": 15,
  "uuid": "client-tracking-456",
  "status": "completed",
  "message": "Report completed - returning data",
  "data": {
    "pdf_available": true,
    "json_data": "...",
    "pdf_url": "/serve_pdf/15",
    "created_at": "2025-08-12T15:30:15.123456",
    "completed_at": "2025-08-12T15:31:20.789012"
  }
}

Processing Report (202)

{
  "success": true,
  "report_id": 20,
  "uuid": "client-tracking-456",
  "status": "processing",
  "message": "Report is currently being processed",
  "data": {
    "pdf_available": false,
    "external_request_id": "133ac7b4-83b5-458b-8f13-c8203abc04cf",
    "created_at": "2025-08-13T12:36:15.360007"
  }
}

UUID Not Found (404)

{
  "error": "No request found for provided UUID"
}

Validation Error (400)

{
  "error": "Fiscal code must be exactly 16 characters"
}

A2A Business Reports API

Retrieve comprehensive business reports for Italian companies through the A2A SOAP API with smart UUID-based tracking.

POST /api/a2a/business

Request Fields

Field	Type	Required	Description
`vat_number`	String	New Requests	Italian VAT number (Partita IVA) - 11 digits
`uuid`	String	Optional	Client-provided UUID for tracking multiple requests
`name`	String	New Requests	Company name or business name
`street`	String	New Requests	Street address of the business
`municipality`	String	New Requests	Municipality/City name
`province`	String	New Requests	Province code (2 letters, e.g., MI, RM)
`postal_code`	String	New Requests	5-digit postal code (CAP)

Usage Patterns

New Request

{
  "vat_number": "01613510161",
  "uuid": "a2a-biz-tracking-789",
  "name": "Example Company SRL",
  "street": "Via Roma 123",
  "municipality": "Milano",
  "province": "MI",
  "postal_code": "20100"
}

Creates new A2A business request with UUID tracking

Status Check

{
  "uuid": "a2a-biz-tracking-789"
}

Check status of existing A2A business request using UUID only

Validation Rules

vat_number: Must be exactly 11 digits
name: Required for new requests, company name
Complete address: street, municipality, province, postal_code all required
province: 2-letter Italian province code
postal_code: 5-digit Italian postal code
uuid: Optional for new requests, required for status checks

Response Structure

Completed Report (200)

{
  "success": true,
  "report_id": 25,
  "uuid": "a2a-biz-tracking-789",
  "status": "completed",
  "message": "Report completed - returning data",
  "data": {
    "created_at": "2025-08-14T16:26:18.028560",
    "external_request_id": "ir-code-456",
    "jsonreport": {...}, // Full A2A JSON report data
    "pdf": "base64encodedpdfstring...", // PDF in base64
    "completed_at": "2025-08-14T16:30:45.123456"
  }
}

Processing Report (202)

{
  "success": true,
  "report_id": 26,
  "uuid": "a2a-biz-tracking-789",
  "status": "processing",
  "message": "New A2A business report request created successfully",
  "data": {
    "pdf_available": false,
    "external_request_id": "ir-code-456",
    "created_at": "2025-08-14T16:26:18.028560"
  }
}

UUID Not Found (404)

{
  "error": "No request found for provided UUID"
}

Validation Error (400)

{
  "error": "vat_number is required for new requests"
}

A2A Business Features

SOAP API Integration

Direct SOAP integration with A2A service
Automatic IR code generation and tracking
PDF report generation via SprintRS
Complete request/response logging

Report Content

Company registration details
Financial information and history
Directors and company officers
Credit rating and risk assessment

A2A Consumer Reports API

Retrieve comprehensive individual credit reports for Italian consumers through the A2A SOAP API with smart UUID-based tracking.

POST /api/a2a/consumer

Request Fields

Field	Type	Required	Description
`fiscal_code`	String	New Requests	Italian fiscal code (Codice Fiscale) - 16 characters
`uuid`	String	Optional	Client-provided UUID for tracking multiple requests
`first_name`	String	New Requests	Individual's first name
`last_name`	String	New Requests	Individual's last name
`gender`	String	New Requests	Gender (M for Male, F for Female)
`birth_date`	String	New Requests	Birth date in YYYY-MM-DD format
`street`	String	New Requests	Street address
`municipality`	String	New Requests	Municipality/City name
`province`	String	New Requests	Province code (2 letters, e.g., MI, RM)
`postal_code`	String	New Requests	5-digit postal code (CAP)

Usage Patterns

New Request

{
  "fiscal_code": "FLRMTT96T23L746S",
  "uuid": "a2a-consumer-101",
  "first_name": "MATTEO",
  "last_name": "FLORIDDIA",
  "gender": "M",
  "birth_date": "1996-12-23",
  "street": "Via Roma 123",
  "municipality": "Roma",
  "province": "RM",
  "postal_code": "00100"
}

Creates new A2A consumer request with UUID tracking

Status Check

{
  "uuid": "a2a-consumer-101"
}

Check status of existing A2A consumer request using UUID only

Validation Rules

fiscal_code: Must be exactly 16 characters
first_name, last_name: Required personal information
gender: Must be either "M" or "F"
birth_date: YYYY-MM-DD format required
Complete address: street, municipality, province, postal_code all required
province: 2-letter Italian province code
postal_code: 5-digit Italian postal code
uuid: Optional for new requests, required for status checks

Response Structure

Completed Report (200)

{
  "success": true,
  "report_id": 30,
  "uuid": "a2a-consumer-101",
  "status": "completed",
  "message": "Report completed - returning data",
  "data": {
    "created_at": "2025-08-14T16:26:18.028560",
    "external_request_id": "ir-code-789",
    "jsonreport": {...}, // Full A2A JSON consumer report
    "pdf": "base64encodedpdfstring...", // PDF in base64
    "completed_at": "2025-08-14T16:30:45.123456"
  }
}

Processing Report (202)

{
  "success": true,
  "report_id": 31,
  "uuid": "a2a-consumer-101",
  "status": "processing",
  "message": "New A2A consumer report request created successfully",
  "data": {
    "pdf_available": false,
    "external_request_id": "ir-code-789",
    "created_at": "2025-08-14T16:26:18.028560"
  }
}

UUID Not Found (404)

{
  "error": "No request found for provided UUID"
}

Validation Error (400)

{
  "error": "gender must be M or F"
}

A2A Consumer Features

SOAP API Integration

Direct SOAP integration with A2A SprintConsumerONE
Automatic IR code generation and tracking
PDF report generation via SprintRS
Complete personal data protection

Report Content

Personal identification details
Credit history and payment behavior
Credit score and risk assessment
Associated business activities
Negative credit events and defaults

API Usage Examples

CRIF Company Report Examples

Create New Request:

// Create new CRIF company report with UUID
const response = await fetch('/api/crif/company', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "tax_id": "01613510161",
        "uuid": "my-unique-client-id-123"
    })
});

const result = await response.json();
console.log(result);

// Response (202 - Processing):
// {
//     "success": true,
//     "report_id": 68,
//     "uuid": "my-unique-client-id-123",
//     "status": "processing",
//     "message": "New company report request created successfully",
//     "data": {
//         "pdf_available": false,
//         "external_request_id": "e2d8bd50-e3f6-4aff-99a7-5acd8ab88ff0",
//         "created_at": "2025-08-14T16:26:18.028560"
//     }
// }

Check Status with UUID:

// Check status using only UUID
const statusResponse = await fetch('/api/crif/company', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "uuid": "my-unique-client-id-123"
    })
});

const statusResult = await statusResponse.json();
console.log(statusResult);

// Response when completed (200):
// {
//     "success": true,
//     "report_id": 68,
//     "uuid": "my-unique-client-id-123", 
//     "status": "completed",
//     "message": "Report completed - returning data",
//     "data": {
//         "created_at": "2025-08-14T16:26:18.028560",
//         "external_request_id": "e2d8bd50-e3f6-4aff-99a7-5acd8ab88ff0",
//         "jsonreport": {...}, // Full JSON report data
//         "pdf": "base64encodedpdfstring...", // PDF in base64
//         "completed_at": "2025-08-14T16:28:45.123456"
//     }
// }

Create New Request:

curl -X POST http://your-domain.com/api/crif/company \
  -H "Content-Type: application/json" \
  -d '{
    "tax_id": "01613510161",
    "uuid": "my-unique-client-id-123"
  }'

Check Status:

curl -X POST http://your-domain.com/api/crif/company \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "my-unique-client-id-123"
  }'

Complete Python Example:

import requests
import time
import json

# Create new request
response = requests.post('http://your-domain.com/api/crif/company', 
    json={
        "tax_id": "01613510161",
        "uuid": "my-unique-client-id-123"
    })

result = response.json()
print("Initial Response:", result)

if result.get('success'):
    uuid = result.get('uuid')

    # Poll for completion
    while True:
        status_response = requests.post('http://your-domain.com/api/crif/company',
            json={"uuid": uuid})

        status_result = status_response.json()

        if status_result.get('status') == 'completed':
            print("Report completed!")
            pdf_base64 = status_result['data']['pdf']
            json_data = status_result['data']['jsonreport']

            # Save PDF
            import base64
            with open(f'report_{uuid}.pdf', 'wb') as f:
                f.write(base64.b64decode(pdf_base64))

            # Save JSON
            with open(f'report_{uuid}.json', 'w') as f:
                json.dump(json_data, f, indent=2)

            break
        elif status_result.get('status') == 'processing':
            print("Still processing, waiting...")
            time.sleep(30)
        else:
            print("Error:", status_result)
            break

CRIF Individual Report Examples

// CRIF Individual Report - New Request
const response = await fetch('/api/crif/individual', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "tax_id": "FLRMTT96T23L746S",
        "uuid": "individual-request-456"
    })
});

// Check status later with UUID only
const statusResponse = await fetch('/api/crif/individual', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "uuid": "individual-request-456"
    })
});

import requests

# Create individual report request
response = requests.post('http://your-domain.com/api/crif/individual',
    json={
        "tax_id": "FLRMTT96T23L746S", 
        "uuid": "individual-request-456"
    })

print(response.json())

A2A Business Report Examples

Create New Request:

// Create new A2A business report
const response = await fetch('/api/a2a/business', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "vat_number": "01613510161",
        "uuid": "a2a-business-uuid-789",
        "name": "Example Company SRL",
        "street": "Via Roma 123",
        "municipality": "Milano",
        "province": "MI",
        "postal_code": "20100"
    })
});

const result = await response.json();
console.log(result);

Check Status with UUID:

// Check status using only UUID
const statusResponse = await fetch('/api/a2a/business', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "uuid": "a2a-business-uuid-789"
    })
});

const statusResult = await statusResponse.json();
console.log(statusResult);

Create New Request:

// Create new A2A business report
const response = await fetch('/api/a2a/business', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "vat_number": "01613510161",
        "uuid": "a2a-business-uuid-789",
        "name": "Example Company SRL",
        "street": "Via Roma 123",
        "municipality": "Milano",
        "province": "MI",
        "postal_code": "20100"
    })
});

const result = await response.json();
console.log(result);

Check Status with UUID:

// Check status using only UUID
const statusResponse = await fetch('/api/a2a/business', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "uuid": "a2a-business-uuid-789"
    })
});

const statusResult = await statusResponse.json();
console.log(statusResult);

Create New Request:

curl -X POST http://your-domain.com/api/a2a/business \
  -H "Content-Type: application/json" \
  -d '{
    "vat_number": "01613510161",
    "uuid": "a2a-business-uuid-789",
    "name": "Example Company SRL",
    "street": "Via Roma 123",
    "municipality": "Milano",
    "province": "MI",
    "postal_code": "20100"
  }'

Check Status with UUID:

curl -X POST http://your-domain.com/api/a2a/business \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "a2a-business-uuid-789"
  }'

Response Example (202 - Processing):

{
  "success": true,
  "report_id": 26,
  "uuid": "a2a-business-uuid-789",
  "status": "processing",
  "message": "New A2A business report request created successfully",
  "data": {
    "pdf_available": false,
    "external_request_id": "ir-code-456",
    "created_at": "2025-08-14T16:26:18.028560"
  }
}

import requests

# Create new A2A business report
response = requests.post('http://your-domain.com/api/a2a/business',
    json={
        "vat_number": "01613510161",
        "uuid": "a2a-business-uuid-789",
        "name": "Example Company SRL",
        "street": "Via Roma 123",
        "municipality": "Milano", 
        "province": "MI",
        "postal_code": "20100"
    })

result = response.json()
print("Initial Response:", result)

# Check status later
status_response = requests.post('http://your-domain.com/api/a2a/business',
    json={"uuid": "a2a-business-uuid-789"})

print("Status Response:", status_response.json())

A2A Consumer Report Examples

Create New Request:

// Create new A2A consumer report
const response = await fetch('/api/a2a/consumer', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "fiscal_code": "FLRMTT96T23L746S",
        "uuid": "a2a-consumer-uuid-101",
        "first_name": "MATTEO",
        "last_name": "FLORIDDIA",
        "gender": "M",
        "birth_date": "1996-12-23",
        "street": "Via Roma 123",
        "municipality": "Roma",
        "province": "RM",
        "postal_code": "00100"
    })
});

const result = await response.json();
console.log(result);

Check Status with UUID:

// Check status using only UUID
const statusResponse = await fetch('/api/a2a/consumer', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "uuid": "a2a-consumer-uuid-101"
    })
});

const statusResult = await statusResponse.json();
console.log(statusResult);

Create New Request:

curl -X POST http://your-domain.com/api/a2a/consumer \
  -H "Content-Type: application/json" \
  -d '{
    "fiscal_code": "FLRMTT96T23L746S",
    "uuid": "a2a-consumer-uuid-101",
    "first_name": "MATTEO",
    "last_name": "FLORIDDIA",
    "gender": "M",
    "birth_date": "1996-12-23",
    "street": "Via Roma 123",
    "municipality": "Roma",
    "province": "RM",
    "postal_code": "00100"
  }'

Check Status with UUID:

curl -X POST http://your-domain.com/api/a2a/consumer \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "a2a-consumer-uuid-101"
  }'

Response Example (202 - Processing):

{
  "success": true,
  "report_id": 31,
  "uuid": "a2a-consumer-uuid-101",
  "status": "processing",
  "message": "New A2A consumer report request created successfully",
  "data": {
    "pdf_available": false,
    "external_request_id": "ir-code-789",
    "created_at": "2025-08-14T16:26:18.028560"
  }
}

Response Example (200 - Completed):

{
  "success": true,
  "report_id": 31,
  "uuid": "a2a-consumer-uuid-101",
  "status": "completed",
  "message": "Report completed - returning data",
  "data": {
    "created_at": "2025-08-14T16:26:18.028560",
    "external_request_id": "ir-code-789",
    "jsonreport": {...},
    "pdf": "base64encodedpdfstring...",
    "completed_at": "2025-08-14T16:30:45.123456"
  }
}

import requests

# Create new A2A consumer report
response = requests.post('http://your-domain.com/api/a2a/consumer',
    json={
        "fiscal_code": "FLRMTT96T23L746S",
        "uuid": "a2a-consumer-uuid-101",
        "first_name": "MATTEO",
        "last_name": "FLORIDDIA",
        "gender": "M",
        "birth_date": "1996-12-23",
        "street": "Via Roma 123",
        "municipality": "Roma",
        "province": "RM",
        "postal_code": "00100"
    })

result = response.json()
print("Initial Response:", result)

# Check status later
status_response = requests.post('http://your-domain.com/api/a2a/consumer',
    json={"uuid": "a2a-consumer-uuid-101"})

print("Status Response:", status_response.json())

Integration Best Practices

UUID Strategy: Use meaningful UUIDs that include client/session info
Status Polling: Use UUID-only requests to avoid duplicate processing
Error Handling: Always check HTTP status codes before processing responses
Timeout Management: Set reasonable timeouts for processing (30-60 seconds)

Caching Benefits: Leverage smart caching for frequently requested tax_ids
Multiple Clients: Different UUIDs allow independent tracking per client
PDF URLs: Store PDF URLs as they remain valid for completed reports
Input Validation: Validate tax_id format before sending requests

Common Workflows

Recommended integration patterns and workflows for different use cases.

Single Client Workflow

1. Initial Request

POST /api/crif/company
{
  "tax_id": "11423251005",
  "uuid": "client-session-123"
}

2. Status Polling

POST /api/crif/company
{
  "uuid": "client-session-123"
}

3. Result Handling

HTTP 200: Download PDF and process data
HTTP 202: Continue polling
HTTP 404: UUID not found - check implementation

Multi-Client Workflow

Scenario: Multiple clients need same tax_id

Client A Request

{
  "tax_id": "11423251005",
  "uuid": "client-a-uuid"
}

Client B Request (independent)

{
  "tax_id": "11423251005",
  "uuid": "client-b-uuid"
}

Both clients can track their requests independently using their unique UUIDs, even though they requested the same tax_id.

Batch Processing Workflow

1. Submit Multiple Requests

requests = [
  {"tax_id": "11111111111", "uuid": "batch-1"},
  {"tax_id": "22222222222", "uuid": "batch-2"},
  {"tax_id": "33333333333", "uuid": "batch-3"}
]

for request in requests:
  submit_request(request)

2. Monitor All Requests

uuids = ["batch-1", "batch-2", "batch-3"]

while pending_uuids:
  for uuid in pending_uuids:
    status = check_status(uuid)
    if status == "completed":
      pending_uuids.remove(uuid)
      process_result(uuid)

3. Optimization Tips

Stagger requests to avoid rate limits
Use exponential backoff for polling
Store UUIDs in database for persistence

Error Handling Workflow

Common Error Scenarios

400 Bad Request
Invalid tax_id format or missing required fields

404 Not Found
UUID not found - check UUID spelling or database sync

500 Server Error
External API issues - implement retry logic with backoff

Retry Strategy

def retry_with_backoff(func, max_retries=3):
  for attempt in range(max_retries):
    try:
      return func()
    except Exception as e:
      if attempt == max_retries - 1:
        raise e
      time.sleep(2 ** attempt)  # Exponential backoff

Performance Optimization

Request Optimization

Use meaningful UUIDs
Implement request deduplication
Cache frequently requested tax_ids

Polling Strategy

Start with 10-second intervals
Increase to 30 seconds after 1 minute
Stop after 5 minutes (timeout)

Resource Management

Use connection pooling
Implement proper timeouts
Monitor API usage patterns