Claves de API

Las claves de API ofrecen una forma segura de autenticar las peticiones de servidor a servidor a la API de OrcaRail.

Visión general

Las claves de API tienen dos partes:

Clave (ak_live_...): identificador público
Secreto (sk_live_...): secreto privado (¡guárdalo bien!)

Ambas son necesarias para autenticarse con Basic Auth.

Claves live y sandbox

Organización	Clave	Secreto	Redes
Live	`ak_live_…`	`sk_live_…`	Mainnets, fondos reales
Sandbox	`ak_test_…`	`sk_test_…`	Testnets, sin fondos reales

El prefijo solo te ayuda a distinguir las claves; la API siempre decide el modo a partir de la organización de la clave. El panel muestra una insignia Test o Live junto a cada clave.

Crear claves de API en el panel

La forma más fácil de crear y gestionar claves de API es desde el panel de OrcaRail:

Inicia sesión: abre Panel → Iniciar sesión e introduce tus credenciales.
Crea tu primera organización si se te pide: las cuentas nuevas deben crear una organización antes de continuar en el panel. La configuración guiada muestra el slug generado y te permite editarlo antes de crearla si lo necesitas.
Completa los pasos obligatorios de la configuración guiada: OrcaRail mantiene el panel bloqueado hasta que tu organización tenga un modo de venta, al menos un producto, al menos un precio, una clave de API y un widget.
Crea una clave de API: la configuración guiada incluye un paso de clave de API integrado, o puedes abrir Panel → Claves de API desde la barra lateral.
Copia la clave y el secreto: copia la clave y el secreto de inmediato; el secreto se muestra una sola vez y no se puede recuperar después.

En la misma página del panel también puedes listar, actualizar y revocar claves de API.

Puedes definir un porcentaje de comisión (0–100) en una clave de API. Cuando se crean pagos con esa clave:

La comisión se calcula en la cotización y se muestra al pagador en el checkout.
El importe de la comisión se guarda en la cotización y se incluye en los totales.
En el retiro, la comisión se envía a la dirección de la configuración de retiros de tu cuenta (la misma estrategia y dirección que usas para tus pagos principales).

Úsala para repartir ingresos con socios o ganar una parte de cada pago hecho a través de tu integración.

Crear claves de API mediante la API

Mediante la API

Crea una clave de API con el endpoint de claves de API:

POST /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN

Cuerpo de la petición:

{
  "name": "Production API Key",
  "webhookUrl": "https://api.example.com/webhooks/orcarail",
  "commissionPercent": 4
}

La clave creada pertenece a la organización identificada por :organizationId. El token bearer debe pertenecer a un usuario o sesión autorizado para gestionar exactamente esa organización; el parámetro de ruta es obligatorio y debe coincidir con la organización que quieres gestionar.

commissionPercent (opcional): número de 0 a 100. Si se define, este porcentaje se aplica a los pagos creados con esta clave; el importe se muestra al pagador y se envía a tu dirección de retiro.

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"
  },
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

:::warning Importante El secret solo se muestra una vez, al crear la clave de API. ¡Guárdalo de inmediato! Si lo pierdes, tendrás que crear una clave de API nueva. :::

Ejemplo: crear una clave de API

const response = await fetch(
  'https://api.orcarail.com/api/v1/organizations/org_123/api-keys',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Production API Key',
    }),
  }
)

const { apiKey, key, secret } = await response.json()

// IMPORTANT: Save the secret securely!
console.log('API Key:', key)
console.log('API Secret:', secret) // Only shown once!

Usar las claves de API

Autenticación básica

Las claves de API usan HTTP Basic Authentication. El formato es:

Authorization: Basic base64(key:secret)

Ejemplo con cURL

curl https://api.orcarail.com/api/v1/payment_intents \
  -u ak_live_abc123def456:sk_live_xyz789uvw012 \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "usd",
    "payment_method_types": ["crypto"],
    "tokenId": 1,
    "networkId": 1,
    "return_url": "https://merchant.example.com/return"
  }'

Ejemplo con JavaScript

const key = 'ak_live_abc123def456'
const secret = 'sk_live_xyz789uvw012'

// Create base64 encoded credentials
const credentials = btoa(`${key}:${secret}`)

