Avisar que mandaste los USDT

POST/prefondeos/{id}/envioProbar

ServidorURL base

API key x-api-keyRecordar la clave en este navegador (localStorage, no sale de aquí)

Parámetros de rutaidstringobligatorio

CabecerasIdempotency-KeyÚnico por operación. El alcance es tu cuenta **y el modo** de la key: una `sk_test_` y una `sk_live_` no comparten keys. Dura 24 h. Reintentar con la misma key y payload devuelve la respuesta original, con el mismo código HTTP y la cabecera `Idempotent-Replayed: true`; con otro payload da `409 idempotency_key_reused`. Los campos secretos (el `url` de una gift card, una `apiKey` nueva, un `webhookSecret`) sólo llegan en la primera respuesta: al repetir llegan en `null`.

Cuerpo de la petición (JSON)

La llamada la hace tu navegador, contra el servidor que elijas arriba. Si la documentación no está servida desde el mismo origen que la API, el navegador puede bloquear la respuesta por CORS: en ese caso abre estas páginas desde la propia API (/docs) o usa el curl de arriba.

POST

/prefondeos/{id}/envio

const url = 'http://localhost:3000/v1/prefondeos/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/envio';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: '{"referencia":"example","montoUsdt":1,"direccionOrigen":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://localhost:3000/v1/prefondeos/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/envio \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "referencia": "example", "montoUsdt": 1, "direccionOrigen": "example" }'

Scope prefondeos:write. Exige Idempotency-Key. El hash de la transacción y los micro-USDT enviados, antes de venceEn. Desde aquí el ticket espera a nuestro equipo: una persona confirma la llegada en la red y otra aprueba la carga. Te llega prefondeo.cargado (o prefondeo.rechazado) por webhook. Si llega menos de lo cotizado se cargan los Bs proporcionales a la misma tasa; si llega más, sólo lo cotizado. Sólo se carga si el USDT salió de una de tus wallets de origen activas: lo comprueba nuestro equipo con el from de la transferencia en el explorador. Si salió de una wallet sin registrar, el ticket espera 72 h con su tasa (te llega prefondeo.origen_no_registrado): registra esa wallet y, cuando la aprobemos, se carga; si no, se rechaza y la devolución se coordina contigo fuera del sistema.

Authorizations

ApiKeyAuth

Parameters

Path Parameters

required

string format: uuid

Header Parameters

Idempotency-Key

string

Único por operación. El alcance es tu cuenta y el modo de la key: una sk_test_ y una sk_live_ no comparten keys. Dura 24 h. Reintentar con la misma key y payload devuelve la respuesta original, con el mismo código HTTP y la cabecera Idempotent-Replayed: true; con otro payload da 409 idempotency_key_reused. Los campos secretos (el url de una gift card, una apiKey nueva, un webhookSecret) sólo llegan en la primera respuesta: al repetir llegan en null.

Request Body^required

application/json

object

referencia

required

Hash de la transacción, con o sin 0x. Lo guardamos en minúsculas y sin 0x, así que ABC…, abc… y 0xabc… son el mismo hash. En TRC20 son 64 caracteres hexadecimales. Sin : ni _.

string

/^[A-Za-z0-9-]{6,130}$/

montoUsdt

required

Micro-USDT enviados

integer

>= 1

direccionOrigen

Opcional. La wallet desde la que mandaste: tiene que ser una de tus wallets de origen activas (si no, 422). No aprueba nada: lo que vale es el from que ve nuestro equipo.

string

/^[A-Za-z0-9]{20,64}$/

Example^generated

{
  "referencia": "example",
  "montoUsdt": 1,
  "direccionOrigen": "example"
}

Responses

200

Ticket en enviado

application/json

Un ticket de prefondeo. Montos en minor units como texto: micro-USDT (6 decimales) y céntimos de Bs. Tasas en Bs por 1 USDT con 8 decimales.

object

string format: uuid

estado

cotizado → enviado (avisaste) → recibido (nuestro equipo lo vio en la red) → cargado (otra persona aprobó: tienes los Bs) → consumido (saldo en 0; vuelve a cargado si se revierte un pago). vencido si no avisaste a tiempo; rechazado si lo cancelaste o no llegó.

string

Allowed values: cotizado enviado recibido cargado consumido vencido rechazado

origen

pruebas: tu prefondeo de pruebas, ya cargado con Bs simulados (sin wallet)

string

Allowed values: cotizado manual excedente pruebas

red

Red donde se reciben los USDT

string

direccion

Wallet de recepción (la fija nuestro equipo). null en tu cuenta de pruebas o con una sk_test_

string

nullable

activo

string

Allowed values: USDT

usdtCotizado

string

bsCotizado

string

tasa

Tasa amarrada (con spread)

string

tasaMercado

string

nullable

spreadBps

integer

venceEn

string format: date-time

nullable

referencia

string

nullable

usdtEnviado

string

nullable

enviadoEn

string format: date-time

nullable

usdtRecibido

string

nullable

recibidoEn

string format: date-time

nullable

recibidoTarde

Llegó en la red después de venceEn; se cargó a la tasa de ese momento

boolean

tasaAplicada

La tasa con la que se cargaron los Bs

string

nullable

usdtCargado

string

nullable

bsCargado

string

nullable

usdtExcedente

USDT que llegaron de más (no se cargan en este ticket)

string

excedenteDestino

string

nullable

Allowed values: ticket_nuevo devuelto_fuera

saldoBs

Bs que le quedan al ticket

string

usdtConsumido

Costo en USDT de lo ya gastado

string

cargadoEn

string format: date-time

nullable

motivoRechazo

string

nullable

simulado

Cargado desde la cuenta de pruebas: no es dinero real

boolean

direccionOrigen

El from de la transferencia que anotó nuestro equipo (una de tus wallets de origen)

string

nullable

walletOrigenId

Tu wallet de origen registrada

string format: uuid

nullable

esperaWalletHasta

El USDT llegó desde una wallet sin registrar: el ticket espera hasta aquí (72 h, con su tasa) a que la registres y la aprobemos

string format: date-time

nullable

caducaEn

Sólo tu prefondeo de pruebas: a esta hora se cierra su saldo simulado (te llega prefondeo.vencido)

string format: date-time

nullable

creadoEn

string format: date-time

actualizadoEn

string format: date-time

Example

{
  "estado": "cotizado",
  "origen": "cotizado",
  "activo": "USDT",
  "excedenteDestino": "ticket_nuevo"
}

400

validation_failed (la referencia no tiene el formato de un hash de esa red), wallet_origen_invalida o wallet_origen_red_no_soportada (la direccionOrigen)

application/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

404

prefondeo_not_found

409

prefondeo_estado_invalido o referencia_duplicada (ese hash ya está en otro ticket, en mayúsculas, minúsculas o con 0x)

application/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

422

prefondeo_vencido (cotiza otro ticket) o wallet_origen_no_registrada (la direccionOrigen no es una de tus wallets de origen activas)

application/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

Avisar que mandaste los USDT

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Examplegenerated

Responses

200

Example

400

Example

404

409

Example

422

Example

Request Body^required

Example^generated