@zolve/integration-gateway

SDK TypeScript para o Integration Gateway. Centraliza o acesso a Bling, Shopify e Yampi usando uma unica API key.

Características

• Inicialização explícita – initialize() carrega dados do gateway e cria os clientes
• Clientes tipados – Reutiliza Bling de @zolve/bling, Yampi de @zolve/yampi e Shopify via @shopify/admin-api-client
• Rate limiting e tokens – Gerenciados pelo Integration Gateway; não é necessário implementar retry/backoff no SDK

Instalação

bun add @zolve/integration-gateway

Uso rápido

import { IntegrationGatewaySDK } from '@zolve/integration-gateway'

const sdk = new IntegrationGatewaySDK({
  // opcional: se omitido, usa INTEGRATION_GATEWAY_BASE_URL
  // e depois fallback para https://ig.zolve.com.br/api/v1
  baseURL: 'https://api.seudominio.com',
  // opcional: se omitido, usa INTEGRATION_GATEWAY_API_KEY
  apiKey: process.env.INTEGRATION_GATEWAY_API_KEY!,
})

await sdk.initialize()

const bling = sdk.getBlingByCompanyId('77c6d8af7481552f823f729b91f8dcca')
const shopify = sdk.getShopifyByShopDomain('minha-loja')
const yampi = sdk.getYampiByAlias('minha-loja')

// Bling
const orders = await bling.getOrders({ limite: 50, pagina: 1 })

// Shopify (GraphQL)
const result = await shopify.request(`#graphql
  query {
    shop { name }
  }
`)

// Yampi
const yampiOrders = await yampi.orders.get()

API do SDK

| Método | Retorno | Descrição | |--------|---------|-----------| | initialize() | Promise<void> | Uma chamada a /integration-access/bootstrap carrega credenciais e cria os clientes. Obrigatório antes de usar os getters. | | getBlingByCompanyId(companyId) | Bling | Cliente Bling para o companyId. Lança se o companyId não for encontrado. | | getShopifyByShopDomain(shopDomain) | AdminApiClient | Cliente oficial Shopify Admin API buscando pelo shop domain. Aceita com ou sem .myshopify.com. | | getYampiByAlias(alias) | Yampi | Cliente Yampi para o alias. Lança se o alias não for encontrado. |

Configuração do construtor:

interface IntegrationGatewaySDKConfig {
  baseURL?: string // 1) construtor, 2) INTEGRATION_GATEWAY_BASE_URL, 3) https://ig.zolve.com.br/api/v1
  apiKey?: string  // 1) construtor, 2) INTEGRATION_GATEWAY_API_KEY
}

Também é válido instanciar sem parâmetros:

const sdk = new IntegrationGatewaySDK()

Nesse caso:

• baseURL usa INTEGRATION_GATEWAY_BASE_URL ou, se ausente, https://ig.zolve.com.br/api/v1
• apiKey deve vir de INTEGRATION_GATEWAY_API_KEY

Exemplos por integração

Bling (pedidos, contatos, notas fiscais)

Os métodos disponíveis são os do cliente @zolve/bling. Exemplos:

const bling = sdk.getBlingByCompanyId('77c6d8af7481552f823f729b91f8dcca')

const orders = await bling.getOrders({
  limite: 100,
  pagina: 1,
  dataInicial: '2024-01-01',
  dataFinal: '2024-12-31',
})

const order = await bling.getOrderById(12345678)
const invoices = await bling.getInvoices({ limite: 100, situacao: 1 })
const contact = await bling.getContactById(12345678)

await bling.updateOrderStatus(12345678, 9)
await bling.updateOrder(12345678, { observacoes: 'Atualizado via API' })
await bling.updateContact(12345678, { nome: 'João', email: '[email protected]' })

Shopify (Admin API)

O retorno de getShopifyByShopDomain é um AdminApiClient oficial. Use GraphQL:

const shopify = sdk.getShopifyByShopDomain('minha-loja')
// ou
const shopify = sdk.getShopifyByShopDomain('minha-loja.myshopify.com')

const result = await shopify.request(`#graphql
  query {
    products(first: 10) {
      edges {
        node {
          id
          title
        }
      }
    }
  }
`)

Yampi (pedidos, catálogo, cupons)

O retorno de getYampiByAlias é uma instância de Yampi configurada para falar com o gateway. Os módulos da Yampi continuam disponíveis normalmente:

const yampi = sdk.getYampiByAlias('minha-loja')

const orders = await yampi.orders.get()
const product = await yampi.catalogProducts.getById(12345)
const promocodes = await yampi.pricingPromocodes.get()

Tratamento de erros

• Configuração ausente (construtor/env):
  • Integration Gateway baseURL is required. Provide it via constructor or INTEGRATION_GATEWAY_BASE_URL.
  • Integration Gateway apiKey is required. Provide it via constructor or INTEGRATION_GATEWAY_API_KEY.
• Não inicializado: IntegrationGatewaySDK not initialized. Call initialize() first.
• Sem acesso ao companyId/domain/alias: No Bling access for companyId <id>, No Shopify access for shop domain <domain>, No Yampi access for alias <alias>
• Falha na inicialização: Failed to initialize Integration Gateway SDK: <motivo>

Erros HTTP (401, 429, etc.) vêm das chamadas internas (axios); trate no seu fluxo conforme a resposta.

Documentação para agentes/LLMs

• llms.txt – Guia curto para descoberta por agentes/LLMs.
• llms-full.txt – Referência técnica detalhada do SDK.

Tipos exportados

O pacote exporta:

• IntegrationGatewaySDK (classe)
• IIntegrationGatewaySDK (interface)
• Bling, BlingOAuth (re-export de @zolve/bling)
• Yampi (re-export de @zolve/yampi)

Tipos de pedidos, contatos, notas fiscais etc. vêm do pacote @zolve/bling; tipos específicos da Yampi vêm de @zolve/yampi. Importe de lá quando precisar.

Segurança

• Não commite API keys no código; use variáveis de ambiente.
• Use sempre HTTPS para o baseURL.
• Mantenha as API keys restritas ao ambiente (dev/staging/prod).

Desenvolvimento

bun install
bun run build
bun test

Licença

Apache-2.0 com restrição Commons Clause: o software não pode ser utilizado para fins comerciais. Ver LICENSE no repositório.