Guía del desarrollador

​

Idempotencia

• Usa un UUID v4 o un identificador de negocio único (por ejemplo, tu ID de orden interno)
• Longitud máxima: 255 caracteres
• Las claves tienen alcance según la organización efectiva — la misma clave de dos organizaciones diferentes se trata como dos solicitudes distintas
• Las respuestas en caché se devuelven durante la ventana de idempotencia configurada (IDEMPOTENCY_RETRY_WINDOW_SEC, por defecto 300 segundos)
• Las respuestas reemitidas son byte-idénticas a la original (mismo código de estado y mismo body); la respuesta no expone actualmente un header para distinguir replays de ejecuciones nuevas, así que diseña tu cliente para ser seguro en cualquier caso

POST /v1/transfers/initiate
X-Organization-Id: 019c9ac2-3f5d-7df9-9215-bdccc1451def
X-Idempotency: 7f3d9a1b-4e2c-4f8a-b3d1-9e6f2a4c8b7e

​

Detección de duplicados

• senderAccountId
• los datos del destinatario (ISPB, agencia, cuenta, documento del titular)
• el monto
• el propósito

​

Estrategia de reintentos

​

Manejo de estados

​

Máquina de estados de TED OUT

​

Máquina de estados de iniciación

​

Máquina de estados de TED IN

​

Máquina de estados de P2P

​

Polling vs. webhooks

​

Integración de webhooks

​

Validación de firma

• X-Webhook-Signature — firma HMAC-SHA256 versionada en el formato v1,sha256=<hex>
• X-Webhook-Timestamp — timestamp Unix en segundos (UTC) de cuando el plugin construyó la solicitud
• X-Webhook-Event — el tipo de evento (por ejemplo, transfer.completed); no forma parte de la firma

X-Webhook-Signature: v1,sha256=hex(HMAC_SHA256(WEBHOOK_SIGNING_SECRET, "v1:" + <timestamp> + "." + <raw_body>))

1. Lee X-Webhook-Signature y X-Webhook-Timestamp de los headers de la solicitud.
2. Construye el payload firmado: "v1:" + timestamp + "." + rawBody.
3. Calcula HMAC-SHA256 sobre el payload firmado usando tu WEBHOOK_SIGNING_SECRET y codifica el resultado en hex.
4. Antepón v1,sha256= y compara contra X-Webhook-Signature usando una función de igualdad de tiempo constante.
5. Rechaza la solicitud si el timestamp está fuera de una ventana de frescura aceptable (una tolerancia de 5 minutos es típica) para prevenir replay.

const crypto = require('crypto');
const express = require('express');

const TOLERANCE_SECONDS = 300; // 5 minutos

function validateWebhook(rawBody, timestamp, signature, secret) {
  if (!timestamp || !signature) return false;

  const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - parseInt(timestamp, 10));
  if (Number.isNaN(ageSeconds) || ageSeconds > TOLERANCE_SECONDS) return false;

  const signedPayload = Buffer.concat([
    Buffer.from('v1:', 'utf8'),
    Buffer.from(timestamp, 'utf8'),
    Buffer.from('.', 'utf8'),
    rawBody,
  ]);

  const expected = 'v1,sha256=' + crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  const expectedBuf = Buffer.from(expected);
  const receivedBuf = Buffer.from(signature);
  if (expectedBuf.length !== receivedBuf.length) return false;

  return crypto.timingSafeEqual(expectedBuf, receivedBuf);
}

// Use raw body — not req.body (parsed JSON)
app.post('/webhooks/ted',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const timestamp = req.headers['x-webhook-timestamp'];
    const signature = req.headers['x-webhook-signature'];

    if (!validateWebhook(req.body, timestamp, signature, process.env.WEBHOOK_SIGNING_SECRET)) {
      return res.status(401).send('Invalid signature');
    }

    const payload = JSON.parse(req.body.toString());
    // process payload...
    res.status(200).send('OK');
  }
);

import hmac
import hashlib
import time

TOLERANCE_SECONDS = 300  # 5 minutos

def validate_webhook(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    if not timestamp or not signature:
        return False

    try:
        age = abs(int(time.time()) - int(timestamp))
    except ValueError:
        return False
    if age > TOLERANCE_SECONDS:
        return False

    signed_payload = b"v1:" + timestamp.encode() + b"." + raw_body
    expected = "v1,sha256=" + hmac.new(
        secret.encode(),
        signed_payload,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strconv"
    "time"
)

const toleranceSeconds = 300 // 5 minutos

func validateWebhook(rawBody []byte, timestamp, signature, secret string) bool {
    if timestamp == "" || signature == "" {
        return false
    }

    ts, err := strconv.ParseInt(timestamp, 10, 64)
    if err != nil {
        return false
    }
    if diff := time.Now().Unix() - ts; diff < -toleranceSeconds || diff > toleranceSeconds {
        return false
    }

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte("v1:"))
    mac.Write([]byte(timestamp))
    mac.Write([]byte("."))
    mac.Write(rawBody)
    expected := "v1,sha256=" + hex.EncodeToString(mac.Sum(nil))

    return hmac.Equal([]byte(expected), []byte(signature))
}

​

Procesamiento idempotente de webhooks

const alreadyProcessed = await db.webhookEvents.exists({
  transferId: payload.transferId,
  event: payload.type,
});

if (alreadyProcessed) {
  return res.status(200).send('OK'); // acknowledge without reprocessing
}

​

Patrones de manejo de errores

{
  "error": {
    "code": "BTF-0010",
    "service": "plugin",
    "category": "deterministic",
    "message": "Transfers can only be initiated Monday-Friday between 06:30 and 17:00 Brasília time",
    "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
    "fields": {
      "currentTime": "2026-01-21T18:30:00-03:00",
      "nextAvailableTime": "2026-01-22T06:30:00-03:00"
    }
  }
}

​

Lista de verificación para salida en producción

• X-Idempotency se envía en cada solicitud de initiate, process y cancel
• Lógica de reintentos implementada con backoff exponencial para errores 5xx/503
• Endpoint de webhook desplegado y devolviendo 200 en menos de 5 segundos
• Validación de firma activa en el endpoint de webhook
• Deduplicación de eventos de webhook implementada usando transferId + event
• Horario de funcionamiento validado en el lado del cliente antes de llamar a initiate (reduce los 422 innecesarios)
• Tanto transferId como confirmationNumber almacenados para reconciliación
• Estados terminales (COMPLETED, REJECTED, FAILED, CANCELLED) gestionados en la interfaz
• Expiración de iniciación (24h) manejada — se solicita al usuario que reinicie si la ventana expira
• Readiness del servicio monitoreado en tu sistema de alertas para despliegues BYOC
• Redis está disponible y monitoreado — el servicio no aceptará solicitudes si Redis es inalcanzable
• PLUGIN_AUTH_ENABLED=true configurado en producción, con un PLUGIN_AUTH_ADDRESS válido (HTTPS)