Conciliação

Em desenvolvimento

Este módulo ainda não está disponível na API. A documentação abaixo é uma prévia da funcionalidade planejada.

Importação e matching de lançamentos bancários para conciliação financeira.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/baas/api/v1/reconciliations`	Criar conciliação	`BAAS_RECONCILIATION_CREATE`
GET	`/baas/api/v1/reconciliations`	Listar conciliações	`BAAS_RECONCILIATION_READ`
GET	`/baas/api/v1/reconciliations/:id`	Obter conciliação por ID	`BAAS_RECONCILIATION_READ`
GET	`/baas/api/v1/reconciliations/:id/entries`	Listar lançamentos da conciliação	`BAAS_RECONCILIATION_READ`

Atributos da Conciliação

Campo	Tipo	Descrição
`accountId`	string (UUID)	ID da conta bancária
`status`	enum	Status: `PENDING`, `PROCESSING`, `COMPLETED`, `PARTIALLY_MATCHED`, `FAILED`
`periodStart`	date	Data inicial do período
`periodEnd`	date	Data final do período
`totalEntries`	integer	Total de lançamentos importados
`matchedEntries`	integer	Lançamentos conciliados
`unmatchedEntries`	integer	Lançamentos não conciliados
`totalAmount`	number	Valor total dos lançamentos
`matchedAmount`	number	Valor conciliado
`unmatchedAmount`	number	Valor não conciliado
`source`	enum	Origem: `FILE_UPLOAD`, `API_IMPORT`, `AUTOMATIC`
`failureReason`	string	Motivo da falha (quando aplicável)
`completedAt`	datetime	Data de conclusão
`createdAt`	datetime	Data de criação
`updatedAt`	datetime	Data da última atualização

Atributos do Lançamento (Entry)

Campo	Tipo	Descrição
`type`	enum	Tipo: `CREDIT`, `DEBIT`
`amount`	number	Valor
`description`	string	Descrição do lançamento
`transactionDate`	date	Data da transação
`matchStatus`	enum	Status: `MATCHED`, `UNMATCHED`, `MANUAL`
`matchedStatementId`	string (UUID)	ID da movimentação do extrato (quando matched)
`externalRef`	string	Referência externa (do arquivo importado)

Criar Conciliação

POST /baas/api/v1/reconciliations

Cria uma nova conciliação importando lançamentos para matching com o extrato bancário.

Atributos

Campo	Tipo	Obrigatório	Descrição
`accountId`	string	Sim	ID da conta bancária
`periodStart`	date	Sim	Data inicial do período
`periodEnd`	date	Sim	Data final do período
`source`	enum	Sim	Origem: `FILE_UPLOAD`, `API_IMPORT`
`entries`	array	Sim	Lançamentos para conciliação

Atributos de cada Entry

Campo	Tipo	Obrigatório	Descrição
`type`	enum	Sim	`CREDIT` ou `DEBIT`
`amount`	number	Sim	Valor do lançamento
`description`	string	Sim	Descrição
`transactionDate`	date	Sim	Data da transação
`externalRef`	string	Não	Referência externa

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/reconciliations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "reconciliations",
      "attributes": {
        "accountId": "550e8400-e29b-41d4-a716-446655440100",
        "periodStart": "2024-01-01",
        "periodEnd": "2024-01-31",
        "source": "API_IMPORT",
        "entries": [
          {
            "type": "DEBIT",
            "amount": 5000.00,
            "description": "Pagamento NF 12345",
            "transactionDate": "2024-01-10",
            "externalRef": "ERP-PAG-12345"
          },
          {
            "type": "CREDIT",
            "amount": 15000.00,
            "description": "Recebimento cliente ABC",
            "transactionDate": "2024-01-12",
            "externalRef": "ERP-REC-67890"
          },
          {
            "type": "DEBIT",
            "amount": 3000.00,
            "description": "Pagamento fornecedor XYZ",
            "transactionDate": "2024-01-15",
            "externalRef": "ERP-PAG-11111"
          }
        ]
      }
    }
  }'

const response = await fetch('https://baas.stg.catalisa.app/baas/api/v1/reconciliations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'reconciliations',
      attributes: {
        accountId: '550e8400-e29b-41d4-a716-446655440100',
        periodStart: '2024-01-01',
        periodEnd: '2024-01-31',
        source: 'API_IMPORT',
        entries: [
          {
            type: 'DEBIT',
            amount: 5000.00,
            description: 'Pagamento NF 12345',
            transactionDate: '2024-01-10',
            externalRef: 'ERP-PAG-12345',
          },
          {
            type: 'CREDIT',
            amount: 15000.00,
            description: 'Recebimento cliente ABC',
            transactionDate: '2024-01-12',
            externalRef: 'ERP-REC-67890',
          },
          {
            type: 'DEBIT',
            amount: 3000.00,
            description: 'Pagamento fornecedor XYZ',
            transactionDate: '2024-01-15',
            externalRef: 'ERP-PAG-11111',
          },
        ],
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Conciliação criada: ${data.id}`);
console.log(`Status: ${data.attributes.status}`);
console.log(`Total de lançamentos: ${data.attributes.totalEntries}`);

