# Fliinow Partner API - Complete Technical Documentation

> Comprehensive API documentation for OTA partners integrating travel financing via the Fliinow Partner REST API.

---

## 1. Introduction

Fliinow is a travel financing platform that enables Online Travel Agencies (OTAs) to offer installment payment options to their customers. The Fliinow Partner API provides a RESTful interface for creating financing operations, retrieving available payment plans, and managing the complete financing lifecycle.

### Key Features
- **Fast Integration**: First operation in less than 5 minutes
- **Multi-Provider**: Automatic fallback between multiple finance providers
- **Secure**: API Key authentication, HTTPS required
- **Conversion Boost**: Enable customers who can't pay upfront

---

## 2. Authentication

### API Keys
All requests require the `X-Fliinow-API-Key` header. You'll receive two keys:
- **Sandbox Key**: Prefix `fk_test_` - For testing and development
- **Production Key**: Prefix `fk_live_` - For live operations

### Environments

| Environment | Base URL | Purpose |
|-------------|----------|---------|
| Sandbox | https://demo.fliinow.com/integration-api/v1 | Testing and development |
| Production | https://app.fliinow.com/integration-api/v1 | Live operations |

### Example Request
```http
GET /operations/12345/status HTTP/1.1
Host: demo.fliinow.com
X-Fliinow-API-Key: fk_test_your_api_key_here
Content-Type: application/json
```

### Security Warning
Never expose your API Key in frontend code. All API calls must be made from your server.

---

## 3. API Endpoints

### 3.0 Health Check
**GET /health**

Returns API health status, current version, server timestamp, and your partner code. Useful for connectivity testing and monitoring.

#### Response
```json
{
  "status": "ok",
  "version": "1.2.0",
  "timestamp": "2026-01-31T12:00:00Z",
  "partnerCode": "YOUR_PARTNER_CODE"
}
```

#### Use Cases
- Verify API connectivity before starting integration
- Monitor API availability from your systems
- Check if your API key is valid
- Synchronize timestamps between systems

### 3.1 Create Operation
**POST /operations**

#### Request Body
```json
{
  "externalId": "YOUR-BOOKING-123",
  "successCallbackUrl": "https://yoursite.com/booking/success",
  "errorCallbackUrl": "https://yoursite.com/booking/error",
  "client": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "juan@example.com",
    "prefix": "+34",
    "phone": "612345678",
    "documentId": "12345678A",
    "documentValidityDate": "31-12-2030",
    "gender": "MALE",
    "birthDate": "15-06-1985",
    "nationality": "ESP",
    "address": "Calle Mayor 1",
    "city": "Madrid",
    "postalCode": "28001",
    "countryCode": "ES"
  },
  "packageName": "Cancun All Inclusive",
  "flightDtoList": [],
  "hotelDtoList": [],
  "feeDtoList": [],
  "totalPrice": 1500.00
  // totalReserve is deprecated - calculated automatically
}
```

#### Response
```json
{
  "id": "op_abc123",
  "status": "GENERATED",
  "accessToken": "token_xyz789",
  "financingUrl": "https://fliinow.com/financing/op_abc123"
}
```

### 3.2 Get Financing Plans
**GET /operations/{id}/plans**

Retrieves available financing plans for an operation.

#### Response
```json
{
  "plans": [
    {
      "financialProviderId": 1,
      "financingProvider": {
        "id": 1,
        "name": "PROVIDER_A"
      },
      "installments": 3,
      "commonQuota": {
        "amount": 520.00,
        "currency": "EUR"
      },
      "apr": 0,
      "totalAmountPaid": 1560.00
    },
    {
      "financialProviderId": 2,
      "financingProvider": {
        "id": 2,
        "name": "PROVIDER_B"
      },
      "installments": 6,
      "commonQuota": {
        "amount": 265.00,
        "currency": "EUR"
      },
      "apr": 9.9,
      "totalAmountPaid": 1590.00
    }
  ]
}
```

### 3.3 Start Financing
**POST /operations/{id}/financing**

Initiates the financing process with a selected plan.

