Offerings API — Vitrina de Ofertas

1. Visión General

La Offerings API es el servicio responsable de presentar a su cliente las ofertas de productos y servicios disponibles para contratación con Getnet. Piense en ella como una vitrina digital: usted consulta el catálogo actualizado de soluciones de pago — máquinas, plataformas de e-commerce, servicios digitales y sus respectivas condiciones comerciales — y muestra esa información de forma personalizada para cada cliente.

El servicio resuelve un problema central en el proceso de acreditación: ¿cómo saber qué productos y qué tasas puede contratar un cliente específico, de forma dinámica y siempre actualizada? La Offerings API responde a esa pregunta en tiempo real, considerando el perfil del cliente, el canal de venta y las condiciones comerciales vigentes.

2. Contexto y Casos de Uso

¿Cuándo usar este servicio?

Use la Offerings API siempre que necesite:

Mostrar un catálogo de soluciones disponibles antes de iniciar una contratación.
Presentar las tasas de adquirencia (MDR) personalizadas por marca y modalidad de pago.
Verificar los métodos de entrega disponibles para un equipo antes de finalizar un pedido.
Recalcular el precio de una oferta con base en un perfil comercial específico.

Escenarios Reales de Negocio

Escenario	Descripción
Acreditación de nuevo cliente	Un consultor accede al portal y muestra al merchant las ofertas disponibles para el canal y país seleccionado, con información de precio y condiciones.
Comparación de tasas	El cliente visualiza la vitrina y, al hacer clic en una oferta específica, el sistema busca las tasas detalladas por marca (Visa, Master, Elo) y modalidad (crédito al contado, en cuotas, débito).
Contratación online (autoservicio)	Una plataforma digital carga toda la vitrina con tasas en una única llamada para mostrar el catálogo completo sin interacción adicional del usuario.
Verificación de flete antes de la contratación	Antes de confirmar un pedido con máquina física, el sistema consulta los métodos de entrega disponibles para el código postal del cliente y muestra las opciones (normal, exprés, programada).
Tarificación dinámica por perfil	Un cliente con alta facturación mensual recibe tasas diferenciadas; la API recalcula la oferta con base en `monthly_card_income` y en el rubro de actividad (`merchant_category_code`).

3. Flujo Principal

La Offerings API posee tres operaciones principales, cada una con una finalidad distinta. No están necesariamente encadenadas: el canal elige el flujo más adecuado a su contexto.

Operación 1 — Vitrina de Ofertas

Esta operación consiste en buscar las ofertas disponibles para el canal. Hay dos flujos posibles — elija uno de ellos:

Flujo 1 — Vitrina en dos llamadas (carga la lista primero y, tras la elección del cliente, busca las tasas de la oferta seleccionada)

text

Consumidor  ──600;">GET /offerings?country=BR&channel={canal}──►  Offerings API
            ◄── Lista de ofertas (sin tasas de adquirencia) ──

text

Consumidor  ──600;">GET /offerings?country=BR&channel={canal}──►  Offerings API
            ◄── Lista de ofertas (sin tasas de adquirencia) ──

text

Consumidor  ──600;">GET /offerings?priced_offering_id={id}──►  Offerings API
            ◄── Objeto único con tasas detalladas por marca ──

text

Consumidor  ──600;">GET /offerings?priced_offering_id={id}──►  Offerings API
            ◄── Objeto único con tasas detalladas por marca ──

Flujo 2 — Vitrina en una única llamada (carga lista y tasas juntas; requiere header Accept-Encoding: gzip)

text

Consumidor  ──600;">GET /offerings?country=BR&channel={canal}&show_acquirers=true──►  Offerings API
            ◄── Lista de ofertas ya con tasas incluidas ──

text

Consumidor  ──600;">GET /offerings?country=BR&channel={canal}&show_acquirers=true──►  Offerings API
            ◄── Lista de ofertas ya con tasas incluidas ──

Operación 2 — Métodos de Entrega (cuando la oferta contiene equipo físico)

Usada en el momento en que el cliente necesita saber qué opciones de flete están disponibles para los productos del pedido, considerando el código postal de entrega informado.

text

Consumidor  ──600;">GET /offerings/delivery-data?legal_document_number={doc}&postal_code={cep}──►  Offerings API
            ◄── Opciones de entrega disponibles (normal, exprés, programada) ──

text

