Guia do desenvolvedor TED

​

Idempotência

• Use um UUID v4 ou um identificador de negócio único (ex: o ID interno do seu pedido)
• Comprimento máximo: 255 caracteres
• As chaves têm escopo por organização — a mesma chave de duas organizações diferentes é tratada como duas requisições distintas
• As respostas em cache são retornadas por 24 horas

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

​

Detecção de duplicatas

​

Estratégia de retry

​

Gerenciamento de estado

​

Máquina de estados do TED OUT

​

Máquina de estados da iniciação

​

Máquina de estados do TED IN

​

Máquina de estados do P2P

​

Polling vs. webhooks

​

Integração com webhooks

​

Validação de assinatura

X-Signature: sha256=a1b2c3d4e5f6...

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

function validateWebhook(rawBody, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  const receivedSignature = signature.replace('sha256=', '');

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(receivedSignature)
  );
}

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

    if (!validateWebhook(req.body, signature, process.env.WEBHOOK_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

def validate_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    received = signature.replace('sha256=', '')

    return hmac.compare_digest(expected, received)

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strings"
)

func validateWebhook(payload []byte, signature, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(payload)
    expected := hex.EncodeToString(mac.Sum(nil))
    received := strings.TrimPrefix(signature, "sha256=")
    return hmac.Equal([]byte(expected), []byte(received))
}

​

Processamento idempotente de webhooks

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

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

​

Padrões de tratamento de erros

{
  "error": {
    "code": "BTF-0010",
    "message": "Transfers can only be initiated Monday-Friday between 06:30 and 17:00 Brasília time",
    "fields": {
      "currentTime": "2026-01-21T18:30:00-03:00",
      "nextAvailableTime": "2026-01-22T06:30:00-03:00"
    }
  }
}

​

Checklist para entrar em produção

• X-Idempotency é enviado em cada requisição de initiate, process e cancel
• Lógica de retry implementada com backoff exponencial para erros 5xx/503
• Endpoint de webhook implantado e retornando 200 em até 5 segundos
• Validação de assinatura ativa no endpoint de webhook
• Deduplicação de eventos de webhook implementada usando transferId + event
• Horários de funcionamento validados no lado do cliente antes de chamar initiate (reduz 422s desnecessários)
• Tanto transferId quanto confirmationNumber armazenados para reconciliação
• Estados terminais (COMPLETED, REJECTED, FAILED, CANCELLED) tratados na UI
• Expiração da iniciação (24h) tratada — o usuário é solicitado a reiniciar se a janela encerrar
• GET /health/ready monitorado no seu sistema de alertas para deployments BYOC
• Redis está disponível e monitorado — o serviço não aceitará requisições se o Redis estiver inacessível
• PLUGIN_AUTH_ENABLED=true configurado em produção, com PLUGIN_AUTH_ADDRESS, PLUGIN_AUTH_CLIENT_ID e PLUGIN_AUTH_CLIENT_SECRET válidos