SelectwinSelectwin

Cria um produto

POST/v1/products

Autentique com o header SelectKey: a chave sk_test_ opera no sandbox, a sk_live_ em produção. Como autenticar.

Corpo da requisição

  • namestringobrigatório

    Nome do produto (o slug é derivado dele).

  • typestringobrigatório

    physical (enviado), digital ou other.

    Valores:physicaldigitalother
  • fiscalobjectpode ser nulo

    Perfil fiscal do produto; null limpa.

    +10 campos de fiscal
    • nbsstring

      Código NBS, 9 dígitos (serviço).

    • ncmstring

      Código NCM, 8 dígitos (mercadoria).

    • ceststring

      Código CEST, 7 dígitos (mercadoria com substituição tributária).

    • gtinstring

      GTIN/EAN — 8, 12, 13 ou 14 dígitos.

    • kindstring

      service emite NFS-e, goods emite NF-e. Omitido: um produto physical é mercadoria, os outros são serviço.

      Valores:servicegoods
    • unitstring

      Unidade comercial (UN, KG, CX…).

    • origininteger

      Origem da mercadoria (tabela A do ICMS, 0 a 8; 0 = nacional).

    • cClassTribstring

      Classificação tributária do IBS/CBS (cClassTrib, 6 dígitos).

    • serviceCodestring

      Item da lista de serviços da LC 116 (01.07 ou 0107).

    • cityServiceCodestring

      Código do serviço na sua prefeitura.

  • imagesstring (uri)[]

    URLs de imagem. Para anexar um arquivo, envie-o antes (POST /v1/assets/uploads e depois a confirmação) e mande a URL do arquivo.

  • enabledboolean

    Se o produto está à venda.

  • categorystringobrigatório

    Categoria, texto livre.

  • languagestring

    Idioma do produto (ex.: pt-BR).

  • variantsobject[]obrigatório

    As variantes (1 a 100). A primeira é a principal.

    +10 campos de variants
    • skustring

      O seu SKU.

    • namestringobrigatório

      Nome da variante.

    • fiscalobjectpode ser nulo

      O que a variante muda no perfil fiscal do produto; null limpa.

      +10 campos de fiscal
      • nbsstring

        Código NBS, 9 dígitos (serviço).

      • ncmstring

        Código NCM, 8 dígitos (mercadoria).

      • ceststring

        Código CEST, 7 dígitos (mercadoria com substituição tributária).

      • gtinstring

        GTIN/EAN — 8, 12, 13 ou 14 dígitos.

      • kindstring

        service emite NFS-e, goods emite NF-e. Omitido: um produto physical é mercadoria, os outros são serviço.

        Valores:servicegoods
      • unitstring

        Unidade comercial (UN, KG, CX…).

      • origininteger

        Origem da mercadoria (tabela A do ICMS, 0 a 8; 0 = nacional).

      • cClassTribstring

        Classificação tributária do IBS/CBS (cClassTrib, 6 dígitos).

      • serviceCodestring

        Item da lista de serviços da LC 116 (01.07 ou 0107).

      • cityServiceCodestring

        Código do serviço na sua prefeitura.

    • imagesstring (uri)[]

      URLs de imagem. Para anexar um arquivo, envie-o antes (POST /v1/assets/uploads e depois a confirmação) e mande a URL do arquivo.

    • enabledboolean

      Se a variante está à venda.

    • pricingobjectobrigatório

      Preço e modelo de cobrança da variante.

      +22 campos de pricing
      • typestring

        oneTime (uma venda) ou recurring (um plano de assinatura).

        Valores:oneTimerecurring
      • tiersobject[]

        As faixas de preço (schema=tiered), em ordem crescente de upTo.

        +3 campos de tiers
        • upTointegerpode ser nulo

          Limite superior da faixa (unidades); null = sem limite (a última faixa).

        • flatPriceintegerpode ser nulo

          Valor fixo somado quando a faixa é atingida, em centavos.

        • unitPriceintegerobrigatório

          Preço unitário dentro da faixa, em centavos.

      • cyclesintegerpode ser nulo

        Número de ciclos até a assinatura acabar; null = até ser cancelada.

      • schemastring

        Como o preço é calculado: unit (preço × quantidade), tiered (por faixas de quantidade) ou package (por bloco de unidades).

        Valores:unittieredpackage
      • currencystring

        Código de moeda ISO 4217

      • oldPriceinteger

        O preço antes de um desconto, em centavos — mostrado riscado.

      • daysTrialinteger

        Duração do período de teste de um plano recorrente, em dias.

      • tiersModestring

        graduated: cada faixa precifica as próprias unidades; volume: a faixa atingida precifica todas as unidades.

        Valores:graduatedvolume
      • unitPriceinteger

        Preço unitário, em centavos (mínimo 500 em unit; não usado em tiered).

      • usageTypestring

        licensed (quantidade fixa) ou metered (cobrado pelo uso que você reporta).

        Valores:licensedmetered
      • billingTypestring

        Quando um ciclo é cobrado: prepaid (no início), postpaid (no fim) ou exactday (em billingExactDay).

        Valores:prepaidpostpaidexactday
      • costPerIteminteger

        O seu custo por unidade, em centavos (para os seus relatórios de margem).

      • trialIntervalstring

        Unidade da duração do teste.

        Valores:dayweekmonthyear
      • meterEventNamestring

        Nome do medidor de uso que você reporta (só metered).

      • billingExactDayinteger

        Dia do mês em que o ciclo é cobrado (billingType=exactday).

      • renewalShippingboolean

        Planos recorrentes: cobrar o frete cotado no checkout em CADA renovação (padrão true).

      • billingFrequencystring

        Unidade do intervalo de cobrança.

        Valores:dailyweeklymonthlyyearly
      • usageAggregationstring

        Como os registros de uso de um ciclo são agregados: sum, max, lastDuringPeriod ou lastEver.

        Valores:summaxlastDuringPeriodlastEver
      • transformQuantityobject

        Em schema=package: quantas unidades formam um bloco, e como um bloco parcial é arredondado.

        +2 campos de transformQuantity
        • roundstring

          Como um bloco parcial é arredondado.

          Valores:updown
        • divideByintegerobrigatório

          Unidades por bloco.

      • trialIntervalCountinteger

        Duração do teste, em unidades de trialInterval.

      • billingFrequencyCountinteger

        Quantas unidades de billingFrequency por ciclo.

      • renewalMethodDiscountboolean

        Planos recorrentes: estender o desconto do meio de pagamento do checkout às renovações cobradas pelo mesmo meio (padrão false).

    • metadataobject

      Objeto JSON livre — no máximo 50 chaves, chaves de até 40 caracteres, cada valor com até 500 caracteres (o JSON dele, quando não é texto), o objeto inteiro com até 8192 bytes em JSON.

    • attributesobject

      Atributos livres da variante (tamanho, cor…).

    • descriptionstring

      Descrição.

    • externalReferencestring

      O seu próprio identificador da variante.

  • salesPagestring

    URL da página de vendas.

  • descriptionstring

    Descrição.

  • warrantyDaysintegerobrigatório

    Garantia oferecida ao comprador, em dias (7 a 3650).

  • externalReferencestring

    O seu próprio identificador do produto.

