TypeScript SDK

@retorna-tech/retorna-gateway-sdk (npm, 1.0.4) se distribuye como ESM y CJS a la vez, con tipos de TypeScript nativos — no hace falta instalar un paquete @types aparte. Se encarga del intercambio de token, la firma de requests, los reintentos y los headers de identidad, y te devuelve modelos tipados en cada llamada.

Instalación

Requiere Node >=18.18.0.

pnpm add @retorna-tech/retorna-gateway-sdk
# or
npm install @retorna-tech/retorna-gateway-sdk
# or
yarn add @retorna-tech/retorna-gateway-sdk

Construir un cliente

Renombrado en 1.0.1

El builder es RetornaClientBuilder, el mismo nombre que usan los SDK de Python y Java. El anterior RetornaTypeScriptSDKConfigBuilder sigue funcionando como alias deprecado y desaparece en 2.0.

import {
  RetornaClientBuilder,
  RetornaEnvironment,
} from "@retorna-tech/retorna-gateway-sdk";

const client = new RetornaClientBuilder()
  .environment(RetornaEnvironment.SANDBOX)
  .clientId(process.env.RETORNA_CLIENT_ID!)
  .clientSecret(process.env.RETORNA_CLIENT_SECRET!)
  .privateKey(process.env.RETORNA_PRIVATE_KEY!) // PEM RSA, newlines intact
  .buildClient();

const me = await client.getMyClient();
console.log(me.client.name, me.client.isActive);

Variable	Qué contiene
`RETORNA_CLIENT_ID`	Client ID emitido durante el aprovisionamiento.
`RETORNA_CLIENT_SECRET`	Client secret emitido durante el aprovisionamiento.
`RETORNA_PRIVATE_KEY`	Clave privada RSA en formato PEM usada para firmar cada request — mantén los saltos de línea intactos.

getMyClient() lee la compañía asociada a tus credenciales — no hay ownerId que pasar, el token ya viene con ese alcance. buildClient() es la llamada terminal: devuelve el cliente listo para usar. Si falta un campo obligatorio, el builder lanza una excepción antes de hacer cualquier llamada de red.

Configuración

Opción	Método	Obligatorio	Default	Notas
Ambiente	`.environment(env)`	Sí	—	`RetornaEnvironment.DEVELOP \| SANDBOX \| PRODUCTION`
Client ID	`.clientId(value)`	Sí	—	Emitido durante el aprovisionamiento
Client secret	`.clientSecret(value)`	Sí	—	Emitido durante el aprovisionamiento
Clave privada	`.privateKey(value)`	Sí	—	Clave RSA usada para firmar cada request
Scope	`.scope(value)`	No	Default del ambiente	Sobrescribe el scope de OAuth2 pedido
Base URL override	`.baseUrlOverride(url)`	No	Default del ambiente	Tiene que empezar con `https://`
Nivel de logging	`.loggingLevel(level)`	No	—	Uno de `none`, `error`, `warn`, `info`, `debug`
Deshabilitar logging	`.disableLogging()`	No	Logging habilitado	Apaga por completo el logger propio del SDK
Reintentos	`.retries(count)`	No	`3`	Intentos ante fallas transitorias
Backoff	`.backoffMs(ms)`	No	`200`	Backoff base entre reintentos, en milisegundos

Toda cadena termina en .buildClient().

Ambientes

enum RetornaEnvironment {
  DEVELOP = "develop",
  SANDBOX = "sandbox",
  PRODUCTION = "production",
}

Todos los ejemplos de esta página corren contra RetornaEnvironment.SANDBOX, que resuelve a https://api.gateway.sandbox.retorna.app. Producción resuelve a https://api.gateway.retorna.app. DEVELOP es de uso interno solamente.

Headers de identidad

Cada request que manda el SDK lleva X-Retorna-Client: typescript-sdk/1.0.4 y un User-Agent que carga el mismo dato, así la plataforma — y nuestro equipo de soporte, si alguna vez lo necesitas — puede saber qué SDK y qué versión hizo la llamada.

Autenticación y firma

