Autenticación

Cada llamada a la API lleva una llave de API de tu organización, como token Bearer en la cabecera Authorization:

Authorization: Bearer $RFC_API_KEY

Una llave pertenece a una organización y solo llega a esa organización, dentro de los permisos con los que se creó.

Crea una llave

La persona dueña de la organización, o una persona a quien ella se lo permita, crea las llaves en la aplicación, en Ajustes › API y conexiones › Llaves de API. Una llave tiene:

Un nombre, que dice qué la usa, como Reportes de ventas.
Lo que puede hacer: Solo lectura (puede ver todo y no puede cambiar nada), Acceso completo (puede ver y cambiar todo lo que una llave puede) o Personalizado (tú eliges qué puede hacer en cada área). En cualquier caso, una llave nunca tiene más que la persona que la crea.
Cuándo vence: como máximo días después de crearla.

La llave se muestra una sola vez, al crearla: cópiala en ese momento. Las llaves de producción empiezan por rfc_key_. La aplicación guarda solo una huella de la llave, nunca la llave misma, y su lista muestra cada llave por su comienzo y sus últimos cuatro caracteres. Una organización tiene como máximo llaves vigentes, ni anuladas ni vencidas. Da a cada programa su propia llave, para poder reemplazar o anular una sin detener las demás.

Trata una llave como una contraseña. Mantenla fuera de tu código, de tu repositorio y de todo lo que corre en un navegador o en el dispositivo de un cliente: léela de una variable de entorno o de un almacén de secretos, como hace cada ejemplo de este sitio con RFC_API_KEY. Si una llave se filtra, anúlala de inmediato en Llaves de API.

Comprueba una llave

Obtener la credencial que llama responde quién es la llave: su organización, su nombre, su vencimiento, sus permisos, sus límites y las llamadas que aún puede hacer. No cuenta para ningún límite, así que es la llamada que conviene hacer primero, y cada vez que un programa arranca.

curl https://app.readyforcommerce.com/api/v1/credential \
  --header "Authorization: Bearer $RFC_API_KEY"

import os

import requests

response = requests.get(
    "https://app.readyforcommerce.com/api/v1/credential",
    headers={"Authorization": f"Bearer {os.environ['RFC_API_KEY']}"},
)
print(response.json())

<?php
$curl = curl_init('https://app.readyforcommerce.com/api/v1/credential');
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('RFC_API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($curl);

const response = await fetch('https://app.readyforcommerce.com/api/v1/credential', {
  headers: { Authorization: `Bearer ${process.env.RFC_API_KEY}` },
});
console.log(await response.json());

El org.id de la respuesta es el orgId de todas las demás rutas: /api/v1/orgs/{orgId}/….

Lo que puede hacer una llave

Solo su propia organización. Una ruta con el id de otra organización responde como si la llave no existiera.
Los permisos con los que se creó, y nada más. Un permiso que la aplicación agrega después, como el de una función nueva o el de un módulo que la organización activa más tarde, nunca se suma a una llave existente, ni siquiera a una de Acceso completo. Crea una llave nueva para usarlo.
Nunca lo que solo hace una persona. Eliminar o transferir la organización, sus personas y roles, sus módulos, su tarjeta y sus pagos, y sus llaves de API y conexiones de IA se quedan en la aplicación. Una llave que llama a una de esas acciones recibe 403 core.human_only.

Cuando se rechaza una llamada

Respuesta	Código	Qué significa	Qué hacer
`401`	`core.invalid_credential`	La llave es desconocida, está anulada o vencida, o es de otra organización. Las cuatro responden igual, así que la respuesta no dice nada de otras llaves.	Comprueba que el programa envía la llave correcta y que sigue vigente en Llaves de API.
`403`	`core.forbidden`	A la llave le falta el permiso que la llamada necesita; `params.permission` lo nombra.	Crea una llave que lo tenga: los permisos de una llave existente nunca crecen.

Repetir cualquiera de las dos llamadas sin cambios responde lo mismo: corrige primero la llave. La forma de cada error está en Errores.

Vencimiento y rotación

Una llave deja de funcionar al vencer. La persona dueña de la organización recibe un aviso días antes, por correo y en la aplicación. Para reemplazar una llave sin detener tu programa:

Crea la llave nueva

En Ajustes › API y conexiones › Llaves de API, con los permisos que tu programa necesita.

Ponla en uso

Pon la llave nueva donde tu programa la lee, y compruébala con Obtener la credencial que llama.

Anula la llave anterior

Anúlala en la misma lista. Una llave anulada se rechaza desde su siguiente llamada.

Primeros pasos

Uso de la API

Asistentes de IA

Crea una llave

Comprueba una llave

Lo que puede hacer una llave

Cuando se rechaza una llamada

Vencimiento y rotación