Respostas

201Criado
  • idstringobrigatório

    Identificador público (prd_/pro_…)

  • namestringobrigatório

    Nome do produto.

  • slugstringobrigatóriopode ser nulo

    Slug, derivado do nome.

  • typestringobrigatório

    physical, digital ou other.

    Valores:physicaldigitalother
  • fiscalobjectobrigatóriopode ser nulo

    Perfil fiscal do produto; null quando não há.

    +10 campos de fiscal
    • nbsstring

      Código NBS (serviço).

    • ncmstring

      Código NCM (mercadoria).

    • ceststring

      Código CEST (mercadoria).

    • gtinstring

      GTIN/EAN.

    • kindstring

      service (NFS-e) ou goods (NF-e).

      Valores:servicegoods
    • unitstring

      Unidade comercial.

    • origininteger

      Origem da mercadoria (0 a 8).

    • cClassTribstring

      Classificação tributária do IBS/CBS.

    • serviceCodestring

      Item da lista de serviços da LC 116.

    • cityServiceCodestring

      Código do serviço na sua prefeitura.

  • imagesum de[]obrigatóriopode ser nulo

    URLs das imagens; null quando não há.

  • enabledbooleanobrigatório

    Se o produto está à venda.

  • categorystringobrigatório

    Categoria.

  • languagestringobrigatóriopode ser nulo

    Idioma do produto.

  • salesQtyintegerobrigatóriopode ser nulo

    Número de vendas do produto; null quando desconhecido.

  • variantsobject[]obrigatório

    As variantes do produto.

    +17 campos de variants
    • idstringobrigatório

      Identificador público (var_/prv_…)

    • skustringobrigatóriopode ser nulo

      O seu SKU; null quando não há.

    • namestringobrigatóriopode ser nulo

      Nome da variante.

    • slugstringobrigatóriopode ser nulo

      Slug da variante.

    • fiscalobjectobrigatóriopode ser nulo

      O que a variante muda no perfil fiscal do produto; null = nada.

      +10 campos de fiscal
      • nbsstring

        Código NBS (serviço).

      • ncmstring

        Código NCM (mercadoria).

      • ceststring

        Código CEST (mercadoria).

      • gtinstring

        GTIN/EAN.

      • kindstring

        service (NFS-e) ou goods (NF-e).

        Valores:servicegoods
      • unitstring

        Unidade comercial.

      • origininteger

        Origem da mercadoria (0 a 8).

      • cClassTribstring

        Classificação tributária do IBS/CBS.

      • serviceCodestring

        Item da lista de serviços da LC 116.

      • cityServiceCodestring

        Código do serviço na sua prefeitura.

    • imagesum de[]obrigatóriopode ser nulo

      URLs das imagens; null quando não há.

    • enabledbooleanobrigatório

      Se a variante está à venda.

    • pricingobjectobrigatório

      Preço e modelo de cobrança da variante.

      +22 campos de pricing
      • typestringobrigatório

        oneTime (uma venda) ou recurring (um plano de assinatura).

        Valores:oneTimerecurring
      • tiersanypode ser nulo

        As faixas de preço; null fora de tiered.

      • cyclesintegerobrigatóriopode ser nulo

        Número de ciclos até a assinatura acabar; null = até ser cancelada.

      • schemastringobrigatório

        Como o preço é calculado: unit, tiered ou package.

        Valores:unittieredpackage
      • currencystringobrigatório

        Moeda (ISO 4217).

      • oldPriceintegerobrigatóriopode ser nulo

        O preço antes de um desconto, em centavos; null quando não há.

      • daysTrialintegerobrigatóriopode ser nulo

        Duração do período de teste, em dias; null quando não há.

      • tiersModestringobrigatóriopode ser nulo

        graduated ou volume; null fora de tiered.

      • unitPriceintegerobrigatóriopode ser nulo

        Preço unitário, em centavos; null em tiered.

      • usageTypestringobrigatório

        licensed ou metered.

      • billingTypestringobrigatóriopode ser nulo

        Quando um ciclo é cobrado: prepaid, postpaid ou exactday; null em venda avulsa.

      • costPerItemintegerobrigatóriopode ser nulo

        O seu custo por unidade, em centavos; null quando não definido.

      • trialIntervalstringobrigatóriopode ser nulo

        Unidade da duração do teste; null quando não há.

      • meterEventNamestringobrigatóriopode ser nulo

        Nome do medidor de uso; null fora de metered.

      • billingExactDayintegerobrigatóriopode ser nulo

        Dia do mês em que o ciclo é cobrado; null quando não é fixo.

      • renewalShippingbooleanobrigatório

        Planos recorrentes: se o frete cotado no checkout é cobrado em cada renovação.

      • billingFrequencystringobrigatóriopode ser nulo

        Unidade do intervalo de cobrança; null em venda avulsa.

      • usageAggregationstringobrigatóriopode ser nulo

        Como o uso é agregado; null fora de metered.

      • transformQuantityanypode ser nulo

        Unidades por bloco e arredondamento; null fora de package.

      • trialIntervalCountintegerobrigatóriopode ser nulo

        Duração do teste, em unidades de trialInterval; null quando não há.

      • billingFrequencyCountintegerobrigatóriopode ser nulo

        Quantas unidades por ciclo; null em venda avulsa.

      • renewalMethodDiscountbooleanobrigatório

        Planos recorrentes: se o desconto do meio de pagamento do checkout se estende às renovações.

    • primarybooleanobrigatório

      Se é a variante principal do produto.

    • metadataobjectobrigatóriopode ser nulo

      Os seus metadados chave-valor; null quando não há.

    • createdAtstringobrigatório

      Quando o recurso foi criado (ISO 8601, UTC).

    • productIdstringobrigatório

      O produto a que a variante pertence.

    • updatedAtstringobrigatório

      Quando o recurso foi atualizado pela última vez (ISO 8601, UTC).

    • attributesobjectobrigatóriopode ser nulo

      Atributos livres da variante; null quando não há.

    • checkoutUrlstringobrigatóriopode ser nulo

      URL do checkout hospedado desta variante; null quando não há.

    • descriptionstringobrigatóriopode ser nulo

      Descrição; null quando não há.

    • externalReferencestringobrigatóriopode ser nulo

      O seu próprio identificador da variante; null quando não há.

  • createdAtstringobrigatório

    Quando o recurso foi criado (ISO 8601, UTC).

  • salesPagestringobrigatóriopode ser nulo

    URL da página de vendas; null quando não há.

  • updatedAtstringobrigatório

    Quando o recurso foi atualizado pela última vez (ISO 8601, UTC).

  • descriptionstringobrigatóriopode ser nulo

    Descrição; null quando não há.

  • warrantyDaysintegerobrigatório

    Garantia oferecida ao comprador, em dias.

  • imageAssetIdsanypode ser nulo

    Ids dos arquivos de imagem; null quando não há.

  • externalReferencestringobrigatóriopode ser nulo

    O seu próprio identificador do produto; null quando não há.

