Dicionário de Dados

Descrição detalhada de todas as entidades, campos e enumerações da API

Visão geral

Este dicionário documenta todas as entidades retornadas pela API, seus campos, tipos e valores possíveis. Use como referência ao integrar com a Conta Simples.

Entidades

Card, CardTransaction, BankingTransaction, Category, CostCenter, Attachment, Vcn (em breve)

Enumerações

Tipos de cartão, status, operações e tipos de transação

Entidades principais

CardTransaction

Representa uma transação realizada com cartão de crédito.

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador único da transação (ULID, ex.: `01JB4M8WQ2YX5KN7RT9HF3DE6C`)
`operation`	enum	Sim	Tipo de operação (ver valores)
`transactionDate`	string	Sim	Data/hora da transação (ISO 8601)
`status`	enum	Sim	Status da transação (ver valores)
`type`	enum	Sim	Tipo da transação (ver valores)
`merchant`	string	Sim	Nome do estabelecimento
`amountBrl`	number	Sim	Valor em Reais (BRL)
`exchangeRateUsd`	number	Sim	Taxa de câmbio USD (para transações internacionais)
`isCanceled`	boolean	Sim	Indica se a transação foi cancelada
`isConciled`	boolean	Sim	Indica se a transação foi conciliada
`installment`	number	Sim	Número da parcela (1 para à vista)
`card`	Card	Sim	Dados do cartão utilizado
`category`	Category	Sim	Categoria da transação
`costCenter`	CostCenter	Sim	Centro de custo associado
`attachments`	array[Attachment]	Sim	Comprovantes anexados

Exemplo

{
  "id": "01JB4M8WQ2YX5KN7RT9HF3DE6C",
  "operation": "CASH_OUT",
  "transactionDate": "2025-01-15T14:30:00.000Z",
  "status": "PROCESSED",
  "type": "PURCHASE",
  "merchant": "UBER *TRIP",
  "amountBrl": 45.90,
  "exchangeRateUsd": 0,
  "isCanceled": false,
  "isConciled": true,
  "installment": 1,
  "card": {
    "id": "card_xyz789",
    "maskedNumber": "**** **** **** 1234",
    "responsibleName": "João Silva",
    "responsibleEmail": "joao@empresa.com",
    "type": "VIRTUAL"
  },
  "category": {
    "id": "cat_001",
    "name": "Transporte"
  },
  "costCenter": {
    "id": "cc_001",
    "name": "Comercial"
  },
  "attachments": []
}

BankingTransaction

Representa uma movimentação do extrato bancário — Pix, TED, transferência entre contas Conta Simples, pagamento de boleto e demais operações da conta. Retornada por Extrato Bancário e atualizada por Atualizar Transação Bancária.

Campo	Tipo	Obrigatório	Descrição
`id`	integer	Sim	Identificador da transação. Use em Atualizar Transação Bancária e Comprovante de Transação Bancária
`transactionType`	object	Sim	Tipo da movimentação: `{ id, description, icon, subType }`
`companyId`	string	Sim	ID da empresa
`status`	integer	Sim	Status numérico: `1` cancelado, `2` processado, `3` pendente
`statusDescription`	string	Sim	Descrição do status
`accountId`	integer	Sim	ID da conta bancária
`finalCardNumber`	string	Não	Últimos dígitos do cartão (quando aplicável)
`bearerName`	string	Não	Nome do portador do cartão (quando aplicável)
`transactionDate`	string	Sim	Data/hora da transação (ISO 8601)
`brlAmount`	number	Sim	Valor em Reais (BRL)
`usdAmount`	number	Sim	Valor em dólares (USD)
`usdExchangeRate`	number	Sim	Taxa de câmbio USD/BRL utilizada
`usdExchangeRateDate`	string	Não	Data da taxa de câmbio
`totalTransactionAmount`	number	Sim	Valor total da transação, incluindo encargos
`iofAmount`	number	Sim	Valor do IOF
`feeServiceAmount`	number	Sim	Valor da tarifa de serviço
`mccCode`	integer	Não	Código MCC do estabelecimento
`mccGroup`	integer	Não	Grupo MCC do estabelecimento
`idPurchaseEvent`	integer	Não	ID do evento de compra vinculado
`mccDescription`	string	Não	Descrição do MCC do estabelecimento
`sourceDestinationName`	string	Não	Nome da origem ou destino da transação
`placeEstablishment`	string	Não	Local do estabelecimento
`attachments`	array[Attachment]	Sim	Documentos anexados à transação (notas fiscais, recibos). Distinto de `showReceipt`
`conciliation`	object	Não	Estado da conciliação: `{ description, conciled }` — `conciled: true` quando a transação já foi conferida
`showReceipt`	boolean	Sim	Indica se a operação gerou comprovante bancário na plataforma. Confira este campo antes de chamar Comprovante de Transação Bancária; não é anexo — para documentos, use `attachments`
`description`	string	Não	Descrição da transação
`notes`	string	Não	Observação da transação (editável, até 1000 caracteres)
`category`	object	Não	Categoria da transação: `{ id, description }`
`costCenter`	object	Não	Centro de custo da transação: `{ id, description }`
`user`	object	Não	Usuário responsável: `{ id, email }`
`requesterUser`	object	Não	Usuário solicitante: `{ id, email }`
`customCategory`	object	Não	Categoria customizada: `{ id, name }`

