Ambiente Sandbox (Homologação)

O ambiente de homologação permite testar a integração sem afetar dados de produção.

Known Issues no Sandbox

O ambiente de homologação possui algumas divergências conhecidas em relação à documentação e ao ambiente de Produção.

Leia antes de codificar: Known Issues & Gotchas

Resumo das Divergências

Característica	Documentação	Sandbox (Real)
Case dos Campos	UPPERCASE	Inconsistente
Formato de Data	String ISO	Número (20250207)
Status	Dinâmico	Fixo EM_PROCESSAMENTO
Datas dos Dados	Atuais	Fixas (2025)

Dica: Use o Wrapper de Normalização para lidar com essas inconsistências automaticamente.

---

Limitações do Sandbox

O ambiente de homologação possui algumas limitações intencionais para simplificar os testes:

Funcionalidade	Sandbox	Produção
Webhooks	Indisponível	Disponível
Status dinâmico	Fixo EM_PROCESSAMENTO	Completo
IDs de configuração	Fixos (35176, 35177)	Obtidos via API
Download de dados	Imediato	Após CONCLUIDO

Webhooks no Sandbox

Os Webhooks NÃO estão disponíveis no ambiente Sandbox.

Para testar sua integração durante a homologação:

• Utilize Polling (GET /retornos?id={ID}) para consultar o status
• Lembre-se: no Sandbox, não espere o status mudar - faça o download imediatamente
• Desenvolva a lógica de Webhook, mas valide-a apenas em Produção

Dica para desenvolvimento local: Use ferramentas de sua preferência para expor seu endpoint local e testar Webhooks em Produção de forma controlada.

---

Atenção: Comportamento do Status no Sandbox

IMPORTANTE: No ambiente Sandbox, o campo situacao é fixo como EM_PROCESSAMENTO.

Isso significa que:

• O status NUNCA mudará para CONCLUIDO
• O campo quantidadePaginas sempre retornará null
• Os dados JÁ ESTÃO DISPONÍVEIS para download imediatamente após a geração

Como proceder no Sandbox:

1. Gere a remessa (você receberá um id)
2. IGNORE o status EM_PROCESSAMENTO
3. Faça o download dos dados imediatamente (os dados mockados já estão prontos)

Exemplo de Resposta no Sandbox

[
  {
    "id": 4000000000476410,
    "situacao": "EM_PROCESSAMENTO",
    "tipoRemessa": "Vendas - Equals (API)",
    "quantidadePaginas": null
  }
]

[!TIP] Dica para desenvolvimento: Ao implementar a lógica de polling, adicione uma condição especial para o ambiente Sandbox. No ambiente de homologação, não espere - os dados estão prontos imediatamente.

Comparação: Status Sandbox vs Produção

Característica	Sandbox	Produção
Status	Fixo EM_PROCESSAMENTO	Dinâmico (AGUARDANDO EM_PROCESSAMENTO CONCLUIDO/ERRO)
quantidadePaginas	Sempre null	Preenchido quando CONCLUIDO
Quando baixar	Imediatamente após geração	Após status CONCLUIDO
Polling	Não necessário	Necessário (ou usar Webhook)

---

Credenciais (Homologação)

As credenciais de sandbox são obtidas exclusivamente no Portal Developers:

1. Inicie a jornada Equals Connect
2. Acesse "Ambiente de homologação"
3. Abra a modal "Dados do ambiente de homologação"

Campo	Exemplo	Descrição
Usuário	email@email.com.br	Email para autenticação Basic Auth
BaseUrl	https://partner.equals.com.br/sandbox/api/equals-retorno	URL base do ambiente sandbox
Token	jcvVbje...	Token gerado automaticamente

[!NOTE] Diferente da produção, o token de homologação é gerado automaticamente na jornada do Portal Developers e pode ser consultado novamente a qualquer momento.

IDs Fixos

No Sandbox, use sempre estes IDs para geração de remessas:

Tipo	ID	Descrição
Vendas	35176	Remessa de Vendas (Sandbox)
Financeiro	35177	Remessa Financeira (Sandbox)

Comportamento Específico

• Os dados retornados são mockados e não refletem transações reais
• O status pode permanecer como EM_PROCESSAMENTO, mas os dados já podem ser baixados
• Use este ambiente para validar o fluxo de autenticação, geração e download

Migrando para Produção

Quando estiver pronto para produção:

Item	Sandbox	Produção
Base URL	https://partner.equals.com.br/sandbox/api/equals-retorno	https://app.equals.com.br/api/equals-retorno
Token	Gerado no Portal Developers	Gerado em Administração > Tokens de API
Email	Exibido na modal	Seu email de login do Equals
IDs de Configuração	Fixos (35176, 35177)	Obtidos via GET /retornos/configuracoes