Trinio Checkout SDK

Documentação para integração do Trinio Checkout SDK em lojas VTEX.

Sumário

Como carregar o SDK
Como inicializar o checkout
Propriedades de inicialização

Como carregar o SDK

Para utilizar o TrinioCheckout no navegador, adicione os seguintes scripts na página da sua loja VTEX:

Script Tags

Adicione as tags no <head> ou no final do <body> da sua página HTML:

HTML

<!-- CSS do Trinio Checkout -->
<link
  rel="stylesheet"
  type="text/css"
  href="https://cdn.trinio.co/static/css/style.css"
/>

<!-- SDK do Trinio Checkout -->
<script src="https://cdn.trinio.co/static/plugin-vtex-sdk/latest/trinio-plugin-vtex-sdk.iife.js"></script>

<!-- Utilização do Trinio Checkout -->
<script>
  const checkout = window.TrinioCheckout.createCheckout('MERCHANT_ID', {...})
</script>

Carregamento dinâmico (Alternativo)

Caso prefira carregar os scripts dinamicamente via JavaScript, utilize o exemplo abaixo com callback de onReady:

JavaScript

(function() {
  const BASE_URL = 'cdn.trinio.co'

  function loadTrinioCheckout(onReady) {
    // Carrega o CSS
    const linkStylesheet = document.createElement('link')
    linkStylesheet.rel = 'stylesheet'
    linkStylesheet.type = 'text/css'
    linkStylesheet.href = `https://${BASE_URL}/static/css/style.css`
    document.head.appendChild(linkStylesheet)

    // Carrega o SDK
    const script = document.createElement('script')
    script.src = `https://${BASE_URL}/static/plugin-vtex-sdk/latest/trinio-plugin-vtex-sdk.iife.js`
    script.onload = function() {
      onReady(window.TrinioCheckout)
    }
    document.body.appendChild(script)
  }

  // Uso com callback
  loadTrinioCheckout(function(trinioCheckout) {
    console.log('Trinio Checkout pronto para uso!', trinioCheckout)
  })
})()

Como inicializar o checkout

A função createCheckout cria a instância do Trinio Checkout, permitindo utilizá-lo em qualquer página da sua loja VTEX. Esta instância deve ser criada e inicializada somente uma única vez na página.

Dica

Verifique a tabela de propriedades de inicialização para preencher as propriedades corretamente.

Exemplo básico

JavaScript

const props = {
  vtexAccountName: 'trinio',
  vtexEndpointAPI: 'https://vtex.trinio.dev/api/vtexid',
  vtexPublicEndpoint: 'myvtex.com',
  vtexWorkspace: 'master',
  onErrorFallback: (error) => {
    console.error('Erro no checkout Trinio:', error)
    // Caso ocorra algum erro durante a jornada no checkout,
    // é possível realizar alguma ação nesta callback (ex: redirecionar para o checkout nativo VTEX)
  },
  // outras props aqui...
}

// Cria a instância do checkout
const checkout = window.TrinioCheckout.createCheckout('YOUR_MERCHANT_ID', props)

// Inicia o app (iniciar somente uma única vez na página)
const app = await checkout.startApp()

// Caso o app não esteja habilitado, crie um fallback se necessário (ex: redirecionar para o checkout nativo VTEX)
if (app.enabled) {
  // O checkout pode ser aberto utilizando a função `open()` (ex: abrir no click de um botão)
  const result = await app.open({ orderFormId: 'YOUR_VTEX_ORDER_FORM_ID' })

  // Verifica se houve erro ao abrir o checkout
  if (result.error) {
    // Caso ocorra erro de abertura de checkout, crie um fallback se necessário (ex: redirecionar para o checkout nativo VTEX)
    console.error('Erro ao abrir checkout:', result.error)
  }
}

Tipos de retorno

A função startApp() retorna um objeto com a seguinte estrutura:

TypeScript

// Quando habilitado
{
  enabled: true,
  open: (args: { orderFormId: string }) => Promise<{ error?: Error }>,
  getCachedOrderForm: () => Readonly<VTEXCart> | undefined
}

// Quando não habilitado
{
  enabled: false,
  error?: Error
}

open: Abre o checkout Trinio para o orderFormId fornecido.
getCachedOrderForm: Retorna o orderForm VTEX em cache no momento da chamada. Retorna undefined caso o orderForm ainda não esteja disponível.

Propriedades de inicialização

A função createCheckout recebe dois parâmetros:

merchantId (string) - ID do merchant fornecido pela Trinio
props (objeto) - Objeto com as propriedades de configuração

Propriedades

