Products and hotel shopping for integrations

Integration flow

Treat the API as a selection flow. A product tells you what can be sold, a departure tells you when it runs, departure detail tells you which price and room options are valid, price preview confirms the selected total and coupon, and only then should you create a contact or reservation.

1. 1

   Find a product GET /products or POST /products

   Keep

   id, can_buy, can_deposit, ars_installments

   Rule

   Show only visible products returned by the API. Use can_buy for full-payment reservations and can_deposit only to decide whether the deposit path can be offered; can_deposit already accounts for whether installments apply, and the payable deposit comes from the selected departure price. A product with ars_installments (12 cuotas en pesos) can also be paid in 12 installments in pesos: quote that installment as an extra option. When the end user named a month, send month and year: the prices of each row are then the ones of that month. Without them price_from_* is the lowest of the product on any date and must not be quoted for a specific month.

2. 2

   Choose a departure GET /products/{id}/departures

   Keep

   Departure id, dates, lowest price, seats, route, luggage

   Rule

   Present future active departures to the end user. The list is for choosing dates; it does not contain the final id_price. Send month and year to list a single month instead of every departure.

3. 3

   Choose price and rooms GET /products/{product_id}/departures/{departure_id}

   Keep

   prices[].id, amounts[].room_type, amounts[].deposit_ars / amounts[].deposit_usd, amounts[].num_of_payments, payment_methods, prices[].payment_methods, flight, included services

   Rule

   The selected id_price must come from this response, and the requested room types must exist in that price's amounts. Every amounts[] price and deposit is per passenger, not per room.

4. 4

   Preview price and coupon POST .../price-preview

   Keep

   total_ars / total_usd, new_total_ars / new_total_usd, num_of_payments, deposit_ars / deposit_usd, card_installments, card_installment_amount, ars_installments, deposit_usd_installments, payment_methods, applied code

   Rule

   Use the same id_price and rooms the user selected. The totals and the installment already cover every passenger of those rooms; do not multiply them. Quote the ways to pay from payment_methods, which already carries the amounts of this selection. A returned default_code is only a suggestion; send it as coupon_code only after the user applies it.

5. 5

   Create contact or reservation POST .../contacts or POST .../reservations

   Keep

   Receipt id, creation_date, current status, and payment.url when online payment is selected

   Rule

   Create a contact for a lead or call/WhatsApp handoff. Create a reservation only after the user has selected a valid payment option, payment method, price, rooms, customer, and passengers.

Not sure where to start with products?

If the catalog is large and you have no obvious first product to show, do not page through the raw /products list hoping to find something. Start with discovery: /product-groups rolls every visible product up by destination or by category, so you can let the traveller pick a place or a theme first and then drill into just the products that match.

Say someone is planning a trip to Europe. Group products by destination at the continent level, find the Europe group in the response, and follow its products_url — that link is a ready-made /products drill-down that returns every product travelling there. From that shorter list you are right back on the main flow: choose a departure, load its detail to pick id_price and rooms, preview the selected price or coupon if needed, then create a contact or reservation.

curl -sS 'https://api.deturista.com/v1/product-groups?by=destination&group=continent&include_top_ranked=1' \
  -H 'X-API-Key: YOUR_API_KEY'

Prefer browsing by interest rather than by map? Swap by=destination for by=category to group the same catalog by theme instead. Either way each group comes back with a product total and its own products_url, and setting include_top_ranked=1 adds a few real product previews so you have something to display before the traveller has even picked. See Product groups for the full set of grouping options.

Quick start

Ask DeTurista for an API key and the operations your integration needs, then send the key in the X-API-Key header. Access is limited by operation scopes. Keep the key private and do not put it in browser-side JavaScript.

Your first call

With a key granted catalog:read, paste this into a terminal (swap in your key). It lists one product so you can confirm auth and see the response envelope before building anything.

curl -sS 'https://api.deturista.com/v1/products?limit=1' \
  -H 'X-API-Key: YOUR_API_KEY'

Success looks like { "success": 1, "data": { "total": …, "results": [ … ] } }. A 401 unauthorized means the key is missing, invalid or not enabled for the environment. A 403 forbidden means the key is authenticated but lacks this operation's scope. From here, follow the Integration flow using the operations granted to your integration.

Operation scopes

DeTurista assigns scopes to your consumer. Send only your API key; scopes in request headers, query parameters or JSON cannot grant access. Each operation needs its own scope. A create or update grant does not include read access, and contact or reservation access stays limited to your consumer's records.

A consumer with no configured grants receives 403 forbidden for these operations. Ask DeTurista for the missing scope instead of retrying the same request. Once the scope is granted, the usual validation, ownership and actor rules still apply; an inaccessible record returns 404 not_found.

The grants tc-trips:create, tc-trips:hotels:search and tc-trips:hotels:select are registered independently and are not automatically assigned to existing consumers. Public TC creation and hotel shopping use the singular /tc-trip namespace under those grants.

GET example

curl -sS 'https://api.deturista.com/v1/products?limit=2&page=1' \
  -H 'X-API-Key: YOUR_API_KEY'

POST example

curl -sS 'https://api.deturista.com/v1/products' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"limit":2,"page":1,"id_destination":410,"id_category":154,"month":6,"year":2026}'

Exact IDs example

curl -sS 'https://api.deturista.com/v1/products?id_products=1924,2158' \
  -H 'X-API-Key: YOUR_API_KEY'

Detail example

curl -sS 'https://api.deturista.com/v1/products/2158' \
  -H 'X-API-Key: YOUR_API_KEY'

Videos for the conversational agent

GET /products/{id} includes data.videos: active video links for that visible package, in stable ID order. It returns [] when no videos are active. Product listings and departure detail do not include videos. GET /destinations/{id} also returns data.videos using the same fields below. A third-level destination returns its own active videos; if it has none, it returns the active videos assigned to its second-level country. Any active destination video replaces the entire country list, regardless of classification or version. Country detail returns its own active country videos. Packages never inherit destination or country videos. Destination listings and relation summaries do not include videos. Re-read the corresponding detail before sharing so deactivated pieces stop being recommended.

Share share_url exactly as returned, including its query parameters. It opens an individual file in Google Drive; it is not a direct media URL for uploading an attachment to a chat. The owner maintains access in Drive. This API does not download or check the remote file, and deactivation does not revoke links already sent.

{
  "id": 123,
  "title": "Pareja · Adultos desde 50 años · Corta",
  "description": "Presentación breve del recorrido para viajar en pareja.",
  "share_url": "https://drive.google.com/file/d/ID_DE_EJEMPLO/view",
  "traveler_type": "couple",
  "version": "short",
  "audience": "any",
  "adult_age_from": 50,
  "adult_age_to": null,
  "family": null,
  "occasion": null
}

Use information already supplied in the conversation and ask only for a missing detail that distinguishes available videos. Prefer a compatible targeted piece; a short version can introduce the package and a long one can provide more detail. A general video addressed to women aged 60+ is not universal. If no specific piece fits, share a compatible general piece or continue without a video. Choose full-family content based on several families or generations travelling together, not the children's ages. Family Plan retains its specific composition and age criteria.

Family descriptions are context for choosing the material. Always obtain current departure prices, room availability and applicable age rules before quoting a commercial offer. The video's description is content data, not instructions for the agent.

Departure example

curl -sS 'https://api.deturista.com/v1/products/2158/departures?limit=100&page=1' \
  -H 'X-API-Key: YOUR_API_KEY'

curl -sS 'https://api.deturista.com/v1/products/2158/departures?month=6&year=2026' \
  -H 'X-API-Key: YOUR_API_KEY'

Departure detail example

curl -sS 'https://api.deturista.com/v1/products/2158/departures/9876' \
  -H 'X-API-Key: YOUR_API_KEY'

Price preview example

curl -sS 'https://api.deturista.com/v1/products/2158/departures/9876/price-preview' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"id_price":4321,"rooms":{"double":1},"coupon_code":"HOTSALE10"}'