Consumidor  ──600;">GET /offerings/delivery-data?legal_document_number={doc}&postal_code={cep}──►  Offerings API
            ◄── Opciones de entrega disponibles (normal, exprés, programada) ──

Operación 3 — Tarificación Directa (cuando el canal ya conoce el identificador de la oferta)

Ideal para canales que ya saben de antemano qué oferta estará disponible para sus clientes y, por lo tanto, no necesitan recorrer la vitrina. Con el offering_id en mano, el canal consulta directamente los precios calculados para el perfil del cliente.

text

Consumidor  ──600;">GET /offerings/{offering_id}/pricing?monthly_card_income={valor}──►  Offerings API
            ◄── Oferta con precios calculados para el perfil del cliente ──

text

Consumidor  ──600;">GET /offerings/{offering_id}/pricing?monthly_card_income={valor}──►  Offerings API
            ◄── Oferta con precios calculados para el perfil del cliente ──

Resumen de los Endpoints

Endpoint	Finalidad
`GET /offerings`	Listar la vitrina de ofertas o consultar una oferta individual con tasas
`GET /offerings/delivery-data`	Consultar métodos y valores de flete disponibles para el código postal del cliente
`GET /offerings/{offering_id}/pricing`	Obtener precios de una oferta conocida directamente, sin recorrer la vitrina

4. Prerrequisitos

Autenticación

Todos los endpoints exigen un token de acceso válido. El token debe obtenerse previamente a través del endpoint POST /token y enviarse en el header de cada solicitud:

text

Authorization: {token}

text

Authorization: {token}

⚠️ Atención: El token se envía directamente, sin el prefijo Bearer.

Dependencias

Servicio de Autenticación: El token JWT debe obtenerse antes de cualquier llamada.
Código postal válido: Necesario solo para la consulta de métodos de entrega (/delivery-data).
priced_offering_id: Generado en la primera llamada a la vitrina; necesario para buscar una oferta individual con tasas.

Ambientes Disponibles

Ambiente	URL Base
Homologación	`https://api-homologacao.getnet.com.br:443/v1`
Producción	`https://api-backoffice.getnet.com.br:443/v1`

5. Guía Rápida de Integración

Esta guía presenta el camino más común: mostrar la vitrina y, tras la elección del cliente, buscar las tasas de la oferta seleccionada.

Paso 1 — Listar la Vitrina

Haga la llamada informando el país y el canal de venta:

http

600;">GET /v1/offerings?country=BR&channel=mi_canal
Authorization: {token}

http

600;">GET /v1/offerings?country=BR&channel=mi_canal
Authorization: {token}

Lo que usted recibe: Una lista (array) con todas las ofertas disponibles para ese canal. Cada oferta contiene nombre, descripción, precio y los productos incluidos (terminales, servicios, etc.). Las tasas de adquirencia no se retornan en esta etapa.

Campos importantes en la respuesta:

Campo	Para qué sirve
`offering_id`	Identificador permanente de la oferta
`priced_offering_id`	Use este ID para buscar las tasas en la próxima llamada
`price`	Valor total de la oferta en centavos (ej.: `14999` = R$149,99)
`items`	Lista de productos incluidos en la oferta

Paso 2 — Buscar Tasas de la Oferta Seleccionada

Después de que el cliente elija una oferta, use el priced_offering_id recibido en el paso anterior:

http

600;">GET /v1/offerings?priced_offering_id=abc-123-def-456
Authorization: {token}

http

600;">GET /v1/offerings?priced_offering_id=abc-123-def-456
Authorization: {token}

Lo que usted recibe: Un objeto único (no una lista) con la oferta completa, incluyendo las tasas de adquirencia por marca, modalidad y plazo de liquidación.

Ejemplo de tasa retornada:

json

{
  "name": "VISA|CREDITO A VISTA|FISICO",
  "brand": "visa",
  "acquirer_product_type": "credit",
  "pricing_model": {
    "pricing_type": "mdr",
    "percentage_default": 199,
    "percentage_min": 149,
    "percentage_max": 199,
    "settlement_period": "installments_31"
  }
}

json

{
  "name": "VISA|CREDITO A VISTA|FISICO",
  "brand": "visa",
  "acquirer_product_type": "credit",
  "pricing_model": {
    "pricing_type": "mdr",
    "percentage_default": 199,
    "percentage_min": 149,
    "percentage_max": 199,
    "settlement_period": "installments_31"
  }
}