El SDK consigue y cachea tu token de OAuth2, y firma cada request con tu clave privada — nunca tocas el endpoint de token ni construyes el string de firma a mano. Consulta autenticación y firma de solicitudes para ver qué pasa por detrás.

Objetos

Cada método está documentado en detalle — firma, parámetros, modelo de retorno y errores — en su propia página de objeto:

Cotizaciones fijan un tipo de cambio, comisiones y montos resultantes para un corredor antes de que te comprometas a enviar — createQuotation y getQuotation.

Órdenes consumen una cotización y ejecutan un pago a un beneficiario nombrado — createOrder, listOrders y getOrder.

Rutas listan los corredores disponibles hoy para tu compañía, con su tipo de cambio, comisiones y límites — getRoutes.

Wallets guarda el balance en USDR que financia tus órdenes — getMyWallet y getMyWalletTransactions.

Cliente es el registro de tu propia compañía tal como lo ve la API — getMyClient.

Cotizar y enviar

const quotation = await client.createQuotation({
  source: { currency: "USDR" },
  destination: {
    country: "VE",
    currency: "VES",
    payout_method: { type: "P2P_PHONE_TRANSFER" },
  },
  quote: { mode: "SEND_EXACT", amount: "10.00" },
});

const order = await client.createOrder(
  {
    quotation_id: quotation.id,
    purpose: "FAMILY_SUPPORT",
    sender: {
      names: "Ana María",
      last_names: "Pérez Gómez",
      document: { type: "CC", id: "1020304050", country: "CO" },
      country: "CO",
    },
    destination: {
      receiver: {
        names: "Carlos Andrés",
        last_names: "Rodríguez López",
        document: { type: "V", id: "12345678", country: "VE" },
        email: "[email protected]",
        country: "VE",
      },
      payment_instructions: {
        bank_phone_account: {
          bank_name: "BNC_VE",
          phone_number: "+584121234567",
          document_id: "12345678",
        },
      },
    },
  },
  "invoice-2026-00456", // idempotency key — comes back as order.idempotency_key
);

console.log(order.id, order.status, order.idempotency_key);

Una cotización se fija con createQuotation, y después la consume exactamente un createOrder — consulta cotizaciones y órdenes para cada campo, error y detalle a tener en cuenta, incluyendo la semántica de la clave de idempotencia y el catálogo cerrado detrás de bank_name.

Errores

import { RetornaB2BError, RetornaSdkError } from "@retorna-tech/retorna-gateway-sdk";

try {
  await client.createOrder(request, "invoice-2026-00456");
} catch (err) {
  if (err instanceof RetornaB2BError) {
    console.error(err.code, err.category, err.httpStatus, err.correlationId);

    if (err.code === "B2B_QUOTATION_EXPIRED") return requote();
    if (err.category === "TRANSIENT") return retryWithSameKey();
    throw err; // PERMANENT — fix the request first
  }

  if (err instanceof RetornaSdkError) {
    console.error(err.context, err.message); // local validation or transport
  }
  throw err;
}

RetornaB2BError es el sobre de error tipado de la API; RetornaSdkError cubre todo lo demás que el propio SDK atrapa — una validación fallida del builder, o una respuesta que nunca llegó a tener esa forma de sobre. El catálogo completo de códigos vive en códigos de error, y las distintas formas que puede tomar un cuerpo de error están explicadas en manejo de errores. Un reintento de createOrder solo es seguro con la misma clave de idempotencia del intento original.

Reportes

El SDK también expone un cliente de reportes completo — crear, listar, descargar y programar generaciones y entregas de reportes. Queda fuera del alcance de esta página; consulta el repositorio del SDK para su README y sus definiciones de tipos.

Próximos pasos

Cada endpoint que envuelve el SDK tiene un ejemplo completo de request/response y un panel "Try it" en la Referencia de API.
¿Prefieres HTTP crudo? El quickstart recorre las mismas llamadas sin el SDK.

Instalación​

Construir un cliente​

Configuración​

Ambientes​

Autenticación y firma​

Objetos​

Cotizar y enviar​

Errores​

Reportes​

Próximos pasos​