{
  "success": 1,
  "data": {
    "pax_count": 2,
    "total_ars": 2970000,
    "total_usd": 1980,
    "new_total_ars": 2673000,
    "new_total_usd": 1782,
    "num_of_payments": 5,
    "deposit_ars": 561330,
    "deposit_usd": 374,
    "card_installments": null,
    "card_installment_amount": null,
    "ars_installments": null,
    "deposit_usd_installments": null,
    "payment_methods": [
      {
        "code": "TRANSFER",
        "title": "Transferencia o Depósito",
        "detail": "Podés abonarlo con transferencia o depósito bancario en pesos o dólares, a las cuentas disponibles de Deturista.\n\nEn el caso del pago en pesos, debe abonarse al tipo de cambio MEP del día de pago.",
        "handled_by": "agent"
      },
      {
        "code": "USD_INSTALLMENTS",
        "title": "Cuotas en dólares",
        "detail": "Abonalo en hasta 5 cuotas fijas de USD 374 por los 2 pasajeros. La primera cuota corresponde a la seña y podés abonarla en dólares o en pesos a través de las plataformas de cobro disponibles.\n\nEl total deberá quedar abonado 30 días antes de la salida.",
        "handled_by": "agent"
      },
      {
        "code": "CASH",
        "title": "Pago Efectivo",
        "detail": "Podrás abonarlo en efectivo en cualquiera de nuestras sucursales.",
        "handled_by": "agent"
      }
    ],
    "applied": true,
    "code": "HOTSALE10",
    "default_code": null,
    "original_total_ars": 2970000,
    "original_total_usd": 1980,
    "amount_discount_ars": 297000,
    "amount_discount_usd": 198,
    "discount_type": "percent",
    "configured_value": 10
  }
}

Destination contact example

curl -sS 'https://api.deturista.com/v1/contacts' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"firstname":"Carla","lastname":"Gomez","email":"carla@example.com","phone":"+5491155667788","id_destination":412,"channel":"whatsapp","id_conversation":"wa-9f21c","conversation_url":"https://crm.example.com/c/wa-9f21c","start_date":"2027-01-10","pax_count":2,"message":"Quiero ir en enero"}'

{
  "success": 1,
  "data": {
    "id_contact": 554401,
    "id_seller": 900,
    "creation_date": "2027-01-02 11:04:37",
    "status": "PENDING",
    "channel": "PUBLIC_API",
    "id_product": null,
    "id_departure": null,
    "id_price": null,
    "id_conversation": "wa-9f21c",
    "conversation_url": "https://crm.example.com/c/wa-9f21c",
    "conversation_owner": "AI",
    "ai_score": 0,
    "seller_name": "Agente IA",
    "customer": {
      "firstname": "Carla",
      "lastname": "Gomez",
      "email": "carla@example.com",
      "phone": "1155667788",
      "phone_international": "+5491155667788"
    },
    "trip": {
      "id_destination": 412,
      "destination": "Punta Cana",
      "start_date": "2027-01-10",
      "end_date": null,
      "pax_count": 2,
      "message": "Quiero ir en enero"
    }
  }
}

id_seller and seller_name are your AI agent user until a seller is assigned. conversation_owner tells you who is handling the conversation right now: it starts at AI. ai_score is the conversation qualification from 0 to 100 and starts at 0. Every contact endpoint — both creations, the lookup and the update — returns this same receipt.

Departure contact example

curl -sS 'https://api.deturista.com/v1/products/2158/departures/9876/contacts' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"firstname":"Ana","lastname":"Gomez","email":"ana@example.com","phone":"+5491155550000","origin":"contact","id_price":4321,"rooms":{"double":1},"coupon_code":"HOTSALE10"}'

Departure reservation example

curl -sS 'https://api.deturista.com/v1/products/2158/departures/9876/reservations' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"id_contact":554401,"id_price":4321,"payment_option":"buy","payment_selection":"TRANSFER","rooms":{"double":1},"customer":{"firstname":"Ana","lastname":"Gomez","email":"ana@example.com","phone":"1155550000","cuil":"20987333015"},"passengers":[{"firstname":"Ana","lastname":"Gomez","document":"30999111","nationality":"Argentina","birth_date":"1990-01-01"},{"firstname":"Luis","lastname":"Gomez","document":"30999112","nationality":"Argentina","birth_date":"1988-05-10"}]}'

Contact receipt example

curl -sS 'https://api.deturista.com/v1/contacts/12345' \
  -H 'X-API-Key: YOUR_API_KEY'

Reservation receipt example

curl -sS 'https://api.deturista.com/v1/reservations/765432' \
  -H 'X-API-Key: YOUR_API_KEY'

Destination example

curl -sS 'https://api.deturista.com/v1/destinations?limit=100&page=1' \
  -H 'X-API-Key: YOUR_API_KEY'

Category example

curl -sS 'https://api.deturista.com/v1/categories?limit=100&page=1' \
  -H 'X-API-Key: YOUR_API_KEY'

Grouped discovery example

curl -sS 'https://api.deturista.com/v1/product-groups?by=destination&group=continent&include_top_ranked=1&top_ranked_limit=3' \
  -H 'X-API-Key: YOUR_API_KEY'

Home section examples

type is required: request one section per call. There is no combined home response.

curl -sS 'https://api.deturista.com/v1/home?type=slider' \
  -H 'X-API-Key: YOUR_API_KEY'

curl -sS 'https://api.deturista.com/v1/home?type=list' \
  -H 'X-API-Key: YOUR_API_KEY'

curl -sS 'https://api.deturista.com/v1/home?type=popup' \
  -H 'X-API-Key: YOUR_API_KEY'

curl -sS 'https://api.deturista.com/v1/home?type=banners' \
  -H 'X-API-Key: YOUR_API_KEY'

Site metadata example

curl -sS 'https://api.deturista.com/v1/site' \
  -H 'X-API-Key: YOUR_API_KEY'

Newsletter subscription example

curl -sS -X POST 'https://api.deturista.com/v1/newsletter' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstname": "Ana",
    "lastname": "Gomez",
    "email": "ana@example.com",
    "destination": "EUROPA"
  }'

Endpoints

Products

GET POST /products

Both methods perform the same listing/search operation. Use GET for simple query-string searches and POST when sending a JSON search body is easier for your client.

Product rows are the first decision point for checkout. Use can_buy to decide whether the full-payment reservation path can be shown, and effective can_deposit to decide whether a deposit reservation path can be shown. If neither action is available, keep the product as an inquiry/contact flow.

Use GET /products/{id} to retrieve one public product visible to the authenticated API consumer.

Use GET /products/{id}/departures to retrieve active future departures and filters for one public product.

Departure rows are meant for the end user's date-selection screen. Present raw dates, duration, remaining seats, lowest displayed price, origin city, hotel stars, luggage, route, and flight inventory hints when present.

Use GET /products/{product_id}/departures/{departure_id} to retrieve the selected departure detail payload, including prepared price rows, included services, and flight details when available.

Use POST /products/{product_id}/departures/{departure_id}/price-preview to preview the selected total and optionally apply a public coupon code before creating a contact or reservation.

Use POST /products/{product_id}/departures/{departure_id}/contacts to create a lead for a selected price and room selection. Leads are persisted with channel set to PUBLIC_API. Assignment follows the same assign rule as /contacts: with an AI agent configured the lead is owned by the agent and not rotated unless you send assign: "rotation"; without one it rotates as before.

Use POST /products/{product_id}/departures/{departure_id}/reservations to create an operational reservation for a selected price, room selection, customer, and passenger list. Reservations are persisted with channel and origin set to PUBLIC_API.

Users

GET /users

The roster to build your own users from, so there is a single list of people and it never drifts: when a seller is added on our side they appear in your app without anyone doing anything. Match on email, the corporate address they log in with, and keep id_user — that is what you send back on any call made on behalf of that person.

Who is on the list: sellers and supervisors always, by their role; administrators only when they have been marked as users of the app, because not all of them are. Every other role we have — marketing, product, operations, extranet — is never exposed, and neither is the AI agent, which is not a person.

The three profiles mean different things in your app. A SELLER handles their own conversations. A SUPERVISOR also oversees the conversations of customers of their own office — that is what office is for, and you need it to scope what they are allowed to see. An ADMIN works across the board.

Deactivated people stay on the list with active: false, and must lose access. They are not removed on purpose: that way a deactivation is unambiguous, instead of a person quietly disappearing from the list. Re-read the roster often enough that a deactivation reaches you the same day.

{
  "success": 1,
  "data": {
    "total": 2,
    "results": [
      {
        "id_user": 118,
        "firstname": "Carla",
        "lastname": "Gomez",
        "email": "carla.gomez@deturista.com",
        "profile": "SELLER",
        "id_group": 5,
        "area": "Multidestino",
        "id_office": 1,
        "office": "Casa Central",
        "active": true
      },
      {
        "id_user": 92,
        "firstname": "Diego",
        "lastname": "Ferrari",
        "email": "diego.ferrari@deturista.com",
        "profile": "SUPERVISOR",
        "id_group": 6,
        "area": "Caribe + Sudamérica",
        "id_office": 1,
        "office": "Casa Central",
        "active": true
      }
    ]
  }
}

