Items

Um Item representa a conexão de um usuário com uma instituição financeira. Através dele, você acessa contas, transações e dados de identidade.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	/api/v1/items/sync	Sincronizar item	OPENFINANCE_WRITE
GET	/api/v1/items	Listar items	OPENFINANCE_READ
GET	/api/v1/items/:id	Obter item	OPENFINANCE_READ
POST	/api/v1/items/:id/refresh	Atualizar status	OPENFINANCE_WRITE
POST	/api/v1/items/:id/sync-data	Sincronizar dados completos	OPENFINANCE_WRITE
POST	/api/v1/items/:id/link-person	Vincular a pessoa	OPENFINANCE_WRITE
DELETE	/api/v1/items/:id	Excluir item	OPENFINANCE_ADMIN

---

Sincronizar Item

POST /api/v1/items/sync

Sincroniza um item após o usuário conectar via widget. Este é o primeiro passo após o fluxo de connect.

Request

Campo	Tipo	Obrigatório	Descrição
externalItemId	string	Sim	ID do item retornado pelo provedor
configId	string	Não	ID da configuração do provedor
personId	string	Não	ID da pessoa no módulo Customers
businessId	string	Não	ID da empresa no módulo Customers
metadata	object	Não	Metadados adicionais

cURL

curl -X POST 'https://open-finance.stg.catalisa.app/api/v1/items/sync' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalItemId": "pluggy-item-id-123",
    "personId": "550e8400-e29b-41d4-a716-446655440000",
    "metadata": {
      "source": "onboarding"
    }
  }'

JavaScript

const response = await fetch('https://open-finance.stg.catalisa.app/api/v1/items/sync', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    externalItemId: 'pluggy-item-id-123',
    personId: '550e8400-e29b-41d4-a716-446655440000',
  }),
});

const { data } = await response.json();
console.log(`Item sincronizado: ${data.id}`);
console.log(`Status: ${data.attributes.status}`);

Response (201 Created)

{
  "data": {
    "type": "openfinance-item",
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "links": {
      "self": "/api/v1/open-finance/items/550e8400-e29b-41d4-a716-446655440001"
    },
    "attributes": {
      "status": "UPDATED",
      "connectorId": "connector-banco-do-brasil",
      "connectorName": "Banco do Brasil",
      "personId": "550e8400-e29b-41d4-a716-446655440000",
      "lastSyncAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

---

Sincronizar Dados Completos

POST /api/v1/items/:id/sync-data

Realiza uma sincronização completa dos dados do item: contas, transações e identidade.

cURL

curl -X POST 'https://open-finance.stg.catalisa.app/api/v1/items/550e8400-e29b-41d4-a716-446655440001/sync-data' \
  -H 'Authorization: Bearer SEU_TOKEN'

---

Atualizar Status

POST /api/v1/items/:id/refresh

Atualiza o status do item junto ao provedor.

cURL

curl -X POST 'https://open-finance.stg.catalisa.app/api/v1/items/550e8400-e29b-41d4-a716-446655440001/refresh' \
  -H 'Authorization: Bearer SEU_TOKEN'

---

Vincular a Pessoa

POST /api/v1/items/:id/link-person

Vincula um item a uma pessoa cadastrada no módulo Customers.

Request

Campo	Tipo	Obrigatório	Descrição
personId	string	Sim	ID da pessoa no módulo Customers

cURL

curl -X POST 'https://open-finance.stg.catalisa.app/api/v1/items/550e8400-e29b-41d4-a716-446655440001/link-person' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "personId": "550e8400-e29b-41d4-a716-446655440000"
  }'

---

Listar Items

GET /api/v1/items

Lista os items da organização com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
pageNumber	integer	Número da página
pageSize	integer	Itens por página
filterStatus	string	Filtrar por status
filterPersonId	string	Filtrar por pessoa
filterBusinessId	string	Filtrar por empresa

cURL

curl 'https://open-finance.stg.catalisa.app/api/v1/items?filterStatus=UPDATED' \
  -H 'Authorization: Bearer SEU_TOKEN'

---

Obter Identidade

GET /api/v1/items/:itemId/identity

Retorna os dados de identidade do titular da conta, conforme informados pela instituição financeira.

cURL

curl 'https://open-finance.stg.catalisa.app/api/v1/items/550e8400-e29b-41d4-a716-446655440001/identity' \
  -H 'Authorization: Bearer SEU_TOKEN'

Response (200 OK)

{
  "data": {
    "type": "openfinance-identity",
    "attributes": {
      "fullName": "João da Silva",
      "documentNumber": "12345678900",
      "email": "joao@exemplo.com",
      "phoneNumber": "+5511999887766",
      "birthDate": "1990-05-15",
      "address": {
        "street": "Rua das Flores",
        "number": "123",
        "city": "São Paulo",
        "state": "SP",
        "zipCode": "01234-567"
      }
    }
  }
}

---

Erros Comuns

Código	Erro	Descrição
400	VALIDATION	externalItemId inválido ou ausente
404	NOT_FOUND	Item não encontrado
404	NOT_FOUND	Pessoa não encontrada (ao vincular)