# 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)
- **Key types**: Agency keys (single agency) and management group keys. Management group keys must also send the `X-Fliinow-Agency` header with the id of the agency they act on behalf of — on every endpoint except `GET /agencies`.

## Core Endpoints

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

### GET /agencies
Management group keys only: returns the active agencies of the group (id, tradeName, address, postalCode, city, countryCode), sorted by id. The only endpoint that does NOT require the `X-Fliinow-Agency` header; the returned ids are the valid values for that header everywhere else.

### POST /operations
Create a new financing operation with customer and travel data (`flights`, `hotels`, `services`). Returns the operation identifier and a `financingUrl` to redirect the customer to.
Optional: `successRedirectUrl` and `errorRedirectUrl` to redirect customers to your own URLs after financing, and `webhookUrl` to receive status change notifications.

### GET /operations
List all operations with pagination and filters (status, from, to).

### 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/{operationIdentifier}/status
Check the current status of an operation.
**HTTP Caching**: Supports ETag and Cache-Control headers. Use `If-None-Match` header for 304 responses.

### POST /operations/{operationIdentifier}/cancel
Cancel an operation the customer has not signed yet (GENERATED, PENDING or ERROR). Leaves it CANCELLED; no provider is called and no money moves. Optional body: `reason` (max 255 chars). CLIENT_REQUESTED cannot be cancelled (its request is already live at the provider) and CONFIRMED must be refunded instead — both return 400 OPERATION_NOT_CANCELLABLE.

### GET /operations/{operationIdentifier}/refund/details
Preview what the customer would get back if a CONFIRMED operation were refunded now: `totalReserve`, `managementFees`, `fliinowCancellationFee`, `fliinowCancellationFeePercentage`, `totalToRefund`. Amounts carry their currency. 400 OPERATION_NOT_REFUNDABLE if the operation is not CONFIRMED.

### POST /operations/{operationIdentifier}/refund
Refund a CONFIRMED operation through its finance provider and leave it REFUNDED. Optional body: `agencyCancellationFee`, `providerCancellationFee` (both default to 0 and lower what the customer receives) and `reason`. 400 if the operation is not CONFIRMED; 422 if the provider rejects the refund, in which case nothing changes.

### GET /financing/simulate/{totalPrice}
Simulate the financing offers available for an amount, without creating an operation (provider, installments, TIN/TAE, quotas, total financed).

### GET /financing/{operationIdentifier}
Retrieve the eligible financing offers for an existing operation (id, companyName, installments, TIN/TAE, quotas, total financed).

### POST /financing
Start the financing process for an operation with the customer's selected offer. Body: `operationIdentifier` + `financialOfferId`. Returns the provider checkout `paymentUrl` (financingStatus REQUESTED), or REFUSED/ERROR with `hasAlternativeFinancialOffers`.

### PUT /operations/webhook-events/ack
Acknowledge a webhook event. Send back the SAME payload received in the webhook (`operationIdentifier`, `operationStatus`, `eventId`) to confirm delivery.

## Webhooks

If you provide a `webhookUrl` when creating an operation, Fliinow sends a POST to it whenever the operation reaches a final or actionable status. The body carries three fields: `operationIdentifier`, `operationStatus`, `eventId`. Intermediate statuses (such as PENDING) do not trigger a webhook; you may receive CONFIRMED, REFUSED, EXPIRED, CANCELLED, REFUNDED or ERROR. Confirm each event with `PUT /operations/webhook-events/ack`.

## HTTP Caching (ETags)

GET /operations/{operationIdentifier}/status supports HTTP caching:
- **ETag header**: Returned with each response for conditional requests
- **Cache-Control**: `max-age=60, must-revalidate`
- **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 successRedirectUrl/errorRedirectUrl/webhookUrl)
3. Redirect customer to Fliinow
4. Fliinow handles plan selection and provider checkout
5. Customer returns to your redirect URLs (if provided) or Fliinow defaults
6. GET /operations/{operationIdentifier}/status to verify result (or wait for the webhook)
7. Use GET /operations/by-external-id/{externalId} to sync with your booking system

### Advanced Flow (Optional)
1. POST /operations → Create operation
2. GET /financing/{operationIdentifier} → Display the eligible offers on your site
3. Customer selects an offer
4. POST /financing → Get the provider checkout paymentUrl
5. Redirect customer to provider
6. Customer returns via redirect URL
7. GET /operations/{operationIdentifier}/status to verify result (or wait for the webhook)

## 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: support@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