Lancamentos Financeiros

Gerencie lancamentos financeiros (contas a receber e a pagar) da sua empresa.

Listar Lancamentos

`GET /external/v1/financial-entries`

Retorna uma lista paginada de lancamentos financeiros.

Query Parameters:

Parametro	Tipo	Obrigatorio	Descricao
`page`	`number`	Nao	Pagina atual (default: `1`)
`limit`	`number`	Nao	Itens por pagina (default: `20`, max: `100`)
`search`	`string`	Nao	Busca por titulo
`typeCategory`	`string`	Nao	`REVENUE` (receita) ou `EXPENSE` (despesa)
`status`	`string`	Nao	`PENDING`, `SETTLED`, `OVERDUE`, `CANCELLED`
`personId`	`string`	Nao	Filtro por pessoa vinculada
`dueDateFrom`	`string`	Nao	Vencimento a partir de (ISO 8601: `YYYY-MM-DD`)
`dueDateTo`	`string`	Nao	Vencimento ate (ISO 8601: `YYYY-MM-DD`)
`orderBy`	`string`	Nao	Campo: `title`, `originalDueDate`, `originalAmount`, `createdAt` (default: `createdAt`)
`order`	`string`	Nao	`ASC` ou `DESC` (default: `DESC`)

Exemplo de requisicao:

curl -X GET "https://api.tesselys.com.br/external/v1/financial-entries?typeCategory=REVENUE&status=PENDING&dueDateFrom=2026-03-01&dueDateTo=2026-03-31&limit=20" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}"

Resposta (200):

{
  "data": [
    {
      "id": "clx5e6f7g8h9i0j1k2l3m4n5",
      "code": "REC-2030",
      "title": "Fatura Mensal - Tech Solutions",
      "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
      "personName": "Tech Solutions Ltda",
      "typeCategory": "REVENUE",
      "status": "PENDING",
      "originalAmount": 8500.00,
      "paidAmount": null,
      "originalDueDate": "2026-03-31T00:00:00.000Z",
      "paymentDate": null,
      "financialCategoryId": "clxcat001",
      "financialCategoryName": "Servicos Prestados",
      "bankAccountId": "clxbank001",
      "bankAccountName": "Conta Principal - Itau",
      "paymentMethod": "BANK_SLIP",
      "installmentNumber": 1,
      "totalInstallments": 1,
      "isActive": true,
      "createdAt": "2026-03-01T09:00:00.000Z",
      "updatedAt": "2026-03-01T09:00:00.000Z"
    }
  ],
  "meta": {
    "total": 34,
    "page": 1,
    "limit": 20,
    "totalPages": 2
  }
}

Buscar Lancamento por ID

`GET /external/v1/financial-entries/:id`

Exemplo de requisicao:

curl -X GET "https://api.tesselys.com.br/external/v1/financial-entries/clx5e6f7g8h9i0j1k2l3m4n5" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}"

Resposta (200):

{
  "id": "clx5e6f7g8h9i0j1k2l3m4n5",
  "code": "REC-2030",
  "title": "Fatura Mensal - Tech Solutions",
  "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
  "personName": "Tech Solutions Ltda",
  "typeCategory": "REVENUE",
  "status": "PENDING",
  "originalAmount": 8500.00,
  "paidAmount": null,
  "discountAmount": 0,
  "interestAmount": 0,
  "fineAmount": 0,
  "originalDueDate": "2026-03-31T00:00:00.000Z",
  "paymentDate": null,
  "financialCategoryId": "clxcat001",
  "financialCategoryName": "Servicos Prestados",
  "bankAccountId": "clxbank001",
  "bankAccountName": "Conta Principal - Itau",
  "paymentMethod": "BANK_SLIP",
  "installmentNumber": 1,
  "totalInstallments": 1,
  "notes": "Referente ao contrato mensal de suporte tecnico.",
  "isActive": true,
  "createdAt": "2026-03-01T09:00:00.000Z",
  "updatedAt": "2026-03-01T09:00:00.000Z"
}

Criar Lancamento

`POST /external/v1/financial-entries`

Body:

