API Reference
  1. Autra Platform API

Banking

Como operar uma conta digital Autra após o onboarding: consultar saldo, extrato, chaves Pix, alterar status e validar chaves no DICT.

Este guia mostra como operar uma conta digital Autra depois que o onboarding terminou: consultar dados, saldo, extrato, alterar status e listar chaves Pix. Toda a infra é baseada na DockOne (Caradhras One), mas você fala apenas com a API da Autra.

Pré-requisito: o titular precisa ter uma proposta de onboarding concluída (status = COMPLETED). Se ainda não tem, comece pelo guia de Onboarding Banking — Conta Digital.

Conceitos fundamentais

TermoO que é
accountIdUUID da conta na DockOne. Devolvido em dock_account_id ao final do onboarding. É o que você passa em /v1/banking/accounts/{accountId}/....
operationIdUUID de uma operação (TED/P2P/Pix). Aparece nos lançamentos do extrato em operationId — guarde para consultar comprovantes.
businessKeyChave de idempotência da operação no provider. Aparece no extrato e em comprovantes.
endToEndId (E2E)Identificador padrão BACEN de operações Pix. Aparece nos lançamentos quando o lançamento é Pix.
DICTDiretório de Identificadores de Contas Transacionais — onde ficam todas as chaves Pix do Brasil.
device_id (BACEN 491)Identificador do dispositivo do usuário, exigido pela Resolução 491 para operações Pix mutantes (criar chave, enviar Pix). Já registrado automaticamente no onboarding.

Antes de começar — checklist

  • Você tem client_id + client_secret da Autra.
  • Você sabe gerar Bearer JWT via POST /v1/oauth/token.
  • O titular finalizou o onboarding (status = COMPLETED) e você guardou o dock_account_id.

Resumo dos endpoints

#O que fazEndpoint
1Detalhes da contaGET /v1/banking/accounts/{accountId}
2Saldo enxutoGET /v1/banking/accounts/{accountId}/balance
3Extrato com paginaçãoGET /v1/banking/accounts/{accountId}/transactions
4Listar chaves PixGET /v1/banking/accounts/{accountId}/pix-keys
5Alterar status (BLOCK/CANCEL)PATCH /v1/banking/accounts/{accountId}/status
6Validar chave Pix no DICTGET /v1/banking/pix/dict/validate
7Criar chave PixPOST /v1/banking/accounts/{accountId}/pix-keys
8Remover chave PixDELETE /v1/banking/accounts/{accountId}/pix-keys/{key}

Prefixo: https://api.autra.io. Headers em todas as chamadas:

Authorization: Bearer <JWT>
Content-Type: application/json

Isolamento entre tenants

Toda chamada valida ownership. Internamente a Autra confere se o accountId da URL pertence ao tenant do JWT (lookup em onboarding_proposals). Se não pertence, devolvemos 404 ACCOUNT_NOT_FOUND — nunca 403 — para evitar revelar que a conta existe.

Se você está construindo uma plataforma white-label, isso significa que um cliente seu não consegue ler a conta de outro cliente seu mesmo sabendo o UUID — desde que cada cliente esteja em um tenant diferente.

1. Detalhes da conta

curl -H "Authorization: Bearer $TOKEN" \
  https://api.autra.io/v1/banking/accounts/019de043-2bd2-1536-98cb-ce143fb2b1f5

Resposta 200:

{
  "id": "019de043-2bd2-1536-98cb-ce143fb2b1f5",
  "externalId": "019de043-2bd2-1536-98cb-ce143fb2b1f5",
  "provider": "DOCKONE",
  "productId": "01989e87-eb15-e7fc-6268-cdcb6680b2cb",
  "bank": "301",
  "agency": "0001",
  "number": "1048897891",
  "status": "ACTIVE",
  "ownerId": "019d4f6e-c21d-4199-9424-9c37a2a1c65d"
}

Campos

CampoSempre presente?Notas
id · provider · bank · agency · number · status✅sempre vêm
externalId · productId · ownerId✅sempre vêm (UUIDs DockOne)
ownerType⚠ quando disponívelPF ou PJ. Em fase de rollout — pode vir omitido.
createdAt⚠ quando disponívelISO-8601 UTC. Pode vir omitido se a Dock não retornar.
balance❌ não vem aquiUse o endpoint #2 (/balance).

⚠ Sobre number (número da conta): vem com o dígito verificador embutido (padrão DockOne BAM). A string contém conta + DV concatenados sem separador. Pra exibir como conta-DV na UI, faça split do último caractere no front-end. Pra Pix/TED/transferências, envie a string inteira como recebida. Mesma regra vale pra agency (sem split oficial — string opaca).

Quando usar: abertura de tela de conta no dashboard, exibir agência/número/status. Para saldo, chame o endpoint #2 separadamente.

2. Saldo enxuto

curl -H "Authorization: Bearer $TOKEN" \
  https://api.autra.io/v1/banking/accounts/019de043-2bd2-1536-98cb-ce143fb2b1f5/balance