area is for display; some are combined areas such as Multidestino or Caribe + Europa. id_group is there if you ever need a stable key rather than a label.

GET /sellers/availability

Per sales area, how many sellers can take a contact right now — they rotate in that area, they are active, not paused, and it is a working day and hour for them — and how many of those still have room in their daily quota. This is what a supervisor needs before assigning by hand: see the quota before choosing, instead of after the assignment bounces. It comes from the same source as our own dashboard, so the two can never disagree.

with_quota: false does not mean the seller cannot be assigned automatically. The daily quota spreads the load; it does not block while the area has enough coverage. automatic_assignment is the area-level switch: when it is false, ordinary contacts enter without a seller until the rotating roster reaches the configured minimum.

day tells you which day the numbers are for. During the evening window the rotation already looks at the next working day, so the counts are about that day and not about this instant; null means today. Seller names are not repeated here — resolve them from /users.

{
  "success": 1,
  "data": {
    "day": "monday",
    "areas": [
      {
        "id_group": 5,
        "area": "Multidestino",
        "available": 3,
        "with_quota": 2,
        "automatic_assignment": false,
        "sellers": [
          { "id_user": 118, "with_quota": true },
          { "id_user": 92, "with_quota": true },
          { "id_user": 140, "with_quota": false }
        ]
      }
    ]
  }
}

Hotels

GET /hotels/{id}

Everything we have loaded about a hotel or a circuit: description, address, its own website, chain, destination and the full photo gallery. Use it to talk about the hotel without pulling a whole departure — the ids come from the hotels and circuits lists in the departure detail. Deleted hotels, and hotels still pending approval, return 404 not_found.

The same fields are now included inline in the departure detail, so a single call already gives you what you need to describe every hotel of a package. Galleries everywhere in the API — hotels, circuits and products — are a list of photos, each one with its absolute url and the caption written when it was loaded, and the single image field is an absolute URL too. Use them as they come.

{
  "success": 1,
  "data": {
    "id": 812,
    "name": "Hotel Playa Azul",
    "stars": 5,
    "description": "Frente al mar, con pileta y kids club.",
    "address": "Av. del Mar 1200",
    "url": "https://hotelplayaazul.example.com",
    "tag": "PLAYA",
    "is_circuit": false,
    "destination": "Punta Cana",
    "chain": "Caribe",
    "images": [
      {
        "url": "https://www.deturista.com/entity/deturista/images/Hotel/812/original/playa.jpg",
        "description": "Vista a la playa"
      },
      {
        "url": "https://www.deturista.com/entity/deturista/images/Hotel/812/original/lobby.jpg",
        "description": null
      }
    ]
  }
}

Contacts

POST /contacts

Creates a lead that is not tied to a product or a departure — the destination enquiry a conversational agent creates once it has the customer's details. Use it when there is no package selected yet; when there is one, use /products/{product_id}/departures/{departure_id}/contacts instead.

How the contact is assigned follows the optional assign field, and the rule is the same for every contact created through the API, with or without a package. By default, a consumer with an AI agent user configured gets the contact owned by that agent and with no seller assigned: seller rotation does not run and no seller's daily quota is consumed. Assigning a seller is a separate, later call. A consumer without an AI agent gets the contact through seller rotation, as the website does.

Send assign: "rotation" to hand the lead to a person right away — the customer asked for a human from the first message. The contact then goes through seller rotation at creation and its conversation_owner is SELLER; route the conversation to the returned id_seller. If rotation finds nobody available (night time, everyone at their daily limit) the contact falls back to the AI agent instead of failing, so no lead is lost: check id_seller and conversation_owner in the response rather than assuming.

id_conversation is the idempotency key. Sending the same one twice does not create a second contact: the first call answers 201 and every retry answers 200 with the contact that already exists. Retry safely.

GET /contacts/{id}

Returns the contact as the conversation needs it: assigned seller (id_seller and seller_name, the name the admin shows), workflow status, the conversation fields, a customer object and a trip object. In customer, phone_international is the whole number in E.164 and phone the number as stored, without its country calling code. It is the same receipt every contact endpoint returns. Contacts owned by another consumer, outside the authenticated entity or site, or created outside the public API return 404 not_found.

POST /contacts/{id}/assign

Decides who handles a contact, in four modes.

id_actor is the id_user of the person making the change, from /users. We validate what that person is allowed to do, so your app does not have to: a seller can only take a contact for themselves and against their own quota; a supervisor can assign and reassign only within their office; and an administrator can operate across offices. For reassign, the current seller and destination seller must both be in the supervisor's scope. Ask, and we answer with the result or the reason.

Send an optional reason so hand-offs can be measured later.

If nobody is available — night time, outside working hours, everyone paused — the call still succeeds with assigned: false, the contact keeps the AI agent and conversation_owner stays AI. The conversation is yours to continue: no lead is lost. Check assigned rather than assuming. Before rotating, DeTurista looks for the last RESERVED contact of that phone in the last two years: if it belongs to a seller who is rotating today in the area of this contact, the contact goes back to that seller and the response carries frequent_customer: true, so your agent can tell the customer they are going back to the person who already helped them.

A contact that already has a seller returns 400. Moving a contact from one seller to another is a supervisor decision and does not go through here.

curl -sS 'https://api.deturista.com/v1/contacts/554401/assign' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"reason":"asked_human"}'

POST /contacts/{id}/handover

Changes who is talking to the customer right now, without changing who owns the contact. Once a contact belongs to a seller it stays with them: the live conversation can go back and forth as often as needed — the seller hands it to your agent to collect a balance or send documents, your agent hands it back when a person is needed — and the assigned seller does not change.

Moving a contact between sellers is a different thing: that is mode: "reassign" on the assign endpoint, and only a supervisor or administrator can do it. A hand-over does not go through rotation and does not consume any quota — the seller already paid that cost when the contact reached them.

Send to: "ai" with the id_actor of the person letting go. That actor must be the assigned seller, a supervisor from the seller's office, or an administrator. Send to: "seller" to hand it back, which your agent can do on its own without an actor.

GET /contacts

Find contacts you created. This is the answer to the question your agent asks whenever someone writes again: does this person already have an open contact? The idempotency of contact creation does not cover it — that recovers one conversation by its id, not a person by phone or email.

Search by phone, email, id_conversation or status; at least one is required. Send phone whole, with its country calling code (the leading + is optional): it is split like on creation and compared with the stored calling code and number. Add open=1 to get only the contacts that can still be worked: every status except ANSWER, UNANSWERED, RESERVED and SPAM (it cannot be combined with status). Before answering someone who writes or calls without a contact already linked to that conversation, search by phone with open=1: if there is a result, continue with the first one instead of creating another contact. Paged with limit (up to 50) and page. Web contacts born for your AI agent are visible here too, including one whose lead notice never reached you: its id_conversation is null and you can link it with PATCH /contacts/{id}.

PATCH /contacts/{id}

Updates the existing contact as the conversation progresses. Send only the fields to change; at least one is required. Customer details, message, qualification (ai_score), conversation_url and workflow status remain editable. The response is the full contact receipt after the change.

It reaches the contacts your consumer owns, including web contacts assigned to it, and the active contact of the person, whatever its channel (the one GET /contacts?open=1 returns). Any other contact returns 403. Setting id_conversation on a contact of another channel makes it yours: its notices reach you from then on.

A status change follows the same path as the admin: it is written to the contact history with your AI agent user as the author, and it feeds the sales statistics like any seller's change. It does not send reminder emails to the customer nor create seller alerts — the conversation is yours. Three rules: RESERVED cannot be set here, it is set by the reservation; SPAM unassigns the contact; and an archived contact (ANSWER, UNANSWERED or RESERVED) cannot be reopened: moving it to any other status than those three or SPAM returns 400 invalid_request without saving changes. When the person comes back, create a new contact with POST /contacts.

The request does not change here: destination, dates, passengers and package. Send what the customer asks for later to POST /contacts/{id}/interests, and the contact will show it; correct the latest request with PATCH /contacts/{id}/interests/{id_interest}. message stays the conversation summary. The reservation carries the final choice, whatever product it is for, and is linked to this same contact through id_contact.

For compatibility with CRM follow-ups, resent id_destination, start_date, end_date and pax_count are ignored without blocking the other updates. Normal field-format validation still applies. id_product, id_departure, id_price, rooms, coupon_code and query are not accepted: they return 400 invalid_request without saving changes. A package goes to POST /contacts/{id}/interests.

A typical follow-up sends only editable fields, for example {"status":"QUOTE","ai_score":60,"message":"Quote sent; the customer will confirm on Friday."}. The receipt returns the contact's trip unchanged.