Conciliação: leitura e escrita usam campos diferentes. No extrato, o estado vem em conciliation.conciled. Para conciliar, envie isConciled na raiz do corpo de Atualizar Transação Bancária — o campo aceita apenas true, e a conciliação é irreversível via API.

Exemplo

{
  "id": 987654,
  "transactionType": {
    "id": 12,
    "description": "PIX ENVIADO",
    "icon": "pix",
    "subType": "PIX_OUT"
  },
  "companyId": "01JB4M8WQ2YX5KN7RT9HF3DE6C",
  "status": 2,
  "statusDescription": "PROCESSADO",
  "accountId": 4321,
  "transactionDate": "2025-01-15T13:05:22.000Z",
  "brlAmount": 1250.00,
  "usdAmount": 0,
  "usdExchangeRate": 0,
  "totalTransactionAmount": 1250.00,
  "iofAmount": 0,
  "feeServiceAmount": 0,
  "sourceDestinationName": "Fornecedor Exemplo LTDA",
  "attachments": [],
  "conciliation": {
    "description": "Conferido",
    "conciled": true
  },
  "showReceipt": true,
  "description": "Pagamento de fornecedor",
  "notes": "Ref. pedido 4471",
  "category": {
    "id": "cat_014",
    "description": "Fornecedores"
  },
  "costCenter": {
    "id": "cc_002",
    "description": "Operações"
  },
  "user": {
    "id": "usr_001",
    "email": "financeiro@empresa.exemplo"
  },
  "customCategory": {
    "id": 7,
    "name": "Insumos"
  }
}

Card

Representa um cartão de crédito (físico ou virtual).

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador único do cartão
`maskedNumber`	string	Sim	Número do cartão mascarado (ex: `** ** 1234`)
`responsibleName`	string	Sim	Nome do responsável pelo cartão
`responsibleEmail`	string	Sim	E-mail do responsável pelo cartão
`type`	enum	Sim	Tipo do cartão (ver valores)

Exemplo

{
  "id": "card_xyz789",
  "maskedNumber": "**** **** **** 1234",
  "responsibleName": "Maria Santos",
  "responsibleEmail": "maria@empresa.com",
  "type": "PHYSICAL"
}

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador único da categoria
`name`	string	Sim	Nome da categoria

CostCenter

Representa um centro de custo para alocação contábil de despesas.

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador único do centro de custo
`name`	string	Sim	Nome do centro de custo

Exemplo

{
  "id": "cc_001",
  "name": "Marketing"
}

Attachment

Representa um arquivo anexado a uma transação (comprovante, nota fiscal, etc.).

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador único do anexo
`name`	string	Sim	Nome do arquivo
`_links`	object	Não	Links HATEOAS para acesso ao conteúdo

Exemplo

{
  "id": "att_001",
  "name": "comprovante.pdf",
  "_links": {
    "content": {
      "href": "/attachments/v1/content/att_001",
      "rel": "GET"
    }
  }
}

Para baixar o conteúdo do anexo, use o endpoint GET /attachments/v1/content/{attachmentId} documentado na API Reference.

Vcn

🚧 Em breve — os endpoints de VCN ainda não estão disponíveis em Sandbox nem Produção. Os termos abaixo já estão publicados para você preparar a integração.

Cartão virtual de uso restrito (VCN, Virtual Card Number) emitido para pagar uma reserva de turismo — hospedagem (HOTEL) ou aérea (AERIAL) — ou um uso definido por você (CUSTOM, ex.: um cartão por fornecedor, recarregável). Retornado por Criar VCN e atualizado por Atualizar VCN.

Campo	Tipo	Obrigatório	Descrição
`vcnId`	string	Sim	Identificador do VCN (ULID). Endereça Atualizar VCN e Revelar dados do VCN
`type`	enum	Sim	Vínculo do cartão: `HOTEL`, `AERIAL` ou `CUSTOM`
`partner`	string	Sim	Plataforma integradora, resolvida da credencial e ecoada na resposta — o parceiro não a envia
`hotelBooking.reservationId`	string	Condicional	Id da reserva na OBT — chave de idempotência do tipo `HOTEL`
`flightBooking.recordLocator`	string	Condicional	Localizador da reserva (PNR, Passenger Name Record) — chave de idempotência do tipo `AERIAL`
`reference.id`	string	Condicional	Identificador opaco definido por você — chave de idempotência do tipo `CUSTOM`
`status`	enum	Sim	`ACTIVE`, `BLOCKED` ou `CANCELLED`
`startDate` / `endDate`	string	Sim	Janela de uso do cartão, em data pura (`YYYY-MM-DD`) — o que você informou no pedido ou, na ausência, o dia da emissão e o default do tipo. São os mesmos nomes nas duas direções; não é a validade física (`card.expirationDate`)
`limit`	object	Sim	Teto de gasto vigente `{value, currency}` (decimal, 2 casas): informado no `CUSTOM`, derivado do `amount` nos tipos de reserva
`card`	object	Sim	`pan`, `cvv` e `expirationDate` em claro — não logue nem cacheie

