Estructura de Endpoints
Introducción
Comprender la estructura de los endpoints de la API de Passport es clave para lograr una integración fluida. En esta sección te explicamos la URL base, el sistema de versionado y las mejores prácticas para construir tus solicitudes API.
URL Base
Todas las solicitudes a la plataforma Passport deben enviarse a la siguiente URL base:
Sandbox:https://api.paas-sandbox.co.passportfintech.com
Production: https://api.paas.co.passportfintech.com
Ejemplo
JSON+ https://api.paas-sandbox.co.passportfintech.comAsegúrate siempre de utilizar HTTPS para garantizar la seguridad en la transmisión de datos.
Versionado de la API
La API de Passport utiliza un sistema de versionado para mantener la compatibilidad hacia atrás. La versión se incluye como parte de la ruta del endpoint:
https://api.paas-sandbox.co.passportfintech.com/{version}/Versión Estable Actual
https://api.paas-sandbox.co.passportfintech.com/v1/Consejo: Revisa siempre en esta documentación cuál es la versión más reciente de la API para aprovechar mejoras y actualizaciones.
Formato de los Endpoints
Cada endpoint sigue una estructura definida:
{base_url}/{version}/{resource}/{identifier}Ejemplo
- https://api.paas-sandbox.co.passportfintech.com/v1/iam/oauth/tokens
- https://api.paas-sandbox.co.passportfintech.com/v1/customers/{customer_id}
- https://api.paas-sandbox.co.passportfintech.com/v1/accounts
- https://api.paas-sandbox.co.passportfintech.com/v1/payments/{payment_id}
Desglose del Ejemplo
| Segmento | Descripción |
|---|---|
| {base_url} | Dominio raíz donde se envían las solicitudes. |
| {version} | Versión de la API (por ejemplo, v1). |
| {resource} | Recurso principal al que estás accediendo (por ejemplo, iam/oauth/tokens). |
| {identifier} | ID único, si aplica (por ejemplo, en un GET a iam/oauth/tokens/{token_id}). |
Peticiones DELETE devuelven el código HTTP 204 Content Not Found, sin cuerpo de respuesta.
Códigos HTTP
| Método | Descripción |
|---|---|
| GET | Se utiliza para recuperar un recurso específico o una colección de recursos del servidor, permitiendo que los clientes accedan y usen los datos de forma eficiente. |
| POST | Permite crear un recurso o enviar una acción específica dentro de la plataforma. |
| PATCH | Permite modificar únicamente los campos que deben cambiarse sin alterar el recurso completo. Asegúrate de que el cuerpo incluya solo los campos que deseas actualizar en el formato adecuado. |
| DELETE | Elimina o revoca permisos o acceso para un usuario o recurso específico. |
Estructura de Solicitud y Respuesta
Formato de Solicitud
Todas las solicitudes deben enviarse en formato JSON e incluir los headers de autenticación necesarios.
Ejemplo de Solicitud
curl --location --request GET 'https://api.paas-sandbox.co.passportfintech.com/v1/accounts/f1dce2ff-7413-4fab-91e4-ca84489cf74c' \--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \--data ''Formato de la Respuesta
Las respuestas de la API están estructuradas en JSON y te ofrecen una vista clara y detallada del objeto retornado.
Ejemplo de la Respuesta
{ "created_at": "2025-09-29T15:14:24.560Z", "updated_at": "2025-09-30T13:42:22.706Z", "entity_customer_id": "a9326341-40e6-497e-b44a-72c49a2c3910", "available_balance": { "currency": "COP", "value": "90000000000000000" }, "number": "880310992", "type": "ORDINARY", "pending_balance": { "currency": "COP", "value": "0" }, "id": "f1dce2ff-7413-4fab-91e4-ca84489cf74c"}Parámetros de consulta (Query Parameters)
Los métodos GET admiten parámetros de consulta. Para más detalles, revisa Parámetros de Consulta.