Guia do desenvolvedor

​

Idempotência

• Use um UUID v4 ou um identificador de negócio único (por exemplo, o ID do pedido no seu sistema)
• Comprimento máximo: 255 caracteres, formados por letras, dígitos, ., _ e -
• O plugin dá a cada chave o escopo da organização efetiva. A mesma chave vinda de duas organizações conta como duas requisições distintas.
• O plugin repete uma resposta de sucesso por 7 dias. A repetição traz o mesmo código de status e o mesmo corpo, mais o header X-Idempotency-Replayed: true.
• Uma resposta 4xx não consome a chave: corrija a requisição e envie de novo com a mesma chave.
• Depois de uma resposta 5xx, o resultado é desconhecido: leia o recurso primeiro e envie a requisição de novo apenas com uma nova chave. Uma chave que a resposta bloqueou (X-Idempotency-Fenced: true) é recusada com 422 BTF-0014. Uma resposta 503 BTF-9000 ou 503 BTF-9017 não executou nada: envie a requisição de novo com a mesma chave.
• A mesma chave com um corpo diferente é recusada com 422 BTF-0017. Um novo envio enquanto a primeira requisição ainda está em execução recebe 409 BTF-0016 com Retry-After.
• Cada recusa de idempotência informa sua solução em detail. Leia-a antes de enviar de novo.

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

​

Detecção de duplicatas

• senderAccountId
• dados do destinatário (ISPB, agência, conta, documento do titular)
• valor
• finalidade

​

Estratégia de novas tentativas

​

Tratamento de estado

​

Máquina de estados da TED OUT

​

Máquina de estados da iniciação

​

Máquina de estados da TED IN

​

Máquina de estados do P2P

​

Polling vs. webhooks

​

Integração de webhook

​

Validação da assinatura

• X-Webhook-Signature: assinatura HMAC-SHA256 versionada no formato v1,sha256=<hex>
• X-Webhook-Timestamp: timestamp Unix em segundos (UTC) de quando o plugin montou a requisição
• X-Webhook-Event: o tipo do evento (por exemplo, transfer.completed). Este header não faz parte da assinatura.

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

1. Leia X-Webhook-Signature e X-Webhook-Timestamp nos headers da requisição.
2. Monte a string assinada: "v1:" + timestamp + "." + rawBody.
3. Calcule HMAC-SHA256 sobre a string assinada com o signingSecret do registro do webhook e codifique o resultado em hexadecimal.
4. Coloque v1,sha256= na frente e compare com X-Webhook-Signature usando uma função de igualdade de tempo constante.
5. Rejeite a requisição se o timestamp estiver fora de uma janela de validade aceitável (uma tolerância de 5 minutos é típica) para evitar replay.

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

const TOLERANCE_SECONDS = 300; // 5 minutes

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.TED_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 minutes

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 minutes

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))
}

​

Processamento idempotente de webhook

const alreadyProcessed = await db.webhookEvents.exists({
  transferId: payload.transferId,
  event: req.headers['x-webhook-event'],
  status: payload.status, // return events of a TED IN
  reconciliationReasonCode: payload.reconciliationReasonCode,
});

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

​

Padrões de tratamento de erros

{
  "type": "https://errors.lerian.studio/v1/BTF-0010",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "transfers can only be initiated Monday-Friday between 06:30 and 17:00 America/Sao_Paulo time",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "BTF-0010",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin",
  "category": "deterministic",
  "currentTime": "2026-01-21T18:30:00-03:00",
  "nextAvailableTime": "2026-01-22T06:30:00-03:00",
  "openTime": "06:30",
  "closeTime": "17:00",
  "timezone": "America/Sao_Paulo"
}

​

Checklist de entrada em produção

• Envie X-Idempotency em cada requisição de initiate, process e cancel
• Lógica de nova tentativa implementada com backoff exponencial para erros 5xx/503
• Endpoint de webhook com o deploy feito e retornando 200 em até 5 segundos
• Validação de assinatura ativa no endpoint de webhook
• Deduplicação de eventos de webhook implementada com transferId + event
• Horário de funcionamento validado no cliente antes de chamar initiate (reduz 422 desnecessários)
• transferId e confirmationNumber armazenados para conciliação
• Estados terminais (COMPLETED, REJECTED, FAILED, CANCELLED) tratados na interface
• Expiração da iniciação tratada (expiresAt): peça ao usuário para recomeçar quando ela passar
• Readiness do serviço monitorada no seu sistema de alertas para deploys BYOC
• Redis acessível e monitorado: o serviço rejeita requisições quando o Redis está fora
• PLUGIN_AUTH_ENABLED=true configurado em produção, com um PLUGIN_AUTH_ADDRESS válido (HTTPS)