Transferências

Criação e gestão de transferências bancárias TED e DOC.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	/baas/api/v1/transfers	Criar transferência	BAAS_TRANSFERS_CREATE
GET	/baas/api/v1/transfers	Listar transferências	BAAS_TRANSFERS_READ
GET	/baas/api/v1/transfers/:id	Obter transferência por ID	BAAS_TRANSFERS_READ

Atributos

Campo	Tipo	Descrição
accountId	string (UUID)	ID da conta de origem
type	enum	Tipo: TED, DOC
amount	number	Valor da transferência
status	enum	Status: PENDING, PROCESSING, COMPLETED, FAILED, REVERSED
description	string	Descrição/motivo da transferência
scheduledDate	date	Data agendada (opcional, formato YYYY-MM-DD)
recipient	object	Dados do destinatário
externalRef	string	Referência no provedor bancário
failureReason	string	Motivo da falha (quando aplicável)
completedAt	datetime	Data de conclusão
createdAt	datetime	Data de criação
updatedAt	datetime	Data da última atualização

Estrutura do Destinatário (recipient)

Campo	Tipo	Descrição
name	string	Nome do destinatário
document	string	CPF/CNPJ
documentType	enum	CPF ou CNPJ
bankCode	string	Código do banco (ex: 001, 341)
branch	string	Agência
accountNumber	string	Número da conta
accountType	enum	CHECKING ou SAVINGS

---

Criar Transferência

POST /baas/api/v1/transfers

Cria uma nova transferência TED ou DOC. Transferências DOC são processadas no próximo dia útil.

Atributos

Campo	Tipo	Obrigatório	Descrição
accountId	string	Sim	ID da conta de origem
type	enum	Sim	TED ou DOC
amount	number	Sim	Valor da transferência
description	string	Não	Descrição/motivo
scheduledDate	date	Não	Data para agendamento
recipient	object	Sim	Dados do destinatário

cURL

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/transfers' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "transfers",
      "attributes": {
        "accountId": "550e8400-e29b-41d4-a716-446655440100",
        "type": "TED",
        "amount": 5000.00,
        "description": "Pagamento fornecedor NF 12345",
        "recipient": {
          "name": "Fornecedor XYZ Ltda",
          "document": "98.765.432/0001-10",
          "documentType": "CNPJ",
          "bankCode": "341",
          "branch": "1234",
          "accountNumber": "56789-0",
          "accountType": "CHECKING"
        }
      }
    }
  }'

JavaScript

const response = await fetch('https://baas.stg.catalisa.app/baas/api/v1/transfers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'transfers',
      attributes: {
        accountId: '550e8400-e29b-41d4-a716-446655440100',
        type: 'TED',
        amount: 5000.00,
        description: 'Pagamento fornecedor NF 12345',
        recipient: {
          name: 'Fornecedor XYZ Ltda',
          document: '98.765.432/0001-10',
          documentType: 'CNPJ',
          bankCode: '341',
          branch: '1234',
          accountNumber: '56789-0',
          accountType: 'CHECKING',
        },
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Transferência criada: ${data.id}`);
console.log(`Status: ${data.attributes.status}`);

Response (201 Created)

{
  "data": {
    "type": "transfers",
    "id": "550e8400-e29b-41d4-a716-446655440200",
    "links": {
      "self": "/baas/api/v1/transfers/550e8400-e29b-41d4-a716-446655440200"
    },
    "attributes": {
      "accountId": "550e8400-e29b-41d4-a716-446655440100",
      "type": "TED",
      "amount": 5000.00,
      "status": "PENDING",
      "description": "Pagamento fornecedor NF 12345",
      "scheduledDate": null,
      "recipient": {
        "name": "Fornecedor XYZ Ltda",
        "document": "98.765.432/0001-10",
        "documentType": "CNPJ",
        "bankCode": "341",
        "branch": "1234",
        "accountNumber": "56789-0",
        "accountType": "CHECKING"
      },
      "externalRef": null,
      "failureReason": null,
      "completedAt": null,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  },
  "links": {
    "self": "/baas/api/v1/transfers/550e8400-e29b-41d4-a716-446655440200"
  }
}

---

Listar Transferências

GET /baas/api/v1/transfers

Lista transferências com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
page[number]	integer	Número da página
page[size]	integer	Itens por página
filter[accountId]	UUID	Filtrar por conta de origem
filter[status]	enum	Filtrar por status
filter[type]	enum	Filtrar por tipo (TED/DOC)
filter[dateFrom]	date	Data inicial (YYYY-MM-DD)
filter[dateTo]	date	Data final (YYYY-MM-DD)

cURL

curl 'https://baas.stg.catalisa.app/baas/api/v1/transfers?filter[accountId]=550e8400-e29b-41d4-a716-446655440100&filter[status]=COMPLETED&page[size]=20' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const params = new URLSearchParams({
  'filter[accountId]': '550e8400-e29b-41d4-a716-446655440100',
  'filter[status]': 'COMPLETED',
  'page[size]': '20',
});

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/transfers?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta } = await response.json();
console.log(`Total de transferências: ${meta.totalItems}`);

---

Obter Transferência por ID

GET /baas/api/v1/transfers/:id

Obtém os detalhes de uma transferência específica.

cURL

curl 'https://baas.stg.catalisa.app/baas/api/v1/transfers/550e8400-e29b-41d4-a716-446655440200' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const transferId = '550e8400-e29b-41d4-a716-446655440200';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/transfers/${transferId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Valor: R$ ${data.attributes.amount.toFixed(2)}`);
console.log(`Destinatário: ${data.attributes.recipient.name}`);
console.log(`Status: ${data.attributes.status}`);

---

Transferência Agendada

Para agendar uma transferência para uma data futura, inclua o campo scheduledDate:

const response = await fetch('https://baas.stg.catalisa.app/baas/api/v1/transfers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'transfers',
      attributes: {
        accountId: '550e8400-e29b-41d4-a716-446655440100',
        type: 'TED',
        amount: 10000.00,
        scheduledDate: '2024-02-01',
        description: 'Pagamento mensal fornecedor',
        recipient: {
          name: 'Fornecedor XYZ Ltda',
          document: '98.765.432/0001-10',
          documentType: 'CNPJ',
          bankCode: '341',
          branch: '1234',
          accountNumber: '56789-0',
          accountType: 'CHECKING',
        },
      },
    },
  }),
});

---

Erros Comuns

Código	Erro	Descrição
400	VALIDATION	Dados inválidos (valor, destinatário, etc.)
400	INSUFFICIENT_BALANCE	Saldo insuficiente na conta de origem
404	NOT_FOUND	Transferência ou conta não encontrada
409	CONFLICT	Conta de origem não está ativa
422	UNPROCESSABLE	Data agendada no passado ou fora do horário de corte