Primeiros passos com a API de TED

A API de TED permite enviar uma TED a partir de uma conta da sua empresa, devolver uma TED recebida, consultar uma TED e listar as TEDs enviadas e recebidas. O resultado de cada TED chega por webhook.

Endpoint	O que faz	Scope
`POST /api/v1/ted`	Envia uma TED	`TED_POST`
`POST /api/v1/ted/{correlationID}/refund`	Devolve uma TED recebida	`TED_REFUND_POST`
`GET /api/v1/ted/{correlationID}`	Consulta uma TED	`TED_GET`
`GET /api/v1/ted`	Lista as TEDs	`TED_GET_LIST`

Referência completa

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

A TED é assíncrona

Quem liquida uma TED é o BACEN, pelo STR. Por isso, a resposta de POST /api/v1/ted diz que a TED foi aceita para processamento, e não que o dinheiro chegou. Normalmente ela volta com status: PROCESSING.

O resultado chega depois, por webhook:

TED_OUT_CONFIRMED: a TED foi liquidada no BACEN.
TED_OUT_REJECTED: a TED não foi liquidada, o débito foi estornado e o saldo voltou para a conta.

Não trate a resposta do POST como pagamento concluído. Espere o webhook ou consulte a TED. Os caminhos possíveis e o evento de cada um estão em Ciclo de vida de uma TED.

Pré-requisitos

Uma chave de API (AppID) da sua empresa. Veja Primeiros passos com a API.
A funcionalidade TED habilitada na empresa. Sem ela, todos os endpoints respondem 403. Peça a ativação ao suporte.
Os scopes da tabela acima na sua aplicação, conforme os endpoints que ela usa.
Uma conta da empresa para debitar a TED: a conta vinculada à aplicação ou, se ela não tiver, a conta padrão da empresa. Veja Conta de origem.

Autenticação

Envie o AppID no header Authorization, sem o prefixo Bearer:

curl https://api.woovi.com/api/v1/ted \
  --header 'Authorization: {APP_ID}'

Ambiente	URL base
Produção	`https://api.woovi.com`
Sandbox	`https://api.woovi-sandbox.com`

A empresa e a conta de origem vêm do AppID, nunca da requisição: você só envia de contas da sua empresa, e só enxerga as TEDs dela.

Erros

Toda resposta de erro traz dois campos:

errorCode: um código estável. Use-o no seu código para decidir o que fazer.
error: a mensagem, para mostrar ao seu usuário. Ela segue o header Accept-Language (pt-BR ou en); sem o header, vem em português.

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

Não compare o texto de error: ele pode mudar. Compare o errorCode, e novos códigos podem surgir.

nota

Os erros de autenticação (401) e de scope (403) são respondidos pelo gateway, antes da API de TED, e trazem só o error.

Por que uma TED falhou

Uma TED FAILED ou REFUNDED explica o motivo em dois campos, na consulta e nos webhooks:

Campo	Para quê
`errorCode`	Código estável do motivo. Use-o para decidir
`reason`	O `errorCode` explicado, para mostrar ao usuário. Segue o `Accept-Language`; nos webhooks vem em português

{
  "status": "FAILED",
  "errorCode": "RECEIVER_ACCOUNT_CLOSED",
  "reason": "Conta recebedora encerrada"
}

`errorCode`	`reason`
`INSUFFICIENT_BALANCE`	Saldo insuficiente
`OUTSIDE_STR_WINDOW`	Fora do horário de funcionamento da TED
`STR_REJECTED`	Rejeitada pelo Banco Central
`STR_CANCELLED`	Cancelada no Banco Central
`REFUSED_BY_RECEIVER_BANK`	Devolvida pelo banco recebedor
`RECEIVER_ACCOUNT_NOT_FOUND`	Conta recebedora não encontrada
`RECEIVER_ACCOUNT_CLOSED`	Conta recebedora encerrada
`RECEIVER_ACCOUNT_BLOCKED`	Conta recebedora bloqueada para receber TED
`FEE_FETCH_FAILED`	Falha ao calcular a tarifa
`LEDGER_ERROR`	Falha ao lançar a transação no saldo
`SPB_PUBLISH_FAILED`	Falha ao enviar a TED ao Banco Central
`SPB_DEAD_LETTERED`	TED não entregue ao Banco Central por um erro interno
`UNKNOWN`	Motivo desconhecido

Em uma TED que não falhou, os dois campos são null.

Valores

Todos os valores são inteiros em centavos: 150050 é R$ 1.500,50.

Status de uma TED

`status`	Significado
`PENDING`	Em processamento
`PROCESSING`	Enviada ao STR, aguardando a resposta do BACEN
`SCHEDULED`	Reservado; hoje nenhuma TED fica neste `status`
`COMPLETED`	Liquidada
`FAILED`	Não liquidada; o saldo voltou para a conta
`REFUNDED`	Liquidada e depois devolvida

`type`	Significado
`TED_OUT`	TED que você enviou
`TED_IN`	TED que você recebeu
`TED_REFUND_SENT`	Devolução que você enviou
`TED_REFUND_RECEIVED`	Devolução que você recebeu

O type já diz para que lado o dinheiro foi.

Quem paga e quem recebe

Como no Pix, debitParty é quem enviou o dinheiro e creditParty quem recebeu:

Campo	Descrição
`account.branch`	Agência
`account.account`	Número da conta
`account.accountType`	Tipo da conta: `CACC` (corrente), `SVGS` (poupança), `SLRY` (salário) ou `PAYMENT` (pagamento)
`psp.id`	ISPB da instituição
`holder.name`	Nome do titular
`holder.taxID`	CPF (`BR:CPF`) ou CNPJ (`BR:CNPJ`) do titular

A TED é assíncrona​

Pré-requisitos​

Autenticação​

Erros​

Por que uma TED falhou​

Valores​

Status de uma TED​

Quem paga e quem recebe​