@nhvbeauty/tpl

SDK TypeScript para integração com a API da TPL (https://oms.tpl.com.br/api).

Instalação

npm install @nhvbeauty/tpl

Uso rápido

import { Tpl } from '@nhvbeauty/tpl'

const client = new Tpl()

const auth = await client.auth.login({
  apikey: 'SUA_API_KEY',
  token: 'SEU_TOKEN',
  email: '[email protected]',
})

const authedClient = new Tpl(auth.token)

Cliente

const client = new Tpl(authToken?, baseUrl?)

• authToken (opcional): token retornado em auth.login.
• baseUrl (opcional): padrão https://oms.tpl.com.br/api.

Módulos disponíveis

auth

login(body)

Endpoint: POST /get/auth

const result = await client.auth.login({
  apikey: 'SUA_API_KEY',
  token: 'SEU_TOKEN',
  email: '[email protected]',
})

orders

find(params)

Endpoint: POST /get/orderdetail

Aceita um dos formatos:

• { id: number | bigint }
• { number: string }

const byId = await client.orders.find({ id: 12345 })
const byNumber = await client.orders.find({ number: 'PED-12345' })

shipping

validateZipcode(params)

Endpoint: POST /get/valid-zipcode

Payload:

• { zipcode: string }

const zipcode = await client.shipping.validateZipcode({
  zipcode: '13270000',
})

Resposta de sucesso:

{
  "code": 200,
  "message": "Sucesso",
  "dados": [
    {
      "cidade": "Valinhos",
      "logradouro": "",
      "bairro": "Centro",
      "uf": "SP"
    }
  ]
}

Quando o CEP não é encontrado, a API responde 404 (ex.: { "code": 404, "message": "CEP nao encontrado" }) e o SDK lança erro.

getFreight(params)

Endpoint: POST /get/freight

Payload nesta versão:

• identification?: string
• to: string
• weight: number (gramas)
• value: number (valor do pedido sem frete)

const freight = await client.shipping.getFreight({
  identification: '12345678901',
  to: '13270000',
  weight: 1200,
  value: 199.9,
})

Resposta (exemplo real):

[
  {
    "shipmentCompany": "Loggi (4 dias)",
    "deadline": 4,
    "value": "9.90",
    "originalvalue": "8.20",
    "region": "INTERIOR",
    "observation": "",
    "safe": 0,
    "cost": 0,
    "safecost": 0,
    "role": "0",
    "extra": 0,
    "extraWeight": "0",
    "extraValue": "0.00",
    "icms": 0.88,
    "iss": "0",
    "aplicou": 0,
    "weightVolume": 15,
    "weightm3": -1,
    "shipmentId": "3",
    "state": "SP",
    "cubageFactor": "167.00"
  }
]

Observação: no retorno de frete, campos numéricos podem vir como string ou number dependendo da regra aplicada pela API.

Tratamento de erros

Para respostas HTTP fora de 2xx, o SDK lança erro contendo:

• message
• statusCode
• response (quando retornado pela API)

try {
  await client.shipping.validateZipcode({ zipcode: '00000000' })
}
catch (error: any) {
  console.error(error.statusCode)
  console.error(error.response)
}