# FINAUTON — setup Postman

Todos os artefatos deste setup ficam nesta pasta. As 11 coleções cobrem **todas** as 47 operações (todos os métodos) dos 42 caminhos do OpenAPI. A 12ª coleção, **Erros esperados**, é a camada final: provoca os erros documentados e confere status HTTP, `error.code` e `requestId`. O pacote foi reconstruído depois da exclusão dos arquivos anteriores; ele não é uma exportação dos valores ou alterações atuais do aplicativo.

## Estrutura

- `workspace-finauton/`: coleções para importar e dois ambientes sem credenciais (`FINAUTON PILOT` → `https://api.finauton.com` e `FINAUTON Local`).
- `source/`: snapshot do contrato (`openapi.yaml/json`) e documentos para o parceiro (guia, catálogo de erros, semântica de PnL). O runbook de operações é interno e não entra no pacote.
- `globals/`: arquivo de globais existente do Postman, preservado.
- `CHECKLIST.md` e `ROUTES.json`: inventário completo para testar rota a rota.
- `SOURCE.json`: origem e hash do contrato usado na geração.
- `VALIDATION.json`: resultado da validação offline do pacote.
- `generate.mjs`: recria coleções, ambientes, inventário e checklist a partir de `source/openapi.json`.
- `errors.mjs`: casos da camada de erros (rota, corpo, status e códigos esperados).
- `verify.mjs`: verifica cobertura, URLs, credenciais e scripts sem enviar requisições.
- `share.ps1`, `share/` e `FINAUTON-Postman-Compartilhar.zip`: montagem e pacote para compartilhar.

O contrato canônico continua em `docs/b2b/`, porque é consumido por outras ferramentas da aplicação. O diretório técnico `.postman/` na raiz mantém a configuração existente do aplicativo.

## Importar e compartilhar

1. Extraia `FINAUTON-Postman-Compartilhar.zip`.
2. No Postman, crie ou selecione o workspace desejado e clique em **Import**.
3. Importe os 12 arquivos de `colecoes/` (11 de operações + `erros`) e os ambientes de `ambiente/`.
4. Se importar diretamente desta pasta, use os arquivos em `workspace-finauton/`.
5. Selecione **FINAUTON PILOT (produção restrita)** para a API publicada (`https://api.finauton.com`) ou **FINAUTON Local** para um backend local (`http://127.0.0.1:4455`). `baseUrl` vai sem `/v1` e sem barra final.
6. Preencha `clientId` e `clientSecret` com a credencial B2B recebida do FINAUTON (use o Vault do Postman para segredos). **Não há tenant para configurar:** o contrato é um só por parceiro e `POST /v1/users` só precisa de `externalUserId`. A variável `tenantId` só é usada nas rotas `/v1/tenants/{tenantId}` e é o id do seu parceiro (aparece em `GET /v1/tenants`).
7. Ajuste `externalUserId`, `providerId`, `strategyId` e os IDs das entidades conforme os dados do backend.

O ZIP contém ambiente vazio de credenciais, coleções, guia, checklist e os documentos em `source/`. Os scripts de manutenção ficam no repositório. Cada pessoa precisa de seu próprio backend local ou de uma URL acessível: `127.0.0.1` aponta para o computador de quem executa o Postman.

## Fluxo de testes

Execute manualmente, uma requisição por vez, nesta ordem:

