# Clareza

> Plataforma de gestão financeira para acompanhar movimentações, contas, cartões, despesas, entradas, assinaturas, compromissos a pagar e integrações.

O Clareza possui uma API autenticada para agentes consultarem o contexto financeiro de um espaço e, quando autorizados, criarem ou corrigirem movimentações.

Orientações essenciais:

- Comece consultando o espaço para obter o `activeCompanyId` e os identificadores válidos de categorias, centros de custo e meios de pagamento.
- Use apenas o espaço associado ao token. Não invente nem reutilize identificadores de outro espaço.
- Trate todos os dados como privados e nunca revele tokens em URLs, mensagens, registros ou respostas.
- Antes de escrever, confirme os campos inferidos e consulte movimentações semelhantes para evitar duplicidade.
- Envie valores positivos. Use `direction` para diferenciar `income`, `expense` e `transfer`.
- Preserve a moeda original da movimentação. Códigos aceitos incluem moedas fiduciárias e criptoativos, como `BRL`, `USD`, `USDC` e `BTC`.
- Cada conta ou cartão possui sua própria moeda. Ao informar `paymentMethodId`, use a moeda exibida nesse meio de pagamento; a moeda padrão do espaço só vale quando nenhuma conta ou moeda mais específica foi informada.
- Não some nem converta moedas diferentes silenciosamente. Uma transferência entre moedas distintas exige uma operação de câmbio explícita com os valores de origem e destino.
- Para impostos, preserve separadamente o tributo (`taxType`, como `IRRF` ou `ICMS`) e o documento de arrecadação (`taxDocumentType`, como `DARF`, `DAS`, `GPS`, `GNRE` ou `DAE`). Omita esses campos quando não houver evidência suficiente; o Clareza também executa detecção conservadora pela descrição.
- Uma transferência exige conta de origem e destino e não deve ser tratada como entrada ou despesa.

## Documentação para agentes

- [Guia da API](https://clareza.me/agent-api.md): fluxo recomendado, autenticação, permissões, exemplos e tratamento de erros.
- [Especificação OpenAPI](https://api.clareza.me/agent-openapi.json): operações, parâmetros e modelos de dados em formato legível por máquinas.

## Aplicação

- [Clareza](https://clareza.me/): aplicação web autenticada para configurar acessos e acompanhar os dados financeiros.