Precios de Oferta

Un precio de oferta asocia un importe concreto, en una moneda específica, a una oferta. Una oferta puede tener varios precios — uno por moneda — de modo que el mismo plan pueda venderse en BRL, USD, EUR y más. Exactamente un precio por oferta puede marcarse como el predeterminado de esa oferta.

Los precios son la hoja del catálogo. La oferta define cómo factura un plan (ciclo, prueba, configuración); el precio define cuánto cuesta en cada moneda.

Cómo funciona la fijación de precios

• Los importes son unidades menores enteras. Almacena centavos, no decimales. R$99.00 es 9900; US$150.00 es 15000. Siempre empareja un amount con una currency ISO 4217.
• Un precio por moneda, por oferta. Una oferta no puede tener dos precios activos en la misma moneda. Crear o actualizar un precio hacia una moneda que ya está ocupada devuelve 409 Conflict.
• Un predeterminado por oferta. A lo sumo un precio de una oferta puede tener is_default: true. El predeterminado es el precio que Tokeflow muestra primero (y lista primero) para esa oferta.
• first_charge_amount determina los cargos de configuración. Cuando la oferta padre tiene setup_charge = true, el primer ciclo se factura con first_charge_amount en lugar de amount. Un valor de 0 significa un primer cargo únicamente de validación de tarjeta. Déjalo en null para facturar el amount estándar en el primer ciclo. Una oferta con free_trial = true factura 0 en el primer ciclo con independencia de este campo, salvo que se configure un first_charge_amount mayor que 0 como tarifa de alta inicial.

El objeto precio de oferta

{
  "id": "opr_b1c2d3e4f5",
  "offer_id": "ofr_a1b2c3d4e5",
  "currency": "BRL",
  "amount": 9900,
  "first_charge_amount": 0,
  "is_default": true,
  "created_at": "2026-05-19T12:00:00.000Z",
  "updated_at": "2026-05-19T12:00:00.000Z"
}

Endpoints

Todos los endpoints de precios de oferta se encuentran bajo https://api.tokeflow.com/api/v1. La autenticación usa una clave secreta — consulta Autenticación.

POST/api/v1/offers/:offerId/prices

Auth: clave de Organization (con merchant_id) o clave de Merchant.

Añade un precio a una oferta existente. La oferta padre debe pertenecer al merchant autenticado.

Parámetros de ruta

Parámetros del cuerpo

curl -X POST https://api.tokeflow.com/api/v1/offers/ofr_a1b2c3d4e5/prices \
  -H "Authorization: Bearer sk_live_mer_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c3b9f1e-2a4d-4c8e-9f1a-6b2d8e0c4a11" \
  -d '{
    "currency": "BRL",
    "amount": 9900,
    "first_charge_amount": 0,
    "is_default": true
  }'

Respuesta 201 Created

{
  "success": true,
  "data": {
    "id": "opr_b1c2d3e4f5",
    "offer_id": "ofr_a1b2c3d4e5",
    "currency": "BRL",
    "amount": 9900,
    "first_charge_amount": 0,
    "is_default": true,
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T12:00:00.000Z"
  },
  "request_id": "req_8f3c2a1b9d",
  "timestamp": "2026-05-19T12:00:00.000Z"
}

GET/api/v1/offers/:offerId/prices

Auth: clave de Organization (con merchant_id) o clave de Merchant.

Lista los precios de una oferta, el predeterminado primero y luego por moneda. Admite filtrado y paginación.

Parámetros de ruta

Parámetros de consulta

curl "https://api.tokeflow.com/api/v1/offers/ofr_a1b2c3d4e5/prices?page=1&limit=20&currency=BRL&is_default=true" \
  -H "Authorization: Bearer sk_live_mer_REPLACE_ME"

Respuesta 200 OK

