Ir para o conteúdo
DocsAPI 2026-11-13

Comece aqui

Sandbox e produção

Dois ambientes completamente separados: implantações, bancos de dados, chaves e eventos próprios. Nada atravessa de um para o outro.

O que muda entre os ambientes

Diferenças entre Sandbox e produção
SandboxProdução
Chavesep_test_…ep_live_…
DinheiroNenhum valor real é cobrado ou transferido.Dinheiro real, sujeito às regras do provedor.
Campo environmentsandboxproduction
WebhooksHTTPS recomendado; http:// aceito para testes.Só HTTPS.
CheckoutSelo de ambiente de testes visível para o pagador.Sem selo.
DisponibilidadeImediata para contas em integração.Só para contas aprovadas, com as habilitações do provedor concluídas.

Todo recurso e todo evento carregam environment. Um recurso criado no Sandbox não existe em produção (404), e uma chave de um ambiente é recusada no outro (401 INVALID_API_KEY).

Testando os fluxos

  • Use CPF/CNPJ sintéticos com dígitos verificadores válidos (ex.: 52998224725). Nunca use dados de pessoas reais em testes.
  • O pagamento de Pix e boleto no Sandbox é confirmado pelo ambiente de testes do provedor; os eventos chegam ao seu webhook como em produção.
  • Teste também os caminhos ruins: recusa de cartão, 3DS, operação UNKNOWN, reenvio de webhook e endpoint fora do ar.
  • Envie um evento de teste para o seu endpoint com POST /v1/webhook-endpoints/{id}/test.

Versões do contrato

A API usa o caminho /v1 e uma versão de data, hoje 2026-11-13. Toda resposta traz o header Eclipta-Pay-Version com a versão usada; você pode fixá-la enviando o mesmo header (valor desconhecido responde 400 UNSUPPORTED_API_VERSION). Campos e rotas novos podem aparecer a qualquer momento: ignore campos desconhecidos e aceite valores novos em listas. Mudança incompatível numa rota implementada (remover campo, tornar campo obrigatório, mudar tipo) só sai com uma nova versão de data, verificada automaticamente a cada mudança do contrato.

Antes de ir para produção

  1. Crie chaves de produção só com os escopos necessários e guarde-as num cofre.
  2. Cadastre endpoints de webhook HTTPS de produção e verifique a assinatura em todas as entregas.
  3. Garanta idempotência no seu lado: deduplicação por eventId e uma Idempotency-Key por intenção.
  4. Trate UNKNOWN e MANUAL_REVIEW como estados normais na interface ("processando", "em verificação").
  5. Registre requestId, operationId e eventId nos seus logs, sem dados pessoais.

Próximo: Autenticação e chaves