Playground

Chame daqui mesmo.

Cole um client id e um secret aprovados e o console abaixo roda contra o ambiente de avaliação, direto do seu navegador. Seis chamadas levam do nada até uma conta financiada com extrato, e cada uma mostra a requisição exata e a resposta exata.

Ambiente de avaliação

Ele é compartilhado entre avaliadores, é reiniciado com aviso e não tem SLA. Nada que você criar aqui é privado em relação aos outros avaliadores, e nada disso move dinheiro de verdade em nenhum trilho.

Lendo isto sem credencial

Esta página e a referência inteira são legíveis como estão. Chamar exige uma credencial aprovada, que liberamos por pedido para conseguirmos dosar e retomar capacidade em um ambiente só. O roteiro abaixo continua mostrando cada chamada e cada corpo que ela enviaria. Pedir acesso.

Credenciais

sem conexão

Destino https://api-sbx.sonacore.com.br. O seu client id e o seu secret ficam no armazenamento local deste navegador e são enviados só para o endpoint de token. Não existe servidor neste site para mandá-los a outro lugar.

Cinco minutos, seis chamadas

Crie uma parte, dê a ela uma conta, financie essa conta com um crédito vindo de fora, e depois leia o saldo e o extrato. Cada passo mostra exatamente o que foi enviado e exatamente o que voltou, erros incluídos.

01
Criar uma parte
Uma parte é a pessoa ou a empresa. Ela não guarda valor por conta própria. Repare que esta devolve 200, e não 201.
POST /v1/parties
```
{
  "type": "individual",
  "display_name": "Playground 88431",
  "country": "BR"
}
```
02
Criar uma conta
Contas guardam valor e pertencem a uma parte. O tipo é em maiúsculas e a moeda é um código de três letras. O id volta como id, não como account_id.
Esperando a resposta do passo anterior.
03
Vincular uma coordenada de entrada
Dinheiro chega como evidência sobre uma coordenada. Vincular uma diz ao ledger a qual conta pertence um crédito naquela coordenada.
Esperando a resposta do passo anterior.
04
Registrar um crédito
R$ 1.000,00 chegando naquela coordenada. O ledger casa os dois e cria as obrigações. A data de efetivação é um dia contábil de São Paulo, não UTC.
Esperando a resposta do passo anterior.
05
Ler o saldo
Derivado, não armazenado, então ele se decompõe em available e pending em vez de ser um número só. Esta leitura é eventualmente consistente — se o crédito ainda não apareceu, rode de novo.
Esperando a resposta do passo anterior.
06
Ler o extrato
Um extrato formal sobre um intervalo de datas. As duas datas são obrigatórias e são dias contábeis de São Paulo. Débitos e créditos são do ponto de vista da conta.
Esperando a resposta do passo anterior.

Qualquer chamada

Tudo o que está na referência é alcançável daqui. Escritas recebem um Idempotency-Key automaticamente, e a mesma chave é reenviada em uma retentativa em vez de virar uma segunda transação.

Por que financiar leva duas chamadas

Não existe endpoint de torneira, e isso é deliberado. O ledger não inventa valor a pedido; valor entra porque algo de fora dele diz que dinheiro chegou. Então financiar é: vincular uma coordenada a uma conta, e depois registrar um crédito que nomeie essa coordenada. O ledger casa os dois e cria as obrigações.

É o mesmo caminho que os nossos próprios scripts de demonstração usam, e é por isso que o roteiro usa ele em vez de um atalho. As duas chamadas também não são cerimônia — elas são o modelo, e entender as duas é boa parte de entender esta API.

Colocar um produto seu no ledger

As seis chamadas acima usam o ledger como ele vem. Se o que você quer avaliar é pôr um produto seu nele — um validador com o seu próprio ciclo de vida, as suas próprias regras de quando o valor pode sair — Produtos no playground vincula um template publicado como um produto em rascunho, roda os cenários que o manifesto declara e mostra o boletim de certificação.

Contra um ambiente local

Adicione ?dev à URL desta página e o console passa a apontar para http://localhost:8080. Um ambiente local sintetiza uma identidade com todos os escopos, então não precisa de credencial e a troca de token é pulada. É assim que os roteiros que não rodam no ambiente de avaliação devem ser seguidos.

⚠️ E vale saber o que ele não prova: um ambiente local não vincula nenhum tenant. A identidade sintética não nomeia nenhum, então quem responde pelo tenant é a variável de ambiente e não a credencial — o isolamento entre tenants e a separação de escopos só são exercitáveis no ambiente de avaliação hospedado. Um roteiro verde aqui prova que nada regrediu, não que a barreira funciona.

local

git clone git@github.com:Banco-Sona/sona-core.git
cd sona-core && ./scripts/devlocal.sh up

# depois abra esta página com ?dev

Quando não funciona

Nenhuma resposta. Quase sempre é um preflight de CORS recusado, e não uma falha de rede: a API mantém uma lista das origens que podem chamá-la de um navegador, e uma página servida de qualquer outro lugar falha aqui enquanto a mesma chamada funciona no curl.
O token funciona e toda chamada devolve 401. O seu cliente tem os escopos concedidos mas não está registrado no gateway. Fale com a gente em vez de rotacionar o seu secret — veja Autenticação.
O saldo continua zero mesmo depois de o crédito devolver 2xx. Esperado, por pouco tempo. Leituras de saldo são eventualmente consistentes; rode o passo de novo. Nunca trate um saldo inalterado como falha — Garantias explica por quê.
Um 404 em algo que você acabou de criar. Um recurso que não é seu responde como ausente, não como proibido. Se o id veio da rodada de outro avaliador, isso é essa regra funcionando.
Estava tudo aqui ontem e sumiu. O ambiente de avaliação é reiniciado com aviso. Nada que você criar sobrevive a um reinício.

← Referência da API Roteiros de demonstração →