Cadastro de Contato

Permite cadastrar um contato, destinatário de futuras transações Pix ou transferências, vinculado a uma conta por meio de um endpoint.

Endpoint: POST /accounts/{account}/contacts.

Passos para Integrar

Realizar autenticação na API - [API Reference]
Realizar o cancelamento de uma solicitação de alteração de limite - [API Reference]

Parâmetros da requisição

Campo	Tipo	Descrição	Obrigatório
account	string	Identificador da conta à qual o contato será vinculado.	Sim

Regras gerais

O contato pode ser cadastrado como comum ou com a intenção de torná-lo favorito, conforme o valor do campo isFavorite.
O comportamento da API varia de acordo com essa informação:
- Contato comum (isFavorite: false): o cadastro é realizado de forma síncrona. A API retorna HTTP 200, com status SUCCESS e os dados do contato criado.
- Favorito (isFavorite: true): a solicitação é processada de forma assíncrona. A API retorna HTTP 200, com status PROCESSING, indicando que o pedido foi encaminhado para processamento interno. A ativação como favorito depende do prazo de aprovação interna, padrão de 24 horas.

Exemplo de request

{
  "clientRequestId": "REQ-12345",
  "alias": "LTDA - Fornecedor",
  "isFavorite": false,
  "type": "MANUAL",
  "creditParty": {
    "bank": "13935893",
    "account": "40021234",
    "branch": "0001",
    "taxId": "12345678000199",
    "name": "Fornecedor LTDA",
    "accountType": "CACC",
    "key": "[email protected]",
    "personType": "LEGAL_PERSON"
  }
}

cURL da chamada

curl --request PATCH \
  --url 'https://sandbox.openfinance.celcoin.dev/baas/v2/accounts/123456/limits/PIX_OUT?periodType=DIURNAL' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: app

Campos do Request

Campo	Tipo	Obrig.	Descrição
`clientRequestId`	string	Sim	Id único da solicitação no cliente - chave de idempotência
`alias`	string	Não	Apelido do contato (até 100 caracteres);
`isFavorite`	bool	Não	`true` = cadastrar como favorito (default `false`)
`type`	string	Não	`MANUAL` / `DICT` — só persistido
`creditParty.bank`	string	Sim	Banco (ISPB)
`creditParty.account`	string	Sim	Conta do destinatário
`creditParty.branch`	string	Sim	Agência
`creditParty.taxId`	string	Sim	CPF/CNPJ
`creditParty.name`	string	Sim	Nome (até 140 caracteres)
`creditParty.accountType`	string	Sim	`CACC`, `SVGS`, `SLRY`, `TRAN`
`creditParty.personType`	string	Sim	`NATURAL_PERSON`, `LEGAL_PERSON`
`creditParty.key`	string	Não	Chave Pix;

Exemplo de retorno

👍
Sucesso 200 - não favorito (síncrono)

{
  "status": "SUCCESS",
  "version": "1.0.0",
  "body": {
    "contactId": "6f1b2c3d-4e5f-6789-abcd-ef0123456789",
    "account": "30000",
    "isFavorite": false,
    "alias": "LTDA - Fornecedor",
    "status": "ACTIVE",
    "clientRequestId": "REQ-12345",
    "type": "MANUAL",
    "creditParty": {
      "bank": "13935893",
      "account": "40021234",
      "branch": "0001",
      "taxId": "12345678000199",
      "name": "Fornecedor LTDA",
      "accountType": "CACC",
      "key": "[email protected]",
      "personType": "LEGAL_PERSON"
    },
    "createdAt": "2026-09-16T10:00:00",
    "updatedAt": "2026-09-16T10:00:00"
  }
}

Comportamento:

O contato é gravado imediatamente.
O status da resposta é SUCCESS.
O campo creditParty retorna os dados enviados pelo cliente, sem máscara.
O campo message não é retornado.

👍
Sucesso 200 - Cadastro de contato como favorito — assíncrono

{
  "status": "PROCESSING",
  "version": "1.0.0",
  "body": {
    "contactId": "6f1b2c3d-4e5f-6789-abcd-ef0123456789",
    "account": "30000",
    "isFavorite": false,
    "alias": "LTDA - Fornecedor",
    "status": "ACTIVE",
    "clientRequestId": "REQ-12345",
    "type": "MANUAL",
    "creditParty": {
      "bank": "13935893",
      "account": "40021234",
      "branch": "0001",
      "taxId": "12345678000199",
      "name": "Fornecedor LTDA",
      "accountType": "CACC",
      "key": "[email protected]",
      "personType": "LEGAL_PERSON"
    },
    "createdAt": "2026-09-16T10:00:00",
    "updatedAt": "2026-09-16T10:00:00",
    "message": "O cadastro do limite do favorito valerá apenas após 24 horas."
  }
}

