Saltar al contenido principal

Postman y SDKs

No necesitas armar solicitudes desde cero: la colección Postman y el spec OpenAPI se generan de la misma fuente que la Referencia de la API y siempre están en sincronía con ella.

Colección Postman​

Colecciones en formato Postman v2.1, una por idioma:

Cada colección viene organizada en carpetas por recurso (Clientes, Cobros, Acuerdos, Disputas, Tareas, Interacciones, Notificaciones, Reglas de cobranza, Plantillas de mensaje, Clasificaciones, Campañas de negociación, Negativaciones, Protestos, Importaciones, Exportaciones, Webhooks, Pista de auditoría, Métricas, Layouts de e-mail, Preferencias de notificación), con ejemplos de body listos. Los parámetros opcionales vienen deshabilitados, para que la solicitud corra limpia a la primera.

Importar y configurar​

  1. En Postman: Import → arrastra el JSON (o pega la URL).
  2. Completa las dos variables de la colección:
    • baseUrl: ya viene con producción (https://dunning.kobana.com.br/api/v1);
    • bearerToken: tu clave de API.
  3. Ejecuta GET /people para validar el setup y explora por las carpetas.

La misma colección funciona en Insomnia y en Bruno (ambos importan Postman v2.1); para esas herramientas, importar directamente el OpenAPI (abajo) suele dar un resultado aún mejor.

OpenAPI: la fuente de la verdad​

El spec OpenAPI 3.1 está disponible en los tres idiomas, directo de la 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

Sin ?locale=, vale el Accept-Language (por defecto: portugués). Detalles en Especificaciones OpenAPI.

Generar un SDK​

No hay SDKs oficiales por lenguaje; el camino soportado es generar un cliente a partir del OpenAPI, que describe todos los endpoints, schemas y códigos de error. Con el OpenAPI Generator:

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

# Otros lenguajes: -g python | go | ruby | php | csharp | java ...

Dos cuidados en el cliente generado:

  • Configura el User-Agent identificando tu integración (es obligatorio).
  • Envía X-Idempotency-Key en las mutaciones; los generadores no lo hacen solos (por qué).

Mantenerse actualizado​

La referencia, la colección y el spec salen todos del mismo OpenAPI versionado. Cuando la API gane recursos, re-importa la colección (Postman preserva tus variables) o re-genera el cliente apuntando a la URL del spec.