const response = await fetch(
  'https://api.orcarail.com/api/v1/payment_intents',
  {
    method: 'POST',
    headers: {
      Authorization: `Basic ${credentials}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '100.00',
      currency: 'usd',
      payment_method_types: ['crypto'],
      tokenId: 1,
      networkId: 1,
      return_url: 'https://merchant.example.com/return',
    }),
  }
)

Ejemplo con Node.js

const https = require('https')

const key = 'ak_live_abc123def456'
const secret = 'sk_live_xyz789uvw012'
const credentials = Buffer.from(`${key}:${secret}`).toString('base64')

const options = {
  hostname: 'api.orcarail.com',
  path: '/api/v1/payment_intents',
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
}

const req = https.request(options, (res) => {
  // Handle response
})

req.write(
  JSON.stringify({
    amount: '100.00',
    currency: 'usd',
    payment_method_types: ['crypto'],
    tokenId: 1,
    networkId: 1,
    return_url: 'https://merchant.example.com/return',
  })
)

req.end()

Ejemplo con Python

import requests
import base64

key = 'ak_live_abc123def456'
secret = 'sk_live_xyz789uvw012'

# Create base64 encoded credentials
credentials = base64.b64encode(f'{key}:{secret}'.encode()).decode()

response = requests.post(
    'https://api.orcarail.com/api/v1/payment_intents',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': '100.00',
        'currency': 'usd',
        'payment_method_types': ['crypto'],
        'tokenId': 1,
        'networkId': 1,
        'return_url': 'https://merchant.example.com/return',
    },
)

Gestionar claves de API

Puedes listar, actualizar y revocar claves de API desde Panel → Claves de API, o usar la API como se indica a continuación.

Listar tus claves de API

GET /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN

Respuesta:

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

Actualizar una clave de API

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

PATCH /api/v1/api-keys/:id
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Cuerpo de la petición:

{
  "name": "Updated API Key Name",
  "webhookUrl": "https://api.example.com/webhooks/orcarail"
}

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"
}

Para quitar una URL de webhook, ponla a null:

{
  "webhookUrl": null
}

Revocar una clave de API

POST /api/v1/api-keys/:id/revoke
Authorization: Bearer YOUR_JWT_TOKEN

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"
}

Buenas prácticas de seguridad

1. Mantén los secretos a salvo

Nunca subas claves de API al control de versiones
Guarda los secretos en variables de entorno o en sistemas de gestión de secretos
Usa claves distintas para cada entorno (desarrollo, staging, producción)

2. Rota las claves con regularidad

Crea claves de API nuevas periódicamente
Revoca las claves antiguas después de crear las nuevas
Actualiza tus aplicaciones para que usen las claves nuevas

3. Usa nombres descriptivos

Pon nombres descriptivos a tus claves de API para seguir su uso:

{
  "name": "Production - Payment Service"
}

4. Limita el alcance de las claves

Crea claves de API separadas para distintos servicios o entornos:

Production - Web Server
Production - Background Jobs
Staging - Testing
Development - Local

5. Supervisa el uso de las claves

Revisa periódicamente tus claves de API y revoca las que ya no necesites.

Probar claves de API

Puedes comprobar si tu clave de API es válida:

POST /api/v1/api-keys/test

Cuerpo de la petición:

{
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

Respuesta:

{
  "ok": true
}

Respuestas de error

Credenciales no válidas

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

Falta la cabecera Authorization

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

Configuración de webhooks

Las claves de API pueden tener una webhookUrl opcional que recibe los eventos de pago. Cuando ocurre un evento de pago, OrcaRail envía un webhook a la URL configurada.

Consulta Configuración de webhooks para ver instrucciones detalladas.

Próximos pasos

Configuración de webhooks: configura webhooks para tus claves de API
Tokens Bearer: aprende sobre la autenticación JWT
Primeros pasos: crea tu primer pago

Visión general​

Claves live y sandbox​

Crear claves de API en el panel​

Comisión (reparte y obtén tu parte)​

Crear claves de API mediante la API​

Mediante la API​

Ejemplo: crear una clave de API​

Usar las claves de API​

Autenticación básica​

Ejemplo con cURL​

Ejemplo con JavaScript​

Ejemplo con Node.js​

Ejemplo con Python​

Gestionar claves de API​

Listar tus claves de API​

Actualizar una clave de API​

Revocar una clave de API​

Buenas prácticas de seguridad​

1. Mantén los secretos a salvo​

2. Rota las claves con regularidad​

3. Usa nombres descriptivos​

4. Limita el alcance de las claves​

5. Supervisa el uso de las claves​

Probar claves de API​

Respuestas de error​

Credenciales no válidas​

Falta la cabecera Authorization​

Configuración de webhooks​

Próximos pasos​

Visión general

Claves live y sandbox

Crear claves de API en el panel

Comisión (reparte y obtén tu parte)

Crear claves de API mediante la API

Mediante la API

Ejemplo: crear una clave de API

Usar las claves de API

Autenticación básica

Ejemplo con cURL

Ejemplo con JavaScript

Ejemplo con Node.js

Ejemplo con Python

Gestionar claves de API

Listar tus claves de API

Actualizar una clave de API

Revocar una clave de API

Buenas prácticas de seguridad

1. Mantén los secretos a salvo

2. Rota las claves con regularidad

3. Usa nombres descriptivos

4. Limita el alcance de las claves

5. Supervisa el uso de las claves

Probar claves de API

Respuestas de error

Credenciales no válidas

Falta la cabecera Authorization

Configuración de webhooks

Próximos pasos