1. **Saúde e contrato**: saúde, seu contrato (`GET /v1/tenants`) e uso.
2. **Catálogos**: providers, mercados e estratégias permitidas.
3. **Clientes**: cadastro, consulta, status e situação comercial.
4. **Estratégias do cliente**: consulta e definição.
5. **Conexão da corretora**: contas, providers e sessões de conexão.
6. **Risco**: setup, preview e limites.
7. **Automação**: consulta e configuração. O corpo de exemplo mantém `enabled: false`.
8. **Posições e ordens**: consultas e contratos de preparação, execução e reconciliação.
9. **Performance**: resultado e extrato.
10. **Cobrança e pagamento**: obrigações, faturas de depósito, instruções e consulta/confirmacão.
11. **Feed de eventos**: consulta do feed.
12. **Erros esperados** (camada final): autenticação (401), idempotência (400/409), escopo e isolamento (404/403), grants e risco (403/422/400) e conexão (403/422). Cada teste confere status, `error.code` e `requestId`, e grava o último erro em `lastErrorCode`/`lastErrorRequestId`. Nenhum caso envia ordem, paga ou conclui conexão; o par de idempotência faz upsert do cliente sintético `{{externalUserId}}`. O caso `CREDENTIALS_MISSING` precisa de um cliente sem corretora conectada. Fora da coleção: `429 RATE_LIMITED` e `409 TENANT_MISMATCH`. A camada é validada contra a API real em `backend/src/v1/modules/b2b/__tests__/b2b-postman-errors.test.ts`.

Registre status HTTP, requestId e PASS/FAIL em `CHECKLIST.md`. Todos os resultados começam PENDENTE.

Os corpos são exemplos sintéticos construídos a partir do contrato, com campos obrigatórios. Revise-os antes de enviar; vínculos de domínio, readiness e regras comerciais são validados pelo backend. Os IDs de sessão, obrigação e pagamento começam vazios; `intentId` começa em `ord-qa-postman-0001` (troque a cada nova ordem). **Ordens manuais** (`/v1/orders/*`) vêm com o corpo completo de exemplo (abertura LIMIT com stop e alvos): `prepare` só valida, mas **`execute` envia ordem REAL** à corretora do cliente — use só com autorização. Não há credenciais de corretora nos exemplos.

## Scripts

Não há bloqueios locais de URL, credenciais ou flags `allow*`, nem `pm.execution.skipRequest()`. O script antes da requisição apenas prepara a chave nas rotas que exigem `Idempotency-Key`.

Cada chave permanece salva no ambiente como `idem_<operationId>_<externalUserId>_<providerId>`. Reutilize a mesma chave e o mesmo corpo ao repetir a mesma ação. Para uma nova ação, apague a variável correspondente e envie novamente. A geração e os testes offline não executam rotas.

Após a resposta, os testes verificam o status de sucesso documentado e o schema JSON do código recebido. A rota legada `PUT /v1/users/{externalUserId}/accounts/{provider}` documenta somente `403 HOSTED_CONNECT_REQUIRED`; o teste dessa rota espera `403`. Para testar outro erro esperado, defina temporariamente `expectedStatus`, por exemplo `401`, e limpe-o ao terminar. Os scripts capturam apenas IDs de entidades no primeiro nível da resposta ou em `data`; outros formatos exigem preenchimento manual.

## Manutenção no repositório

Na raiz do projeto:

```powershell
node postman/verify.mjs
# Recriar os arquivos gerados e o checklist; substitui o ambiente modelo e seus valores:
node postman/generate.mjs
# Validar e atualizar o ZIP:
pwsh -NoProfile -File postman/share.ps1
```

Para atualizar o contrato, sincronize os snapshots `source/openapi.yaml` e `source/openapi.json` antes de gerar. Nenhuma dependência nova é necessária para gerar ou verificar a partir do JSON.

Este pacote é gerado de `docs/b2b/openapi.yaml` (contrato único por parceiro, `tenantId` opcional). Documentação navegável: https://docs-fin.tokeneasily.com/docs. O setup não inicia backend, MongoDB ou Engine e não constitui evidência de sucesso das rotas reais.

## Publicação

A branch codex/postman-setup é excluída do push do Build CI. Os jobs de Build, QA e conectividade também são ignorados quando essa branch é a referência ou a origem do PR. Ao mesclar na main, os gatilhos existentes continuam ativos. O deploy mantém suas condições atuais.