Trinio
Documentação

Trinio.js SDK

Documentação para integração com os serviços da Trinio através do Trinio.js SDK.

Sumário

  1. Como carregar o SDK
  2. Inicialização
  3. visitor.getId()
  4. vtex.cartSimulate()
  5. Tratamento de erros

Como carregar o SDK

Para utilizar o Trinio.js no navegador, adicione o script na página da sua loja. Após o carregamento, a API fica disponível em window.Trinio.SDK.

Script Tags

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

HTML
<!-- SDK Trinio.js -->
<script src="https://cdn.trinio.co/static/trinio-js/latest/trinio.iife.js"></script>

<!-- Utilização -->
<script>
  window.Trinio.SDK.init({ merchantId: 'YOUR_MERCHANT_ID' })
</script>

Carregamento dinâmico (Alternativo)

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

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

  function loadTrinioJs(onReady) {
    const script = document.createElement('script')
    script.src = `https://${BASE_URL}/static/trinio-js/latest/trinio.iife.js`
    script.onload = function () {
      onReady(window.Trinio.SDK)
    }
    document.body.appendChild(script)
  }

  // Uso com callback
  loadTrinioJs(function (sdk) {
    console.log('Trinio.js pronto para uso!', sdk)
  })
})()

Inicialização

Antes de chamar qualquer método, inicialize o SDK com o seu merchantId. Basta fazer isso uma única vez na página.

JavaScript
window.Trinio.SDK.init({ merchantId: 'YOUR_MERCHANT_ID' })
ParâmetroTipoObrigatórioDescrição
merchantIdstringSimID do merchant fornecido pela Trinio
Dica

Chamar um método antes de init (ou com um merchantId vazio) lança um TrinioConfigError. Inicialize o SDK o quanto antes no carregamento da página.

visitor.getId()

Retorna um identificador de visitante estável (UUID v4). Na primeira chamada o valor é gerado no client e persistido em localStorage; nas chamadas seguintes o mesmo valor é retornado. É o identificador enviado no header x-trinio-visitor-id das chamadas à API da Trinio.

TypeScript
window.Trinio.SDK.visitor.getId(): Promise<string>
JavaScript
const visitorId = await window.Trinio.SDK.visitor.getId()
// ex: "f47ac10b-58cc-4372-a567-0e02b2c3d479"

O cartSimulate já chama visitor.getId() internamente — você só precisa usar este método diretamente se quiser obter o id por conta própria (ex.: para propagá-lo em outras integrações).

Consistência A/B

Esse identificador mantém o usuário na mesma variante de testes A/B entre a simulação e o checkout. Veja Visitor ID e consistência A/B na Simulation API.

vtex.cartSimulate()

Simula um carrinho VTEX a partir da Trinio, retornando a resposta original da simulação VTEX junto com as opções de frete geradas pelo motor de roteamento. O SDK injeta automaticamente os headers x-trinio-merchant-id (do init) e x-trinio-visitor-id (do visitor.getId()), e reconcilia o visitor id em cache caso o servidor devolva um valor diferente.

TypeScript
window.Trinio.SDK.vtex.cartSimulate(req): Promise<{
  cartSimulation: VtexCartSimulateResponse
  shippingMethods: VtexShippingMethod[]
  visitorId: string
}>

Exemplo

JavaScript
const result = await window.Trinio.SDK.vtex.cartSimulate({
  cartSimulation: {
    items: [{ id: '1234', quantity: '1', seller: '1' }],
    postalCode: '22071060',
    country: 'BRA',
  },
})

console.log(result.shippingMethods) // opções de frete
console.log(result.visitorId)       // id usado na chamada

Parâmetro req

A estrutura do req é a mesma do corpo da requisição da Simulation API. Consulte o Request Body da Simulation API para a lista completa de campos (incluindo clientProfileData para promoções cluster-based e leanShipping).

CampoTipoObrigatórioDescrição
cartSimulationobjectSimCarrinho a simular (items, postalCode, country, ...). Ver Simulation API.
leanShippingbooleanNãoRetorna no máximo a opção mais rápida e a mais econômica. Default: false.

Retorno

CampoTipoDescrição
cartSimulationobjectResposta original da simulação VTEX, sem modificações.
shippingMethodsarrayOpções de frete geradas pelo motor de roteamento. Ver Campos da Response.
visitorIdstringIdentificador de visitante usado na chamada (ecoado ou emitido pelo servidor).

Tratamento de erros

Os métodos do SDK lançam classes de erro tipadas. Use instanceof ou a propriedade code para tratá-las.

ErrocodeQuando ocorre
TrinioConfigErrortrinio_configinit não foi chamado, ou o merchantId é inválido/vazio.
TrinioApiErrortrinio_apiA API respondeu com erro HTTP. Inclui status e problem (detalhes).
TrinioNetworkErrortrinio_networkA requisição falhou na rede (sem resposta do servidor).
TrinioTimeoutErrortrinio_timeoutA requisição excedeu o tempo limite (10s por padrão).
JavaScript
try {
  const result = await window.Trinio.SDK.vtex.cartSimulate({
    cartSimulation: {
      items: [{ id: '1234', quantity: '1', seller: '1' }],
      postalCode: '22071060',
      country: 'BRA',
    },
  })
} catch (error) {
  if (error.code === 'trinio_api') {
    console.error('Erro da API:', error.status, error.problem)
  } else {
    console.error('Falha na simulação:', error)
  }
}
Usando o Trinio Checkout SDK?

O id de visitor.getId() pode ser passado na prop trinioVisitorId do createCheckout para manter a mesma variante A/B do carrinho até o checkout.