Solicitar Alteração de Limite

O endpoint de Solicitação de Alteração de Limite permite registrar solicitações de aumento ou redução de limites configurados para uma conta.

Endpoint: PATCH /accounts/{account}/limits/{limitType}

Passos para Integrar

1. Realizar autenticação na API - [API Reference]
2. Realizar solicitação de alteração de limite - [API Reference]

Parâmetros da requisição

Campos do Request

Regras gerais

• Na solicitação deve ser informada a conta (account) e o tipo de limite (limitType) que será alterado;
• Regras para periodType:
  • O campo periodType aceita NOCTURNAL ou DIURNAL e deve ser informado quando o tipo de limite possuir duas janelas de consumo.
  • Quando o limite possuir apenas uma janela, o valor enviado em periodType será ignorado, sem geração de erro.
  • Por exemplo, as operações Pix podem possuir limites distintos para os períodos diurno e noturno, exigindo a identificação da janela correspondente.
• Idempotência por clientRequestId: O envio de clientRequestId é opcional. Quando informado, o identificador não pode já existir para o mesmo cliente.
• O campo operationType determina o fluxo a ser executado:
  • INCREASE: solicitação de aumento de limite, sujeita às regras de teto máximo e à verificação de solicitações em aberto.
  • DECREASE: solicitação de redução de limite, aprovada automaticamente e publicada imediatamente, sem agendamento.
• Processamento assíncrono: A resposta inicial da API não representa necessariamente a conclusão de todo o fluxo. Após o registro da solicitação, o processamento segue conforme o tipo de operação informado, e o resultado final é comunicado ao cliente por meio de webhook.
• A resposta inicial pode retornar os status SCHEDULED ou REJECTED:
  • O status SCHEDULED indica que a solicitação foi registrada para processamento conforme o fluxo correspondente.
  • O status REJECTED ocorre quando uma solicitação de aumento é rejeitada automaticamente por ultrapassar o teto máximo configurado para o tenant/cliente.

Solicitação de Aumento de Limite (INCREASE)

O aumento permite solicitar a elevação do valor de um limite existente.

Por segurança, toda solicitação aprovada é agendada antes de sua efetivação.

Regras de negócio

1. Verificação de solicitações em aberto
   • Se já existir uma solicitação aberta para a mesma conta, com status SCHEDULED ou PENDING, uma nova solicitação de aumento será bloqueada.
   • Nesse cenário, a API retorna erro, e a nova solicitação não é gravada nem publicada.
2. Validação do teto máximo

• O aumento está sujeito ao teto máximo configurado para o tenant/cliente;
• Se o valor solicitado for igual ao teto máximo, a solicitação poderá ser aprovada;
• Se o valor solicitado ultrapassar o teto máximo, a solicitação será rejeitada automaticamente, com status REJECTED.
• O teto global do tenant/cliente prevalece sobre o limite individual para essa validação.

3. Validação do valor solicitado

• Quando currentValue for maior que zero, o valor solicitado deve ser superior ao limite atual.
• Se requestedValue for igual ou inferior a currentValue, a API retorna erro.

4. Agendamento da alteração

• Quando aprovada, a solicitação recebe status SCHEDULED e é agendada para efetivação após o período de carência configurado, cujo padrão é de 24 horas. Portanto, resposta inicial não significa que o novo limite já esteja efetivo.
• A solicitação de aumento pode resultar em:
  • SCHEDULED: solicitação aprovada e agendada para efetivação.
  • REJECTED: solicitação rejeitada automaticamente por ultrapassar o teto máximo do tenant/cliente.
• Após o processamento, o resultado é comunicado ao cliente por meio de webhook.

Exemplo de request - Aumento de limite

{
  "operationType": "INCREASE",
  "requestedValue": 3000.00,
  "periodType": "DIURNAL",
  "clientRequestId": "90007f94-9ce5-41d6-8493-000000000001",
  "reason": "Solicitação de aumento do limite transacional."
}

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: application/json' \
  --data '{
    "operationType": "INCREASE",
    "requestedValue": 3000.00,
    "clientRequestId": "90007f94-9ce5-41d6-8493-000000000001",
    "reason": "Solicitação de aumento do limite transacional."
  }'

Exemplo de retorno