Comportamento:

A solicitação de cadastro como favorito é encaminhada para processamento interno.
O status da resposta é PROCESSING.
O campo isFavorite retorna false enquanto a classificação como favorito não estiver efetivada.
O campo message informa o prazo para aplicação dos limites de favorito.
O prazo padrão é de 24 horas;
Um Webhook ("entity": "favorite") será enviado assim que o cadastro for classificado como Favorito. E neste caso será possível atribuir a ele limites diferenciados.

Campos do Response

Campo	Descrição
`status`	Status do processamento da requisição. Retorna `SUCCESS` para cadastro comum concluído ou `PROCESSING` para solicitação de favorito em processamento.
`version`	Versão do contrato da resposta.
`body`	Objeto contendo os dados do contato cadastrado ou da solicitação em processamento.
`body.contactId`	Identificador único do contato.
`body.account`	Identificador da conta vinculada ao contato.
`body.isFavorite`	Indica se o contato já está efetivamente classificado como favorito. (Boolean - True ou False)
`body.alias`	Nome ou apelido do contato.
`body.status`	Status do contato. No exemplo, `ACTIVE`.
`body.clientRequestId`	Identificador da solicitação informado pelo cliente.
`body.type`	Tipo de cadastro do contato.
`body.creditParty`	Objeto que contem os dados do destinatário, incluindo instituição, conta, agência, documento, nome, tipo de conta, chave Pix e tipo de pessoa.
`body.createdAt`	Data e hora (date-time) de criação do contato.
`body.updatedAt`	Data e hora (date-time)da última atualização do contato.
`body.message`	Mensagem complementar retornada no fluxo assíncrono de cadastro como favorito. Não é exibida no cadastro comum.

❗
Error 400

{
  "status": "ERROR",
  "version": "1.0.0",
  "error": {
    "errorCode": "CBE234",
    "message": "Não foi possivel realizar essa operação. Tente novamente mais tarde."
  }
}

Webhook

Evento	Descrição
favorite	Evento disparado sempre assim que um contato for classificado como favorito.

Exemplo de webhook

{
	"entity": "favorite",
	"status": "CONFIRMED",
	"webhookId": "fndkfdkfndf",
	"createTimestamp": "",
	"body": {
		"contactId": "guid-aqui",
		"alias": "LTDA - Fornecedor",
		"status": "ACTIVE",
		"favorite": true,
		"creditParty": {
			"bank": "{{pixapi_participantcredit}}",
			"account": "{{pixapi_accountredit}}",
			"branch": "{{pixapi_branchcredit}}",
			"taxId": "{{pixapi_taxidcredit}}",
			"name": "{{pixapi_namecredit}}",
			"accountType": "****",
			"key": "{{pixapi_key}}",
			"personType": "NATURAL_PERSON"
		},
		"createdAt": "2026-08-17T14:36:00Z",
		"updatedAt": "2026-08-17T14:36:00Z"
	}
}

Tabela de errorCode

Code	Message
`CBE091`	É necessário informar o campo: `account.`
`CBE261`	clientRequestId é obrigatório.
`CBE308`	clientRequestId possui tamanho máximo de 200 caracteres.
`CBE115`	creditParty é obrigatório.
`CBE126`	creditParty.bank é obrigatório e deve existir na lista de participantes Pix.
`CBE116`	creditparty.account é obrigatório.
`CBE118`	creditparty.account possui tamanho maximo de 20 caracteres.
`CBE119`	creditParty.branch é obrigatório.
`CBE121`	creditParty.taxId é obrigatório.
`CBE127`	creditParty.name é obrigatório e possui tamanho maximo de 140 caracteres.
`CBE128`	creditParty.accountType não foi informado ou é invalido.
`CBE269`	creditParty.personType não foi informado ou é invalido.
`CBE704`	alias não pode ser vazio e possui tamanho máximo de 100 caracteres.
`CBE225`	A propriedade {campo} esta fora do padrão. Verifique a documentação.
`CBE239`	Não foi possivel recuperar os dados do cliente para busca do JWT.
`CBE488`	Ja existe dados na base com o mesmo clientRequestId enviado.
`CBE703`	Já existe um contato cadastrado com os dados informados.
`CBE234`	Não foi possivel realizar essa operação. Tente novamente mais tarde.
`CIE999`	Ocorreu um erro interno durante a chamada da api.

Updated about 1 hour ago

Did this page help you?