Alterar Favorito do Contato

Permite marcar ou desmarcar um contato cadastrado como favorito e, opcionalmente, alterar seu apelido (alias), por meio de um endpoint.

Endpoint: PATCH /accounts/{account}/contacts/{contactId}

Passos para Integrar

1. Realizar autenticação na API - [API Reference]
2. Realizar a alteração de favorito do contato - [API Reference]

Parâmetros da requisição

Regras gerais

• O processamento da alteração é sempre assíncrono e a resposta de sucesso retorna PROCESSING.
• Somente contatos com status ACTIVE podem ser alterados.
• Contatos inexistentes ou com status diferente de ACTIVE, incluindo REMOVED e PENDING, são tratados como não encontrados e retornam erro.
• Ao favoritar um contato (isFavorite: true), a efetivação é agendada para o término do prazo de aprovação interna, padrão de 24 horas.
• Ao desfavoritar um contato (isFavorite: false), o efeito é imediato, mesmo que a resposta da API seja PROCESSING.
• O campo alias pode ser utilizado para atualizar o apelido do contato.
• Comportamento durante a ativação de favorito:
  • Durante o prazo de aprovação (24 horas), o contato permanece registrado com isFavorite: false.
  • Nesse intervalo, uma solicitação para desfavoritar (isFavorite: false) retorna erro, pois o contato ainda não está efetivamente marcado como favorito. O agendamento existente permanece ativo.
  • Uma nova solicitação para favoritar (isFavorite: true) publica novamente o pedido de ativação
• Ao final do processo, será enviado um Webhook de confirmação;

Request

{
  "clientRequestId": "REQ-67890",
  "isFavorite": true,
  "alias": "LTDA - Fornecedor"
}

curl --request PATCH \
  --url 'https://sandbox.openfinance.celcoin.dev/baas/v2/accounts/30000/contacts/6f1b2c3d-4e5f-4a6b-8c9d-abc123456789' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "clientRequestId": "REQ-67890",
    "isFavorite": true,
    "alias": "LTDA - Fornecedor"
  }'

Descrição dos campos do request

Exemplo de retorno

{
  "status": "PROCESSING",
  "version": "1.0.0"
}

{
  "status": "ERROR",
  "version": "1.0.0",
  "error": {
    "errorCode": "CBE523",
    "message": "<limitType` não informado>"
  }
}

Webhook

Exemplo de webhook

{
  "entity": "favorite",
  "status": "CONFIRMED",
  "webhookId": "446f625f-e283-44af-b2d1-346f63a000fa",
  "createTimestamp": "2026-10-23T14:13:06.17Z",
  "body": {
    "contactId": "2a5bd7c2-47a4-435f-80b4-62098e4e49df",
    "alias": "Fornecedor X",
    "status": "ACTIVE",
    "favorite": true,
    "creditParty": {
      "bank": "13935893", 
      "account": "000000000", 
      "branch": "0001",
      "taxId": "00000000000000", 
      "name": "Fornecedor X",
      "accountType": "CACC", 
      "key": null, 
      "personType": "LEGAL_PERSON"
    },
    "createdAt": "2026-10-21T13:33:58.114Z",
    "updatedAt": "2026-10-23T14:13:06.17Z"
  }
}

Tabela de errorCode