`trinioVisitorId`

Identificador opaco de visitante usado para manter a mesma variante de A/B testing entre o /v1/orders-api/vtex/cart/simulation/ (simulação do carrinho) e o /v1/orders-api/router/ (decisão de roteamento no checkout). Sem ele, o usuário pode cair em variantes diferentes nos dois endpoints e ver opções de frete inconsistentes entre o carrinho e o pedido final.

Como obter o valor: o backend retorna esse valor no header x-trinio-visitor-id da response do /v1/orders-api/vtex/cart/simulation/. Consulte a seção Visitor ID e consistência A/B da Simulation API.

Opcional: quando não fornecido, o plugin mantém a consistência da variante internamente. Ainda assim, recomendamos fornecer sempre que possível, especialmente em integrações server-side que chamam ambos os endpoints. Não use identificadores pessoais (customer ID, e-mail, CPF, etc.).

Tipo	Obrigatório	Valor Padrão
`string`	Não	`undefined`

`vtexAccountName`

Onde encontrar

Copiar o valor do checkout nativo da VTEX acessando: window.vtex.accountName

Tipo	Obrigatório	Valor Padrão
`string`	Sim	—

`vtexEndpointAPI`

Onde encontrar

Copiar o valor do checkout nativo da VTEX acessando: window.vtex.endpointAPI

Tipo	Obrigatório	Valor Padrão
`string`	Sim	—

`vtexPublicEndpoint`

Onde encontrar

Copiar o valor do checkout nativo da VTEX acessando: window.vtex.renderRuntime.publicEndpoint

Tipo	Obrigatório	Valor Padrão
`string`	Sim	—

`vtexWorkspace`

Onde encontrar

Copiar o valor do checkout nativo da VTEX acessando: window.vtex.renderRuntime.workspace

Tipo	Obrigatório	Valor Padrão
`string`	Sim	—

`onErrorFallback`

Callback disparada quando ocorre algum erro no checkout durante a jornada do shopper. Ex: redirecionar o shopper para o checkout nativo da VTEX.

Tipo	Obrigatório	Valor Padrão
`(error: unknown) => Promise<void> \| void`	Sim	—

`vtexLeanShipping`

Tipo	Obrigatório	Valor Padrão
`string`	Não	`undefined`

`vtexCallcenter`

Tipo	Obrigatório	Valor Padrão
`Record<any, any>`	Não	`undefined`

`getVtexDeviceFingerprint`

Callback disparada para obter o device fingerprint durante o pagamento.

Tipo	Obrigatório	Valor Padrão
`() => Promise<string \| number \| undefined>`	Não	`undefined`

`vtexShowInstallmentsPreviewValue`

Exibe o preview do valor das parcelas no checkout.

Tipo	Obrigatório	Valor Padrão
`boolean`	Não	`undefined`

`trackBeginCheckout`

Callback disparada ao abrir o checkout. Ex: integrar com o Google Analytics. Caso a callback não seja implementada, nenhum evento será disparado.

Tipo	Obrigatório	Valor Padrão
`(args: { orderForm: VTEXCart \| undefined }) => Promise<void>`	Não	`undefined`

`trackAddShippingInfo`

Callback disparada ao selecionar um método de entrega. Ex: integrar com o Google Analytics. Caso a callback não seja implementada, nenhum evento será disparado.

Tipo	Obrigatório	Valor Padrão
`(args: { orderForm: VTEXCart \| undefined }) => Promise<void>`	Não	`undefined`

`trackAddPaymentInfo`

Callback disparada ao submeter o formulário de pagamento. Ex: integrar com o Google Analytics. Caso a callback não seja implementada, nenhum evento será disparado.

Tipo	Obrigatório	Valor Padrão
`(args: { orderForm: VTEXCart \| undefined }) => Promise<void>`	Não	`undefined`

`getSellerCode`

Callback disparada para obter o código do vendedor no checkout. Utilize para implementar sua própria lógica.

Tipo	Obrigatório	Valor Padrão
`(vtexCart: VTEXCart) => string \| Promise<string>`	Não	`undefined`

`hasMultiplesCoupons`

Habilita o suporte a múltiplos cupons de desconto.

Tipo	Obrigatório	Valor Padrão
`boolean`	Não	`false`

`defaultCashbackProvider`

Provedor de cashback padrão utilizado no checkout.

Onde encontrar

Copiar o valor do checkout nativo da VTEX acessando: window.TRINIO_PLUGIN_CONFIG.options.defaultCashbackProvider

Tipo	Obrigatório	Valor Padrão
`string`	Não	`undefined`