{
  "success": true,
  "data": [
    {
      "id": "opr_b1c2d3e4f5",
      "offer_id": "ofr_a1b2c3d4e5",
      "currency": "BRL",
      "amount": 9900,
      "first_charge_amount": 0,
      "is_default": true,
      "created_at": "2026-05-19T12:00:00.000Z",
      "updated_at": "2026-05-19T12:00:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  },
  "request_id": "req_3a1d7f9c2b",
  "timestamp": "2026-05-19T12:00:00.000Z"
}

GET/api/v1/offer-prices/:id

Auth: clave de Organization (con merchant_id) o clave de Merchant.

Recupera un único precio por su ID opr_. El precio debe pertenecer a una oferta propiedad del merchant autenticado.

Parámetros de ruta

curl https://api.tokeflow.com/api/v1/offer-prices/opr_b1c2d3e4f5 \
  -H "Authorization: Bearer sk_live_mer_REPLACE_ME"

Respuesta 200 OK

{
  "success": true,
  "data": {
    "id": "opr_b1c2d3e4f5",
    "offer_id": "ofr_a1b2c3d4e5",
    "currency": "BRL",
    "amount": 9900,
    "first_charge_amount": 0,
    "is_default": true,
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T12:00:00.000Z"
  },
  "request_id": "req_5b2e8c0a1f",
  "timestamp": "2026-05-19T12:00:00.000Z"
}

Un precio inexistente o fuera de alcance devuelve 404 Not Found con un not_found_error.

PATCH/api/v1/offer-prices/:id

Auth: clave de Organization (con merchant_id) o clave de Merchant.

Actualiza parcialmente un precio. Envía solo los campos que quieras cambiar.

Parámetros de ruta

Parámetros del cuerpo (todos opcionales)

curl -X PATCH https://api.tokeflow.com/api/v1/offer-prices/opr_b1c2d3e4f5 \
  -H "Authorization: Bearer sk_live_mer_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 12900 }'

Respuesta 200 OK

{
  "success": true,
  "data": {
    "id": "opr_b1c2d3e4f5",
    "offer_id": "ofr_a1b2c3d4e5",
    "currency": "BRL",
    "amount": 12900,
    "first_charge_amount": 0,
    "is_default": true,
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T13:45:00.000Z"
  },
  "request_id": "req_9d4f1a7e3c",
  "timestamp": "2026-05-19T13:45:00.000Z"
}

DELETE/api/v1/offer-prices/:id

Auth: clave de Organization (con merchant_id) o clave de Merchant.

Borra lógicamente un precio. El registro se conserva para fines de auditoría y puede recuperarse con restaurar. El borrado lógico libera el espacio de moneda del precio — y, si era el predeterminado, el espacio predeterminado — para que un nuevo precio pueda ocuparlos.

Parámetros de ruta

curl -X DELETE https://api.tokeflow.com/api/v1/offer-prices/opr_b1c2d3e4f5 \
  -H "Authorization: Bearer sk_live_mer_REPLACE_ME"

Respuesta 204 No Content

El cuerpo de la respuesta está vacío en caso de éxito.

POST/api/v1/offer-prices/:id/restore

Auth: clave de Organization (con merchant_id) o clave de Merchant.

Restaura un precio borrado lógicamente, devolviéndolo al uso activo. La restauración se rechaza si un precio activo ha tomado desde entonces el mismo espacio de moneda, o — para un precio predeterminado — si la oferta ya tiene un predeterminado nuevamente.

Parámetros de ruta

curl -X POST https://api.tokeflow.com/api/v1/offer-prices/opr_b1c2d3e4f5/restore \
  -H "Authorization: Bearer sk_live_mer_REPLACE_ME"

Respuesta 201 Created

{
  "success": true,
  "data": {
    "id": "opr_b1c2d3e4f5",
    "offer_id": "ofr_a1b2c3d4e5",
    "currency": "BRL",
    "amount": 12900,
    "first_charge_amount": 0,
    "is_default": true,
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T14:10:00.000Z"
  },
  "request_id": "req_1c7a3e9f2d",
  "timestamp": "2026-05-19T14:10:00.000Z"
}

Errores

Los endpoints de precios de oferta usan el sobre de error estándar de Tokeflow. Casos comunes:

{
  "error": {
    "type": "conflict_error",
    "code": "OFFER_PRICE_CURRENCY_EXISTS",
    "message": "Offer ofr_a1b2c3d4e5 already has a price in currency BRL",
    "details": {},
    "request_id": "req_2f8b1d4c7a",
    "timestamp": "2026-05-19T12:05:00.000Z"
  }
}

Relacionado

• Ofertas — la configuración de facturación a la que se asocian los precios.
• Productos — los artículos vendibles a los que pertenecen las ofertas.
• Familias de Productos — agrupación de productos.
• Autenticación — claves, scopes y contexto de merchant.