Referência da API (OpenAPI + Postman)

A Allya publica uma especificação OpenAPI 3.1 gerada a partir dos próprios schemas Zod usados em runtime — não existe documento paralelo. Se o contrato muda no código, o build regenera os artefatos e o CI bloqueia PRs que esquecem de commitar a atualização.

Artefatos disponíveis

Todos os artefatos têm duas formas de acesso. O conteúdo é equivalente (gerado pela mesma função); use a forma que sua ferramenta preferir.

As rotas /v1/openapi.* são geradas a partir do mesmo código que produz os arquivos estáticos. Os arquivos em / ficam versionados no repositório — fazem diferença em revisão de contrato no PR e para Postman, que importa de arquivo.

Importar em ferramentas

Postman

1. Em File → Import, escolha o arquivo allya-payments.postman_collection.json ou cole a URL acima.
2. Crie um environment com as variáveis listadas em Variáveis esperadas abaixo.
3. As requisições já vêm com Authorization: Bearer {{ALLYA_API_KEY}} na collection-level auth — basta escolher o environment.

Insomnia

Insomnia importa OpenAPI diretamente. No menu de importação da sua versão, escolha "From URL" e cole https://payments-api.allyasolutions.com/v1/openapi.yaml, ou "From File" apontando para o openapi.yaml baixado. Não há collection Insomnia dedicada — manter dois formatos paralelos não compensa o ganho.

Outros clientes OpenAPI

Bruno, Hoppscotch, RapidAPI e demais clientes compatíveis com OpenAPI 3.1 leem openapi.yaml direto, seja via URL ou arquivo.

Gerar cliente HTTP tipado

# TypeScript via openapi-typescript
npx openapi-typescript https://payments-api.allyasolutions.com/v1/openapi.yaml -o allya.d.ts

Variáveis esperadas

Defina no environment do Postman antes de disparar requisições. A collection já referencia esses nomes.

Para produção, troque sk_test_ por sk_live_. Detalhes em Indo para produção.

O OpenAPI cobre apenas as rotas síncronas. A validação de webhooks outbound (HMAC com ALLYA_WEBHOOK_SECRET) está descrita em Webhooks — não há requisição equivalente na collection.

Como a sincronia é garantida

• Geração — pnpm openapi:generate (executado automaticamente em pnpm build).
• Fonte — schemas Zod em src/modules/*/schemas.ts e src/modules/*/responses.ts.
• Contract check — toPublicPayment e toPublicSubscription têm assertivas em typecheck contra os schemas de resposta. Divergência quebra a compilação.
• CI — workflow openapi-check falha em PR se os arquivos versionados em public/ não baterem com a saída atual do gerador.

Se você encontrar divergência de contrato (campos, tipos, status codes) entre as páginas em prosa e o OpenAPI, considere o OpenAPI a referência autoritativa: ele é gerado do código. As páginas em prosa adicionam tutoriais, decisões de gateway e troubleshooting que não cabem em JSON Schema.

Limitações conhecidas

• Algumas regras cruzadas — card rejeitado quando method=pix, customer.phone obrigatório no Pagar.me com cartão, gateway.pagarme.planId obrigatório no Pagar.me — não são expressáveis em JSON Schema. Ficam descritas nos campos e validadas em runtime. Veja Criar pagamento e Criar assinatura.
• Webhooks outbound (payment.*, subscription.*) não fazem parte do OpenAPI, que descreve só endpoints HTTP síncronos. Use Webhooks como referência.

Veja também

• Playground da API: testar os endpoints síncronos no navegador com uma chave sandbox.
• Autenticação: formato e uso da API key.
• Webhooks: payload e validação dos eventos outbound.
• Erros: catálogo completo dos códigos retornados.