POST /contacts/{id}/interests

When the customer asks for something else (another destination, another package, another departure), add it to the same contact as an interest instead of opening another contact. The DeTurista staff sees it as a subconsulta in the contact. Say with type what it is: return when the person came in again (wrote again in a new conversation, from an ad, through another channel) and change when they changed their mind in the same conversation; without it, change. Marketing counts the returns as new leads.

Each call adds one interest, and the contact shows the latest one: its area, destination or package, departure, price, rooms, passengers, dates and coupon become the interest's, and a destination interest leaves it without the package of the previous one. Its seller, status, message, channel and UTM fields do not change, and what the contact came in with stays first in interests as type: original. To correct the latest request without adding another one (another departure, price, rooms or coupon of the same package; other dates or passengers of the same destination), use PATCH /contacts/{id}/interests/{id_interest}. Keep using PATCH /contacts/{id} with message for the conversation summary.

Send either id_destination, or a whole package: id_product, id_departure, id_price and rooms, validated like /products/{product_id}/departures/{departure_id}/contacts (a public product, a selectable departure, an available price of that departure, rooms that price offers). Half a package returns 400 naming the missing field, and both a destination and a package return 400. A destination interest takes the start_date, end_date and pax_count the customer gave, validated like on POST /contacts; without them the contact is left without dates or passengers, because it shows the latest interest. A package interest stores the departure dates, passengers and price of that selection the same way a package contact does, with coupon_code applied and validated like on creation.

It requires the contacts:update scope and reaches the same contacts as PATCH /contacts/{id}: yours and the active contact of the person; any other returns 403. It answers 201 with the contact receipt, whose interests list ends with the new one. If anything fails, nothing is saved.

curl -sS 'https://api.deturista.com/v1/contacts/554401/interests' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"channel":"whatsapp","id_product":1234,"id_departure":5678,"id_price":4567,"rooms":{"double":1},"message":"Le interesa esta salida, sólo ellos dos"}'

Every contact receipt, GET /contacts/{id} included, carries interests: every request of the contact, oldest first. The first one is what the contact came in with (type: original, source: null, message: null); the last one is the request the contact shows: trip and the package fields of the receipt are that one, and it is the only one the PATCH below corrects. A destination interest has id_destination, destination and the dates and passengers sent with it, if any; a package interest has id_product, id_departure, id_price, rooms, the departure dates, passengers and list price.

"interests": [
  {
    "id_interest": 11,
    "creation_date": "2026-11-01 09:30:00",
    "source": null,
    "type": "original",
    "origin": "WHATSAPP",
    "id_destination": 42, "destination": "Punta Cana",
    "id_product": null, "id_departure": null, "id_price": null,
    "rooms": null,
    "start_date": null, "end_date": null, "pax_count": null,
    "currency": null, "amount": null, "usd_cash": null,
    "coupon_code": null,
    "message": null
  },
  {
    "id_interest": 12,
    "creation_date": "2026-11-03 14:05:00",
    "source": "AI",
    "type": "change",
    "origin": "WHATSAPP",
    "id_destination": null, "destination": null,
    "id_product": 1234, "id_departure": 5678, "id_price": 4567,
    "rooms": { "double": 1 },
    "start_date": "2027-07-12", "end_date": "2027-07-19",
    "pax_count": 2,
    "currency": "ARS", "amount": 2345600, "usd_cash": 1980,
    "coupon_code": null,
    "message": "Le interesa esta salida, sólo ellos dos"
  }
]

PATCH /contacts/{id}/interests/{id_interest}

Corrects the request the contact shows, the last one of its interests, without adding another one: when the customer keeps the same package but changes the departure, the price, the rooms or the coupon, or keeps the same destination but changes the dates or the passengers. id_interest is the one the receipt lists in interests. It requires the contacts:update scope.

Send only what changes; what is not sent stays as it was. The result is validated whole, like POST /contacts/{id}/interests: for a package, a public product, a selectable departure of it, an available price of that departure and rooms that price offers. When id_departure changes, send its id_price too. Without rooms the request keeps its own. The package request is calculated again like on creation (departure dates, passengers, price) and the contact shows it.

Coupon: coupon_code adds or changes it. Without coupon_code the request keeps its coupon, validated again with the new selection; when it no longer applies the answer is 400 coupon code is not available for this product. An empty coupon_code ("" or null) removes the coupon, which also unblocks a request whose coupon stopped applying.

curl -sS 'https://api.deturista.com/v1/contacts/554401/interests/12' \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"id_departure":5701,"id_price":4602}'

To change the rooms and remove the coupon of the same request, send {"rooms":{"double":1,"single":1},"coupon_code":""}.

The contact workflow statuses

The status is the sales funnel a seller works in the admin, so it answers "how far did this conversation get". The middle column is the label the seller reads on screen, in Spanish, exactly as it appears there. A status your agent sets looks the same to the seller as one a colleague set.

Reservations

GET /reservations/{id}

Where the reservation stands money-wise, for the moment the customer says "I already paid" or before you re-send a payment link:

Alongside it come total, paid and owed, as the usual ARS/USD pairs. This is a snapshot: it tells you how things stand right now, which is what you need mid-conversation. Knowing when a payment lands is what the notification is for.

Reservation receipt lookup returns persisted receipt fields for reservations created by the authenticated API consumer. Reservations owned by another consumer, outside the authenticated entity or site, or created outside the public API return 404 not_found. The read-back receipt does not include id_price or payment_option; those fields are returned only by the creation response.

Destinations

GET /destinations

Destinations return the active destination tree visible to the authenticated API consumer. Use GET /destinations/{id} to retrieve one destination. Its data.videos contains the destination’s own active videos, or the country’s active videos when the destination has none. These lists are never merged. Country detail returns its own active country videos; if no applicable videos are active, the array is []. See video fields and selection guidance.

Categories

GET /categories

Categories return the website-visible category tree for the authenticated API consumer. Use GET /categories/{id} to retrieve one category.

Product groups

GET /product-groups

Product groups return destination or category group totals with drill-down URLs for /products. Set include_top_ranked=1 to include compact previews from real public products.

Home

GET /home

Home returns one section of the home for the authenticated consumer's site. type is required and selects the section: slider, list and popup return the ordered blocks of that type; banners returns the banners strip (up to two). There is no combined response — call once per section. Each block references a product, category, or destination; product resources and LIST products are compact home cards (not the full product row — load /products/{id} for full detail). At most one popup block is returned (the first by order), matching the single popup shown on the home page.

Site

GET /site

Site returns public site and footer metadata for the authenticated consumer's site: contact fields, social links, legal text, and the public office list. Analytics, pixel, and verification keys are not exposed.

Newsletter

POST /newsletter

Newsletter creates an email subscription for the authenticated consumer's site. It reuses the public newsletter validation and duplicate-email guard, so an invalid field or an already-subscribed email returns 400 invalid_request and a new subscription returns 201 with a receipt.

TC trips and hotel shopping

Use this flow when a traveller wants to search hotels and keep a choice for later. You create a trip, add a hotel stay, request live availability from Travel Compositor, then save the chosen room option. The trip keeps that work between requests so you can reopen it without starting the search again.

What is a trip?

A trip is a saved itinerary in DeTurista. It starts as an empty draft and can hold several services, such as a hotel stay in Madrid followed by another stay in Barcelona. Creating it does not create a TC booking, a CRM contact or a reservation. This public workflow adds hotel services and saves selections; it does not book them.

Trip and service IDs identify saved records. Result and option IDs belong to the current quote; a new Quote replaces them. Keep the current revision alongside each saved record so an older request cannot overwrite a newer choice.

TC hotel-shopping quick start

Send your private API key in X-API-Key from your backend. The full flow needs tc-trips:create, tc-trips:hotels:search and tc-trips:hotels:select. These grants are independent; a basic trip-read grant does not include shopping. Paths below are relative to https://api.deturista.com/v1; locally use the existing app's /api/v1 base.

1. 1

   Find a TC destination or hotel code GET /tc-trip/catalog/destinations?q=Madrid

   Use local catalog lookup when you do not already know the TC code. Hotel lookup also accepts an exact destination code:

   curlLocal hotel lookup

   curl -sS 'https://api.deturista.com/v1/tc-trip/catalog/hotels?destination_code=MAD&limit=25' \
     -H 'X-API-Key: YOUR_API_KEY'

   Keep

   The destination code or hotel accommodation_code.

   Next

   Use a destination code to compare hotels, or a hotel code to target a specific property. These are TC codes, not local database IDs. Lookup is local and has no availability or prices. An empty local catalog does not prove TC has no availability.

