Offerings API — Vitrine de Ofertas

1. Visão Geral

A Offerings API é o serviço responsável por apresentar ao seu cliente as ofertas de produtos e serviços disponíveis para contratação junto à Getnet. Pense nela como uma vitrine digital: você consulta o catálogo atualizado de soluções de pagamento — máquinas, plataformas de e-commerce, serviços digitais e respectivas condições comerciais — e exibe essas informações de forma personalizada para cada cliente.

O serviço resolve um problema central no processo de credenciamento: como saber quais produtos e quais taxas um cliente específico pode contratar, de forma dinâmica e sempre atualizada? A Offerings API responde a essa pergunta em tempo real, considerando o perfil do cliente, o canal de venda e as condições comerciais vigentes.

2. Contexto e Casos de Uso

Quando usar este serviço?

Use a Offerings API sempre que precisar:

Exibir um catálogo de soluções disponíveis antes de iniciar uma contratação.
Apresentar as taxas de adquirência (MDR) personalizadas por bandeira e modalidade de pagamento.
Verificar os métodos de entrega disponíveis para um equipamento antes de finalizar um pedido.
Recalcular o preço de uma oferta com base em um perfil comercial específico.

Cenários Reais de Negócio

Cenário	Descrição
Credenciamento de novo cliente	Um consultor acessa o portal e exibe para o lojista as ofertas disponíveis para o canal e país selecionado, com informações de preço e condições.
Comparação de taxas	O cliente visualiza a vitrine e, ao clicar em uma oferta específica, o sistema busca as taxas detalhadas por bandeira (Visa, Master, Elo) e modalidade (crédito à vista, parcelado, débito).
Contratação online (autoatendimento)	Uma plataforma digital carrega toda a vitrine com taxas em uma única chamada para exibir o catálogo completo sem interação adicional do usuário.
Verificação de frete antes da contratação	Antes de confirmar um pedido com máquina física, o sistema consulta os métodos de entrega disponíveis para o CEP do cliente e exibe as opções (normal, expressa, agendada).
Precificação dinâmica por perfil	Um cliente com alto faturamento mensal recebe taxas diferenciadas; a API recalcula a oferta com base no `monthly_card_income` e no ramo de atividade (`merchant_category_code`).

3. Fluxo Principal

A Offerings API possui três operações principais, cada uma com finalidade distinta. Elas não são necessariamente encadeadas: o canal escolhe o fluxo mais adequado ao seu contexto.

Operação 1 — Vitrine de Ofertas

Esta operação consiste em buscar as ofertas disponíveis para o canal. Há dois fluxos possíveis — escolha um deles:

Fluxo 1 — Vitrine em duas chamadas (carrega a lista primeiro e, após a escolha do cliente, busca as taxas da oferta selecionada)

text

Consumidor  ──600;">GET /offerings?country=BR&channel={canal}──►  Offerings API
            ◄── Lista de ofertas (sem taxas de adquirência) ──

text

Consumidor  ──600;">GET /offerings?country=BR&channel={canal}──►  Offerings API
            ◄── Lista de ofertas (sem taxas de adquirência) ──

text

Consumidor  ──600;">GET /offerings?priced_offering_id={id}──►  Offerings API
            ◄── Objeto único com taxas detalhadas por bandeira ──

text

Consumidor  ──600;">GET /offerings?priced_offering_id={id}──►  Offerings API
            ◄── Objeto único com taxas detalhadas por bandeira ──

Fluxo 2 — Vitrine em uma única chamada (carrega lista e taxas juntas; requer header Accept-Encoding: gzip)

text

Consumidor  ──600;">GET /offerings?country=BR&channel={canal}&show_acquirers=true──►  Offerings API
            ◄── Lista de ofertas já com taxas incluídas ──

text

Consumidor  ──600;">GET /offerings?country=BR&channel={canal}&show_acquirers=true──►  Offerings API
            ◄── Lista de ofertas já com taxas incluídas ──

Operação 2 — Métodos de Entrega (quando a oferta contém equipamento físico)

Usada no momento em que o cliente precisa saber quais opções de frete estão disponíveis para os produtos do pedido, considerando o CEP de entrega informado.

text

