Ambientes e hosts

1. Os dois ambientes

Ambiente	Quando usar	Persistência	Efeito real
Sandbox	Integração inicial, testes automatizados, homologação contratual com a IORQ	Operações são persistidas e ficam disponíveis para consulta	Nenhum — não há sinalização para administradora, não há desembolso real
Produção	Operações reais	Persistência completa, integração ativa com administradora, custodiante e bancarizador	termo de cessão real, desembolso real, registro contábil real no fundo

📘
Princípio
Sandbox é uma réplica funcional de produção — o mesmo contrato HTTP, os mesmos códigos de erro, os mesmos webhooks. A diferença é que sandbox não tem ponte para o mundo financeiro real. Use sandbox sem medo: nada que você faça lá movimenta dinheiro.

2. Hosts

A API é composta por serviços distintos por ambiente: o servidor de autenticação (emite tokens), o servidor de aplicação (recebe as chamadas operacionais) e o serviço de webhooks (registro e entrega). As rotas operacionais e as de webhook ficam todas sob o prefixo /api no respectivo host; apenas a autenticação (/oauth2/token) fica na raiz. O ambiente de integração/homologação ("sandbox") corresponde ao stage development.

Sandbox (development)

Serviço	Host
Autenticação	`https://auth-dev.iorq.com.br`
API operacional	`https://hs-receiver-app-development.iorq.com.br/api`
Webhooks	`https://webhook-sender-manager-development.iorq.com.br/api`

Produção

Serviço	Host
Autenticação	`https://auth.iorq.com.br`
API operacional	`https://hs-receiver-app-production.iorq.com.br/api`
Webhooks	`https://webhook-sender-manager-production.iorq.com.br/api`

🚧
Atenção
Credenciais de sandbox não funcionam em produção e vice-versa. O fund_id também é diferente entre ambientes — cada ambiente tem seu próprio UUID no e-mail de credenciais correspondente. A autenticação usa Amazon Cognito: o token é obtido em POST /oauth2/token no host de autenticação (ver Autenticação).

3. Requisitos de rede

Toda comunicação é via HTTPS (TLS 1.2+). HTTP simples é rejeitado.
Não há restrição de IP de saída para clientes da API. Você pode chamar de qualquer origem que resolva os hosts acima.
Para receber webhooks, sua URL pública precisa estar acessível para os IPs de saída da IORQ — veja Webhooks · Configuração e segurança.

4. Como obter acesso

O acesso à API é provisionado pela IORQ após assinatura do contrato comercial:

Time comercial da IORQ provisiona suas credenciais OAuth2 (client_id + client_secret) e o fund_id em sandbox — entregues por e-mail
Você integra, testa e homologa em sandbox
Após a aprovação técnica, novas credenciais são emitidas para produção (novo e-mail, com fund_id de produção)
Guarde o UUID de cada fundo do e-mail — ele será usado no header iorq-fund-id em todas as APIs (operacional e webhooks)

5. Versionamento

A API é versionada por compatibilidade contratual, não por path. Mudanças breaking são tratadas como exceção e comunicadas com antecedência mínima de 90 dias via:

E-mail para o contato técnico cadastrado
Changelog público

Mudanças aditivas (novos campos opcionais, novos eventos de webhook, novos códigos de erro) são liberadas sem aviso prévio — clientes que ignoram campos desconhecidos não quebram.

6. Próximos passos

Próximo passo — Autenticação

Obtenha seu primeiro Bearer JWT via OAuth2 client_credentials.

Voltar — Visão geral

Princípios e fluxo macro da API.