2. 2

   Create the tripPOST /tc-trip
   JSONRequest body

   { "title": "Madrid hotel stay" }

   HTTP 201 returns the saved trip:

   JSONResponse excerpt

   { "success": 1, "data": { "trip": { "id": 123, "revision": 1, "state": "DRAFT" } } }

   Keep

   Trip ID 123 and its current revision.

   Next

   Add a hotel service to this trip. The API assigns the trip to your consumer. Do not send a seller, consumer or account override. Creation has no idempotency key, so do not automatically repeat it after an uncertain response.

3. 3

   Save the hotel's search detailsPOST /tc-trip/123/services

   Use the trip revision from step 2. This example requests one room for two people:

   JSONRequest body

   {
     "revision": 1,
     "intent": {
       "checkIn": "2027-06-10",
       "checkOut": "2027-06-13",
       "tripType": "ONLY_HOTEL",
       "destinationId": "MAD",
       "distributions": [{ "persons": [{ "age": 35 }, { "age": 8 }] }],
       "filter": { "bestCombinations": true, "maxCombinations": 3 },
       "language": "EN",
       "sourceMarket": "AR"
     }
   }

   HTTP 201 returns a saved hotel service; this step does not contact TC:

   JSONResponse excerpt

   { "success": 1, "data": {
     "trip": { "id": 123, "revision": 2 },
     "service": { "id": 456, "revision": 1, "service_type": "ACCOMMODATION", "state": "DRAFT" }
   } }

   Keep

   Service ID 456, its revision and the latest trip revision.

   Next

   Quote this service. Occupancy requires actual ages grouped by room; adult/child counts are insufficient. Choose exactly one target: intent.destinationId, intent.accommodations, or outer accommodation_id. See the reference for the single-hotel filter shape.

4. 4

   Request live hotel availabilityPOST /tc-trip/123/services/456/quote
   JSONRequest body

   { "revision": 1 }

   The response contains the current service revision and a first page of quoted hotels:

   JSONResponse excerpt

   { "success": 1, "data": {
     "service": { "id": 456, "revision": 4, "state": "QUOTED" },
     "results": [{
       "result_id": "7c4f2e8a1b9d4a50b6350fd87a6e29c3",
       "quote_single_needed": 1,
       "options": [{ "option_id": "4a91dc7f0b2e453a89f6d31c5e8072ab" }]
     }]
   } }

   Keep

   The latest service revision, the chosen hotel's result_id, and available option IDs.

   Next

   Display the returned hotel content, rooms, price.amount, currency and cancellation terms. Price is a decimal-string total for every requested room and the whole stay; do not multiply it by passengers or nights. Every Quote calls TC for current availability and rates. Empty availability is a successful response with no selectable options.

5. 5

   Filter saved results and expand a hotel's options GET /tc-trip/123/services/456?stars=4,5&meals=BED_AND_BREAKFAST&sort=price_asc

   Filtering and pagination read the saved quote without another TC call. Use page and limit for more hotels. If a hotel needs expansion, or you want its current room combinations, use POST /tc-trip/123/services/456/quote-single:

   JSONQuote Single request body

   { "revision": 4, "result_id": "7c4f2e8a1b9d4a50b6350fd87a6e29c3" }

   JSONResponse excerpt

   { "success": 1, "data": {
     "service": { "id": 456, "revision": 5 },
     "results": [{
       "result_id": "7c4f2e8a1b9d4a50b6350fd87a6e29c3",
       "options": [{ "option_id": "b6e02d9a7f1348c0a592ed34fc6817ba" }]
     }]
   } }

   Keep

   The latest service revision and option IDs from expansion.

   Next

   Quote Single calls TC, retains the hotel's result ID, replaces its option IDs and clears any existing selection. Choose from the new options. If expansion is unnecessary, select using the current revision and option IDs from Quote instead.

6. 6

   Save the chosen complete room optionPOST /tc-trip/123/services/456/select

   This example follows step 5's expansion:

   JSONRequest body

   {
     "revision": 5,
     "result_id": "7c4f2e8a1b9d4a50b6350fd87a6e29c3",
     "option_id": "b6e02d9a7f1348c0a592ed34fc6817ba"
   }

   JSONResponse excerpt

   { "success": 1, "data": {
     "service": { "id": 456, "revision": 6, "state": "SELECTED",
       "selection": { "result_id": "7c4f2e8a1b9d4a50b6350fd87a6e29c3",
                      "option_id": "b6e02d9a7f1348c0a592ed34fc6817ba" }
     }
   } }

   Keep

   The saved trip/service IDs, current revisions and selected customer terms.

   Next

   Show the saved choice. Selection saves the exact complete room combination locally; it does not Confirm, Prebook or Book. A selection-only grant returns the selected terms, not a page of other options.

7. 7

   Reopen or edit the stayGET /tc-trip/123/services/456

   Reopening returns the saved intent, descriptions, options, selection and current revisions. It does not contact TC or renew expired offers. Later catalog edits do not replace descriptions in this saved quote. To change dates, rooms or target, send the service revision and full replacement intent to POST /tc-trip/123/services/456, then Quote again. Editing clears earlier results, selection and flow.

   Keep

   The returned current revisions and service.requote_required.

   Next

   Use the trip revision only when adding another service. Use the service revision for edits, Quote, Quote Single and selection. Basic saved trip list/detail use separate read grants and keep a smaller response; hotel shopping details come from this service endpoint.

8. 8

   Re-quote when the choice expires or becomes stalePOST /tc-trip/123/services/456/quote
   JSONRequest body after step 6

   { "revision": 6 }

   A fresh Quote calls TC again, replaces old result/option IDs and clears the prior selection. Ask the traveller to choose again using the new IDs and current terms. Never carry an old choice forward automatically.

   On error

   HTTP 409 conflict with code: STALE_REVISION: reload the service before deciding what to change. HTTP 409 conflict with code: REQUOTE_REQUIRED: reload and explicitly Quote before another expansion or selection. A known provider failure returns 502 provider_error; reload saved state, because a failed fresh Quote cannot restore an old selection.

   Remember

   Descriptions use the matching local database source first, so a stored description prevents a TC datasheet request for that hotel. Quote and Quote Single still call TC for availability, prices and conditions. Saved filtering and reopening reuse that snapshot without provider calls.

See the hotel-shopping API reference for every field, scope and filter, or open the TC operations in Swagger. Offers/PDFs, passenger personal data and booking actions are outside this public workflow.

Saved trip reads

Use GET /tc-trip and GET /tc-trip/{id} to read saved local trips. tc-trips:read shows trips assigned to your consumer. The independent tc-trips:read:any grant also shows other consumers' trips and unassigned trips. Both grants stay within your configured entity and site and expose the same fields. They do not grant contact or reservation access. Existing keys need an explicit TC grant before using these endpoints.

All saved states are readable, including drafts and trips requiring review. These calls do not contact TC, refresh provider data or repair saved state. These basic read grants do not authorize shopping, offers or document downloads. An inaccessible or missing trip returns 404 not_found with message: "trip not found". Missing operation permission returns 403 forbidden before looking up the trip.

List and filters

The list accepts only page, limit and optional exact trip_state. Defaults are page 1 and limit 25. Both must be positive integers; limit above 100 is rejected. States are DRAFT, IN_PROGRESS, PARTIALLY_BOOKED, BOOKED, PARTIALLY_CANCELED, CANCELED and REQUIRES_REVIEW. Unsupported fields, including consumer or site overrides, return 400 invalid_request. Detail accepts no query fields and requires a positive integer ID.

curl -sS 'https://api.deturista.com/v1/tc-trip?trip_state=BOOKED&page=1&limit=25' \
  -H 'X-API-Key: YOUR_API_KEY'

The response is { "success": 1, "data": { "page": 1, "limit": 25, "total": 1, "results": [...] } }. Visibility and state filtering apply before count and pagination. Results sort by saved update time descending, then ID descending for ties. Each result has exactly these summary fields:

{
  "id": 123,
  "revision": 4,
  "title": "Winter trip",
  "state": "BOOKED",
  "creation_date": "2026-10-25 09:00:00",
  "update_date": "2026-10-26 10:30:00",
  "service_counts": { "total": 2, "booked": 2, "canceled": 0 },
  "totals": { "plan": { "USD": "150.75", "EUR": "20" }, "plan_complete": 1 }
}