Consumidor  ──600;">GET /offerings/delivery-data?legal_document_number={doc}&postal_code={cep}──►  Offerings API
            ◄── Opções de entrega disponíveis (normal, expressa, agendada) ──

text

Consumidor  ──600;">GET /offerings/delivery-data?legal_document_number={doc}&postal_code={cep}──►  Offerings API
            ◄── Opções de entrega disponíveis (normal, expressa, agendada) ──

Operação 3 — Precificação Direta (quando o canal já conhece o identificador da oferta)

Ideal para canais que já sabem de antemão qual oferta estará disponível para seus clientes e, portanto, não precisam percorrer a vitrine. Com o offering_id em mãos, o canal consulta diretamente os preços calculados para o perfil do cliente.

text

Consumidor  ──600;">GET /offerings/{offering_id}/pricing?monthly_card_income={valor}──►  Offerings API
            ◄── Oferta com preços calculados para o perfil do cliente ──

text

Consumidor  ──600;">GET /offerings/{offering_id}/pricing?monthly_card_income={valor}──►  Offerings API
            ◄── Oferta com preços calculados para o perfil do cliente ──

Resumo dos Endpoints

Endpoint	Finalidade
`GET /offerings`	Listar vitrine de ofertas ou consultar uma oferta individual com taxas
`GET /offerings/delivery-data`	Consultar métodos e valores de frete disponíveis para o CEP do cliente
`GET /offerings/{offering_id}/pricing`	Obter preços de uma oferta conhecida diretamente, sem percorrer a vitrine

4. Pré-requisitos

Autenticação

Todos os endpoints exigem um token de acesso válido. O token deve ser obtido previamente através do endpoint POST /token e enviado no header de cada requisição:

text

Authorization: {token}

text

Authorization: {token}

⚠️ Atenção: O token é enviado diretamente, sem o prefixo Bearer.

Dependências

Serviço de Autenticação: O token JWT deve ser obtido antes de qualquer chamada.
CEP válido: Necessário apenas para consulta de métodos de entrega (/delivery-data).
priced_offering_id: Gerado na primeira chamada à vitrine; necessário para buscar uma oferta individual com taxas.

Ambientes Disponíveis

Ambiente	URL Base
Homologação	`https://api-homologacao.getnet.com.br:443/v1`
Produção	`https://api-backoffice.getnet.com.br:443/v1`

5. Guia de Integração Rápida

Este guia apresenta o caminho mais comum: exibir a vitrine e, após a escolha do cliente, buscar as taxas da oferta selecionada.

Passo 1 — Listar a Vitrine

Faça a chamada informando o país e o canal de venda:

http

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

http

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

O que você recebe: Uma lista (array) com todas as ofertas disponíveis para aquele canal. Cada oferta contém nome, descrição, preço e os produtos incluídos (terminais, serviços, etc.). As taxas de adquirência não são retornadas nesta etapa.

Campos importantes na resposta:

Campo	Para que serve
`offering_id`	Identificador permanente da oferta
`priced_offering_id`	Use este ID para buscar as taxas na próxima chamada
`price`	Valor total da oferta em centavos (ex.: `14999` = R$149,99)
`items`	Lista de produtos incluídos na oferta

Passo 2 — Buscar Taxas da Oferta Selecionada

Após o cliente escolher uma oferta, use o priced_offering_id recebido no passo 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}

O que você recebe: Um objeto único (não uma lista) com a oferta completa, incluindo as taxas de adquirência por bandeira, modalidade e prazo de liquidação.

Exemplo de taxa 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"
  }
}

O valor 199 representa 1,99% (dois decimais fixos).

Alternativa — Tudo em Uma Chamada

Se preferir carregar vitrine e taxas ao mesmo tempo, adicione show_acquirers=true e o header de compressão:

http

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

http

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

⚠️ O header Accept-Encoding: gzip é obrigatório quando show_acquirers=true.

6. Regras de Negócio

Modos de Operação do `GET /offerings`

Os parâmetros não devem ser misturados entre os modos:

Modo	Parâmetros Obrigatórios	Retorno
Vitrine	`country` + `channel`	Array de ofertas
Vitrine com taxas	`country` + `channel` + `show_acquirers=true`	Array de ofertas com MDR
Oferta individual	somente `priced_offering_id`	Objeto único com taxas