400Requisição inválida (validação)
  • errorobjectobrigatório
    +8 campos de error
    • codestringobrigatório
    • paramsobject[]
    • statusstringobrigatório
    • detailsstring
    • messagestringobrigatório
    • categorystringobrigatório
      Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
    • resourcestringobrigatório
    • statusCodeintegerobrigatório
401Não autenticado (credencial ausente ou inválida)
  • errorobjectobrigatório
    +8 campos de error
    • codestringobrigatório
    • paramsobject[]
    • statusstringobrigatório
    • detailsstring
    • messagestringobrigatório
    • categorystringobrigatório
      Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
    • resourcestringobrigatório
    • statusCodeintegerobrigatório
403Sem permissão
  • errorobjectobrigatório
    +8 campos de error
    • codestringobrigatório
    • paramsobject[]
    • statusstringobrigatório
    • detailsstring
    • messagestringobrigatório
    • categorystringobrigatório
      Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
    • resourcestringobrigatório
    • statusCodeintegerobrigatório
409Conflito (idempotência ou estado)
  • errorobjectobrigatório
    +8 campos de error
    • codestringobrigatório
    • paramsobject[]
    • statusstringobrigatório
    • detailsstring
    • messagestringobrigatório
    • categorystringobrigatório
      Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
    • resourcestringobrigatório
    • statusCodeintegerobrigatório
500Erro interno do servidor
  • errorobjectobrigatório
    +8 campos de error
    • codestringobrigatório
    • paramsobject[]
    • statusstringobrigatório
    • detailsstring
    • messagestringobrigatório
    • categorystringobrigatório
      Valores:validationauthenticationauthorizationpaymentclientserverrate_limitpending
    • resourcestringobrigatório
    • statusCodeintegerobrigatório
AnteriorLista os produtosPróximaConsulta um produto

Preferências de cookies

Hoje o site usa só cookies essenciais: nenhuma ferramenta de medição ou de anúncios está ligada, e nada é compartilhado com terceiros. Se isso mudar, você decide aqui antes de qualquer coisa ser carregada.

  • Essenciais

    Mantêm o site funcionando: segurança, a sua escolha sobre cookies e preferências como a versão da documentação. Não dependem de consentimento.

    Sempre ativos
Política de privacidade