Como enviar uma TED via API

Para enviar uma TED a partir de uma conta da sua empresa, use o endpoint POST /api/v1/ted.

info

Sua aplicação precisa do scope TED_POST e a empresa precisa da funcionalidade TED. Veja Primeiros passos com a API de TED.

Referência completa

Para o schema, parâmetros e exemplos interativos, veja a API Reference.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`correlationID`	string	sim	Seu identificador da TED. No máximo 20 caracteres e sem espaços. Veja Reenvio seguro.
`value`	number	sim	Valor em centavos, inteiro e maior que zero
`accountId`	string	sim	Conta de origem, de `GET /api/v1/account`
`receiver`	object	sim	Quem recebe a TED (veja abaixo)
`moveDate`	string	não	Data de liquidação, `YYYY-MM-DD`. Padrão: hoje
`clientFinality`	number	não	Finalidade da transferência. Padrão: `10` (crédito em conta). Veja Finalidade
`description`	string	não	Descrição livre
`schedule`	boolean	não	Reservado. Hoje, com o STR fechado, a TED é recusada com `422` (`OUTSIDE_STR_SESSION`) mesmo com `schedule: true`

`receiver`

Campo	Tipo	Descrição
`name`	string	Nome do titular
`document`	string	CPF ou CNPJ, só dígitos
`ispb`	string	ISPB da instituição, 8 dígitos
`agency`	number	Agência, sem o dígito
`account`	number	Número da conta
`accountType`	string	`CACC` conta corrente, `SVGS` poupança, `SLRY` conta salário

O correlationID é curto

O correlationID vai para o STR como número de controle da operação, por isso aceita no máximo 20 caracteres. Um UUID (36 caracteres) é recusado com 400.

Finalidade (`clientFinality`)

A finalidade é o código FinlddCli do BACEN que a TED leva ao STR. É por ele que o banco recebedor classifica o crédito (salário, fornecedor, imposto...). Sem clientFinality, a TED vai como 10.

Código	Finalidade
`1`	Pagamento de impostos, tributos e taxas
`2`	Pagamento a concessionárias de serviço público
`3`	Pagamento de dividendos
`4`	Pagamento de salários
`5`	Pagamento de fornecedores
`6`	Pagamento de honorários
`7`	Pagamento de aluguéis e taxas de condomínio
`8`	Pagamento de duplicatas e títulos
`9`	Pagamento de mensalidade escolar
`10`	Crédito em conta
`100`	Depósito judicial
`101`	Pensão alimentícia

Qualquer outro valor é recusado com 400 (INVALID_REQUEST_BODY).

Exemplo de requisição

{
  "correlationID": "payout-20260203-1",
  "value": 150050,
  "accountId": "6290ccfd42831958a405debc",
  "moveDate": "2026-02-03",
  "receiver": {
    "name": "Joao da Silva",
    "document": "12345678901",
    "ispb": "87654321",
    "agency": 4321,
    "account": 98765,
    "accountType": "CACC"
  },
  "clientFinality": 10,
  "description": "Pagamento de serviços"
}

Exemplo de resposta

Se a TED foi aceita, o status code é 200 e o corpo traz o objeto ted:

{
  "ted": {
    "correlationID": "payout-20260203-1",
    "nuop": "1234567820260203000001",
    "status": "PROCESSING",
    "type": "PAYMENT",
    "direction": "OUT",
    "value": 150050,
    "moveDate": "2026-02-03",
    "accountId": "6290ccfd42831958a405debc",
    "sender": {
      "name": "Empresa LTDA",
      "document": "12345678000199",
      "ispb": "12345678",
      "agency": 1234,
      "account": 567890,
      "accountType": "CACC"
    },
    "receiver": {
      "name": "Joao da Silva",
      "document": "12345678901",
      "ispb": "87654321",
      "agency": 4321,
      "account": 98765,
      "accountType": "CACC"
    },
    "errorCode": null,
    "reason": null,
    "bcbCode": null,
    "createdAt": "2026-02-03T14:30:00.000Z",
    "updatedAt": "2026-02-03T14:30:00.000Z"
  }
}

200 não quer dizer que o dinheiro chegou

A resposta confirma que a TED foi aceita. A liquidação é confirmada pelo webhook TED_OUT_CONFIRMED, e a falha pelo TED_OUT_REJECTED. Veja Webhooks de TED.

O nuop (Número Único de Operação) é o identificador da TED no SPB, gerado pela Woovi. Guarde-o para conciliar com o extrato e para falar com o suporte.

Reenvio seguro com o mesmo `correlationID`

Reenviar com um correlationID que já existe não cria outra TED: a resposta é 200 com a TED que já existe, sem um segundo débito e sem uma segunda mensagem ao STR. Assim, se a requisição der timeout ou a conexão cair, reenvie com o mesmo correlationID sem risco de pagar duas vezes.

Um correlationID por TED

