# Amadeus API Quick Reference

## Quick Start

```bash
# 1. Setup Amadeus credentials
./setup-amadeus.sh

# 2. Test integration
./test-amadeus-integration.sh

# 3. View Swagger UI
open http://localhost:8081/swagger-ui.html
```

---

## Common API Calls

### 1. Search Flights

```bash
curl -X POST "http://localhost:8081/api/v1/flights/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "originLocationCode": "MAD",
    "destinationLocationCode": "NYC",
    "departureDate": "2026-03-15",
    "returnDate": "2026-03-22",
    "adults": 1,
    "travelClass": "ECONOMY",
    "currencyCode": "EUR"
  }'
```

**Response**: List of flight offers with pricing

---

### 2. Get Fare Rules

```bash
curl -X GET "http://localhost:8081/api/v1/flights/fare-rules/{offerId}" \
  -H "Authorization: Bearer $TOKEN"
```

**Response**: Detailed fare rules, cancellation policies, baggage allowances

---

### 3. Create Booking

```bash
curl -X POST "http://localhost:8081/api/v1/bookings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flightOffer": {...},
    "travelers": [{
      "id": "1",
      "dateOfBirth": "1990-01-01",
      "name": {
        "firstName": "JOHN",
        "lastName": "DOE"
      },
      "gender": "MALE",
      "contact": {
        "emailAddress": "john.doe@example.com",
        "phones": [{
          "deviceType": "MOBILE",
          "countryCallingCode": "34",
          "number": "612345678"
        }]
      },
      "documents": [{
        "documentType": "PASSPORT",
        "number": "A12345678",
        "expiryDate": "2030-12-31",
        "issuanceCountry": "ES",
        "nationality": "ES"
      }]
    }]
  }'
```

**Response**: Booking confirmation with PNR

---

### 4. Issue Ticket

```bash
curl -X POST "http://localhost:8081/api/v1/tickets/issue" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bookingId": "BOOKING_ID_HERE"
  }'
```

**Response**: Ticket numbers and confirmation

---

### 5. Void Ticket

```bash
curl -X POST "http://localhost:8081/api/v1/tickets/{ticketNumber}/void" \
  -H "Authorization: Bearer $TOKEN"
```

**Response**: Void confirmation (within 24 hours, no penalty)

---

### 6. Refund Ticket

```bash
curl -X POST "http://localhost:8081/api/v1/tickets/{ticketNumber}/refund" \
  -H "Authorization: Bearer $TOKEN"
```

**Response**: Refund amount and penalties

---

## Airport Codes

### Common Airports

| Code | City | Airport |
|------|------|---------|
| MAD | Madrid | Adolfo Suárez Madrid-Barajas |
| BCN | Barcelona | Barcelona-El Prat |
| NYC | New York | All NYC airports |
| JFK | New York | John F. Kennedy |
| LHR | London | Heathrow |
| CDG | Paris | Charles de Gaulle |
| FRA | Frankfurt | Frankfurt Airport |
| AMS | Amsterdam | Schiphol |
| DXB | Dubai | Dubai International |
| SIN | Singapore | Changi |

**Find more**: https://www.iata.org/en/publications/directories/code-search/

---

## Travel Classes

- `ECONOMY` - Economy class
- `PREMIUM_ECONOMY` - Premium economy
- `BUSINESS` - Business class
- `FIRST` - First class

---

## Currency Codes

- `EUR` - Euro
- `USD` - US Dollar
- `GBP` - British Pound
- `JPY` - Japanese Yen
- `AED` - UAE Dirham

**Full list**: https://www.iso.org/iso-4217-currency-codes.html

---

## Passenger Types

- `ADULT` - 12+ years
- `CHILD` - 2-11 years
- `INFANT` - Under 2 years (seated)
- `HELD_INFANT` - Under 2 years (on lap)

---

## Document Types

- `PASSPORT` - Passport
- `IDENTITY_CARD` - National ID card
- `VISA` - Visa
- `DRIVERS_LICENSE` - Driver's license

---

## Monitoring

### Check Health

```bash
curl http://localhost:8081/actuator/health | jq
```

### Check Amadeus Status

```bash
curl http://localhost:8081/actuator/health | jq '.components.amadeusApi'
```

### Check Circuit Breaker

```bash
curl http://localhost:8081/actuator/health | jq '.components.circuitBreakers.details.amadeus'
```

### View Logs

```bash
# All Amadeus logs
docker-compose logs app | grep -i amadeus

# Authentication logs
docker-compose logs app | grep -i "amadeus" | grep -i "auth"

# Error logs
docker-compose logs app | grep -i "amadeus" | grep -i "error"
```

---

## Troubleshooting

### Mock Mode (No Credentials)

**Symptom**: Logs show "credentials not configured, using mock"

**Solution**: Run `./setup-amadeus.sh` to configure credentials

---

### Authentication Failed

**Symptom**: "Failed to authenticate with Amadeus API"

**Solution**:
1. Verify credentials in `.env` file
2. Check for extra spaces
3. Ensure using correct environment (test vs production)
4. Restart: `docker-compose restart app`

---

### Circuit Breaker Open

**Symptom**: "Circuit breaker is OPEN"

**Solution**:
1. Wait 10 seconds for auto-recovery
2. Check Amadeus API status
3. Review error logs

---

### Timeout Errors

**Symptom**: "Request timed out"

**Solution**:
1. Check network connectivity
2. Verify Amadeus API is responding
3. Increase timeout in `application.yml`

---

## Useful Links

- **Amadeus Developer Portal**: https://developers.amadeus.com/
- **API Documentation**: https://developers.amadeus.com/self-service
- **Code Examples**: https://github.com/amadeus4dev
- **Support**: https://developers.amadeus.com/support
- **API Status**: https://developers.amadeus.com/status

---

## Environment Variables

```bash
# Test Environment (Free Tier)
AMADEUS_API_BASE_URL=https://test.api.amadeus.com
AMADEUS_API_KEY=your_test_api_key
AMADEUS_API_SECRET=your_test_api_secret

# Production Environment
AMADEUS_API_BASE_URL=https://api.amadeus.com
AMADEUS_API_KEY=your_production_api_key
AMADEUS_API_SECRET=your_production_api_secret
```

---

## Rate Limits

### Test Environment
- **Transactions per second**: 10
- **Transactions per month**: 2,000 (free tier)

### Production Environment
- Varies by plan
- Contact Amadeus for enterprise plans

---

## Best Practices

1. **Cache Results**: Cache flight search results for 5-10 minutes
2. **Handle Errors**: Always implement proper error handling
3. **Use Circuit Breaker**: Let it protect your system
4. **Monitor Metrics**: Track API usage and errors
5. **Test Thoroughly**: Test in test environment before production
6. **Secure Credentials**: Never commit credentials to git
7. **Log Transactions**: Keep audit trail of all bookings
8. **Validate Input**: Validate all user input before API calls

---

**Last Updated**: January 2026