#### Request Body
```json
{
  "financialProviderId": 1,
  "installments": 3,
  "successCallbackUrl": "https://yoursite.com/booking/success",
  "errorCallbackUrl": "https://yoursite.com/booking/error"
}
```

#### Response
```json
{
  "operationId": "op_abc123",
  "status": "PENDING",
  "checkout": {
    "redirectUrl": "https://provider.com/checkout/xyz"
  }
}
```

### 3.4 Check Status
**GET /operations/{id}/status**

Returns the current status of an operation. Always verify status after callback.

#### HTTP Caching
This endpoint supports ETag-based caching:
- **ETag Header**: Format `"{status}-{updatedAtEpoch}"`
- **Cache-Control**: `max-age=60, must-revalidate`
- **If-None-Match**: Include previous ETag to receive 304 Not Modified if unchanged

#### Response
```json
{
  "operationId": "op_abc123",
  "status": "FAVORABLE",
  "updatedAt": "2026-01-15T10:30:00Z"
}
```

#### Response Headers
```
ETag: "FAVORABLE-1706789012"
Cache-Control: max-age=60, must-revalidate
```

#### 304 Not Modified
When `If-None-Match` header matches current ETag, returns 304 with no body.

### 3.5 List Operations
**GET /operations**

Lists all operations with pagination and optional filters.

#### Query Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| page | integer | Page number (from 0) |
| size | integer | Operations per page (max 100) |
| status | string | Filter by status (optional) |
| from | date | Date from yyyy-MM-dd (optional) |
| to | date | Date to yyyy-MM-dd (optional) |

### 3.6 Cancel Operation
**POST /operations/{id}/cancel**

Cancels an operation. Only valid for GENERATED or PENDING status.

### 3.7 Get Operation by External ID
**GET /operations/by-external-id/{externalId}**

Retrieves an operation using your external reference ID (the `externalId` you provided when creating the operation).

#### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| externalId | string | Yes | Your external reference ID for the operation |

#### Response (200 OK)
```json
{
  "id": "abc123xyz",
  "externalId": "BOOKING-12345",
  "status": "CREATED",
  "financingUrl": "https://app.fliinow.com/pay/abc123xyz",
  "client": {
    "firstName": "Juan",
    "lastName": "García"
  },
  "totalPrice": 1500.00,
  "createdAt": "2026-01-31T10:00:00Z"
}
```

#### Use Cases
- Look up operations using your internal booking reference
- Sync operation status with your booking system
- Avoid storing Fliinow operation IDs in your database

---

## 4. Operation Statuses

| Status | Description | Recommended Action |
|--------|-------------|-------------------|
| GENERATED | Operation created, pending financing initiation | Show plans and wait for customer selection |
| PENDING | Financing process started | Wait for customer to complete checkout |
| CLIENT_REQUESTED | Customer selected a financing option | Wait for provider response |
| PENDING_RESPONSE | Waiting for provider decision | Poll status periodically |
| FAVORABLE | Provider approved the financing | ✅ Confirm booking, issue trip |
| CONFIRMED | Financing confirmed and active | Trip confirmed, process complete |
| REFUSED | All providers rejected the customer | ❌ Offer alternative payment method |
| FINISHED | Operation completed and finalized | Archive operation |
| EXPIRED | Time limit exceeded without completion | Create new operation if customer wants to retry |
| ERROR | Technical error occurred | Contact support or retry |

---

## 5. Integration Flows

### 5.1 Standard Flow (Recommended)
The simplest integration requiring only 2 API calls:

0. **Health Check** (GET /health) - Optional but recommended
   - Verify API connectivity before starting
   - Get current API version and server timestamp

1. **Create Operation** (POST /operations)
   - Send customer and travel data
   - Optionally include `successCallbackUrl` and `errorCallbackUrl` to redirect customers to your URLs
   - Receive `financingUrl`

2. **Redirect to Fliinow**
   - Customer goes to financingUrl
   - Fliinow shows available plans
   - Customer selects plan
   - Automatic redirect to provider checkout

