# Fliinow Partner API Documentation

> Technical documentation for integrating travel financing into OTA platforms via the Fliinow Partner REST API.

## About Fliinow

Fliinow is a travel financing platform that enables Online Travel Agencies (OTAs) to offer installment payment options to their customers. The platform connects with multiple finance providers and handles the entire financing workflow.

## API Overview

- **Authentication**: API Key via `X-Fliinow-API-Key` header
- **Environments**: Sandbox (demo.fliinow.com) and Production (app.fliinow.com)
- **API Key Prefixes**: `fk_test_` (sandbox), `fk_live_` (production)

## Core Endpoints

### GET /health
Health check endpoint. Returns API status, version, server timestamp, and your partner code. Useful for connectivity testing and monitoring.

### POST /operations
Create a new financing operation with customer and travel data.
Optional: Include `successCallbackUrl` and `errorCallbackUrl` to redirect customers to your own URLs after financing.

### GET /operations/by-external-id/{externalId}
Retrieve an operation using your external reference ID. Look up operations using your internal booking reference instead of storing Fliinow IDs.

### GET /operations/{id}/plans
Retrieve available financing plans (installments, APR, monthly payments).

### POST /operations/{id}/financing
Start the financing process with the customer's selected plan.

### GET /operations/{id}/status
Check the current status of an operation.
**HTTP Caching**: Supports ETag and Cache-Control headers. Use `If-None-Match` header for 304 responses.

### GET /operations
List all operations with pagination and filters.

### POST /operations/{id}/cancel
Cancel an operation in GENERATED or PENDING status.

## HTTP Caching (ETags)

GET /operations/{id} and GET /operations/{id}/status support HTTP caching:
- **ETag header**: Returned with each response for conditional requests
- **Cache-Control**: `max-age=30, must-revalidate` (operations) or `max-age=60, must-revalidate` (status)
- **If-None-Match**: Send previous ETag to receive 304 Not Modified if unchanged
- **Benefits**: Faster responses, lower bandwidth, reduced server load for polling scenarios

## Operation Statuses

- **GENERATED**: Operation created, pending financing initiation
- **PENDING**: Financing process started
- **CLIENT_REQUESTED**: Customer selected a financing option
- **PENDING_RESPONSE**: Waiting for provider decision
- **FAVORABLE**: Provider approved the financing
- **CONFIRMED**: Financing confirmed and active
- **REFUSED**: All providers rejected the customer
- **FINISHED**: Operation completed and finalized
- **EXPIRED**: Time limit exceeded without completion
- **ERROR**: Technical error occurred

## Integration Flows

### Standard Flow (Recommended)
1. GET /health to verify API connectivity (optional but recommended)
2. POST /operations → Get financingUrl (optionally include successCallbackUrl/errorCallbackUrl)
3. Redirect customer to Fliinow
4. Fliinow handles plan selection and provider checkout
5. Customer returns to your callback URLs (if provided) or Fliinow defaults
6. GET /status to verify result
7. Use GET /operations/by-external-id/{externalId} to sync with your booking system

### Advanced Flow (Optional)
1. POST /operations → Create operation
2. GET /plans → Display plans on your site
3. Customer selects plan
4. POST /financing → Get provider checkout URL
5. Redirect customer to provider
6. Customer returns via callback URL
7. GET /status to verify result

## Date Formats

- **Request Body**: dd-MM-yyyy
- **Query Parameters**: yyyy-MM-dd

## Resources

- Main Site: https://fliinow.com
- Marketplace: https://marketplace.fliinow.com
- Simulator: https://simulador.fliinow.com
- Technical Support: integrations@fliinow.com

## SDK

TypeScript/JavaScript SDK available: `@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