Coleção de API importável: testar a integração no cliente HTTP sem expor a chave

A especificação OpenAPI descreve uma API. Uma coleção a executa. A diferença parece pequena até a primeira tarde de integração: com a especificação, quem integra ainda precisa montar cada chamada à mão no cliente HTTP; com uma coleção, a chamada chega pronta, com o endereço, o corpo mínimo e a autenticação no lugar, e o trabalho vira preencher a chave e enviar.

É por isso que tanta API publica uma coleção ao lado da documentação. E é por isso também que coleção mal feita é perigosa: ela é um arquivo que a pessoa importa na ferramenta de trabalho, e o que estiver dentro dele vai junto, inclusive o que não deveria estar.

Este artigo trata do que uma coleção importável deve trazer, de como manter a chave fora dela, de por que gerar a coleção da especificação em vez de mantê-la à mão e de um roteiro para a primeira sessão de teste no sandbox.

Especificação descreve, coleção executa

A OpenAPI Specification 3.1.0, mantida pela OpenAPI Initiative, define uma descrição de interface para APIs HTTP que permite a pessoas e a computadores entender o que um serviço faz sem acesso ao código-fonte. Ferramentas usam essa descrição para gerar documentação, clientes, servidores e testes. Ela diz a forma de cada operação: caminho, parâmetros, corpo, respostas e esquema de segurança.

A coleção é outro tipo de artefato. No formato Postman Collection, cada item é uma requisição concreta, com método, endereço, cabeçalhos e corpo, organizada em pastas. As variáveis entram entre chaves duplas e são resolvidas na hora de enviar. O resultado é uma sequência de chamadas que roda como está, na ordem em que alguém faria a integração.

Um formato aberto, que três clientes importam

O Postman Collection v2.1.0 é publicado com um schema JSON no repositório postmanlabs/schemas, sob licença Apache 2.0, e não prende quem integra a uma ferramenta:

• O Postman importa por arquivo, por pasta, por texto colado ou por endereço, e recusa o formato v1, que deixou de ser suportado.
• O Insomnia, da Kong, lista Postman v2.0 e v2.1 entre os formatos de importação, ao lado de OpenAPI 3.0 e 3.1, e aceita arquivo, endereço ou área de transferência.
• O Bruno documenta a migração a partir de coleções exportadas do Postman nos formatos v2 e v2.1.

Como o formato tem schema público, dá para validar a coleção antes de publicar, do mesmo jeito que se valida a especificação.

A chave fica fora do arquivo

A regra mais importante de uma coleção pública é simples: ela nunca carrega chave. A autenticação é declarada com uma variável, e o valor vive no ambiente de quem importa.

A documentação do Postman sobre variáveis explica por que isso funciona. Quando o mesmo nome existe em dois escopos, vale o valor do escopo mais estreito, e a ordem do mais amplo para o mais estreito é global, coleção, ambiente, dados e local. Uma variável de ambiente, portanto, sobrepõe a da coleção. Para valor sensível, a mesma documentação indica o Postman Vault, que guarda segredos separados das coleções e dos ambientes.

Daí saem duas consequências práticas:

• A coleção pode trazer valores que não são segredo, como o endereço base da API, e o ambiente sobrepõe quando for preciso apontar para outro lugar.
• A variável da chave não deve ser definida dentro da coleção, nem com um valor de exemplo que alguém preencha e depois compartilhe o arquivo sem perceber.

Há um segundo cuidado, menos lembrado: script. O formato permite eventos com scripts de pré-requisição e de teste, e o cliente de quem importa executa esses scripts ao enviar a requisição. O Bruno, por exemplo, traduz automaticamente as funções de script mais comuns do Postman ao migrar uma coleção. Uma coleção pública sem nenhum script é mais fácil de auditar e não pede uma confiança que a documentação não precisa pedir.

Gerar da especificação, em vez de manter à mão

Coleção mantida à mão envelhece do mesmo jeito que exemplo de código em documentação: alguém muda um campo obrigatório na API e ninguém lembra do arquivo. O sintoma aparece na pior hora, quando a primeira chamada de quem está avaliando o produto volta com erro de validação.

A alternativa é gerar a coleção a partir da especificação, no mesmo passo em que a especificação é publicada. O que a especificação não diz, como o menor corpo válido de cada operação, entra numa lista fechada, e uma operação nova sem entrada nessa lista quebra a publicação em vez de sair incompleta. A coleção gerada pode ser conferida de três jeitos: toda operação da especificação tem um item, todo campo obrigatório do corpo tem valor e o arquivo valida contra o schema oficial do formato. A mesma disciplina vale para a idempotência em APIs: o que o cliente vai repetir precisa estar certo desde a primeira versão.

Na documentação da UNIFOKAL, por exemplo, a coleção importável da API é gerada da especificação OpenAPI a cada publicação, sem chave e sem script.

Um roteiro de teste no sandbox

Com a coleção importada, a primeira sessão de teste costuma seguir esta ordem:

1. Comece pela chamada que não exige chave, se a API tiver uma, como um catálogo público. Ela prova que o endereço está certo antes de qualquer credencial entrar em jogo.
2. Crie um ambiente com a chave de sandbox e os identificadores de teste de que as chamadas precisam. Nunca use a chave de produção para isso, e o artigo sobre separar sandbox de produção explica por quê.
3. Rode as chamadas que criam recursos e confira cada resposta contra a documentação, campo por campo.
4. Exercite o caminho de recuperação, como a listagem e o reenvio de webhooks que falharam, para vê-lo funcionando antes de precisar dele.

Terminado o teste, se a chave de sandbox ficou salva num ambiente que outras pessoas acessam, gire a chave. O artigo sobre rotação de chave e segredo de webhook cobre o procedimento sem derrubar a integração.

Fontes citadas

• OpenAPI Initiative, OpenAPI Specification v3.1.0 (15 de fevereiro de 2021), seção 1, introdução: spec.openapis.org
• Postman, Collection Format v2.1.0, schema JSON oficial: schema.getpostman.com
• Postman, repositório postmanlabs/schemas, licença Apache 2.0: github.com
• Postman Learning Center, "Store and reuse values using variables", lida em 23 de setembro de 2026: learning.postman.com
• Postman Learning Center, "Import data into Postman", lida em 23 de setembro de 2026: learning.postman.com
• Kong, documentação do Insomnia, página de importação e exportação, lida em 23 de setembro de 2026: developer.konghq.com
• Bruno, documentação de migração a partir do Postman, lida em 23 de setembro de 2026: docs.usebruno.com