El valor 199 representa 1,99% (dos decimales fijos).

Alternativa — Todo en Una Llamada

Si prefiere cargar la vitrina y las tasas al mismo tiempo, agregue show_acquirers=true y el header de compresión:

http

600;">GET /v1/offerings?country=BR&channel=mi_canal&show_acquirers=true
Authorization: {token}
Accept-Encoding: gzip

http

600;">GET /v1/offerings?country=BR&channel=mi_canal&show_acquirers=true
Authorization: {token}
Accept-Encoding: gzip

⚠️ El header Accept-Encoding: gzip es obligatorio cuando show_acquirers=true.

6. Reglas de Negocio

Modos de Operación de `GET /offerings`

Los parámetros no deben mezclarse entre los modos:

Modo	Parámetros Obligatorios	Retorno
Vitrina	`country` + `channel`	Array de ofertas
Vitrina con tasas	`country` + `channel` + `show_acquirers=true`	Array de ofertas con MDR
Oferta individual	solo `priced_offering_id`	Objeto único con tasas

❌ No combine country/channel con priced_offering_id en la misma solicitud.

Formatos de Valores Monetarios

Todos los valores monetarios se expresan en centavos enteros.
- 14999 → R$149,99
- 1000000 → R$10.000,00 (para monthly_card_income)
Los porcentajes MDR usan dos decimales fijos:
- 199 → 1,99%
- 378 → 3,78%

Campos Obligatorios por Producto

Tipo de Producto	Campos Obligatorios
`acquirer`	`brand`, `transaction_currency`, `transaction_channel_type`
`terminal`	`transaction_channel_type`
`device`	`transaction_channel_type`
`service`	`service_type`
`voucher`	`product_type`

Filtros Disponibles en la Vitrina

Usted puede refinar los resultados de la vitrina usando filtros opcionales:

Filtro	Descripción
`fiscal_type`	Tipo de persona: `natural_person` (CPF) o `company` (CNPJ)
`settlement_period`	Plazo de recepción deseado (ej.: `installments_31`, `receive_now_0`)
`offering_type`	Tipo de la oferta: `default`, `promotion`, `affiliate`, `external`, `product_change`, `purchase`
`anticipation`	`true` para mostrar solo ofertas con anticipación de recibibles
`product_type`	Filtra por tipo de producto: `terminal`, `service`, `acquirer`, `composite`, etc.
`modalities`	Modalidad de contratación: `rent` (alquiler), `sale` (venta), `affiliation_fee` (tasa de afiliación)
`monthly_card_income`	Facturación mensual esperada en centavos (influye en la tarificación dinámica)

Opt-ins Obligatorios

Algunas ofertas exigen aceptación explícita de términos. Verifique el campo additional_information.shared_data.opt_ins en la respuesta para identificar si hay aceptaciones pendientes (ej.: lgpd, terms_and_conditions, saas_account_terms_acceptance).

7. Manejo de Errores

Todos los errores siguen la estructura estándar:

json

{
  "status_code": 400,
  "message": "Descripción del problema",
  "details": []
}

json

{
  "status_code": 400,
  "message": "Descripción del problema",
  "details": []
}

Códigos de Respuesta

Código	Significado	Qué hacer
`200`	Éxito	Procesar normalmente el array u objeto retornado.
`400`	Solicitud inválida	Revisar los parámetros enviados. Verifique que no esté mezclando modos incompatibles (ej.: `country` + `priced_offering_id`). Confirme que el `Accept-Encoding: gzip` se haya enviado cuando `show_acquirers=true`.
`401`	Token inválido o expirado	Obtener un nuevo token vía `POST /token` e intentar nuevamente.
`404`	Oferta no encontrada	Verificar que el `offering_id` o `priced_offering_id` sea correcto. La oferta puede haber expirado.
`422`	Error de regla de negocio	Leer el campo `message` de la respuesta para entender qué regla fue violada (común en el endpoint de delivery-data cuando el código postal es inválido).
`500`	Error interno del servidor	Intentar nuevamente después de unos instantes. Si persiste, contactar al soporte de Getnet.

Situaciones Comunes de Error