❌ Não combine country/channel com priced_offering_id na mesma requisição.

Formatos de Valores Monetários

Todos os valores monetários são expressos em centavos inteiros.
- 14999 → R$149,99
- 1000000 → R$10.000,00 (para monthly_card_income)
Percentuais MDR usam dois decimais fixos:
- 199 → 1,99%
- 378 → 3,78%

Campos Obrigatórios por Produto

Tipo de Produto	Campos Obrigatórios
`acquirer`	`brand`, `transaction_currency`, `transaction_channel_type`
`terminal`	`transaction_channel_type`
`device`	`transaction_channel_type`
`service`	`service_type`
`voucher`	`product_type`

Processamento Assíncrono

Quando a precificação não está imediatamente disponível, a API retorna HTTP 201 com um smart_offering_id. Use esse ID para consultar a oferta posteriormente:

http

GET /v1/offerings?smart_offering_id={smart_offering_id}

http

GET /v1/offerings?smart_offering_id={smart_offering_id}

Se a precificação ainda estiver em andamento, a resposta será HTTP 202.

Filtros Disponíveis na Vitrine

Você pode refinar os resultados da vitrine usando filtros opcionais:

Filtro	Descrição
`fiscal_type`	Tipo de pessoa: `natural_person` (CPF) ou `company` (CNPJ)
`settlement_period`	Prazo de recebimento desejado (ex.: `installments_31`, `receive_now_0`)
`offering_type`	Tipo da oferta: `default`, `promotion`, `affiliate`, `external`, `product_change`, `purchase`
`anticipation`	`true` para exibir apenas ofertas com antecipação de recebíveis
`product_type`	Filtra por tipo de produto: `terminal`, `service`, `acquirer`, `composite`, etc.
`modalities`	Modalidade de contratação: `rent` (aluguel), `sale` (venda), `affiliation_fee` (taxa de afiliação)
`monthly_card_income`	Faturamento mensal esperado em centavos (influencia a precificação dinâmica)

Opt-ins Obrigatórios

Algumas ofertas exigem aceite explícito de termos. Verifique o campo additional_information.shared_data.opt_ins na resposta para identificar se há aceites pendentes (ex.: lgpd, terms_and_conditions, saas_account_terms_acceptance).

7. Tratamento de Erros

Todos os erros seguem a estrutura padrão:

json

{
  "status_code": 400,
  "message": "Descrição do problema",
  "details": []
}

json

{
  "status_code": 400,
  "message": "Descrição do problema",
  "details": []
}

Códigos de Resposta

Código	Significado	O que fazer
`200`	Sucesso	Processar normalmente o array ou objeto retornado.
`201`	Precificação assíncrona iniciada	Guardar o `smart_offering_id` e consultar novamente após alguns instantes.
`202`	Precificação ainda em andamento	Aguardar e tentar novamente com o mesmo `smart_offering_id`.
`400`	Requisição inválida	Revisar os parâmetros enviados. Verifique se não está misturando modos incompatíveis (ex.: `country` + `priced_offering_id`). Confirme se o `Accept-Encoding: gzip` foi enviado quando `show_acquirers=true`.
`401`	Token inválido ou expirado	Obter um novo token via `POST /token` e tentar novamente.
`404`	Oferta não encontrada	Verificar se o `offering_id`, `priced_offering_id` ou `smart_offering_id` está correto. A oferta pode ter expirado.
`422`	Erro de regra de negócio	Ler o campo `message` da resposta para entender qual regra foi violada (comum no endpoint de delivery-data quando CEP é inválido).
`500`	Erro interno do servidor	Tentar novamente após alguns instantes. Se persistir, acionar o suporte Getnet.

Situações Comuns de Erro

400 ao usar show_acquirers=true sem gzip: Adicione o header Accept-Encoding: gzip.
404 ao buscar priced_offering_id: O ID tem validade limitada. Volte à vitrine para gerar um novo.
422 no delivery-data: CEP inválido ou sem cobertura para o tipo de produto solicitado.

8. Glossário

