> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Construa e teste no SpherePay sem dinheiro real nem identidades reais. Aprenda como funcionam as chaves de sandbox, as redes de teste e o faucet.

O sandbox é um deployment separado do SpherePay que se comporta como produção e não movimenta nada de valor. Você o usa para construir sua integração, exercitar o ciclo de vida de uma transferência e rodar sua suíte de testes sem clientes reais, fundos reais ou documentos de identidade reais.

Os corpos das suas requisições são idênticos nos dois lugares. Troque tanto a URL base quanto a chave: cada host aceita apenas as chaves do seu próprio ambiente.

## O que é diferente

| | Produção | Sandbox |
| - | - | - |
| URL base | `https://api.spherepay.co` | `https://api.sandbox.spherepay.co` |
| Prefixo da chave de API | `secret_` | `sandbox_secret_` |
| `ethereum` resolve para | Ethereum mainnet | Sepolia |
| `sol` resolve para | Solana mainnet | Solana Devnet |
| Fundos | Reais | Tokens de teste sem valor |

Todo o resto — endpoints, formatos de requisição, formatos de resposta, eventos de webhook, envelopes de erro — é o mesmo código. Esse é o ponto: o que você constrói no sandbox é o que roda em produção.

## Obtenha uma chave de sandbox

As chaves de sandbox são criadas no dashboard, em modo sandbox, em **Developers → API Keys**. Elas começam com `sandbox_secret_` para que você reconheça de imediato que a chave não é uma credencial de produção.

Uma chave de sandbox funciona apenas em `api.sandbox.spherepay.co`, e uma chave de produção funciona apenas em `api.spherepay.co`. Não há roteamento entre os dois: apresente a chave errada e a requisição é rejeitada exatamente como qualquer chave desconhecida seria.

> [!WARNING]
>
> Mantenha as chaves de sandbox e de produção em configurações separadas. Apontar uma suíte de testes para produção porque uma chave foi colada na variável de ambiente errada movimenta dinheiro real.

## Escolha uma rede

Envie os mesmos identificadores de rede que você usa em produção. O sandbox os resolve para redes de teste:

```json theme={"dark"}
{
  "network": "ethereum"
}
```

No sandbox isso chega à Sepolia. `sol` chega à Solana Devnet.

Uma requisição de sandbox que nomeia uma rede sem configuração de teste é rejeitada em vez de cair em uma rede mainnet. Você não alcança a mainnet com uma chave de sandbox.

## Emita tokens de teste

SPHEREUSDC é a stablecoin de teste do sandbox. Emita-a para qualquer endereço em qualquer uma das duas redes de teste com o faucet:

```bash theme={"dark"}
IDEMPOTENCY_KEY=$(uuidgen)
curl -X POST https://api.sandbox.spherepay.co/v2/sandbox/faucet \
  -H "Authorization: Bearer $SPHERE_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "network": "sol",
    "address": "bnZZ5unXUpgzfBjntgpivQkPhqxfjvp7TUyJfYdJ8yN",
    "amount": "1000"
  }'
```

Gere a chave de idempotência uma vez por emissão e reutilize-a se tentar de novo, para que uma resposta perdida não emita duas vezes.

A resposta é `202 Accepted` com um id de emissão. A emissão é assíncrona, então consulte para obter o hash da transação:

```bash theme={"dark"}
curl https://api.sandbox.spherepay.co/v2/sandbox/faucet/{id} \
  -H "Authorization: Bearer $SPHERE_SANDBOX_KEY"
```

`amount` usa `1000` por padrão e aceita no máximo `1000` por chamada. Uma emissão que levaria a carteira acima de `10000` SPHEREUSDC, contando as emissões pendentes, é recusada. Envie um cabeçalho `Idempotency-Key` para que uma nova tentativa retorne a mesma emissão em vez de emitir duas vezes. Reutilizar uma chave com parâmetros diferentes retorna `409`.

> [!NOTE]
>
> O faucet emite tokens, não gas. Financie o saldo nativo da carteira a partir de um faucet público da Sepolia ou da Solana Devnet antes de enviar uma transação a partir dela.

## Avance uma transferência

Em produção uma transferência percorre seu ciclo de vida conforme os depósitos chegam e os trilhos liquidam. No sandbox você a avança:

```bash theme={"dark"}
curl -X POST https://api.sandbox.spherepay.co/v2/sandbox/transfer/{id}/advance \
  -H "Authorization: Bearer $SPHERE_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "fundsReceived" }'
```

Cada avanço executa a mesma máquina de estados e o mesmo pipeline de webhooks que produção, então seus handlers de webhook recebem os eventos que receberão em produção, nos mesmos formatos.

O endpoint é idempotente por estado. Avançar para o status em que a transferência já está retorna o resultado original e não emite nada, então uma chamada repetida ou concorrente é segura.

Apenas algumas transições são válidas a partir de um dado status. Uma inválida retorna `transfer/invalid-transition` em vez de forçar a transferência para um estado inconsistente.

> [!NOTE]
>
> Essas rotas existem apenas no deployment de sandbox. Em `api.spherepay.co` elas retornam `404`, então não há como avançar uma transferência real manualmente.

## Endpoints de simulação

Estes endpoints existem apenas em `https://api.sandbox.spherepay.co`:

* [Avançar um cliente de sandbox](https://docs.spherepay.co/pt-BR/api-reference/sandbox/customer-advance.md): `POST /v2/sandbox/customer/{id}/advance`
* [Avançar uma transferência de sandbox](https://docs.spherepay.co/pt-BR/api-reference/sandbox/transfer-advance.md): `POST /v2/sandbox/transfer/{id}/advance`
* [Emitir tokens de teste](https://docs.spherepay.co/pt-BR/api-reference/sandbox/faucet-post.md): `POST /v2/sandbox/faucet`
* [Recuperar uma emissão de tokens de teste](https://docs.spherepay.co/pt-BR/api-reference/sandbox/faucet-get-id.md): `GET /v2/sandbox/faucet/{id}`

A simulação de depósitos para offloader wallets e contas virtuais chegará em breve.

## Limites de taxa

As rotas exclusivas do sandbox são limitadas por aplicação, não por IP, para que um runner de CI compartilhado não limite a si mesmo:

| Rota | Limite |
| - | - |
| `POST /v2/sandbox/faucet` | 30 por minuto |
| `POST /v2/sandbox/transfer/{id}/advance` | 120 por minuto |

Todos os demais endpoints seguem os limites de [Limites de Taxa](https://docs.spherepay.co/pt-BR/concepts/operational/rate-limits.md).

## O que o sandbox não faz

* Ele não contém fundos reais, então nada que você faça no sandbox move dinheiro.
* Ele não executa verificação de identidade real. Os clientes que você cria não são analisados pela Sumsub.
* Ele não é um ambiente de staging do SpherePay. Ele é implantado a partir do mesmo branch que produção, ao mesmo tempo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.