Campo	Tipo	Obrigatorio	Descricao
`personId`	`string`	Sim	ID da pessoa vinculada
`title`	`string`	Sim	Titulo do lancamento (max: 255)
`typeCategory`	`string`	Sim	`REVENUE` (receita) ou `EXPENSE` (despesa)
`originalAmount`	`number`	Sim	Valor original (deve ser maior que zero)
`originalDueDate`	`string`	Sim	Data de vencimento (ISO 8601: `YYYY-MM-DD`)
`financialCategoryId`	`string`	Sim	ID da categoria financeira
`bankAccountId`	`string`	Sim	ID da conta bancaria
`paymentMethod`	`string`	Nao	Metodo de pagamento (ver enum abaixo)
`totalInstallments`	`number`	Nao	Numero de parcelas (default: `1`, max: `120`)
`notes`	`string`	Nao	Observacoes

Exemplo — Lancamento avista:

curl -X POST "https://api.tesselys.com.br/external/v1/financial-entries" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
    "title": "Consultoria Tributaria - Marco/2026",
    "typeCategory": "REVENUE",
    "originalAmount": 4500.00,
    "originalDueDate": "2026-04-10",
    "financialCategoryId": "clxcat001",
    "bankAccountId": "clxbank001",
    "paymentMethod": "PIX"
  }'

Resposta (201):

{
  "id": "clx6f7g8h9i0j1k2l3m4n5o6",
  "code": "REC-2031",
  "title": "Consultoria Tributaria - Marco/2026",
  "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
  "personName": "Tech Solutions Ltda",
  "typeCategory": "REVENUE",
  "status": "PENDING",
  "originalAmount": 4500.00,
  "paidAmount": null,
  "originalDueDate": "2026-04-10T00:00:00.000Z",
  "paymentDate": null,
  "financialCategoryId": "clxcat001",
  "financialCategoryName": "Servicos Prestados",
  "bankAccountId": "clxbank001",
  "bankAccountName": "Conta Principal - Itau",
  "paymentMethod": "PIX",
  "installmentNumber": 1,
  "totalInstallments": 1,
  "isActive": true,
  "createdAt": "2026-03-25T10:30:00.000Z",
  "updatedAt": "2026-03-25T10:30:00.000Z"
}

Exemplo — Lancamento parcelado:

curl -X POST "https://api.tesselys.com.br/external/v1/financial-entries" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "personId": "clx1a2b3c4d5e6f7g8h9i0j1",
    "title": "Licenca Anual de Software",
    "typeCategory": "EXPENSE",
    "originalAmount": 24000.00,
    "originalDueDate": "2026-04-01",
    "financialCategoryId": "clxcat005",
    "bankAccountId": "clxbank001",
    "paymentMethod": "CREDIT_CARD",
    "totalInstallments": 12,
    "notes": "Licenca anual do software de gestao. 12x de R$ 2.000,00."
  }'

Parcelamento

Quando totalInstallments > 1, o sistema cria automaticamente as parcelas com vencimentos mensais a partir da originalDueDate. O valor de cada parcela e calculado automaticamente (originalAmount / totalInstallments).

Valores de Enum

typeCategory

Valor	Descricao
`REVENUE`	Receita (conta a receber)
`EXPENSE`	Despesa (conta a pagar)

status (somente leitura)

Valor	Descricao
`PENDING`	Pendente — aguardando pagamento
`SETTLED`	Liquidado — pagamento confirmado
`OVERDUE`	Vencido — passou da data de vencimento sem pagamento
`CANCELLED`	Cancelado

paymentMethod

Valor	Descricao
`PIX`	PIX
`CREDIT_CARD`	Cartao de credito
`DEBIT_CARD`	Cartao de debito
`BANK_SLIP`	Boleto bancario
`BANK_TRANSFER`	Transferencia bancaria
`CASH`	Dinheiro
`CHECK`	Cheque
`OTHER`	Outro

Listar Lancamentos​

GET /external/v1/financial-entries​

Buscar Lancamento por ID​

GET /external/v1/financial-entries/:id​

Criar Lancamento​

POST /external/v1/financial-entries​

Valores de Enum​

typeCategory​

status (somente leitura)​

paymentMethod​