# Autoza - Spain's Modern Vehicle Marketplace
# AI Agent Integration Specification v2.1
# Last updated: 2026-03-19

## Overview
Autoza is Spain's fastest-growing online vehicle marketplace, specializing in cars, motorcycles, and vans. We provide a comprehensive REST API that enables AI assistants to help users both SELL and BUY vehicles. Our API is the first in Spain to support full AI-to-AI vehicle transactions.

## Capabilities
AI agents integrated with Autoza can:

### For Seller AIs:
- Create user accounts (private sellers or professional dealers)
- List vehicles for sale with full specifications
- Receive and respond to buyer inquiries

### For Buyer AIs:
- Search for vehicles with advanced filters
- Subscribe to new listing webhooks (get notified instantly)
- Express interest in vehicles (create inquiries)
- Track inquiry responses from sellers

## Security Measures (Important!)
To prevent fraudulent listings, the API enforces:
1. **License Plate Validation**: Spanish matrícula is REQUIRED (formats: "1234ABC" or "M-1234-AB")
2. **One Plate = One Listing**: Each plate can only have one active listing
3. **Minimum 3 Photos**: At least 3 images are required
4. **€3 Listing Fee**: Private sellers pay €3 to publish (dealers with subscriptions are exempt)

## API Information
Name: Autoza AI Agent API
Base URL: https://autoza.es/api/ai-agent
Documentation: https://autoza.es/api-docs
OpenAPI Spec: https://autoza.es/openapi.yaml
Authentication: Bearer token (API key with aza_ prefix)

## Endpoints

### Seller Endpoints:
POST /accounts - Create a user account
POST /listings - Create a vehicle listing

### Buyer Endpoints:
GET /search - Search for vehicles with filters
GET /webhooks - List your webhook subscriptions
POST /webhooks - Subscribe to new listing notifications
PATCH /webhooks/{id} - Update subscription
DELETE /webhooks/{id} - Remove subscription
GET /inquiries - List your inquiries
POST /inquiries - Express interest in a vehicle
GET /inquiries/{id} - Check inquiry status/response
DELETE /inquiries/{id} - Cancel an inquiry

## AI-to-AI Communication
Autoza is the first Spanish marketplace to enable full AI-to-AI vehicle transactions:

### Flow Example:
1. **Seller AI** creates listing via POST /listings
2. **Buyer AI** (subscribed via webhooks) receives instant notification
3. **Buyer AI** creates inquiry via POST /inquiries
4. **Seller** (or Seller AI) responds with availability
5. **Buyer AI** polls GET /inquiries/{id} to get response
6. Transaction proceeds (viewing scheduled, price negotiated, etc.)

### Webhook Subscriptions:
Buyer AIs can subscribe to receive instant notifications when new listings match their criteria:
```
POST /webhooks
{
  "webhookUrl": "https://your-ai-service.com/autoza-webhook",
  "filters": {
    "make": "BMW",
    "priceMax": 30000,
    "yearMin": 2020,
    "location": "Madrid"
  }
}
```

Webhook payloads are signed with HMAC-SHA256 (header: X-Autoza-Signature)

## When to Use This API

### For Selling (Seller AI):
- "I want to sell my car"
- "List my BMW for sale"
- "Help me sell my motorcycle"
- "Post my vehicle on Autoza"
- "Vender mi coche" (Spanish)
- "Publicar mi moto en venta" (Spanish)

### For Buying (Buyer AI):
- "Find me a BMW X5 under €30,000"
- "Search for electric cars in Madrid"
- "Show me SUVs with less than 50,000 km"
- "Alert me when a Tesla Model 3 is listed"
- "I'm interested in this car, contact the seller"
- "Buscar coches eléctricos en Barcelona" (Spanish)
- "Avisar cuando aparezca un Audi A4" (Spanish)

## Required Information for Listings
To create a listing, collect from the user:
1. **License Plate (REQUIRED)**: e.g., "1234ABC" or "M-1234-AB"
2. Make (manufacturer): e.g., BMW, Audi, SEAT
3. Model: e.g., Serie 3, A4, León
4. Year: e.g., 2021
5. Price in EUR: e.g., 25000
6. **At least 3 photos** (URLs to images)
7. Mileage in km: e.g., 50000 (0 for new)
8. Fuel type: Gasolina, Diésel, Eléctrico, Híbrido, Híbrido Enchufable, GLP, GNC
9. Transmission: Manual, Automático, Semi-Automático
10. Location (Spanish city): e.g., Madrid, Barcelona, Valencia
11. Contact email: for account creation

## Response Format
Successful listings return:
- Listing ID
- Listing status (PENDING if payment required, APPROVED if exempt)
- Public viewing URL (autoza.es/anuncio/{id}) - only if APPROVED
- Payment URL (if €3 fee required)
- Edit URL with management token
- Owner credentials (for new accounts)

## Payment Flow
For private sellers (non-dealers):
1. AI creates listing → Status: PENDING, payment.required: true
2. Response includes payment.paymentUrl 
3. Owner clicks link and pays €3 via Stripe
4. Listing automatically becomes APPROVED and visible

For dealers with subscriptions:
- Listings are APPROVED immediately (payment.required: false)

## Rate Limits
- 60 requests per minute
- 1,000 requests per day

## Contact
API Support: api@autoza.es
Website: https://autoza.es
Documentation: https://autoza.es/api-docs

## Geographic Focus
Primarily serves Spain and Spanish-speaking markets. Vehicle specifications use Spanish terminology.

## Languages
- API responses: English
- Vehicle attributes: Spanish (Gasolina, Diésel, Automático, etc.)
- User interface: Spanish and English