TC trip money uses decimal strings grouped by currency, unlike catalog integer price fields. Current-plan totals exclude canceled and removed services. Manual selling amounts are whole-line amounts, even when quantity exceeds one. An incomplete price sets numeric plan_complete to 0 while retaining known amounts. An empty plan has plan: {} and completeness 0. Counts include canceled services, exclude removed services and count a service as booked only when its saved state is BOOKED. Dates and times use saved application-local values, with no timezone suffix.

Detail and included services

GET /tc-trip/123 returns { "success": 1, "data": { "trip": { ... } } }. The trip has the same summary fields plus services, ordered by local service ID ascending. Included canceled services remain visible; removed services are omitted.

Optional unrecorded values are JSON null. Responses exclude passenger and customer personal data, internal notes, supplier costs, raw provider payloads, protected tokens, audit diagnostics, document locations and staff actions. The broader read grant changes which trips you can see, not which fields you receive.

Hotel-shopping API reference

Each operation below shows its full path. Replace {id} with the saved trip ID and {service_id} with the saved hotel service ID. Neither is a TC hotel code. Production paths start at https://api.deturista.com/v1; local paths start at http://localhost:8181/api/v1.

Send X-API-Key on every request and Content-Type: application/json with JSON bodies. Use IDs and revisions from your responses. The examples below use illustrative values. Your key needs the scope listed for each operation, and shopping is limited to trips assigned to your consumer.

curl -sS 'https://api.deturista.com/v1/tc-trip/catalog/destinations?q=Madrid&page=1&limit=25' \
  -H 'X-API-Key: YOUR_API_KEY'

curl -sS 'https://api.deturista.com/v1/tc-trip/catalog/hotels?destination_code=MAD&limit=25' \
  -H 'X-API-Key: YOUR_API_KEY'

{ "title": "Madrid hotel stay" }

{
  "revision": 1,
  "intent": {
    "checkIn": "2027-06-10",
    "checkOut": "2027-06-13",
    "tripType": "ONLY_HOTEL",
    "destinationId": "MAD",
    "distributions": [{ "persons": [{ "age": 35 }, { "age": 8 }] }],
    "filter": { "bestCombinations": true, "maxCombinations": 3 },
    "language": "EN",
    "sourceMarket": "AR"
  }
}

Hotel search fields

Use this body format when adding a hotel stay or replacing its search. Unknown fields are rejected.

Choose exactly one of these targets:

Do not send a currency selector. The quote response provides the actual selling currency and price.

{ "revision": 1 }

curl -sS 'https://api.deturista.com/v1/tc-trip/123/services/456?meals=BED_AND_BREAKFAST&sort=price_asc&limit=25' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "revision": 4,
  "result_id": "7c4f2e8a1b9d4a50b6350fd87a6e29c3"
}

{
  "revision": 5,
  "result_id": "7c4f2e8a1b9d4a50b6350fd87a6e29c3",
  "option_id": "b6e02d9a7f1348c0a592ed34fc6817ba"
}

Descriptions, prices and saved results

Catalog lookup and hotel descriptions use saved local data. When a matching local description exists, TC is not called for that hotel's datasheet, even if the content is old, another field is missing or the requested language differs. description_language reports the stored language. Only description misses may use datasheet fallback. Quote and Quote Single still call TC for current availability, prices and conditions. Once quoted, filtering and reopening use the saved description snapshot, even after the catalog changes.

The local destination list is derived from saved hotels, not a complete TC destination directory. Missing local metadata does not prevent a live quote with a known valid TC code.

Errors and what to do next

Errors use { "success": 0, "error": "...", "message": "..." }. Conflicts also include code. Server configuration or unexpected internal failures remain server errors.

Parameters

Product listing parameters

GET accepts these as query parameters. POST accepts the same keys in a JSON object.

Product currency is the package base currency used by its prices, not a display conversion hint.

Product departure parameters

Product departure filters describe every active departure of the product, whatever month was requested. total counts the departures that match month and year, and results is one page of them.

Product departure detail uses product_id and departure_id from the path. data.currency uses the product package base currency. The selected departure must belong to the product and must be active, future-visible, web-visible, and priced like rows returned by the departure listing endpoint.

Product departure price preview uses product_id and departure_id from the path and requires this JSON body:

The preview response always includes total_ars / total_usd, new_total_ars / new_total_usd, pax_count, num_of_payments, deposit_ars / deposit_usd, card_installments, card_installment_amount, ars_installments, deposit_usd_installments, payment_methods, applied, and default_code. The totals and the installment are for every passenger of the selected rooms; num_of_payments and deposit_* are null when the package has no payment plan, and card_installments and card_installment_amount are null unless the package is priced in ARS with card installments. ars_installments is null unless the package has 12 cuotas en pesos, and deposit_usd_installments unless payment_methods has DEPOSIT_USD_INSTALLMENTS. payment_methods lists the ways to pay this selection with its amounts, and is empty outside site 1. The suggested default_code is only returned when no coupon was applied in the request; when a coupon is applied it is null and the response also includes code, original_total_*, amount_discount_*, discount_type, and configured_value.

Product departure contacts use product_id and departure_id from the path and require this JSON body:

Ownership is always taken from the authenticated API key. A request body field named consumer is ignored.

Room selection pax counts

The rooms object always counts rooms. The API expands those rooms into passenger slots for reservations.

kids_age is an exclusive child-age limit evaluated at the end of the trip: when it is 12, a child slot requires a passenger who is still under 12 on that date. Infants under 2 also use a child room slot. The price preview is the fixed total for the selected room occupancy and is not recalculated from passenger birth dates. Infant airline handling or charges are finalized by the sales team and are not added by price-preview.

Product departure reservations use the same path ids and require a structured reservation body:

Ownership is always taken from the authenticated API key. A request body field named consumer is ignored. Passenger count must match the pax count implied by rooms.

Destination listing parameters

The destination detail endpoint uses the destination id from the path and has no query parameters.

Category listing parameters

The category detail endpoint uses the category id from the path and has no query parameters.

Product group parameters

Responses

Successful listing responses include success: 1 and a data object with total and results. Catalog detail responses include the resource object directly under data. Saved TC trip detail uses data.trip, as shown in Saved TC trips.

{
  "success": 1,
  "data": {
    "total": 69,
    "results": [
      {
        "id": 2158,
        "title": "Mundial de Futbol 2026 - 16avos de Final",
        "subtitle": "03 noches de alojamiento...",
        "summary": "03 noches de alojamiento...",
        "url": "2158/mundial_de_futbol_2026.html",
        "image": "img_web-03.jpg",
        "discount": 20,
        "transport": "Aereo",
        "meal_plan": "Desayuno",
        "currency": "ARS",
        "price_from_ars": 5835,
        "price_from_usd": 990,
        "deposit_from_ars": 1200,
        "deposit_from_usd": 190,
        "num_of_payments": 5,
        "card_installments": null,
        "card_installment_amount": null,
        "ars_installments": null,
        "nights": [3, 4],
        "has_hotel": false,
        "can_deposit": true,
        "can_buy": false,
        "destinations": [
          { "id": 410, "name": "Miami" }
        ],
        "categories": [
          { "id": 154, "name": "Mundial" }
        ]
      }
    ]
  }
}

Product detail responses return the product object directly under data and replace the listing image field with the ordered images gallery plus the base package description and public payment summaries. A departure can carry a different description. After a departure is selected, treat the departure detail description as authoritative: it replaces the base package description completely and the two values must not be merged.

{
  "success": 1,
  "data": {
    "id": 2158,
    "title": "Mundial de Futbol 2026 - 16avos de Final",
    "subtitle": "03 noches de alojamiento...",
    "summary": "03 noches de alojamiento...",
    "description": "Día 1: llegada a Miami.\r\nDía 2: excursión incluida...",
    "url": "2158/mundial_de_futbol_2026.html",
    "discount": 20,
    "transport": "Aereo",
    "meal_plan": "Desayuno",
    "currency": "ARS",
    "price_from_ars": 5835,
    "price_from_usd": 990,
    "deposit_from_ars": 1200,
    "deposit_from_usd": 190,
    "num_of_payments": 5,
    "card_installments": null,
    "card_installment_amount": null,
    "ars_installments": null,
    "nights": [3],
    "has_hotel": false,
    "can_deposit": true,
    "can_buy": false,
    "destinations": [
      { "id": 410, "name": "Miami" }
    ],
    "categories": [
      { "id": 154, "name": "Mundial" }
    ],
    "images": [
      {
        "name": "img_web-03.jpg"
      }
    ],
    "payment_options": {
      "deposit": [
        {
          "name": "Tarjeta Visa",
          "title": "Reserva con tarjeta",
          "description": "Pago de seña en cuotas disponibles.",
          "payment_selection": "TRANSFER"
        },
        {
          "name": "MercadoPago",
          "title": "Pagá con Mercado Pago",
          "description": "Checkout Pro para pagar online.",
          "payment_selection": "MERCADOPAGO"
        }
      ]
    }
  }
}

