Pular para o conteúdo principal

Postman e SDKs

Você não precisa montar requisições do zero: a coleção Postman e o spec OpenAPI são gerados da mesma fonte da Referência da API e ficam sempre em sincronia com ela.

Coleção Postman​

Coleções no formato Postman v2.1, uma por idioma:

Cada coleção vem organizada em pastas por recurso (Clientes, Cobranças, Acordos, Disputas, Tarefas, Interações, Notificações, Réguas de cobrança, Templates de mensagem, Classificações, Campanhas de negociação, Negativações, Protestos, Importações, Exportações, Webhooks, Trilha de auditoria, Métricas, Layouts de e-mail, Preferências de notificação), com exemplos de body prontos. Parâmetros opcionais vêm desabilitados, para a requisição rodar limpa de primeira.

Importar e configurar​

  1. No Postman: Import → arraste o JSON (ou cole a URL).
  2. Preencha as duas variáveis da coleção:
    • baseUrl: já vem com a produção (https://dunning.kobana.com.br/api/v1);
    • bearerToken: sua chave de API.
  3. Rode GET /people para validar o setup e explore pelas pastas.

A mesma coleção funciona no Insomnia e no Bruno (ambos importam Postman v2.1); para essas ferramentas, importar direto o OpenAPI (abaixo) costuma dar resultado ainda melhor.

OpenAPI: a fonte da verdade​

O spec OpenAPI 3.1 está disponível nos três idiomas, direto da API:

GET https://dunning.kobana.com.br/api/v1/openapi.yaml?locale=pt|en|es
GET https://dunning.kobana.com.br/api/v1/openapi.json?locale=pt|en|es

Sem ?locale=, vale o Accept-Language (padrão: português). Detalhes em Especificações OpenAPI.

Gerando um SDK​

Não há SDKs oficiais por linguagem; o caminho suportado é gerar um cliente a partir do OpenAPI, que descreve todos os endpoints, schemas e códigos de erro. Com o OpenAPI Generator:

# TypeScript (fetch)
openapi-generator-cli generate \
  -i https://dunning.kobana.com.br/api/v1/openapi.yaml \
  -g typescript-fetch -o ./dunning-client

# Outras linguagens: -g python | go | ruby | php | csharp | java ...

Dois cuidados no cliente gerado:

  • Configure o User-Agent identificando sua integração (é obrigatório).
  • Envie X-Idempotency-Key nas mutações; geradores não fazem isso sozinhos (por quê).

Mantendo-se atualizado​

A referência, a coleção e o spec saem todos do mesmo OpenAPI versionado. Quando a API ganhar recursos, re-importe a coleção (o Postman preserva suas variáveis) ou re-gere o cliente apontando para a URL do spec.