Liquidacao

Endpoint para disparar o processamento de arquivos de liquidacao (ACMP615) da Nuclea.

Ciclos de Liquidacao

A Nuclea processa liquidacoes em dois ciclos diarios:

Ciclo	Horario	Descricao
Manha	08:30	Processa pagamentos do dia anterior (tarde)
Tarde	16:30	Processa pagamentos do dia atual (manha)

Processamento Automatico

O sistema processa automaticamente os arquivos ACMP615 apos cada ciclo (08:35 e 16:35). Use este endpoint apenas para reprocessamento manual ou testes.

Disparar Processamento

Agenda um job para baixar e processar os arquivos de liquidacao do FTP da Nuclea.

POST /settlements/trigger

Corpo da Requisicao

Todos os campos sao opcionais. Se nao informados, serao usados os valores padrao.

Campo	Tipo	Padrao	Descricao
cycle	integer	ciclo atual	Ciclo de liquidacao: 1 (manha) ou 2 (tarde)
date	string	data atual	Data para buscar arquivos (YYYY-MM-DD)

Exemplo de Requisicao

cURL

curl -X POST "https://api.pixconnect.com.br/api/v1/central/settlements/trigger" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "cycle": 1,
    "date": "2026-02-15"
  }'

JavaScript

const response = await fetch(
  "https://api.pixconnect.com.br/api/v1/central/settlements/trigger",
  {
    method: "POST",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      cycle: 1,
      date: "2026-02-15"
    }),
  }
);

const data = await response.json();
console.log(data);

Python

import requests

url = "https://api.pixconnect.com.br/api/v1/central/settlements/trigger"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}
payload = {
    "cycle": 1,
    "date": "2026-02-15"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Resposta de Sucesso

Status: 202 Accepted

{
  "success": true,
  "data": {
    "job_id": 12345,
    "date": "2026-02-15",
    "cycle": 1,
    "status": "queued"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Processamento Assincrono

O endpoint retorna imediatamente com status 202 Accepted e um job_id. O processamento ocorre em segundo plano. Use webhooks para ser notificado quando o processamento for concluido.

Erros Possiveis

Codigo	Erro	Descricao
500	JOB_QUEUE_FAILED	Falha ao enfileirar o job de processamento

---

Fluxo de Liquidacao

O diagrama abaixo ilustra o fluxo completo de processamento de liquidacao:

┌─────────────────────────────────────────────────────────────────┐
│                    Fluxo de Liquidacao                         │
└─────────────────────────────────────────────────────────────────┘

  ┌──────────┐         ┌──────────┐         ┌──────────┐
  │  API     │         │  Oban    │         │  FTP     │
  │ Request  │─────────│   Job    │─────────│  Nuclea  │
  └──────────┘         └──────────┘         └──────────┘
       │                    │                    │
       │  POST /trigger     │                    │
       │───────────────────▶│                    │
       │                    │                    │
       │  202 Accepted      │  Download ACMP615  │
       │◀───────────────────│───────────────────▶│
       │  (job_id: 12345)   │                    │
       │                    │◀───────────────────│
       │                    │   (arquivo .txt)   │
       │                    │                    │
       │              ┌─────┴─────┐              │
       │              │  Parser   │              │
       │              │  ACMP615  │              │
       │              └─────┬─────┘              │
       │                    │                    │
       │              ┌─────┴─────┐              │
       │              │ Reconcilia│              │
       │              │  Boletos  │              │
       │              └─────┬─────┘              │
       │                    │                    │
       │              ┌─────┴─────┐              │
       │              │  Webhook  │              │
       │              │  boleto.  │              │
       │              │  settled  │              │
       │              └───────────┘              │

Arquivo ACMP615

O arquivo ACMP615 e o arquivo de liquidacao da Nuclea que contem os pagamentos processados.

Estrutura do Arquivo

Tipo de Registro	Descricao
00	Header do arquivo
20	Registro de pagamento
99	Trailer do arquivo

Campos do Registro de Pagamento (Tipo 20)

Posicao	Campo	Descricao
1-2	tipo_registro	Sempre "20"
3-13	nosso_numero	Referencia do boleto
14-30	valor_pago	Valor pago em centavos
31-38	data_pagamento	Data do pagamento (YYYYMMDD)
39-46	hora_pagamento	Hora do pagamento (HHMMSS)

Webhooks Relacionados

Apos o processamento de liquidacao, os seguintes webhooks podem ser disparados:

Evento	Descricao
boleto.settled	Boleto liquidado - fundos transferidos
cycle.completed	Ciclo de liquidacao concluido

Para mais detalhes, consulte a documentacao de Webhooks.

Proximos Passos

• Health Check - Verificar configuracao do FTP
• Fluxo de Liquidacao - Guia completo do processo
• Webhooks - Configurar notificacoes