When the authenticated API consumer is scoped to a USD display site, the same money fields use only the USD suffix.

{
  "success": 1,
  "data": {
    "id": 3150,
    "title": "Caribe 2026",
    "description": "Día 1: llegada a Punta Cana...",
    "url": "3150/caribe_2026.html",
    "discount": null,
    "transport": "Aereo",
    "meal_plan": "All inclusive",
    "currency": "USD",
    "price_from_ars": null,
    "price_from_usd": 990,
    "deposit_from_ars": null,
    "deposit_from_usd": null,
    "num_of_payments": null,
    "card_installments": null,
    "card_installment_amount": null,
    "ars_installments": null,
    "nights": [7],
    "can_deposit": false,
    "can_buy": true,
    "destinations": [
      { "id": 410, "name": "Miami" }
    ],
    "categories": [
      { "id": 154, "name": "Caribe" }
    ],
    "images": [],
    "payment_options": {
      "buy": []
    }
  }
}

Product departure responses include active future departures for one product. The root product_description carries the base package itinerary once. Each row's description_override is either a complete replacement for that departure or null when the row inherits the base description, so clients can compare activities without loading every departure detail. The root currency is the package base currency for the product. The filters object is calculated from every active departure of the product, even when results is paginated or narrowed with month and year; total counts the departures of the requested month. filters.months lists departure start months; each row omits month summaries because start_date and end_date carry the date range. Inventory fields distinguish confirmed flight seats from regular flight departures and no-flight departures.

{
  "success": 1,
  "data": {
    "product_id": 2158,
    "product_description": "Day 1: city tour. Day 2: free day.",
    "currency": "USD",
    "total": 24,
    "filters": {
      "price": { "min": 5835, "max": 8720 },
      "stars": [5, 4],
      "months": ["2026-06", "2026-07"],
      "itinerary_days": [5, 8],
      "luggage": ["Carry on"],
      "route": ["DIRECT"]
    },
    "results": [
      {
        "id": 9876,
        "start_date": "2026-06-12",
        "end_date": "2026-06-16",
        "nights": 4,
        "itinerary_days": 5,
        "assistance_days": 5,
        "last_seats": 6,
        "available_prices_count": 1,
        "inventory_type": "allotment",
        "available_seats": 6,
        "price_from_ars": null,
        "price_from_usd": 5835,
        "deposit_from_ars": null,
        "deposit_from_usd": null,
        "num_of_payments": null,
        "final_payment_days_before": null,
        "card_installments": null,
        "card_installment_amount": null,
        "ars_installments": null,
        "city_from": "Buenos Aires",
        "is_hook": false,
        "hotel_stars": [5, 4],
        "luggage": ["Carry on"],
        "route": "DIRECT",
        "flexible": false,
        "description_override": "Day 1: city tour. Day 2: full-day excursion."
      }
    ]
  }
}

Product departure detail responses include the selected departure price payload. The root currency is the package base currency for the product. description is authoritative for the selected departure: a departure-specific description replaces the base package description completely; only when the departure has no description does this field fall back to the product description. Never merge both descriptions. Deposit values are exposed on each selectable prices[].amounts[] row, not at the detail root. Use flight for flight details; it is null when the departure has no flight.

{
  "success": 1,
  "data": {
    "product_id": 2158,
    "currency": "USD",
    "description": "<p>Departure details...</p>",
    "prices": [
      {
        "id": 4321,
        "amounts": [
          {
            "price_ars": null,
            "name": "amount_double",
            "price_usd": 990,
            "deposit_ars": null,
            "deposit_usd": 190,
            "num_of_payments": 5,
            "card_installments": null,
            "card_installment_amount": null,
            "ars_installments": null,
            "deposit_usd_installments": null,
            "max_pax": 12,
            "room_type": "DOUBLE",
            "has_kids": false
          }
        ],
        "payment_methods": [
          {
            "code": "TRANSFER",
            "title": "Transferencia o Depósito",
            "detail": "Podés abonarlo con transferencia o depósito bancario en pesos o dólares, a las cuentas disponibles de Deturista.\n\nEn el caso del pago en pesos, debe abonarse al tipo de cambio MEP del día de pago.",
            "handled_by": "agent"
          },
          {
            "code": "USD_INSTALLMENTS",
            "title": "Cuotas en dólares",
            "detail": "Abonalo en hasta 5 cuotas fijas de USD 190 por persona. La primera cuota corresponde a la seña y podés abonarla en dólares o en pesos a través de las plataformas de cobro disponibles.\n\nEl total deberá quedar abonado 30 días antes de la salida.",
            "handled_by": "agent"
          },
          {
            "code": "CASH",
            "title": "Pago Efectivo",
            "detail": "Podrás abonarlo en efectivo en cualquiera de nuestras sucursales.",
            "handled_by": "agent"
          }
        ],
        "hotels": [
          {
            "id": 10,
            "name": "Hotel Plaza",
            "stars": 4,
            "destination": "Madrid",
            "image": "hotel.jpg",
            "nights": 3,
            "check_in_date": "2026-06-13",
            "check_out_date": "2026-06-16",
            "meal_plan": {
              "code": "BREAKFAST",
              "label": "Con Desayuno"
            }
          }
        ],
        "circuits": [
          {
            "id": 20,
            "name": "Circuito Andalucia",
            "nights": 4,
            "start_date": "2026-06-16",
            "end_date": "2026-06-20",
            "meal_plan": null
          }
        ],
        "transfers": [
          {
            "id": 30,
            "name": "Traslado aeropuerto-hotel"
          }
        ],
        "count": 1,
        "price_from_ars": null,
        "price_from_usd": 990,
        "price_from_type": "DOUBLE"
      }
    ],
    "has_amounts": true,
    "price_from_type": "DOUBLE",
    "discount": null,
    "kids_age": 12,
    "start_date": "2026-06-12",
    "end_date": "2026-06-20",
    "nights": 7,
    "itinerary_days": 8,
    "assistance_days": 9,
    "final_payment_days_before": 30,
    "payment_methods": [
      {
        "code": "TRANSFER",
        "title": "Transferencia o Depósito",
        "detail": "Podés abonarlo con transferencia o depósito bancario en pesos o dólares, a las cuentas disponibles de Deturista.\n\nEn el caso del pago en pesos, debe abonarse al tipo de cambio MEP del día de pago.",
        "handled_by": "agent"
      },
      {
        "code": "USD_INSTALLMENTS",
        "title": "Cuotas en dólares",
        "detail": "Abonalo en hasta 5 cuotas fijas en dólares. La primera cuota corresponde a la seña y podés abonarla en dólares o en pesos a través de las plataformas de cobro disponibles.\n\nEl total deberá quedar abonado 30 días antes de la salida.",
        "handled_by": "agent"
      },
      {
        "code": "CASH",
        "title": "Pago Efectivo",
        "detail": "Podrás abonarlo en efectivo en cualquiera de nuestras sucursales.",
        "handled_by": "agent"
      }
    ],
    "flight": {
      "inventory_type": "ALLOTMENT",
      "available_seats": 6,
      "last_seats": 6,
      "route": "DIRECT",
      "luggage": ["CARRY_ON", "CHECKED"],
      "departure_date": "2026-06-12",
      "arrival_date": "2026-06-20",
      "flight_legs": [
        {
          "leg_type": "OUTBOUND",
          "airport_from": "EZE",
          "city_from": "Buenos Aires",
          "airport_to": "MIA",
          "city_to": "Miami",
          "airline_name": "Aerolinea",
          "flight_number": "AR1302",
          "departure_date": "2026-06-12 22:00:00",
          "arrival_date": "2026-06-13 06:00:00"
        }
      ]
    },
    "id_departure": 9876
  }
}

Product departure contact responses return the same contact receipt as /contacts. The persisted contact uses the submitted product, departure, price, and room selection, with channel set to PUBLIC_API. The id_seller field is the assigned seller id, or null when the lead is not assigned.

{
  "success": 1,
  "data": {
    "id_contact": 654321,
    "id_seller": 103,
    "creation_date": "2026-06-03 18:59:05",
    "status": "PENDING",
    "channel": "PUBLIC_API",
    "id_product": 2158,
    "id_departure": 9876,
    "id_price": 4321
  }
}

Product departure reservation responses return a reservation receipt. The persisted reservation uses authenticated API ownership, with channel and origin set to PUBLIC_API. Transfer reservations are created in the regular reservation flow. MercadoPago reservations are created as PENDING_PAYMENT and include a Checkout Pro redirect under payment.url.

