Pular para o conteúdo principal
API docs by Redocly

Cash Operations API (Internal) (1.0.0)

Download OpenAPI specification:Download

Operações de Caixa (Cash) - API Interna

Visão Geral

As operações de caixa permitem realizar entradas e saídas de valores, além de lançamentos manuais no sistema. Todas as rotas estão sob o prefixo /internal e requerem autenticação interna.

Requisitos

  • Todas as operações requerem autenticação via header Authorization com token interno

Diferenças entre Operações

Cash-In (Entrada)

  • Processamento: Assíncrono via fila de processamento
  • Response: 202 Accepted (apenas confirma envio para fila de processamento)
  • Uso: Para entradas de valores que serão processadas posteriormente
  • Idempotência: Usa e2eId para evitar duplicação

Cash-Out (Saída)

  • Processamento: Síncrono e imediato
  • Response: 201 Created com dados da transação
  • Uso: Para saídas de valores com processamento imediato
  • Idempotência: Retorna 208 se transação já existe

Manual Entry (Lançamento Manual)

  • Processamento: Síncrono e imediato
  • Response: 200 OK com dados da transação
  • Uso: Para ajustes manuais de saldo (crédito ou débito)
  • Autenticação: Usa usuário interno (ID 1) automaticamente

Cash Operations

Operações de entrada e saída de valores no caixa.

Entrada de valores (Cash-In)

Realiza uma entrada de valores no caixa. Esta operação é assíncrona e envia a requisição para uma fila de processamento.

Importante:

  • O valor deve ser informado como string (ex: "1000.00")
  • Use e2eId para garantir idempotência
  • A resposta apenas confirma o envio para a fila, não o processamento
Authorizations:
InternalAuth
Request Body schema: application/json
required
account
string

Número da conta (obrigatório se accountId não for informado)

accountId
integer

ID da conta (obrigatório se account não for informado)

type
string
Default: "PIX"
Enum: "PIX" "TED" "DOC" "BILLET"

Tipo da transação

amount
required
string^\d+\.\d{2}$

Valor da entrada (string)

msgId
string

ID da mensagem (obrigatório se e2eId não for informado)

e2eId
string

End-to-end ID para idempotência

description
string <= 255 characters

Descrição da transação

object

Dados do boleto (opcional)

object

Dados da transação PIX (opcional)

object

Dados da transação (opcional)

Responses

Request samples

Content type
application/json
Example
{
  • "accountId": 123,
  • "type": "PIX",
  • "amount": "1000.00",
  • "e2eId": "E2E123456789",
  • "description": "Recebimento PIX",
  • "pix": {
    },
  • "transaction": {
    }
}

Response samples

Content type
application/json
{
  • "success": true
}

Saída de valores (Cash-Out)

Realiza uma saída de valores do caixa. Esta operação é síncrona e processa imediatamente.

Importante:

  • O valor deve ser informado como string (ex: "500.00")
  • Retorna 208 se a transação já existe (idempotência)
  • A resposta inclui os dados completos da transação criada
Authorizations:
InternalAuth
Request Body schema: application/json
required
account
string

Número da conta (obrigatório se accountId não for informado)

accountId
integer

ID da conta (obrigatório se account não for informado)

type
string
Default: "PIX"
Enum: "PIX" "TED" "DOC" "BILLET"

Tipo da transação

amount
required
string^\d+\.\d{2}$

Valor da saída (string)

msgId
string

ID da mensagem (obrigatório se e2eId não for informado)

e2eId
string

End-to-end ID para idempotência

description
string <= 255 characters

Descrição da transação

object

Dados do boleto (opcional)

object

Dados da transação PIX (opcional)

object

Dados da transação (opcional)

Responses

Request samples

Content type
application/json
{
  • "accountId": 123,
  • "amount": "500.00",
  • "e2eId": "E2E987654321",
  • "description": "Pagamento fornecedor",
  • "transaction": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Manual Entries

Lançamentos manuais de crédito e débito em contas.

Lançamento manual

Realiza um lançamento manual no sistema (crédito ou débito). Esta operação é síncrona e processa imediatamente.

Importante:

  • O valor deve ser informado como número (ex: 250.00)
  • Tipo pode ser CREDIT ou DEBIT
  • Usa automaticamente o usuário interno (ID 1)
  • Requer reference e reason para auditoria
Authorizations:
InternalAuth
Request Body schema: application/json
required
account
string

Número da conta (obrigatório se accountId não for informado)

accountId
integer >= 1

ID da conta (obrigatório se account não for informado)

amount
required
number >= 0.01

Valor do lançamento (número decimal)

reference
required
string

Referência do lançamento

reason
required
string

Motivo/justificativa do lançamento

type
required
string
Enum: "CREDIT" "DEBIT"

Tipo do lançamento

historicId
string <uuid>

ID do histórico contábil (UUID v4)

accountingEventId
integer >= 1

ID do evento contábil

Responses

Request samples

Content type
application/json
Example
{
  • "accountId": 123,
  • "amount": 250,
  • "reference": "REF123456",
  • "reason": "Ajuste de saldo - crédito promocional",
  • "type": "CREDIT",
  • "historicId": "550e8400-e29b-41d4-a716-446655440000",
  • "accountingEventId": 456
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "amount": "250.00",
  • "type": "MANUAL_ENTRY",
  • "creditDebitType": "CREDIT",
  • "status": "LIQUIDATED",
  • "paymentType": "INSTANT",
  • "actionTag": "PACS008C",
  • "relatedAccountId": 123,
  • "createdAt": "2025-11-18T10:00:00.000Z",
  • "updatedAt": "2025-11-18T10:00:00.000Z"
}