Termo	Definição
Offering (Oferta)	Pacote comercial que agrupa um ou mais produtos (terminal, serviço, adquirência) com suas condições de preço. É o que o cliente efetivamente contrata.
Offering ID	Identificador permanente de uma oferta no catálogo.
Priced Offering ID	Identificador gerado pelo motor de precificação para uma instância específica de oferta já calculada. Tem validade limitada.
Smart Offering ID	Identificador de uma precificação assíncrona em andamento. Usado para consultar o resultado depois.
Request ID	Identificador do grupo de precificações executadas em uma mesma requisição. Usado para rastreabilidade.
MDR (Merchant Discount Rate)	Taxa percentual cobrada sobre cada transação de pagamento, variando por bandeira, modalidade (crédito/débito), número de parcelas e canal.
Settlement Period	Prazo para recebimento dos valores das vendas após a transação. Ex.: `installments_31` = 31 dias após cada parcela; `receive_now_0` = recebimento imediato (Pix/antecipação).
Composite	Tipo de produto que agrupa outros produtos do mesmo tipo. Ex.: um `composite` de adquirência agrupa todas as taxas por bandeira e modalidade de um canal específico.
Acquirer (Adquirência)	Serviço que processa as transações de pagamento. As taxas de adquirência (MDR) definem quanto o estabelecimento paga por cada transação.
Terminal	Equipamento físico ou virtual de pagamento (ex.: maquininha POS, plataforma de e-commerce).
Device	Dispositivo periférico de pagamento (ex.: pinpad).
Service	Serviço digital complementar incluído na oferta (ex.: antecipação de recebíveis, Pix, link de pagamento, antifraude).
Voucher	Produto de pagamento via vale-benefício (ex.: vale-refeição, vale-alimentação) de bandeiras como Alelo, VR, Ticket, Ben.
Modality	Modalidade de contratação do produto: `rent` (aluguel mensal), `sale` (compra) ou `affiliation_fee` (taxa de afiliação).
Pricing Type	Modelo de precificação aplicado ao produto. Os principais são: `mdr` (percentual por transação), `monthly_rent` (aluguel fixo mensal), `fixed_price` (preço único), `transaction_fee` (valor fixo por transação), `no_price` (sem custo adicional).
MCC (Merchant Category Code)	Código que classifica o ramo de atividade do estabelecimento comercial. Influencia as taxas disponíveis.
Channel	Canal de venda responsável pelo credenciamento (ex.: portal web, app, consultor).
Opt-in	Aceite formal de termos pelo cliente (ex.: LGPD, termos e condições, termos da conta digital).
Delivery Data	Informações sobre os métodos de entrega disponíveis para um produto físico, considerando o CEP do cliente.
Price Book	Tabela de preços de referência utilizada no cálculo da precificação dinâmica.
Anticipation	Serviço de antecipação de recebíveis que permite ao lojista receber o valor das vendas parceladas antes do prazo normal.
Brand	Bandeira do cartão de pagamento. Valores suportados: `visa`, `master`, `elo`, `amex`, `hipercard`.
Installment Type	Responsabilidade pelo financiamento do parcelamento: `merchant` (lojista), `issuer` (banco emissor), `bndes`, `iata`, `crediario`.

On this page

Offerings API — Vitrine de Ofertas

Offerings API — Vitrine de Ofertas

1. Visão Geral

2. Contexto e Casos de Uso

Quando usar este serviço?

Cenários Reais de Negócio

3. Fluxo Principal

Operação 1 — Vitrine de Ofertas

Operação 2 — Métodos de Entrega (quando a oferta contém equipamento físico)

Operação 3 — Precificação Direta (quando o canal já conhece o identificador da oferta)

Resumo dos Endpoints

4. Pré-requisitos

Autenticação

Dependências

Ambientes Disponíveis

5. Guia de Integração Rápida

Passo 1 — Listar a Vitrine

Passo 2 — Buscar Taxas da Oferta Selecionada

Alternativa — Tudo em Uma Chamada

6. Regras de Negócio

Modos de Operação do GET /offerings

Formatos de Valores Monetários

Campos Obrigatórios por Produto

Processamento Assíncrono

Filtros Disponíveis na Vitrine

Opt-ins Obrigatórios

7. Tratamento de Erros

Códigos de Resposta

Situações Comuns de Erro

8. Glossário

Modos de Operação do `GET /offerings`