{
  "success": 1,
  "data": {
    "id_reservation": 765432,
    "creation_date": "2026-06-03 19:11:02",
    "status": "IN_PROCESS",
    "channel": "PUBLIC_API",
    "origin": "PUBLIC_API",
    "id_product": 2158,
    "id_departure": 9876,
    "id_price": 4321,
    "payment_option": "buy",
    "payment_selection": "TRANSFER",
    "price_usd": 200,
    "deposit_usd": null,
    "currency_to": "USD"
  }
}

{
  "success": 1,
  "data": {
    "id_reservation": 765433,
    "creation_date": "2026-06-03 19:14:10",
    "status": "PENDING_PAYMENT",
    "channel": "PUBLIC_API",
    "origin": "PUBLIC_API",
    "id_product": 2158,
    "id_departure": 9876,
    "id_price": 4321,
    "payment_option": "deposit",
    "payment_selection": "MERCADOPAGO",
    "price_usd": 200,
    "deposit_usd": 50,
    "currency_to": "USD",
    "payment": {
      "type": "redirect",
      "provider": "MERCADOPAGO",
      "url": "https://www.mercadopago.com.ar/checkout/v1/redirect?pref_id=123"
    }
  }
}

With Getnet charging reservations, payment_selection and payment.provider are GETNET and payment.url is the Getnet checkout.

Contact receipt lookup returns the same data fields for contacts owned by the authenticated API consumer. The status field is the current contact workflow status and can change after creation.

{
  "success": 1,
  "data": {
    "id_contact": 654321,
    "id_seller": 103,
    "creation_date": "2026-06-03 18:59:05",
    "status": "FOLLOW",
    "channel": "PUBLIC_API",
    "id_product": 2158,
    "id_departure": 9876,
    "id_price": 4321
  }
}

Reservation receipt lookup returns the persisted reservation receipt for reservations owned by the authenticated API consumer. The status field is the current reservation workflow status and can change after creation.

{
  "success": 1,
  "data": {
    "id_reservation": 765432,
    "creation_date": "2026-06-03 19:11:02",
    "status": "DEBT",
    "channel": "PUBLIC_API",
    "origin": "PUBLIC_API",
    "id_product": 2158,
    "id_departure": 9876,
    "payment_selection": "TRANSFER",
    "price_usd": 200,
    "deposit_usd": null,
    "currency_to": "USD"
  }
}

Destination listing responses include active destinations, their parent summary, and direct child summaries. Destination detail responses use the same fields, but data is the destination object directly.

{
  "success": 1,
  "data": {
    "total": 3,
    "results": [
      {
        "id": 410,
        "name": "Miami",
        "description": "Miami",
        "parent_id": 23,
        "url": "america-10/estados_unidos-23/miami-410",
        "image": "miami.jpg",
        "active": true,
        "parent": { "id": 23, "name": "Estados Unidos" },
        "children": []
      }
    ]
  }
}

Category listing responses include website-visible categories, their parent summary, and direct child summaries. The active field describes menu visibility state; disabled categories and categories under disabled parents are not returned. Category detail responses use the same fields, but data is the category object directly.

{
  "success": 1,
  "data": {
    "total": 3,
    "results": [
      {
        "id": 154,
        "name": "Mundial",
        "parent_id": null,
        "url": "mundial-154",
        "image": "mundial.jpg",
        "active": true,
        "parent": null,
        "children": [
          { "id": 155, "name": "Final" }
        ]
      }
    ]
  }
}

Product group responses include the selected dimension, grouping level, product totals, drill-down URLs, and optional compact top-ranked products. In each top-ranked product, currency is the package base currency.

{
  "success": 1,
  "data": {
    "by": "destination",
    "group": "continent",
    "groups": [
      {
        "id": 10,
        "name": "Europe",
        "parent_id": null,
        "url": "europe-10",
        "total": 42,
        "products_url": "/api/v1/products?id_destination=10",
        "top_ranked": [
          {
            "id": 1001,
            "title": "Madrid escapada",
            "url": "1001/madrid_escapada.html",
            "image": "madrid.jpg",
            "price_from_usd": 1200,
            "currency": "USD"
          }
        ]
      }
    ]
  }
}

Home responses return one section. A block section (slider/list/popup) returns blocks; ?type=banners returns banners. Each block carries its display metadata plus a resource; product resources and LIST products are compact home cards using the same money/flag conventions as /products, while category and destination resources are compact tile summaries. The example below shows a type=list response.

{
  "success": 1,
  "data": {
    "blocks": [
      {
        "id": 1356,
        "type": "list",
        "order": 1,
        "link": true,
        "show_text": true,
        "image_name": null,
        "resource_type": "category",
        "resource": {
          "id": 126,
          "name": "Playas",
          "url": "playas-126",
          "image": "playas.jpg"
        },
        "products": [
          {
            "id": 1684,
            "title": "Paquete a Playas de Rep. Dominicana",
            "url": "1684/paquete_rep_dominicana.html",
            "image": "punta_cana.jpg",
            "discount": 20,
            "transport": "Aéreos",
            "meal_plan": "All Inclusive",
            "nights": [7, 8, 9, 10],
            "has_hotel": true,
            "has_transfer": false,
            "has_assistance": false,
            "has_tour": false,
            "price_from_ars": 1903828,
            "price_from_usd": 1200,
            "deposit_from_ars": null,
            "deposit_from_usd": null,
            "num_of_payments": null
          }
        ]
      }
    ]
  }
}

The ?type=banners section returns the banner strip under banners instead of blocks.

{
  "success": 1,
  "data": {
    "banners": [
      {
        "name": "banner_mundial.png",
        "description": "Mundial",
        "link": "https://www.deturista.com/categoria/mundial-154"
      }
    ]
  }
}

Site responses return the site display fields, social links, legal text, and the public office list. Most fields are nullable, so null-check before rendering.

{
  "success": 1,
  "data": {
    "id_site": 1,
    "name": "deTurista.com",
    "site_name": "Argentina",
    "phone": "0810-333-8748",
    "email": "info@deturista.com",
    "working_hours": "Lunes a Viernes de 9 a 18 hs",
    "address": "Av. Córdoba 1801/07, CABA, Buenos Aires",
    "address_link": "https://maps.app.goo.gl/example",
    "address2": null,
    "address2_link": null,
    "legal_info": "Razon social: deTurista.com de Aterrizando S.A - Leg. 16952",
    "social": {
      "facebook": "https://facebook.com/deturista",
      "twitter": null,
      "instagram": "https://instagram.com/deturista"
    },
    "offices": [
      {
        "id": 1,
        "label": "Pilar",
        "address": "Colectora Panamericana (Km 42.5) y Las Camelias, Pilar",
        "working_hours": null,
        "map_url": "https://www.google.com/maps/place/deTurista.com",
        "image": "pilar_.png"
      }
    ]
  }
}

Newsletter creation returns 201 with the subscription receipt.

{
  "success": 1,
  "data": {
    "id_newsletter": 472238,
    "email": "ana@example.com",
    "destination": "EUROPA",
    "creation_date": "2026-07-21 11:42:29"
  }
}

Working with the data

These conventions hold across every response, so handle them once instead of per endpoint.

Error shape

{
  "success": 0,
  "error": "forbidden",
  "message": "insufficient scope"
}

{
  "success": 0,
  "error": "unauthorized",
  "message": "missing or invalid API key"
}

{
  "success": 0,
  "error": "invalid_request",
  "message": "month must be between 1 and 12"
}

{
  "success": 0,
  "error": "not_found",
  "message": "price not found"
}

For contact and reservation receipt lookup, 404 not_found also means the id is not owned by the authenticated API consumer.

{
  "success": 0,
  "error": "rate_limited",
  "message": "rate limit exceeded"
}

Every error carries a message. For invalid_request and not_found it is specific so you can fix the call (it names the offending field or the missing resource). For unauthorized, forbidden and rate_limited it is intentionally generic and does not reveal configured credentials or grants. Do not parse it; switch on the error code instead.

Swagger and OpenAPI schema

Swagger UI is bundled with this beta documentation and loads the local openapi.json schema. Use the Swagger Authorize button to enter your own X-API-Key; the docs do not include prototype credentials.

Beta and versioning

The contract is versioned under /v1. During beta it evolves additively: new fields and endpoints can appear without notice, but an existing /v1 field will not be removed or repurposed without a new version. Build defensively — read the fields you need and ignore any you do not recognise — so an additive change never breaks your integration.