A TED existente é devolvida como está, mesmo que o reenvio traga outro valor ou outro recebedor, e o novo corpo é ignorado. Para uma TED nova, use um correlationID novo.

Códigos de resposta

Todo erro traz o errorCode e o error (veja Erros).

Status	`errorCode`	Quando
`200`	—	TED aceita, ou reenvio de um `correlationID` existente
`400`	`INVALID_REQUEST_BODY`	Corpo inválido: campo faltando, tipo errado, `correlationID` com mais de 20 caracteres ou com espaços, `clientFinality` fora da tabela. O detalhe de cada campo vem em `errors`
`400`	`INVALID_CORRELATION_ID`	`correlationID` com mais de 20 caracteres
`401`	—	AppID ausente ou inválido
`403`	`TED_FEATURE_REQUIRED`	Empresa sem a funcionalidade `TED`
`403`	`ACCOUNT_NOT_OWNED`	A conta de origem é de outra empresa
`403`	—	Aplicação sem o scope `TED_POST`
`404`	`SENDER_NOT_FOUND`, `ACCOUNT_NOT_FOUND`	A conta de origem não existe
`422`	`INSUFFICIENT_BALANCE`	Saldo insuficiente
`422`	`TED_PER_TRANSACTION_LIMIT_EXCEEDED`	Valor acima do limite de TED por transação
`422`	`TED_TOTAL_LIMIT_EXCEEDED`	Valor acima do limite de TED disponível no dia
`422`	`ACCOUNT_LIMIT_NOT_FOUND`	A conta não tem limite de TED configurado
`422`	`ACCOUNT_BLOCKED_TED_OUT`	Conta bloqueada para envio de TED
`422`	`OUTSIDE_STR_SESSION`	STR fechado. Envie de novo quando o STR abrir
`422`	`LEDGER_FAILED`	Não foi possível debitar o saldo
`503`	`TED_LIMIT_SERVICE_UNAVAILABLE`, `SPB_FAILED`	Indisponibilidade temporária. Tente de novo com o mesmo `correlationID`

Um 422 é uma recusa de negócio: repetir a mesma requisição dá o mesmo resultado. Um 503 é temporário, e o reenvio com o mesmo correlationID é seguro.

Exemplos de erro

Corpo inválido, com o detalhe de cada campo em errors:

{
  "error": "Corpo da requisição inválido",
  "errorCode": "INVALID_REQUEST_BODY",
  "errors": [
    {
      "origin": "string",
      "code": "too_big",
      "maximum": 20,
      "inclusive": true,
      "path": ["correlationID"],
      "message": "Too big: expected string to have <=20 characters"
    }
  ]
}

{
  "error": "A empresa não possui o recurso TED habilitado",
  "errorCode": "TED_FEATURE_REQUIRED"
}

{
  "error": "Saldo insuficiente para completar a transação",
  "errorCode": "INSUFFICIENT_BALANCE"
}

{
  "error": "Valor acima do limite de TED disponível para o período",
  "errorCode": "TED_TOTAL_LIMIT_EXCEEDED"
}

{
  "error": "O STR está fora da sessão de hoje, o SPB recusaria a mensagem com EGEN0300",
  "errorCode": "OUTSIDE_STR_SESSION"
}

Os limites de TED da conta (por transação e por dia) podem ser consultados em GET /api/v1/limits/{accountId}.

Exemplos em código

Shell + cURL
JavaScript + Fetch

curl --request POST \
  --url https://api.woovi.com/api/v1/ted \
  --header 'Authorization: {APP_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "correlationID": "payout-20260203-1",
    "value": 150050,
    "accountId": "6290ccfd42831958a405debc",
    "receiver": {
      "name": "Joao da Silva",
      "document": "12345678901",
      "ispb": "87654321",
      "agency": 4321,
      "account": 98765,
      "accountType": "CACC"
    }
  }'

const response = await fetch('https://api.woovi.com/api/v1/ted', {
  method: 'POST',
  headers: {
    Authorization: process.env.WOOVI_APP_ID,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    correlationID: 'payout-20260203-1',
    value: 150050,
    accountId: '6290ccfd42831958a405debc',
    receiver: {
      name: 'Joao da Silva',
      document: '12345678901',
      ispb: '87654321',
      agency: 4321,
      account: 98765,
      accountType: 'CACC',
    },
  }),
});

const data = await response.json();

if (!response.ok) {
  // `errorCode` para decidir, `error` para mostrar ao usuário
  throw new Error(`${data.errorCode}: ${data.error}`);
}

console.log(data.ted.status);
// PROCESSING — o resultado chega pelo webhook

Corpo da requisição​

receiver​

Finalidade (clientFinality)​

Exemplo de requisição​

Exemplo de resposta​

Reenvio seguro com o mesmo correlationID​

Códigos de resposta​

Exemplos de erro​

Exemplos em código​