Referencia de la API de claves de API

Referencia completa de los endpoints de la API de claves de API.

URL base

https://api.orcarail.com/api/v1

Crear una clave de API

Crea una nueva clave de API para una organización concreta.

POST /organizations/:organizationId/api-keys

Autenticación

• Token Bearer (JWT): obligatorio

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
organizationId	string	Sí	ID de la organización para la que se crea la clave. El token bearer debe tener acceso.

Usa el id de la organización de Panel → Configuración de la organización o de la respuesta de la API que lista tus organizaciones. El parámetro de ruta es obligatorio; las claves de API se crean exactamente para esa organización.

Cuerpo de la petición

Parámetro	Tipo	Obligatorio	Descripción
name	string	No	Nombre descriptivo de la clave de API
webhookUrl	string	No	URL de webhook para recibir eventos de pago

Respuesta

{
  "apiKey": {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "webhookUrl": "https://api.example.com/webhooks/orcarail",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  },
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

:::warning Importante El secret solo se muestra una vez. ¡Guárdalo de inmediato! :::

Listar claves de API

Lista todas las claves de API de una organización concreta.

GET /organizations/:organizationId/api-keys

Autenticación

• Token Bearer (JWT): obligatorio

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
organizationId	string	Sí	ID de la organización cuyas claves se listan. El token bearer debe tener acceso.

La lista se limita a la organización de la ruta; OrcaRail no deduce otra organización a partir de la sesión cuando este parámetro está presente.

Respuesta

[
  {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z"
  },
  {
    "id": 2,
    "name": "Development API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "createdAt": "2024-01-02T00:00:00.000Z"
  }
]

Actualizar una clave de API

Actualiza el nombre o la URL de webhook de una clave de API.

PATCH /api-keys/:id

Autenticación

• Token Bearer (JWT): obligatorio

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	number	Sí	ID de la clave de API

Cuerpo de la petición

Parámetro	Tipo	Obligatorio	Descripción
name	string	No	Nombre descriptivo de la clave de API
webhookUrl	string	No	URL de webhook para recibir eventos de pago (ponla a null para quitarla)

Respuesta

{
  "id": 1,
  "name": "Updated API Key Name",
  "keyPrefix": "ak_live_",
  "status": "active",
  "webhookUrl": "https://api.example.com/webhooks/orcarail",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Revocar una clave de API

Revoca una clave de API para desactivarla.

POST /api-keys/:id/revoke

Autenticación

• Token Bearer (JWT): obligatorio

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	number	Sí	ID de la clave de API

Respuesta

{
  "id": 1,
  "name": "Production API Key",
  "keyPrefix": "ak_live_",
  "status": "revoked",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Probar una clave de API

Comprueba si una clave de API es válida.

POST /api-keys/test

Autenticación

• No requiere

Cuerpo de la petición

Parámetro	Tipo	Obligatorio	Descripción
key	string	Sí	Clave de API (por ejemplo ak_live_...)
secret	string	Sí	Secreto de API (por ejemplo sk_live_...)

Respuesta

{
  "ok": true
}

Respuesta de error

Si la clave de API no es válida:

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

Objeto de clave de API

Campos

Campo	Tipo	Descripción
id	number	Identificador único
name	string	Nombre descriptivo
keyPrefix	string	Primeros 8 caracteres de la clave (por ejemplo ak_live_)
status	string	Estado: active o revoked
webhookUrl	string	URL de webhook para recibir eventos de pago (puede ser null)
createdAt	string	Marca de tiempo ISO 8601 de creación
updatedAt	string	Marca de tiempo ISO 8601 de la última actualización

Valores de estado

Estado	Descripción
active	La clave de API está activa y se puede usar
revoked	La clave de API se ha revocado y no se puede usar

Códigos de estado

Código de estado	Descripción
200	Correcto
201	Creado
400	Petición incorrecta
401	No autorizado
404	No encontrado
500	Error interno del servidor

Formato de las respuestas de error

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

Consulta también

• Guía de claves de API: documentación detallada de las claves de API
• Configuración de webhooks: configura webhooks para las claves de API
• Visión general de la autenticación: métodos de autenticación