Response (201 Created)

{
  "data": {
    "type": "reconciliations",
    "id": "550e8400-e29b-41d4-a716-446655440600",
    "links": {
      "self": "/baas/api/v1/reconciliations/550e8400-e29b-41d4-a716-446655440600"
    },
    "attributes": {
      "accountId": "550e8400-e29b-41d4-a716-446655440100",
      "status": "PROCESSING",
      "periodStart": "2024-01-01",
      "periodEnd": "2024-01-31",
      "totalEntries": 3,
      "matchedEntries": 0,
      "unmatchedEntries": 3,
      "totalAmount": 23000.00,
      "matchedAmount": 0,
      "unmatchedAmount": 23000.00,
      "source": "API_IMPORT",
      "failureReason": null,
      "completedAt": null,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  },
  "links": {
    "self": "/baas/api/v1/reconciliations/550e8400-e29b-41d4-a716-446655440600"
  }
}

Listar Conciliações

GET /baas/api/v1/reconciliations

Lista conciliações com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[accountId]`	UUID	Filtrar por conta
`filter[status]`	enum	Filtrar por status
`filter[periodStart]`	date	Período a partir de
`filter[periodEnd]`	date	Período até

cURL
JavaScript

curl 'https://baas.stg.catalisa.app/baas/api/v1/reconciliations?filter[accountId]=550e8400-e29b-41d4-a716-446655440100&filter[status]=COMPLETED' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'filter[accountId]': '550e8400-e29b-41d4-a716-446655440100',
  'filter[status]': 'COMPLETED',
});

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/reconciliations?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta } = await response.json();
console.log(`Total de conciliações: ${meta.totalItems}`);

Obter Conciliação por ID

GET /baas/api/v1/reconciliations/:id

Obtém os detalhes e estatísticas de uma conciliação específica.

cURL
JavaScript

curl 'https://baas.stg.catalisa.app/baas/api/v1/reconciliations/550e8400-e29b-41d4-a716-446655440600' \
  -H 'Authorization: Bearer SEU_TOKEN'

const reconciliationId = '550e8400-e29b-41d4-a716-446655440600';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/reconciliations/${reconciliationId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Status: ${data.attributes.status}`);
console.log(`Conciliados: ${data.attributes.matchedEntries}/${data.attributes.totalEntries}`);
console.log(`Valor conciliado: R$ ${data.attributes.matchedAmount.toFixed(2)}`);
console.log(`Valor pendente: R$ ${data.attributes.unmatchedAmount.toFixed(2)}`);

Listar Lançamentos da Conciliação

GET /baas/api/v1/reconciliations/:id/entries

Lista os lançamentos de uma conciliação com seu status de matching.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[matchStatus]`	enum	Filtrar por status: `MATCHED`, `UNMATCHED`, `MANUAL`

cURL
JavaScript

curl 'https://baas.stg.catalisa.app/baas/api/v1/reconciliations/550e8400-e29b-41d4-a716-446655440600/entries?filter[matchStatus]=UNMATCHED' \
  -H 'Authorization: Bearer SEU_TOKEN'

const reconciliationId = '550e8400-e29b-41d4-a716-446655440600';

const params = new URLSearchParams({
  'filter[matchStatus]': 'UNMATCHED',
});

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/reconciliations/${reconciliationId}/entries?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
data.forEach((entry) => {
  console.log(`${entry.attributes.type} R$ ${entry.attributes.amount.toFixed(2)} - ${entry.attributes.description} [${entry.attributes.matchStatus}]`);
});

Response (200 OK)

{
  "data": [
    {
      "type": "reconciliation-entries",
      "id": "550e8400-e29b-41d4-a716-446655440610",
      "attributes": {
        "type": "DEBIT",
        "amount": 3000.00,
        "description": "Pagamento fornecedor XYZ",
        "transactionDate": "2024-01-15",
        "matchStatus": "UNMATCHED",
        "matchedStatementId": null,
        "externalRef": "ERP-PAG-11111"
      }
    }
  ],
  "meta": {
    "totalItems": 1,
    "totalPages": 1,
    "currentPage": 1,
    "itemsPerPage": 20
  }
}

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Dados inválidos (período, lançamentos, etc.)
404	`NOT_FOUND`	Conciliação ou conta não encontrada
409	`CONFLICT`	Já existe conciliação para o mesmo período
422	`UNPROCESSABLE`	Período maior que 90 dias ou sem lançamentos

Endpoints​

Atributos da Conciliação​

Atributos do Lançamento (Entry)​

Criar Conciliação​

Atributos​

Atributos de cada Entry​

Response (201 Created)​

Listar Conciliações​

Query Parameters​

Obter Conciliação por ID​

Listar Lançamentos da Conciliação​

Query Parameters​

Response (200 OK)​

Erros Comuns​

Endpoints

Atributos da Conciliação

Atributos do Lançamento (Entry)

Criar Conciliação

Atributos

Atributos de cada Entry

Response (201 Created)

Listar Conciliações

Query Parameters

Obter Conciliação por ID

Listar Lançamentos da Conciliação

Query Parameters

Response (200 OK)

Erros Comuns