Consulta de Contatos da Conta

Permite consultar, de forma paginada, os contatos ativos vinculados a uma conta, incluindo destinatários comuns e favoritos cadastrados para futuras transações Pix e transferências.

A consulta permite aplicar filtros para localizar contatos específicos e utiliza paginação para controlar a quantidade de registros retornados por requisição.

Endpoint: GET /accounts/{account}/contacts

Passos para Integrar

1. Realizar autenticação na API - [API Reference]
2. Realiza a consulta de contatos da conta - [API Reference]

Parâmetros da requisição

Parâmetros de rota

Parâmetros de query string — filtros

Todos os filtros são opcionais e podem ser combinados na mesma requisição.

Parâmetros de query string — paginação

Funcionamento da paginação

• A consulta utiliza os parâmetros page e limitPerPage para determinar quais registros serão retornados.
• O cálculo dos registros considera:
  • Deslocamento (skip): (page - 1) * limitPerPage
  • Quantidade de registros (limit): limitPerPage
  • Total de páginas (totalPages): teto de totalItems / limitPerPage
• A resposta informa o total de registros encontrados, o total de páginas e a página atual.

cURL da Chamada

curl --request GET \
  --url 'https://sandbox.openfinance.celcoin.dev/baas/v2/accounts/30000/contacts?page=2&limitPerPage=5' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Accept: application/json'

Exemplos de retorno

{
  "status": "SUCCESS",
  "version": "1.0.0",
  "body": {
    "account": "30000",
    "totalItems": 57,
    "totalPages": 12,
    "currentPage": 2,
    "favorites": [
      {
        "contactId": "6f1b2c3d-4e5f-4a6b-8c9d-abc123456789",
        "isFavorite": true,
        "alias": "LTDA - Fornecedor",
        "status": "ACTIVE",
        "clientRequestId": "REQ-12345",
        "creditParty": {
          "bank": "301",
          "account": "****1234",
          "branch": "0001",
          "taxId": "*******8901",
          "name": "Fornecedor LTDA",
          "accountType": "CACC",
          "key": "chave-pix",
          "personType": "LEGAL_PERSON"
        },
        "createdAt": "2026-08-17T14:36:00Z",
        "updatedAt": "2026-08-17T14:36:00Z"
      }
    ]
  }
}

Campos gerais:

Campos de cada contato

Regras de mascaramento

• Na consulta de contatos, os campos creditParty.taxId e creditParty.account são retornados com apenas os quatro últimos caracteres visíveis.
• Para valores com mais de quatro caracteres, somente os quatro últimos ficam visíveis.
• Para valores com quatro caracteres ou menos, o valor é totalmente mascarado.
• Os demais campos de creditParty — bank, branch, name, accountType, key e personType — são retornados sem máscara.

Exemplos:

Consulta sem resultados

• A consulta retorna sucesso mesmo quando não há contatos ativos para a conta consultada ou quando não existem contatos acessíveis no contexto do tenant.
• Nesse cenário, a lista favorites é retornada vazia e totalItems é igual a 0.

Exemplo:

{
  "status": "SUCCESS",
  "version": "1.0.0",
  "body": {
    "account": "30000",
    "totalItems": 0,
    "totalPages": 0,
    "currentPage": 1,
    "favorites": []
  }
}

{
  "status": "ERROR",
  "version": "1.0.0",
  "error": {
    "errorCode": "cashout.accountnotfound",
    "message": "A conta informada não existe ou está incorreta."
  }
}

Tabela de errorCode