Criar uma Anotação de Transação
Use este endpoint para criar uma transação sem impacto financeiro, para incluir operações no ledger, porém sem afetar os saldos das contas.
Nota: o campo pending é aceito no corpo da requisição, mas é ignorado para anotações — o status de uma anotação é sempre definido como NOTED.
Cabeçalhos
O tipo de mídia do recurso. O valor recomendado é application/json.
Um identificador único utilizado para rastrear e acompanhar cada requisição.
Token JWT bearer para autenticação.
Obrigatório quando PLUGIN_AUTH_ENABLED=true (exigido em implantações multi-tenant).
Opcional no modo OSS single-tenant padrão.
Formato: Bearer <token>
Uma chave única que garante a idempotência da transação. Se não fornecida, o sistema gera automaticamente um hash SHA-256 com base no corpo da requisição. As chaves são escopadas por organização e ledger.
Sempre valide o header de resposta X-Idempotency-Replayed para distinguir transações novas de replays em cache.
Consulte Retentativas e idempotência para boas práticas.
O tempo de vida (TTL) da chave de idempotência, definido em segundos. Se não fornecido, o padrão é 300 segundos (5 minutos). Apenas o TTL da primeira requisição é utilizado; alterá-lo em retentativas não tem efeito.
Consulte Retentativas e idempotência para mais detalhes.
Parâmetros de caminho
O identificador único da Organização associada ao Ledger.
O identificador único do Ledger associado.
Corpo
Um objeto contendo informações sobre a transação que será enviada.
O nome do grupo do plano de contas que categoriza esta transação sob um grupo específico.
256"FUNDING"
Uma descrição para a transação.
256Código da transação para referência.
100"TR12345"
Se a transação deve ser criada em estado pendente.
Obsoleto. Use routeId em vez disso. Identificador legado da rota mantido por compatibilidade; é aceito mas não é utilizado na validação de roteamento.
O identificador único (UUID) da Rota de Transação associada a esta transação.
Importante: Quando a validação de Rota de Transação está habilitada para o seu Ledger, este campo se torna obrigatório e deve corresponder a um id existente das suas Rotas de Transação configuradas. No entanto, quando a validação está desabilitada (comportamento padrão), este campo é opcional.
A data em que a transação foi realizada. Usado para adicionar transações passadas. Deve ser uma data no passado.
Um objeto contendo pares de chave-valor para adicionar como metadata, onde o campo name é a chave e o campo value é o valor. Por exemplo, para adicionar um Centro de Custo, use 'costCenter': 'BR_11101997'.
Restrições: as chaves devem ter no máximo 100 caracteres; valores de string no máximo 2000 caracteres. Objetos aninhados não são permitidos (os valores devem ser string, número ou booleano), a estrutura não pode exceder uma profundidade máxima de 10, e é permitido um máximo de 100 chaves.
Resposta
Indica que a requisição foi bem-sucedida e a resposta contém os dados esperados.
A resposta inclui o header X-Idempotency-Replayed.
Se o valor for false, a transação foi recém-processada. Se o valor for true, a resposta é uma repetição de uma requisição processada anteriormente.
Consulte Retentativas e idempotência para mais detalhes.
O identificador único da transação.
O identificador único da transação pai/original para reversões. Este campo é preenchido pelo servidor quando uma transação é revertida e deve ser tratado como somente leitura pelos clientes.
O identificador único da Organização.
O identificador único do Ledger.
Descrição da transação.
Especifica a Rota de Transação associada à transação.
O identificador único da Rota de Transação aplicada a esta transação.
O status da transação (pendente, concluída, revertida).
O valor enviado.
O nome do ativo utilizado na operação.
O nome do grupo do plano de contas.
A lista de contas utilizadas como origem.
A lista de contas utilizadas como destino.
Data e hora de criação (UTC).
Data e hora da última atualização (UTC).
Data e hora da exclusão lógica, se aplicável (UTC).
Um objeto contendo pares de chave-valor para adicionar como metadata, onde o campo name é a chave e o campo value é o valor. Por exemplo, para adicionar um Centro de Custo, use 'costCenter': 'BR_11101997'.
Restrições: as chaves devem ter no máximo 100 caracteres; valores de string no máximo 2000 caracteres. Objetos aninhados não são permitidos (os valores devem ser string, número ou booleano), a estrutura não pode exceder uma profundidade máxima de 10, e é permitido um máximo de 100 chaves.