Exemplos completos de request e response na referência do endpoint.

Enumerações

operation

Indica a direção do fluxo financeiro da transação.

Valor	Descrição
`CASH_IN`	Entrada de valor (crédito, estorno)
`CASH_OUT`	Saída de valor (compra, saque)

status

Estado atual da transação no ciclo de processamento.

Valor	Descrição
`PENDING`	Transação pendente de processamento
`PROCESSED`	Transação processada/liquidada
`CANCELED`	Transação cancelada

type

Classificação detalhada do tipo de transação.

Valor	Descrição
`PURCHASE`	Compra nacional
`PURCHASE_INTERNATIONAL`	Compra internacional
`PURCHASE_BNPL`	Compra parcelada (Buy Now Pay Later)
`WITHDRAW`	Saque nacional
`WITHDRAW_INTERNATIONAL`	Saque internacional
`WITHDRAW_FUNDS`	Resgate de fundos
`BALANCE_INQUIRY`	Consulta de saldo
`PAYMENT_PLAN_INQUIRY`	Consulta de plano de pagamento
`REFUND`	Estorno nacional
`REFUND_INTERNATIONAL`	Estorno internacional
`REFUND_CREDIT_ADJUSTMENT`	Ajuste de crédito (estorno)
`REVERSAL_CREDIT_ADJUSTMENT`	Reversão de ajuste de crédito
`REFUND_IOF`	Estorno de IOF
`REFUND_PURCHASE_BNPL`	Estorno de compra parcelada
`IOF`	Imposto sobre Operações Financeiras
`LIMIT`	Ajuste de limite (débito)
`LIMIT_CREDIT`	Ajuste de limite (crédito)
`SUMMARY`	Resumo/consolidação
`BILL_TARIFF`	Tarifa de fatura
`REFUND_BILL_TARIFF`	Estorno de tarifa
`INVOICE_PAYMENT`	Pagamento de fatura

card.type

Tipo do cartão.

Valor	Descrição
`VIRTUAL`	Cartão virtual (uso online)
`PHYSICAL`	Cartão físico (plástico)

Objetos de request

CardsTransactionRequest

Parâmetros para consulta de extrato de cartão.

Campo	Tipo	Obrigatório	Descrição
`startDate`	string	Sim	Data inicial do período (`YYYY-MM-DD`)
`endDate`	string	Sim	Data final do período (`YYYY-MM-DD`)
`limit`	integer	Sim	Quantidade de resultados (5-100)
`nextPageStartKey`	string	Não	Cursor para paginação

O período consultado (endDate - startDate) não pode exceder 62 dias.

Exemplo

{
  "startDate": "2025-01-01",
  "endDate": "2025-01-31",
  "limit": 50
}

Objetos de response

CardsTransactionResponse

Resposta da consulta de extrato com lista de transações.

Campo	Tipo	Descrição
`transactions`	array[CardTransaction]	Lista de transações
`nextPageStartKey`	string	Cursor para próxima página (se houver mais resultados)

Exemplo

{
  "transactions": [
    {
      "id": "01JB4M9XR3ZY6LN8SU0IG4EF7D",
      "operation": "CASH_OUT",
      "transactionDate": "2025-01-15T14:30:00.000Z",
      "status": "PROCESSED",
      "type": "PURCHASE",
      "merchant": "RESTAURANTE XYZ",
      "amountBrl": 89.90
    }
  ],
  "nextPageStartKey": "eyJsYXN0SWQiOiJ0eG5fMDAxIn0="
}

Regras globais

Datas e períodos

Formato de entrada: YYYY-MM-DD (ex: 2025-01-15)
Formato de saída: ISO 8601 completo (ex: 2025-01-15T14:30:00.000Z)
Período máximo: 62 dias por consulta
Timezone: UTC

Paginação

Limite mínimo: 5 itens
Limite máximo: 100 itens
Cursor: O campo nextPageStartKey é um token opaco — não tente decodificar ou modificar

Anexos e links

Anexos são retornados com links HATEOAS no campo _links
Use o endpoint GET /attachments/v1/content/{attachmentId} para baixar o conteúdo
Formatos suportados: image/png, image/jpeg, application/pdf

Próximos passos

Boas Práticas

Paginação, retry e download de anexos.

Fluxo de Integração

Passo a passo do Sandbox à Produção.

API Reference

Referência técnica dos endpoints.

Erros Comuns

Diagnóstico e resolução de erros.

Was this page helpful?