Começando

Ambientes

A API opera em três ambientes homologados, controlados por variáveis de ambiente. Operações de criação de chave Pix são vinculadas à ENV autorizada — ambientes não homologados não fazem parte deste contrato.

Ambiente	Base URL	Uso
Desenvolvimento	https://apiapp.dev.ideabank.com.br	Provisionado no onboarding. Dados fictícios.
Homologação	https://apiapp.hml.ideabank.com.br	Validação com o time Idea+Cash antes de ir para produção.
Produção	https://apiapp.ideabank.com.br	Liberado após aprovação da homologação.

URLs sujeitas a confirmação

As URLs de HML e Produção são liberadas no onboarding técnico. Sempre valide-as com o time Idea+Cash antes de subir para produção.

Headers obrigatórios

Header	Quando	Valor
Authorization	sempre	Bearer <access_token>
tenantid	sempre	id do tenant da conta (recebido no onboarding)
hostdevelop	só DEV	apiapp.dev.ideabank.com.br
account-id wallet-id tax-identifier	rotas que operam sobre conta (um dos três)	precedência: wallet-id > tax-identifier > account-id
X-Request-ID	recomendado	rastreabilidade — também retorna na resposta

A conta é sempre identificada por header — não há remoteId na query. Sem um dos headers de conta a API responde 422 com account, wallet or tax-identifier header is required.

Ciclo de homologação

Assinatura contratual e cadastro do cliente na Idea+Cash.
Emissão de credenciais M2M (dev + hml + prod).
Integração em dev: quickstart, cobrança e webhook.
Homologação assistida em hml: cenários de erro, retries, devolução.
Liberação em produção com monitoração e canal de suporte ativos.

Boas práticas de configuração

Mantenha URLs, client_id, client_secret e chaves Pix por ambiente separados.
Nunca aponte um ambiente de teste para chaves de produção — a criação de chaves é vinculada à ENV homologada.
Registre o X-Request-ID de cada resposta para rastreabilidade em caso de suporte.