# Coleção de API importável: testar a integração no cliente HTTP sem expor a chave Guia · UNIFOKAL · 23 de setembro de 2026 · 6 min de leitura · Produto e integração O que uma coleção importável de API deve trazer, como ela deixa a chave fora do arquivo, por que gerá-la da especificação e um roteiro para a primeira chamada no sandbox. 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](https://unifokal.com/blog/idempotencia-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](https://unifokal.com/docs/api-rest) é 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](https://unifokal.com/blog/separar-sandbox-de-producao) 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](https://unifokal.com/blog/rotacao-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](https://spec.openapis.org/oas/v3.1.0) - Postman, Collection Format v2.1.0, schema JSON oficial: [schema.getpostman.com](https://schema.getpostman.com/json/collection/v2.1.0/collection.json) - Postman, repositório postmanlabs/schemas, licença Apache 2.0: [github.com](https://github.com/postmanlabs/schemas) - Postman Learning Center, "Store and reuse values using variables", lida em 23 de setembro de 2026: [learning.postman.com](https://learning.postman.com/docs/use/send-requests/variables/variables) - Postman Learning Center, "Import data into Postman", lida em 23 de setembro de 2026: [learning.postman.com](https://learning.postman.com/docs/getting-started/importing-and-exporting/importing-data) - Kong, documentação do Insomnia, página de importação e exportação, lida em 23 de setembro de 2026: [developer.konghq.com](https://developer.konghq.com/insomnia/import-export/) - Bruno, documentação de migração a partir do Postman, lida em 23 de setembro de 2026: [docs.usebruno.com](https://docs.usebruno.com/get-started/import-export-data/postman-migration)