> ## Documentation Index > Fetch the complete documentation index at: https://nexus-docs.ticto.dev/llms.txt > Use this file to discover all available pages before exploring further. # Criar oferta para produto > Cria uma nova oferta para um produto específico. **Campos obrigatórios:** - `price` - Preço da oferta em centavos (valor mínimo aplicável) - `type_of_charge` - Tipo de cobrança ('unique' ou 'recurring') - `allow_credit_card` - Se aceita cartão de crédito - `allow_pix` - Se aceita PIX - `allow_bank_slip` - Se aceita boleto bancário **Campos obrigatórios condicionais:** - `credit_card_installments_options` - Opções de parcelamento (obrigatório se allow_credit_card = true) - `bank_slip_days_due` - Dias para vencimento do boleto (obrigatório se allow_bank_slip = true) - `subscription.interval` - Intervalo da assinatura (obrigatório se type_of_charge = 'recurring') **Campos obrigatórios para produtos físicos (type = 'physical'):** - `quantity_items` - Quantidade de itens disponíveis (1-100 unidades) - Objeto `freight` com os parâmetros de frete descritos no schema `RequestOffer.freight` **Regras de validação:** - Pelo menos um método de pagamento deve estar habilitado - Para assinaturas, cartão de crédito é obrigatório se trial_days > 0 - Para assinaturas, dois cartões de crédito não são permitidos - Preço deve respeitar o valor mínimo da moeda ## OpenAPI ````yaml /api-reference/openapi.yaml post /products/{product_hash}/offers openapi: 3.0.3 info: title: Nexus version: 1.0.2 description: > API para integração entre Ticto e clientes externos # Autenticação Para autenticar as solicitações aos endpoints descritos a seguir, por favor, siga os passos abaixo: 1. **Solicite** seu cadastro como cliente através do e-mail **infraestrutura@ticto.com.br** para obter seu `client_id` e `token`. 2. **Use** seu token e ID de cliente para fazer login no Nexus e obter seu `client_token`. 3. **Em todas as outras requisições**, envie seu `client_token` no header como `X-Api-Client-Token`. 4. **Crie** seus usuários na rota de criação de usuário. Para cada usuário, será retornado um `public_token` único. 5. **Para endpoints que não estão em public.php**, adicione o `public_token` do usuário no cabeçalho **Authorization** utilizando o formato: ```http Authorization: Bearer {public_token} ``` ## Restrição de origem O acesso a esta API não está disponível para todos os sellers. Seu uso é estritamente permitido para parceiros comerciais que a utilizarão em cenários específicos. Por este motivo, o acesso será restrito a endereços IP e domínios previamente informados por esses parceiros. Essa medida visa proporcionar um ambiente mais controlado e seguro para todos os nossos usuários e parceiros. ### O que isso significa para os desenvolvedores? - **Acesso Limitado:** Somente os IPs e domínios pré-autorizados poderão realizar chamadas à API. Qualquer tentativa de acesso de um IP ou domínio não listado será automaticamente rejeitada. - **Processo de Autorização:** Para garantir a continuidade do acesso à API sem interrupções, é essencial que os desenvolvedores enviem os endereços IP ou domínios que necessitam de acesso diretamente à nossa equipe de suporte. - **Como Solicitar Acesso:** Envie um e-mail para **liberacao@ticto.com.br** com o assunto _"Solicitação de Acesso à API de pagamentos"_, incluindo: - Nome da empresa ou do desenvolvedor - Endereços IP ou domínios a serem autorizados - Justificativa para o acesso - Informações de contato para eventuais esclarecimentos ## Alterações e/ou inclusão de novos domínios e IPs Recomendamos que solicitações de adição ou alteração de IPs/domínios sejam feitas o mais breve possível para garantir uma transição suave. Em casos de alterações, os domínios e/ou IPs anteriores serão imediatamente bloqueados após sua remoção. ## Suporte e Dúvidas Para dúvidas ou suporte adicional, entre em contato conosco através do e-mail **liberacao@ticto.com.br**. Estamos comprometidos em auxiliar neste processo e garantir a melhor experiência possível. servers: - url: https://nexus.ticto.com.br/api/v1 description: Produção security: [] tags: - name: Autenticação - name: Configurações do Cliente - name: Usuários - name: Onboarding de usuário - name: Contas Bancárias - name: Faixas de Taxa description: >- Endpoints para consulta de faixas de taxa personalizadas e histórico de alterações. - name: Frete - name: Financeiro - name: PIX Automático description: >- Consulta, cancelamento e nova tentativa de cobrança de assinaturas com PIX Automático (débito recorrente autorizado pelo pagador). - name: Produtos - name: Integrações - name: 'Webhooks: Usuários' description: Eventos relacionados a cadastro e atualização de usuários. - name: 'Webhooks: Contas Bancárias' description: Eventos relacionados a contas bancárias dos sellers. - name: 'Webhooks: Produtos e Ofertas' description: Eventos relacionados a produtos, ofertas, afiliados e coprodutores. - name: 'Webhooks: Financeiro' description: Eventos de reembolso, saque e antecipação. - name: 'Webhooks: Faixas de Taxa' description: Eventos de criação, atualização e exclusão de faixas de taxa. - name: 'Webhooks: Pedidos' description: Eventos de criação e atualização de pedidos. - name: 'Webhooks: Cobranças' description: >- Eventos de criação e mudança de status de cobranças (transações), na primeira compra e nas renovações. - name: 'Webhooks: Assinaturas' description: Eventos do ciclo de vida de assinaturas, cobranças e trial. paths: /products/{product_hash}/offers: post: tags: - Produtos summary: Criar oferta para produto description: > Cria uma nova oferta para um produto específico. **Campos obrigatórios:** - `price` - Preço da oferta em centavos (valor mínimo aplicável) - `type_of_charge` - Tipo de cobrança ('unique' ou 'recurring') - `allow_credit_card` - Se aceita cartão de crédito - `allow_pix` - Se aceita PIX - `allow_bank_slip` - Se aceita boleto bancário **Campos obrigatórios condicionais:** - `credit_card_installments_options` - Opções de parcelamento (obrigatório se allow_credit_card = true) - `bank_slip_days_due` - Dias para vencimento do boleto (obrigatório se allow_bank_slip = true) - `subscription.interval` - Intervalo da assinatura (obrigatório se type_of_charge = 'recurring') **Campos obrigatórios para produtos físicos (type = 'physical'):** - `quantity_items` - Quantidade de itens disponíveis (1-100 unidades) - Objeto `freight` com os parâmetros de frete descritos no schema `RequestOffer.freight` **Regras de validação:** - Pelo menos um método de pagamento deve estar habilitado - Para assinaturas, cartão de crédito é obrigatório se trial_days > 0 - Para assinaturas, dois cartões de crédito não são permitidos - Preço deve respeitar o valor mínimo da moeda operationId: createProductOffer parameters: - name: product_hash in: path required: true description: Hash do produto schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RequestOffer' responses: '201': description: Oferta criada com sucesso content: application/json: schema: $ref: '#/components/schemas/ResponseOffer' '400': description: Requisição inválida '401': description: Não autorizado '403': description: Acesso negado - produto não pertence ao cliente '404': description: Produto não encontrado '422': description: Payload incorreto '500': description: Erro interno do servidor security: - ApiClientToken: [] - bearerAuth: [] components: schemas: RequestOffer: type: object required: - name - price - allow_pix - allow_credit_card - allow_bank_slip - type_of_charge properties: name: type: string maxLength: 191 description: Nome da oferta. example: Oferta Premium price: type: integer minimum: 0 maximum: 99999999 description: Preço da oferta em centavos. quantity_items: type: integer minimum: 1 maximum: 100 description: | Quantidade de itens disponíveis em estoque. - Obrigatório apenas para produtos do tipo 'physical' - Limite: 1 a 100 unidades - Opcional para produtos digitais (course, ebook) type_of_charge: type: string enum: - one-time - recurring description: Tipo de cobrança. allow_pix: type: boolean description: Se aceita pagamento via PIX avulso. allow_pix_recurring: type: boolean description: > Se aceita PIX Automático (débito recorrente). Necessário para vender a oferta com `payment_method=pix_recurring` no checkout. Só vale para ofertas recorrentes (`type_of_charge=recurring`). Quando `true`, `pix_recurring_frequency` e `pix_recurring_authorization_type` passam a ser obrigatórios. **Pré-requisito: PIX Automático liberado para o produtor.** A liberação é feita pela Ticto na conta do produtor dono do produto e não pode ser feita pela API. Solicite ao seu contato na Ticto (inclusive para o ambiente de sandbox). Enquanto o produtor não estiver liberado, a oferta é salva com `allow_pix_recurring = false` mesmo que a requisição envie `true`: o `POST`/`PUT` responde com sucesso e o valor enviado é ignorado, sem erro. O checkout com `payment_method=pix_recurring` para essa oferta é recusado. Se a liberação do produtor for revogada, o PIX Automático é desligado em todas as ofertas dele. Os campos de PIX Automático não são devolvidos na resposta da oferta (`ResponseOffer`); depois de liberar o produtor, reenvie a configuração da oferta e valide com um checkout `pix_recurring`. pix_recurring_frequency: type: string nullable: true enum: - weekly - biweekly - monthly - quarterly - biannual - annual description: >- Frequência de cobrança do PIX Automático. Obrigatório quando `allow_pix_recurring = true`. example: monthly pix_recurring_authorization_type: type: string nullable: true enum: - monthly_auth_monthly_retry description: >- Tipo de autorização do PIX Automático. Obrigatório quando `allow_pix_recurring = true`. Só a autorização mensal com retentativa mensal é aceita. example: monthly_auth_monthly_retry allow_bank_slip: type: boolean description: Se aceita boleto bancário. allow_bank_slip_installments: type: boolean description: Se permite parcelamento no boleto (somente ofertas não recorrentes). bank_slip_days_due: type: integer minimum: 1 maximum: 7 description: Número de dias para vencimento do boleto. bank_slip_installments_limit: type: integer minimum: 1 maximum: 12 description: Limite máximo de parcelas no boleto. allow_credit_card: type: boolean description: Se aceita pagamento via cartão de crédito. credit_card_installments_options: type: array description: Opções de parcelamento para cartão de crédito. items: type: integer minimum: 1 maximum: 36 allow_affiliates: type: boolean description: Se permite afiliação para esta oferta. custom_commission: type: boolean nullable: true description: >- Se a oferta utiliza comissão personalizada (diferente do padrão do produto). commission_only_first_installment: type: boolean nullable: true description: > Se a comissão do afiliado é calculada apenas sobre a primeira parcela. Aplicável apenas para ofertas recorrentes (`type_of_charge=recurring`). affiliates_subscription_percentage: type: number nullable: true minimum: 1 maximum: 80 description: > Percentual de comissão do afiliado para cobranças recorrentes (renovações). Aplicável apenas para ofertas recorrentes (`type_of_charge=recurring`). transfer_fixed_fee_to_buyer: type: boolean description: > Repassa a taxa fixa da transação (R$2,49) ao comprador. - `true` — o comprador paga a taxa fixa (valor adicionado ao total no checkout) - `false` — o produtor absorve a taxa fixa - Quando não informado na criação, o padrão é `true` allow_smart_installment: type: boolean description: > Habilita parcelamento inteligente no cartão de crédito. Quando `true`, ao recusar o cartão por saldo insuficiente, a Ticto cria automaticamente um parcelamento. Sem juros, valor dividido igualmente, máximo 12 parcelas, mínimo R$5 por parcela. producer_pays_interest: type: boolean nullable: true description: Se o produtor absorve os juros do parcelamento no cartão de crédito. subscription: type: object description: Configurações de assinatura (usar quando type_of_charge=recurring). properties: interval: type: string enum: - weekly - monthly - bimonthly - trimonthly - quarterly - semiannual - yearly - twoyears - threeyears description: >- Intervalo da cobrança recorrente. `quarterly` é alias de `trimonthly` (3 meses). trial_days: type: integer minimum: 0 maximum: 365 description: Dias de teste gratuito. trial_days_text: type: boolean description: Indica se exibe o texto de dias de teste. first_charge_price: type: integer minimum: 0 maximum: 99999999 description: Valor da primeira cobrança em centavos. is_extension: type: boolean description: Indica se a assinatura é uma extensão. extension_length: type: integer minimum: 1 maximum: 36 description: Duração da extensão em meses. max_charges: type: integer minimum: 1 maximum: 12 description: Número máximo de cobranças. max_charges_attempts: type: integer minimum: 1 maximum: 5 description: Tentativas de cobrança por fatura. freight: type: object description: Parâmetros de frete (obrigatório para produtos físicos). required: - type - preparation_day - start_day - end_day properties: type: type: string enum: - shipping_company - fixed - free description: Tipo de frete utilizado. preparation_day: type: integer minimum: 0 description: >- Tempo, em dias úteis, necessário para preparar o pedido antes do envio. start_day: type: integer minimum: 0 description: >- Prazo mínimo estimado de entrega (em dias úteis). Para frete `free`, o valor pode ser 0. end_day: type: integer minimum: 1 description: Prazo máximo estimado de entrega (em dias úteis). fixed_price: type: integer minimum: 1 description: >- Valor fixo do frete em centavos (requerido quando `type = fixed`). free_states: type: array description: Lista de estados (siglas) com frete gratuito. items: type: string pattern: ^[A-Z]{2}$ blocked_states: type: array description: >- Lista de estados (siglas UF, maiúsculas) que não recebem o produto. O checkout será recusado se o estado do cliente estiver nesta lista. items: type: string pattern: ^[A-Z]{2}$ is_pac: type: boolean description: >- Indica se o envio via PAC está habilitado (aplicável apenas quando `type = shipping_company`). pac_fallback_price: type: integer minimum: 1 maximum: 100000 description: >- Valor padrão do frete PAC em centavos (obrigatório quando `is_pac = true`). pac_fallback_end_day: type: integer minimum: 1 maximum: 100 description: >- Prazo padrão do PAC em dias úteis (obrigatório quando `is_pac = true`). is_sedex: type: boolean description: >- Indica se o envio via SEDEX está habilitado (aplicável apenas quando `type = shipping_company`). sedex_fallback_price: type: integer minimum: 1 maximum: 100000 description: >- Valor padrão do frete SEDEX em centavos (obrigatório quando `is_sedex = true`). sedex_fallback_end_day: type: integer minimum: 1 maximum: 100 description: >- Prazo padrão do SEDEX em dias úteis (obrigatório quando `is_sedex = true`). zip_code: type: string pattern: ^\d{8}$ description: CEP de origem utilizado no cálculo (formato numérico sem hífen). weight: type: number format: float minimum: 0.1 maximum: 30 description: >- Peso do produto em quilogramas (apenas quando `type = shipping_company`). length: type: integer minimum: 1 maximum: 100 description: >- Comprimento do pacote em centímetros (apenas quando `type = shipping_company`). width: type: integer minimum: 10 maximum: 100 description: >- Largura do pacote em centímetros (apenas quando `type = shipping_company`). height: type: integer minimum: 1 maximum: 100 description: >- Altura do pacote em centímetros (apenas quando `type = shipping_company`). ResponseOffer: type: object description: Objeto de retorno com os dados da oferta. required: - code - name - type_of_charge - price - allow_credit_card - allow_pix - allow_bank_slip - credit_card_installments_options - created_at - updated_at properties: code: type: string description: Código único da oferta. name: type: string description: Nome da oferta. type_of_charge: type: string enum: - one-time - recurring description: Tipo de cobrança. price: type: integer description: Preço da oferta em centavos. fake_initial_price: type: integer nullable: true description: Preço "de" para exibição de desconto (em centavos). quantity_items: type: integer minimum: 1 maximum: 100 description: Quantidade de itens em estoque (para produtos físicos). allow_credit_card: type: boolean description: Indica se aceita cartão de crédito. credit_card_installments_options: type: array description: Opções de parcelamento no cartão de crédito. items: type: integer minimum: 1 maximum: 36 allow_pix: type: boolean description: Indica se aceita PIX. allow_bank_slip: type: boolean description: Indica se aceita boleto bancário. allow_bank_slip_installments: type: boolean description: Se permite parcelamento no boleto. bank_slip_days_due: type: integer minimum: 1 maximum: 7 description: Número de dias para vencimento do boleto. bank_slip_installments_limit: type: integer minimum: 1 maximum: 12 description: Limite máximo de parcelas no boleto. allow_affiliates: type: boolean description: Se permite afiliação para esta oferta. affiliates_percentage: type: number nullable: true minimum: 1 maximum: 80 description: Percentual de comissão do afiliado. affiliates_subscription_percentage: type: number nullable: true minimum: 1 maximum: 80 description: Percentual de comissão do afiliado para cobranças recorrentes. commission_only_first_installment: type: boolean nullable: true description: Se a comissão é calculada apenas sobre a primeira parcela. producer_pays_interest: type: boolean nullable: true description: Se o produtor paga os juros do parcelamento. is_free: type: boolean nullable: true description: Se a oferta é gratuita (price = 0). transfer_fixed_fee_to_buyer: type: boolean description: > Indica se a taxa fixa da transação (R$2,49) é repassada ao comprador. - `true` — comprador paga a taxa fixa - `false` — produtor absorve a taxa fixa subscription: type: object description: Configurações de assinatura (quando type_of_charge = recurring). required: - interval properties: interval: type: string enum: - weekly - monthly - bimonthly - trimonthly - quarterly - semiannual - yearly - twoyears - threeyears description: >- Intervalo da cobrança recorrente. `quarterly` é alias de `trimonthly` (3 meses). trial_days: type: integer minimum: 0 maximum: 365 description: Dias de teste gratuito. trial_days_text: type: boolean description: Indica se exibe o texto de dias de teste. first_charge_price: type: integer nullable: true description: Valor da primeira cobrança em centavos. is_extension: type: boolean description: Indica se a assinatura é uma extensão. extension_length: type: integer minimum: 1 maximum: 36 description: Duração da extensão em meses. max_charges: type: integer minimum: 1 maximum: 12 description: Número máximo de cobranças. max_charges_attempts: type: integer minimum: 1 maximum: 5 description: Tentativas de cobrança por fatura. freight: type: object description: Informações de frete retornadas para produtos físicos. properties: type: type: string enum: - shipping_company - fixed - free description: Tipo de frete configurado. preparation_day: type: integer description: >- Tempo, em dias úteis, necessário para preparar o pedido antes do envio. start_day: type: integer description: Prazo mínimo estimado de entrega em dias úteis. end_day: type: integer description: Prazo máximo estimado de entrega em dias úteis. fixed_price: type: integer description: Valor fixo do frete em centavos (quando `type = fixed`). free_states: type: array description: Lista de estados (siglas) com frete gratuito. items: type: string blocked_states: type: array description: >- Lista de estados (siglas UF, maiúsculas) que não recebem o produto. O checkout será recusado se o estado do cliente estiver nesta lista. items: type: string is_pac: type: boolean description: Indica se o envio via PAC está habilitado. pac_fallback_price: type: integer description: Valor padrão do PAC em centavos (quando `is_pac = true`). pac_fallback_end_day: type: integer description: Prazo padrão do PAC em dias úteis (quando `is_pac = true`). is_sedex: type: boolean description: Indica se o envio via SEDEX está habilitado. sedex_fallback_price: type: integer description: Valor padrão do SEDEX em centavos (quando `is_sedex = true`). sedex_fallback_end_day: type: integer description: Prazo padrão do SEDEX em dias úteis (quando `is_sedex = true`). zip_code: type: string description: CEP de origem utilizado no cálculo. weight: type: number format: float description: Peso do produto em quilogramas. length: type: number format: float description: Comprimento do pacote em centímetros. width: type: number format: float description: Largura do pacote em centímetros. height: type: number format: float description: Altura do pacote em centímetros. created_at: type: string description: Data de criação (formato `YYYY-MM-DD HH:mm:ss`) example: '2026-01-15 14:30:00' updated_at: type: string description: Data de atualização (formato `YYYY-MM-DD HH:mm:ss`) example: '2026-01-15 14:30:00' securitySchemes: ApiClientToken: type: apiKey in: header name: X-Api-Client-Token description: Token de autenticação do cliente obtido via endpoint /auth bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Token de autenticação do usuário (public_token) obtido na criação do usuário ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.