Resposta 200:

{ "amount": 1250.75, "currency": "BRL" }

Em integração — o endpoint dedicado de saldo da DockOne (POST /account-services/management/v1/account-details) está em homologação. Enquanto a integração não conclui, este endpoint pode retornar { "amount": 0, "currency": "BRL" }. Aviso será removido assim que estiver em produção.

Quando usar: widget de saldo, polling no app do cliente, header sticky. Vale ~1/3 do payload do endpoint #1.

3. Extrato com paginação

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.autra.io/v1/banking/accounts/019de043-2bd2-1536-98cb-ce143fb2b1f5/transactions?from=2026-04-04T00:00:00Z&to=2026-05-04T23:59:59Z&limit=50"

Resposta 200:

{
  "items": [
    {
      "id": "tx_01HX9...",
      "operationId": "01HX9V8K...",
      "type": "CREDIT",
      "amount": 250.00,
      "currency": "BRL",
      "description": "Pix recebido",
      "endToEndId": "E18236120202604201234567890123456",
      "createdAt": "2026-05-03T14:22:01Z"
    },
    {
      "id": "tx_01HX8...",
      "operationId": "01HX8V8K...",
      "type": "DEBIT",
      "amount": 89.90,
      "currency": "BRL",
      "description": "TED para Banco do Brasil",
      "businessKey": "be...-c2c7-...",
      "createdAt": "2026-05-02T09:11:55Z"
    }
  ],
  "nextCursor": "eyJwYWdlIjozfQ=="
}

Regras importantes

  • Período máximo 90 dias por chamada (from–to).
  • to não pode ser maior que now().
  • Se vier nextCursor não vazio, há mais lançamentos — chame de novo passando ?cursor=<valor> (mantenha from/to).
  • Lançamentos vêm do mais recente para o mais antigo.
  • type é sempre CREDIT ou DEBIT. O amount é sempre positivo — a natureza está em type.

Exemplo de paginação

# Primeira página
curl ".../transactions?from=...&to=...&limit=50"
# {"items":[...50...], "nextCursor":"eyJwYWdlIjoyfQ=="}

# Próxima página
curl ".../transactions?from=...&to=...&limit=50&cursor=eyJwYWdlIjoyfQ=="
# {"items":[...50...], "nextCursor":"eyJwYWdlIjozfQ=="}

# Última página
curl ".../transactions?from=...&to=...&limit=50&cursor=eyJwYWdlIjozfQ=="
# {"items":[...12...], "nextCursor":""}   ← cursor vazio = fim

Erros comuns

HTTPCodeCausa
400INVALID_DATE_RANGEfrom/to ausentes ou from > to
400DATE_RANGE_TOO_LARGEMais de 90 dias entre from e to

4. Listar chaves Pix da conta

curl -H "Authorization: Bearer $TOKEN" \
  https://api.autra.io/v1/banking/accounts/019de043-2bd2-1536-98cb-ce143fb2b1f5/pix-keys

Resposta 200:

{
  "items": [
    {
      "type": "EVP",
      "value": "550e8400-e29b-41d4-a716-446655440000",
      "status": "ACTIVE",
      "accountId": "019de043-2bd2-1536-98cb-ce143fb2b1f5",
      "createdAt": "2026-04-22T12:00:00Z"
    }
  ]
}

Tipos de chave

TypeO que é
CPFCPF do titular (PF apenas, máx. 1 por pessoa no Brasil inteiro)
CNPJCNPJ do titular (PJ apenas)
EMAILEmail validado
PHONETelefone celular validado por OTP
EVPChave aleatória (UUID gerado pela Dock)

Status

StatusO que significa
ACTIVERegistrada e operacional.
PENDINGAguardando confirmação (portabilidade entre bancos, OTP de email/phone).
INACTIVERemovida — não recebe mais Pix.

Para criar ou remover chave veja seções 7 e 8. Ambas exigem device autorizado pela conta (BACEN 491) — registrado automaticamente no onboarding. Ver Trusted Devices se precisar registrar device manualmente.

5. Alterar status da conta

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  https://api.autra.io/v1/banking/accounts/019de043-2bd2-1536-98cb-ce143fb2b1f5/status \
  -d '{
    "status": "BLOCKED",
    "reason": "Suspeita de fraude — bloqueio manual via suporte"
  }'

Transições válidas

De ↓ / Para →ACTIVEBLOCKEDCANCELED
ACTIVE—✅✅
BLOCKED✅—✅
CANCELED❌ terminal❌ terminal—
  • BLOCKED e CANCELED exigem reason.
  • CANCELED é terminal — não dá pra reverter.
  • Se você tentar uma transição inválida (ex.: ACTIVE → ACTIVE, ou reabrir conta cancelada), a resposta é 422 STATUS_TRANSITION_REJECTED com a mensagem original do banco.

Resposta 200

