Teste em Sandbox

O que é o Sandbox?

O sandbox é um modo de teste da sua conta — não um ambiente separado. Ele usa a mesma API, mesma URL base e mesmos endpoints que produção. A diferença é que sua conta sandbox está conectada a um provedor bancário simulado: transações são processadas instantaneamente, sem transferência real de fundos e sem PIX enviado ao BACEN.

Sandbox e produção são contas separadas, cada uma com suas próprias credenciais (certificado, clientId, clientSecret). Seu certificado pode ser compartilhado entre ambas as contas dependendo da configuração — consulte seu gerente de conta.

Seu código não muda entre sandbox e produção. Quando estiver pronto para ir ao ar, basta trocar para as credenciais da conta de produção. Sem mudança de endpoints, sem mudança de código.

Sandbox vs Produção

	Sandbox	Produção
URL Base	Mesma (`https://api.avista.global`)	Mesma
Conta	Conta sandbox dedicada	Conta produção dedicada
Credenciais	Certificado + clientId/clientSecret próprios	Certificado + clientId/clientSecret próprios
Saldo	Simulado (fictício)	Fundos reais
Transações	Simuladas (persistidas — consultáveis via API)	PIX real via BACEN
Webhooks	Simulados (~1s entrega), mesma estrutura de payload	Reais, entrega depende do provedor
X-Sandbox-Scenario	Suportado (controle o resultado dos webhooks)	Retorna `400 Bad Request`
Documentação	Mesma que produção — todas as páginas da API Reference se aplicam	Mesma

Começando com o Sandbox

Entre em contato com seu gerente de conta ou suporte@avista.global para solicitar uma conta sandbox.

Você receberá um certificado e credenciais OAuth (clientId + clientSecret) para a conta sandbox.

Registre sua URL de webhook via POST /api/webhooks para receber os eventos de webhook simulados.

No dashboard, acesse Configurações para confirmar que sua conta está configurada em modo sandbox.

Autentique-se, faça chamadas à API e use o header X-Sandbox-Scenario para simular diferentes resultados.

Visão Geral

O header X-Sandbox-Scenario permite controlar o resultado do webhook para qualquer transação. Sem ele, o sandbox sempre retorna webhooks de sucesso. Use-o para testar tratamento de erros, atrasos e casos extremos.

Sem o header X-Sandbox-Scenario, o sandbox sempre retorna webhooks de sucesso. Para testar cenários de erro (saldo insuficiente, chave inválida, etc.), você precisa enviar o header explicitamente em cada requisição.

Este recurso funciona apenas em sandbox. Em produção, o header é ignorado e o comportamento é determinado pelo resultado real da transação.

Como Funciona

O X-Sandbox-Scenario não altera a resposta HTTP — a API sempre retorna 201 Created com status: "PENDING". O cenário simulado afeta apenas o webhook assíncrono que chega à sua URL de callback.

┌─────────────┐         ┌──────────────┐         ┌─────────────────┐
│   Seu App   │──POST──▶│   API Avista  │──────▶  │  Provedor Mock  │
│             │◀──201───│              │         │                 │
│             │         │              │         │  Processa o     │
│             │         │              │         │  cenário do     │
│             │         │              │         │  header         │
│             │◀────────│──webhook─────│◀────────│                 │
│             │         │              │         │  ~1s depois     │
└─────────────┘         └──────────────┘         └─────────────────┘
      │                                                  │
      │              Resposta HTTP: sempre 201           │
      │              Webhook: sucesso OU erro            │
      │              (depende do header)                  │

Requisição	Resposta HTTP	Webhook recebido
Sem `X-Sandbox-Scenario`	`201` PENDING	`CONFIRMED` (sucesso)
Com `X-Sandbox-Scenario: success`	`201` PENDING	`CONFIRMED` (sucesso)
Com `X-Sandbox-Scenario: error:insufficient-funds`	`201` PENDING	`ERROR` com `errorCode`
Com `X-Sandbox-Scenario: delayed:5s`	`201` PENDING	`CONFIRMED` após 5s extras

Como Usar

Adicione o header X-Sandbox-Scenario a qualquer request de Cash-In, Cash-Out ou Refund:

curl -X POST https://api.avista.global/api/pix/cash-out \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Sandbox-Scenario: error:insufficient-funds" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 150.00,
    "details": {
      "key": "recipient@email.com",
      "keyType": "EMAIL",
      "name": "Recipient Name",
      "document": "39284918812"
    },
    "externalId": "test-error-001"
  }'

const response = await axios.post(
  'https://api.avista.global/api/pix/cash-out',
  {
    value: 150.00,
    details: {
      key: 'recipient@email.com',
      keyType: 'EMAIL',
      name: 'Recipient Name',
      document: '39284918812',
    },
    externalId: 'test-error-001',
  },
  {
    headers: {
      Authorization: `Bearer ${token}`,
      'X-Sandbox-Scenario': 'error:insufficient-funds',
    },
  }
);

response = requests.post(
    "https://api.avista.global/api/pix/cash-out",
    json={
        "value": 150.00,
        "details": {
            "key": "recipient@email.com",
            "keyType": "EMAIL",
            "name": "Recipient Name",
            "document": "39284918812",
        },
        "externalId": "test-error-001",
    },
    headers={
        "Authorization": f"Bearer {token}",
        "X-Sandbox-Scenario": "error:insufficient-funds",
    },
)

Cenários Disponíveis

Cenários de Erro

Simule diferentes tipos de falha no webhook:

Valor do Header	Descrição	Webhook Status
`error:insufficient-funds`	Conta sem saldo suficiente	`ERROR`
`error:invalid-pix-key`	Chave PIX não existe no DICT	`ERROR`
`error:document-mismatch`	Documento não corresponde ao titular da chave	`ERROR`
`error:account-blocked`	Conta de destino bloqueada ou encerrada	`ERROR`
`error:duplicate-id`	ID de envio duplicado	`ERROR`

Cenário de Sucesso

Valor do Header	Descrição	Webhook Status
`success`	Força sucesso (comportamento padrão)	`CONFIRMED`
(sem header)	Comportamento padrão do sandbox	`CONFIRMED`

Cenários de Delay

Simule processamento lento para testar timeouts e retry:

Valor do Header	Descrição	Webhook Status
`delayed:5s`	Sucesso após 5 segundos extras	`CONFIRMED`
`delayed:30s`	Sucesso após 30 segundos extras	`CONFIRMED`
`delayed:60s`	Sucesso após 60 segundos extras	`CONFIRMED`

O delay máximo permitido é de 120 segundos. Valores acima serão limitados automaticamente.

Exemplos de Webhook Recebido

Webhook de Sucesso (padrão)

{
  "event": "CashOut",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "12345",
  "externalId": "test-success-001",
  "endToEndId": "E17745159XI4QA0EGFU",
  "feeAmount": 0.50,
  "originalAmount": 150.00,
  "finalAmount": 150.50,
  "processingDate": "2026-03-26T10:00:00.000Z",
  "errorCode": null,
  "errorMessage": null,
  "counterpart": {
    "name": "Recipient Name",
    "document": "*.284.918-**",
    "bank": {}
  },
  "metadata": {}
}

Webhook de Erro (error:insufficient-funds)

{
  "event": "CashOut",
  "status": "ERROR",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "12345",
  "externalId": "test-error-001",
  "endToEndId": null,
  "feeAmount": 0.50,
  "originalAmount": 150.00,
  "finalAmount": 150.50,
  "processingDate": "2026-03-26T10:00:00.000Z",
  "errorCode": "INSUFFICIENT_FUNDS",
  "errorMessage": "Conta sem saldo",
  "counterpart": {
    "name": null,
    "document": null,
    "bank": {}
  },
  "metadata": {}
}

Quando o status é ERROR, o campo endToEndId será null (pois o PIX nunca foi confirmado pelo Banco Central) e os campos errorCode e errorMessage descrevem o motivo da falha.

Endpoints Compatíveis

O header X-Sandbox-Scenario funciona com todos os endpoints transacionais:

Endpoint	Método	Descrição
`/api/pix/cash-in`	POST	Gerar cobrança PIX (QR Code)
`/api/pix/cash-out`	POST	Pagamento PIX por chave
`/api/pix/cash-out/qrcode`	POST	Pagamento PIX por QR Code
`/api/pix/refund-in`	POST	Solicitação de estorno

Cenários MED

O módulo MED (Mecanismo Especial de Devolução) não é testável diretamente via X-Sandbox-Scenario. MEDs dependem de integração com BACEN e com o provedor PIX configurado (Woovi, Hyperwallet, etc.), portanto não podem ser simulados pelo provider mock do sandbox.

Para validar sua integração com webhooks MED (MedCreated, MedAccepted, MedRejected):

Use POST /api/webhooks/{id}/resend para reenviar um webhook MED já existente na sua conta para a URL configurada. Útil para depurar o handler localmente após alterações.

Use GET /api/med para listar MEDs associados à conta, filtrar por status e reconciliar com suas transações locais.

Se precisar simular um fluxo MED de ponta a ponta (abertura, análise, aprovação/rejeição), entre em contato com suporte@avista.global para solicitar acesso ao ambiente de homologação.

Os webhooks MED seguem a mesma estrutura de autenticação (Basic Auth) e retry dos demais eventos. O payload completo está documentado em MedCreated, MedAccepted e MedRejected.

Comportamento

A API processa o request normalmente e retorna 201 Created com status PENDING. O header não altera a resposta imediata — apenas o webhook subsequente.

Após ~1 segundo (ou mais, se usar delayed:), o webhook é enviado para a URL configurada com o cenário simulado.

Seu sistema recebe o webhook com o status correspondente ao cenário (CONFIRMED ou ERROR) e deve processar de acordo.

Importante: O header X-Sandbox-Scenario controla apenas o webhook. A resposta HTTP do endpoint sempre retorna sucesso (201 Created) com status: "PENDING", independente do cenário escolhido. O resultado final (sucesso ou erro) chega via webhook.

Restrições

O header X-Sandbox-Scenario funciona exclusivamente com contas configuradas em modo sandbox. Se sua conta está configurada com um provedor de produção e você enviar o header, a API retornará um erro:

{
  "statusCode": 400,
  "message": "X-Sandbox-Scenario header is only supported in sandbox mode. This account is not configured with a sandbox provider."
}

Certifique-se de que sua conta está em modo sandbox antes de usar este recurso. Se você receber este erro, entre em contato com suporte@avista.global para verificar a configuração da sua conta.

Boas Práticas

Teste todos os cenários

Implemente tratamento para cada status de webhook (CONFIRMED, PENDING, ERROR) antes de ir para produção.

Valide os campos de erro

Quando status é ERROR, use errorCode e errorMessage para determinar a ação adequada (retry, notificar usuário, etc.).

Teste com delay

Use cenários delayed: para verificar se seu sistema lida corretamente com webhooks que demoram a chegar.

Idempotência

Use transactionId como chave de idempotência. O mesmo webhook pode ser reenviado em caso de falha de entrega.

Teste em Sandbox

Teste todos os cenários

Valide os campos de erro

Teste com delay

Idempotência

Nesta página