400 al usar show_acquirers=true sin gzip: Agregue el header Accept-Encoding: gzip.
404 al buscar priced_offering_id: El ID tiene validez limitada. Vuelva a la vitrina para generar uno nuevo.
422 en delivery-data: Código postal inválido o sin cobertura para el tipo de producto solicitado.

8. Glosario

Término	Definición
Offering (Oferta)	Paquete comercial que agrupa uno o más productos (terminal, servicio, adquirencia) con sus condiciones de precio. Es lo que el cliente efectivamente contrata.
Offering ID	Identificador permanente de una oferta en el catálogo.
Priced Offering ID	Identificador generado por el motor de tarificación para una instancia específica de oferta ya calculada. Tiene validez limitada.
MDR (Merchant Discount Rate)	Tasa porcentual cobrada sobre cada transacción de pago, variando por marca, modalidad (crédito/débito), número de cuotas y canal.
Settlement Period	Plazo para la recepción de los valores de las ventas tras la transacción. Ej.: `installments_31` = 31 días después de cada cuota; `receive_now_0` = recepción inmediata (Pix/anticipación).
Composite	Tipo de producto que agrupa otros productos del mismo tipo. Ej.: un `composite` de adquirencia agrupa todas las tasas por marca y modalidad de un canal específico.
Acquirer (Adquirencia)	Servicio que procesa las transacciones de pago. Las tasas de adquirencia (MDR) definen cuánto paga el establecimiento por cada transacción.
Terminal	Equipo físico o virtual de pago (ej.: máquina POS, plataforma de e-commerce).
Device	Dispositivo periférico de pago (ej.: pinpad).
Service	Servicio digital complementario incluido en la oferta (ej.: anticipación de recibibles, Pix, link de pago, antifraude).
Voucher	Producto de pago vía vale-beneficio (ej.: vale-comida, vale-alimentación) de marcas como Alelo, VR, Ticket, Ben.
Modality	Modalidad de contratación del producto: `rent` (alquiler mensual), `sale` (compra) o `affiliation_fee` (tasa de afiliación).
Pricing Type	Modelo de tarificación aplicado al producto. Los principales son: `mdr` (porcentaje por transacción), `monthly_rent` (alquiler fijo mensual), `fixed_price` (precio único), `transaction_fee` (valor fijo por transacción), `no_price` (sin costo adicional).
MCC (Merchant Category Code)	Código que clasifica el rubro de actividad del establecimiento comercial. Influye en las tasas disponibles.
Channel	Canal de venta responsable de la acreditación (ej.: portal web, app, consultor).
Opt-in	Aceptación formal de términos por el cliente (ej.: LGPD, términos y condiciones, términos de la cuenta digital).
Delivery Data	Información sobre los métodos de entrega disponibles para un producto físico, considerando el código postal del cliente.
Price Book	Tabla de precios de referencia utilizada en el cálculo de la tarificación dinámica.
Anticipation	Servicio de anticipación de recibibles que permite al merchant recibir el valor de las ventas en cuotas antes del plazo normal.
Brand	Marca de la tarjeta de pago. Valores admitidos: `visa`, `master`, `elo`, `amex`, `hipercard`.
Installment Type	Responsabilidad por la financiación del plan de cuotas: `merchant` (establecimiento), `issuer` (banco emisor), `bndes`, `iata`, `crediario`.

En esta página

Offerings API — Vitrina de Ofertas

Offerings API — Vitrina de Ofertas

1. Visión General

2. Contexto y Casos de Uso

¿Cuándo usar este servicio?

Escenarios Reales de Negocio

3. Flujo Principal

Operación 1 — Vitrina de Ofertas

Operación 2 — Métodos de Entrega (cuando la oferta contiene equipo físico)

Operación 3 — Tarificación Directa (cuando el canal ya conoce el identificador de la oferta)

Resumen de los Endpoints

4. Prerrequisitos

Autenticación

Dependencias

Ambientes Disponibles

5. Guía Rápida de Integración

Paso 1 — Listar la Vitrina

Paso 2 — Buscar Tasas de la Oferta Seleccionada

Alternativa — Todo en Una Llamada

6. Reglas de Negocio

Modos de Operación de GET /offerings

Formatos de Valores Monetarios

Campos Obligatorios por Producto

Filtros Disponibles en la Vitrina

Opt-ins Obligatorios

7. Manejo de Errores

Códigos de Respuesta

Situaciones Comunes de Error

8. Glosario

Modos de Operación de `GET /offerings`