A conta atualizada (mesmo shape do endpoint #1).

Resposta 422

{
  "errors": [
    {
      "code": "STATUS_TRANSITION_REJECTED",
      "msg": "Account is already in status ACTIVE"
    }
  ]
}

6. Validar chave Pix no DICT

Antes de enviar um Pix, você consulta a chave do destinatário no DICT e descobre nome, banco, agência e número de conta dele. É equivalente ao "Quem está recebendo? Confere com você?" do app do banco.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.autra.io/v1/banking/pix/dict/validate?key=21609726812"

Resposta 200:

{
  "found": true,
  "keyType": "CPF",
  "key": "21609726812",
  "holderName": "JORGE AUGUSTO SILVA",
  "nationalRegistrationMask": "***.097.268-**",
  "bankName": "BANCO C6 S.A.",
  "ispb": "31872495",
  "bankAccountNumber": "12345678",
  "bankBranchNumber": "0001"
}

Resposta 404: chave não existe no DICT.

{
  "errors": [{ "code": "DICT_KEY_NOT_FOUND", "msg": "Chave não encontrada" }]
}

Roteamento multi-provider (transparente)

Internamente, contas DockOne usam /spi/dict/v5 e contas legadas (PCH) usam /dict/v4. O cliente não precisa saber qual — basta autenticar e a Autra escolhe o provedor correto a partir do tenant.

7. Criar chave Pix

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  https://api.autra.io/v1/banking/accounts/019de043-2bd2-1536-98cb-ce143fb2b1f5/pix-keys \
  -d '{
    "type": "EVP",
    "deviceId": "8a1d7f2e-b706-4bbb-a600-32e1c9274f30"
  }'

Body

CampoTipoObrigatórioNotas
typestring✅CPF · CNPJ · EMAIL · PHONE · EVP
valuestring⚠Obrigatório para CPF/CNPJ/EMAIL/PHONE. Omitir para EVP — a Dock gera o UUID.
deviceIdstring⚠UUID do device autorizado. Se omitido, a Autra usa automaticamente o device autorizado da conta (registrado no onboarding).

Resposta 200

{
  "type": "EVP",
  "value": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ACTIVE",
  "accountId": "019de043-2bd2-1536-98cb-ce143fb2b1f5",
  "createdAt": "2026-05-08T14:32:11Z"
}

Para EMAIL e PHONE, o status inicial geralmente é PENDING — o titular precisa confirmar via OTP enviado pelo banco. Após confirmação, vira ACTIVE.

Erros comuns

HTTPcodeQuando
400INVALID_KEY_TYPEtype fora de CPF/CNPJ/EMAIL/PHONE/EVP.
400KEY_REQUIREDTipo diferente de EVP sem value.
400DEVICE_REQUIREDSem deviceId e sem device autorizado pra conta — registre um em Trusted Devices.
422NO_AUTHORIZED_DEVICEA conta não tem device autorizado.
404ACCOUNT_NOT_FOUNDaccountId não pertence a este tenant.

8. Remover chave Pix

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://api.autra.io/v1/banking/accounts/019de043-2bd2-1536-98cb-ce143fb2b1f5/pix-keys/550e8400-e29b-41d4-a716-446655440000"

O parâmetro {key} é o valor da chave (UUID, CPF, email…), não um id interno. URL-encode se contiver caracteres especiais (ex.: + em telefones).

Resposta 200

{
  "deleted": true,
  "key": "550e8400-e29b-41d4-a716-446655440000"
}

A chave passa a INACTIVE na Dock. Não é possível reusar a mesma chave depois — uma nova chave do mesmo tipo gera novo UUID/registro.

Erros comuns

HTTPcodeQuando
400—key ausente do path.
404ACCOUNT_NOT_FOUNDaccountId não pertence a este tenant.
500INTERNAL_ERRORChave inexistente ou já removida (Dock devolve 4xx — propagamos como erro).

Erros comuns (todos os endpoints)

HTTPCodeO que fazer
401/403(sem code)JWT inválido/expirado — gere outro via /v1/oauth/token
404ACCOUNT_NOT_FOUNDConta não existe ou não pertence ao tenant. Confira accountId e o tenant do token.
400INVALID_DATE_RANGEfrom/to ausentes ou ordem invertida
400DATE_RANGE_TOO_LARGEPeríodo > 90 dias
400INVALID_STATUSUse ACTIVE, BLOCKED ou CANCELED
422STATUS_TRANSITION_REJECTEDTransição não permitida pelo banco — leia a msg

O que vem por aí

Em breve:

  • Enviar Pix (P2P / TED out) — depende da autorização BACEN 491.
  • Comprovantes (TED/P2P) — GET /v1/banking/transfers/{operationId}/receipt. Já implementado, falta validação completa em produção.
  • QR code dinâmico — gerar QR de cobrança Pix.

Suporte

Dúvidas técnicas: [email protected] · 11 91405-2149.

Esse guia será atualizado conforme novos endpoints forem para produção. Acompanhe a tag Banking no menu lateral da referência da API.

Updated 11 days ago

Did this page help you?

Updated 11 days ago

Did this page help you?