{
  "status": "SCHEDULED",
  "version": "1.0.0",
  "body": {
    "limitId": "6f1a2e3b-7c4d-4a5e-9f10-abc123456789",
    "account": "11111111111",
    "limitType": "PixPJ",
    "clientRequestId": "REQ-12345",
    "name": "Pix - Pessoa Jurídica",
    "period": { "type": "DIURNAL", "label": "Diurno" },
    "operationType": "INCREASE",
    "previousValue": 3000.00,
    "requestedValue": 5000.00,
    "approvedValue": 5000.00,
    "reason": "Aumento de faturamento do cliente",
    "requestedAt": "2026-09-01T15:30:00Z",
    "updateAt": "2026-09-01T15:30:00Z",
    "message": "Por motivos de segurança, solicitações de aumento de limite são efetivadas em até 24 horas."
  }
}

{
  "status": "REJECTED",
  "version": "1.0.0",
  "body": {
    "limitId": "9a8b7c6d-1234-4a5e-9f10-abc123456789",
    "account": "11111111111",
    "limitType": "PixPJ",
    "operationType": "INCREASE",
    "previousValue": 3000.00,
    "requestedValue": 999999.00,
    "approvedValue": null,
    "requestedAt": "2026-09-01T15:31:00Z",
    "updateAt": "2026-09-01T15:31:00Z",
    "message": null
  }
}

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

Solicitação de Redução de Limite (DECREASE)

A redução permite solicitar a diminuição do valor de um limite existente. Diferentemente do aumento, esse fluxo não possui período de carência.

Regras de negócio

1. Sem validação de teto máximo

• A redução não passa pela validação do teto máximo configurado para o tenant/cliente.

2. Sem bloqueio por solicitação em aberto

• A existência de outra solicitação aberta com status SCHEDULED ou PENDING não impede uma nova solicitação de redução.

3. Aprovação automática

• A solicitação de redução é aprovada automaticamente
• A redução é publicada imediatamente, sem agendamento ou período de carência.

• Em caso de sucesso, a API retorna HTTP 200 com status SCHEDULED.
• Esse status indica que a solicitação foi registrada com sucesso e resultado do processamento é comunicado ao cliente por meio de webhook.

Exemplo de request - Redução de limite

{
  "operationType": "DECREASE",
  "requestedValue": 3000.00,
  "periodType": "DIURNAL",
  "clientRequestId": "90007f94-9ce5-41d6-8493-000000000001",
  "reason": "Solicitação de aumento do limite transacional."
}

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: application/json' \
  --data '{
    "operationType": "DECREASE",
    "requestedValue": 3000.00,
    "clientRequestId": "90007f94-9ce5-41d6-8493-000000000001",
    "reason": "Solicitação de aumento do limite transacional."
  }'

Exemplo de retorno

{
  "status": "SCHEDULED",
  "version": "1.0.0",
  "body": {
    "limitId": "6f1b2c3d-4e5f-4a6b-8c9d-abc123456789",
    "account": "11111111111",
    "limitType": "PixPJ",
    "clientRequestId": "REQ-12345",
    "name": "Pix - Pessoa Jurídica",
    "period": { "type": "DAILY", "label": "Diário" },
    "operationType": "DECREASE",
    "previousValue": 3000.00,
    "requestedValue": 1000.00,
    "approvedValue": 1000.00,
    "requestedAt": "2026-08-04T15:30:00Z",
    "updateAt": "2026-08-04T15:30:00Z"
  }
}

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

Descrição dos dados retornados

Webhook

Exemplo de webhook

{
	"entity": "limit-update",
	"createTimestamp": "2024-02-06T16:00:44.564Z",
	"status": "APPROVED",
	"body": {
		"clientRequestId": "90007f94-9ce5-41d6-8493-0",
		"account": "123456",
		"limitId": "5465456",
		"limitType": "PixPJ",
		"periodType": "DAILY",
		"operationType": "DECREASE",
		"requestedValue": 3000.0,
		"approvedValue": 3000.0,
		"previousValue": 1000.0,
		"requestedAt": "2026-08-04T15:30:00Z",
		"updateAt": "2026-08-05T15:30:00Z",
		"reason": ""
	}
}

Tabela de errorCode