Migrar da API v1 para a API v2

​

Rotas do Ledger

• /v2/organizations e /v2/organizations/{organization_id}/ledgers recebem apenas a organização.
• /v2/settings/metadata-indexes não recebe organização nem ledger.
• /v2/transactions/direct, /v2/transactions/hold, /v2/transactions/block e /v2/transactions/unblock não recebem organização nem ledger no path.

​

Organização e ledger no corpo da transação

# API v1: the organization and the ledger are in the path
POST /v1/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/ledgers/9c858901-8a57-4791-81fe-4a34d4dd8ab5/transactions/json

# API v2: the organization and the ledger are in each item of the body
POST /v2/transactions/direct

{
  "debits": [
    {
      "alias": "@source",
      "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
      "amount": "100.00"
    }
  ]
}

• Envie organizationId e ledgerId em cada item. Os dois são obrigatórios, e os dois são UUIDs.
• Todos os itens devem informar a mesma organização e o mesmo ledger.
• A partir da v4.1.0, direct e hold aceitam itens em ledgers diferentes quando cada ledger habilita crossLedger.enabled. Consulte transações entre Ledgers.
• block e unblock sempre precisam de uma organização e um ledger em todos os itens.

​

Exceções

• Anotações. POST /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/annotation não tem rota v2.
• Cotações de ativos. Estas rotas v1 não têm rota v2:
  • PUT /v1/organizations/{organization_id}/ledgers/{ledger_id}/asset-rates
  • GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/asset-rates/{external_id}
  • GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/asset-rates/from/{asset_code}
• Tracer. O Tracer mantém sua própria API v1. Consulte o Início rápido da API do Tracer.

​

CRM e Fees na API v2

​

CRM

​

Fees

​

Mudanças de escopo e de permissão

• Envie a organização no path. Não envie o header X-Organization-Id.
• No Fees, envie o ledger no path. Remova ledgerId do corpo de pacotes, estimativas, pacotes de cobrança e cálculo de cobrança.
• As listas de pacotes e de pacotes de cobrança sempre cobrem um ledger. No plugin, ledgerId era um parâmetro de query opcional. Para listar os pacotes de uma organização inteira, chame a lista uma vez para cada ledger.
• Nos instrumentos do CRM, mantenha ledgerId e accountId no corpo.
• Use estimativas apenas para simular tarifas. Uma estimativa não registra nada.

​

Contrato da transação

• asset: o código do ativo.
• amount: o total, como uma string decimal.
• debits e credits: arrays com um ou mais itens cada.

• alias: o alias da conta.
• organizationId e ledgerId: os UUIDs da organização e do ledger da conta. Consulte Organização e ledger no corpo da transação.
• amount ou share: envie exatamente um dos dois.

• Use /v2/transactions/direct para lançar a transação de imediato.
• Use /v2/transactions/hold para criar uma transação pendente. Depois, confirme ou cancele essa transação.

​

Exemplo de uma transação direta

{
  "asset": "BRL",
  "amount": "100.00",
  "debits": [
    {
      "alias": "@source",
      "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
      "amount": "100.00"
    }
  ],
  "credits": [
    {
      "alias": "@destination",
      "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
      "amount": "100.00"
    }
  ]
}

​

Campos que o corpo v2 não aceita

• rate e remaining em um item.
• metadata em um item. A própria transação ainda aceita metadata.
• transactionDate.
• balanceKey em um item, apenas no Midaz v4.0.x. A partir da v4.1.0, cada item aceita um balanceKey opcional.

​

Respostas e erros

​

Respostas de transação

• source e destination passam a ser debit e credit, no singular.
• A transação não tem mais route e chartOfAccountsGroupName.
• As operações dentro de uma transação não têm mais route e chartOfAccounts. Elas mantêm routeId, routeCode e routeDescription.
• As respostas de uma operação que você lê isoladamente não mudam.
• A partir da v4.1.0, um direct ou hold que abrange vários ledgers retorna um grupo com groupId e transactions[]. Confirmar, cancelar e reverter também podem retornar um grupo.

​

Erros

• type, title, status e detail.
• code: o código de erro do Midaz. O mesmo erro tem o mesmo código na v1 e na v2.
• errors[]: os erros de campo, quando a requisição os tem.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://errors.lerian.studio/v1/0053",
  "title": "Unexpected Fields in the Request",
  "status": 400,
  "detail": "The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.",
  "errors": [
    {
      "message": "unexpected field",
      "location": "transactionDate"
    }
  ],
  "code": "0053"
}

​

Contas e regras na API v2

​

Rotas de conta

• Ler uma conta pelo alias e pelo código externo.
• Atualizar e excluir uma conta.
• Contar as contas com HEAD.

​

Regras de titular

• Quando accounting.requireHolder está ativado, cada conta precisa de um titular da organização. Sem um titular, o Midaz não cria a conta.
• Para pular essa verificação, envie skip.holder. O Midaz aceita esse campo apenas quando overrides.allowHolderSkip está ativado. Caso contrário, o Midaz recusa a requisição com 422 e o erro 0490.
• Quando accounting.requireHolder está desativado e você não envia titular, uma conta não externa recebe o titular da sua organização. Uma conta externa não recebe titular.
• Quando accounting.requireHolder está desativado, o Midaz não verifica se o holderId que você envia existe.
• Uma conta que você cria pela v1 não recebe titular. A v1 não aplica essas regras.

​

Fees e Tracer

• Fees. O Midaz cobra uma tarifa quando um pacote de tarifas corresponde à transação.
• Tracer. O Midaz reserva a transação no Tracer quando o modo Tracer do ledger não é off.

​

Checklist de migração

• Liste as rotas que você usa, a versão do produto e a URL base de cada serviço. Separe as rotas que têm rota v2 das rotas que não têm. Planeje parar de usar as rotas que não têm no máximo até 29 de abril de 2027.
• Para cada transação, selecione direct ou hold. Atualize debits, credits, os valores decimais e o escopo de cada item.
• Troque os aliases do CRM por instrumentos. Mova a organização e o ledger do Fees para o path. Depois da migração dos dados, confira os vínculos e os identificadores.
• Conceda as permissões midaz. Teste as regras de titular das contas em um ambiente de homologação.
• Atualize a forma como você lê as respostas de sucesso e de erro. Teste campos removidos, entradas inválidas, recursos ausentes e acesso negado.
• Teste cada fluxo que sua integração usa: criar, ler, reter, confirmar, cancelar, reverter, bloquear e desbloquear. Confira saldos, operações, tarifas e recusas por limites do Tracer.
• Continue enviando X-Idempotency e X-TTL nas requisições de criação. Não envie a mesma transação pela v1 e pela v2 para comparar resultados. Use dados e cenários controlados em homologação.
• Mova o tráfego em etapas controladas. Monitore os erros e os resultados financeiros. Mantenha um plano de rollback que não envie de novo transações já processadas.