3. **Provider Checkout**
   - Customer completes signing process

4. **Callback**
   - Customer returns to your `successCallbackUrl` or `errorCallbackUrl` (if provided in POST /operations)
   - Otherwise, redirected to Fliinow default URLs

5. **Verify Status** (GET /status)
   - Always confirm actual status before issuing trip

6. **Sync with Booking System** (GET /operations/by-external-id/{externalId}) - Optional
   - Use your internal booking reference to look up operations
   - No need to store Fliinow operation IDs

### 5.2 Advanced Flow (Optional)
For partners who want to display financing plans on their own website:

1. **Create Operation** (POST /operations)
2. **Get Plans** (GET /plans) - Display on your site
3. **Customer Selects Plan** - On your frontend
4. **Start Financing** (POST /financing) - Get provider URL
5. **Redirect to Provider**
6. **Callback**
7. **Verify Status** (GET /status)

### Multi-Funding
If the selected provider rejects the customer, Fliinow automatically tries other providers offering the same installment count. No extra implementation needed.

---

## 6. Error Handling

### HTTP Error Codes

| Code | Name | Description | Action |
|------|------|-------------|--------|
| 400 | Bad Request | Invalid or missing data | Review request body |
| 401 | Unauthorized | Invalid or missing API Key | Verify X-Fliinow-API-Key header |
| 403 | Forbidden | No permission for this operation | Verify operation belongs to your account |
| 404 | Not Found | Operation not found | Verify operation ID |
| 409 | Conflict | Operation not in valid state | Check current status before action |
| 429 | Too Many Requests | Rate limit exceeded | Implement rate limiting |
| 500 | Internal Server Error | Fliinow internal error | Retry with exponential backoff |

### Error Response Format
```json
{
  "error": "BAD_REQUEST",
  "message": "Field 'email' is required",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

---

## 7. Best Practices

### Security
- Store API Key in environment variables, never in code
- Make all calls from backend, never from frontend
- Use HTTPS for callback URLs

### Connectivity & Monitoring
- Use GET /health on application startup to verify API connectivity
- Implement periodic health checks to monitor API availability
- Compare server timestamp to detect clock drift issues

### Operation Management
- Use externalId consistently when creating operations
- Use GET /operations/by-external-id/{externalId} to sync with your booking system
- Consider externalId as your primary reference (no need to store Fliinow IDs)

### Robustness
- Always verify status with GET /status after callback
- Implement retries with exponential backoff for 5xx errors
- Handle all HTTP error codes
- Store accessToken for future reference

### User Experience
- Clearly show APR and total amount to pay
- Indicate redirect is to a secure site
- Have friendly error page for rejections

### Data Formatting
- Use externalId that links to your booking system
- Dates in body: dd-MM-yyyy format
- Dates in query params: yyyy-MM-dd format

---

## 8. Go-Live Checklist

Before switching to production:
- [ ] Full integration tested in Sandbox
- [ ] All statuses handled (FAVORABLE, REFUSED, FINISHED, EXPIRED, ERROR)
- [ ] Callbacks working correctly
- [ ] Status verification implemented
- [ ] Robust error handling
- [ ] Production API Key configured
- [ ] Callback URLs pointing to production

### Switching to Production
Only two changes needed:
1. **Base URL**: demo.fliinow.com → app.fliinow.com
2. **API Key**: fk_test_... → fk_live_...

---

## 9. SDK

A TypeScript/JavaScript SDK is available for easier integration:

**Package**: `@fliinow-com/fliinow-partner-api`

- npm: https://www.npmjs.com/package/@fliinow-com/fliinow-partner-api
- GitHub: https://github.com/fliinow-com/fliinow-partner-api

---

## 10. Support

### Technical Support
- Email: integrations@fliinow.com
- Response time: < 24h business hours

### Urgent Issues
- Email: urgent@fliinow.com
- Response time: < 2h

---

## Resources

- Main Site: https://fliinow.com
- Marketplace: https://marketplace.fliinow.com
- Simulator: https://simulador.fliinow.com
- API Documentation: https://docs.fliinow.com