API para socios

Referencia de la API para socios de Firecrawl que permite crear y gestionar claves de API para sus usuarios

​

Descripción general

La API de integración para socios de Firecrawl permite que tu plataforma cree y gestione claves de API de Firecrawl para tus usuarios directamente desde tu propio backend. Los usuarios empiezan a usar Firecrawl sin salir de tu plataforma.

Configura la Partner API por tu cuenta en el Dashboard de Firecrawl. Cualquier administrador o miembro de una organización puede crear una integración: asígnale un nombre, selecciona una configuración, acepta el acuerdo correspondiente y copia la clave de socio. La clave se muestra una sola vez. Más adelante puedes generar y revocar claves en Settings. No se requiere ninguna solicitud ni aprobación.

Hay dos configuraciones. Ambas aprovisionan cuentas de la misma manera mediante los endpoints que se indican a continuación; la diferencia está en quién paga el consumo del usuario:

• Partner API: cada cuenta aprovisionada mantiene su propio plan y facturación de Firecrawl. Los usuarios comienzan en el plan Free y hacen el upgrade directamente con Firecrawl.
• Gateway: las cuentas que crea tu integración quedan inscritas en Gateway, por lo que su consumo elegible se factura a tu organización una vez que se agotan los créditos propios del usuario. Las cuentas de Gateway son solo de API y no cuentan con acceso propio al Dashboard.

La configuración se selecciona al crear la integración. No es fácil cambiarla después, por lo que recomendamos revisar ambas opciones con detenimiento antes de aceptar el acuerdo. Consulta la página de la Partner API para obtener una visión general.

Algunas ofertas del socio incluyen créditos promocionales para los usuarios aprovisionados; en ese caso, Créditos de socio describe qué recibe el usuario.

​

URL base

https://integrations.firecrawl.dev

​

Autenticación

Todas las solicitudes a la API de integración para socios requieren una cabecera Authorization con tu clave de socio:

Authorization: Bearer <partner key>

Las claves de socio son distintas de las claves de API estándar de Firecrawl. Puedes crearlas y revocarlas en Settings > Partner API, en el Dashboard de Firecrawl.

​

Requisitos de seguridad

• Solo en el servidor: Las claves de socio solo deben usarse en código del lado del servidor. Nunca expongas una clave de socio en código de frontend, JavaScript del lado del cliente ni en aplicaciones móviles.
• Términos del servicio: Antes de llamar a POST /partner/v1/accounts, tu plataforma debe solicitar al usuario que acepte los Términos del servicio de Firecrawl.

---

​

Endpoints

​

Crear usuario

Aprovisiona una cuenta de Firecrawl para uno de tus usuarios, identificado por su correo electrónico, y devuelve su clave de API.

POST /partner/v1/accounts

​

Comportamiento

Con la configuración de Partner API:

• Si el usuario aún no tiene una cuenta de Firecrawl, se crean un nuevo usuario y un nuevo equipo.
• Si el usuario ya tiene una cuenta de Firecrawl pero ningún equipo asociado a tu integración, se crea un nuevo equipo asociado al socio.
• Si el usuario ya tiene una cuenta de Firecrawl y un equipo asociado a tu integración, se devuelve el equipo existente.

Con la configuración de Gateway:

• Cada cuenta se crea exclusivamente para tu integración. Una solicitud nunca se vincula a una cuenta de Firecrawl existente, ni siquiera cuando el correo electrónico coincide con una. El correo electrónico se almacena como dirección de contacto de la cuenta y no se usa para buscar cuentas.
• Las llamadas repetidas con el mismo correo electrónico devuelven la misma cuenta y su clave de API.

Si tu integración incluye créditos promocionales, se aplican una sola vez, al crearse la cuenta por primera vez.

​

Solicitud

cURL

curl -X POST "https://integrations.firecrawl.dev/partner/v1/accounts" \
  -H "Authorization: Bearer <partner key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]"}'

Cuerpo

Campo	Tipo	Obligatorio	Descripción
email	string	Sí	La dirección de correo electrónico del usuario. Con la configuración de Gateway se almacena como la dirección de contacto de la cuenta.

​

Respuesta

200 OK

{
  "apiKey": "fc-...",
  "alreadyExisted": false
}

Con la configuración de Gateway, la respuesta también incluye el estado de inscripción:

{
  "apiKey": "fc-...",
  "alreadyExisted": false,
  "gatewayStatus": "enrolled"
}

Campo	Tipo	Descripción
apiKey	string	La clave de API de Firecrawl para el equipo de este usuario asociado al socio
alreadyExisted	boolean	true si tu integración ya había aprovisionado una cuenta para este correo. No indica nada sobre si el correo existe en otro lugar de Firecrawl.
gatewayStatus	string	Solo para integraciones de pasarela. enrolled en la llamada que crea la cuenta, already_enrolled en llamadas repetidas para el mismo correo.

​

Errores

Estado	Descripción
400	Solicitud incorrecta: falta email o está mal formado
401	No autorizado: la clave de socio es incorrecta o no es válida
500	Error interno del servidor: Firecrawl supervisa estos errores

---

​

Validar la clave de API

Valida una clave de API de Firecrawl y devuelve el nombre del equipo asociado y la dirección de correo electrónico del usuario. La clave de API solo se considerará válida si se creó a través de esta integración de partner.

POST /partner/v1/api-keys/validate

​

Notas importantes

• Las claves de API de Firecrawl no tienen permisos ni fecha de vencimiento.
• Los usuarios pueden eliminar manualmente las claves de API en cualquier momento.
• Las claves de API eliminadas no se conservan como eliminadas de forma lógica. Firecrawl no puede distinguir entre una clave eliminada y una que nunca existió.

​

Solicitud

cURL

curl -X POST "https://integrations.firecrawl.dev/partner/v1/api-keys/validate" \
  -H "Authorization: Bearer <partner key>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "fc-..."}'

Cuerpo

Campo	Tipo	Obligatorio	Descripción
apiKey	string	Sí	La clave de API que se va a validar

​

Respuesta

200 OK

{
  "teamName": "Example Team",
  "email": "[e-mail]"
}

Campo	Tipo	Descripción
teamName	string	El nombre del equipo asociado a esta clave de API
email	string	El correo electrónico con el que se aprovisionó la cuenta. En las cuentas de Gateway, es la dirección de contacto que indicaste.

​

Errores

Estado	Descripción
400	Solicitud incorrecta: la clave de API está mal formada
401	No autorizado: la clave de socio es incorrecta o no es válida
404	No se puede identificar la clave de API: la clave no existe o no se creó mediante esta integración de socio
500	Error interno del servidor: Firecrawl supervisa estos errores

---

​

Rotar la clave de API

Elimina una clave de API de Firecrawl existente y crea una nueva para el mismo usuario y equipo.

POST /partner/v1/api-keys/rotate

​

Solicitud

cURL

curl -X POST "https://integrations.firecrawl.dev/partner/v1/api-keys/rotate" \
  -H "Authorization: Bearer <partner key>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "fc-..."}'

Cuerpo

Campo	Tipo	Obligatorio	Descripción
apiKey	string	Sí	La clave de API que se eliminará y reemplazará

​

Respuesta

200 OK

{
  "apiKey": "fc-..."
}

Campo	Tipo	Descripción
apiKey	string	La clave de API recién creada

​

Errores

Estado	Descripción
401	No autorizado: la clave de socio es incorrecta o no válida
404	No se puede identificar la clave de API: la clave no existe o no se creó a través de esta integración de partner
500	Error interno del servidor: Firecrawl supervisa estos errores

---

​

Empieza a usarlo

Crea tu integración en el Dashboard de Firecrawl: inicia sesión, selecciona Partner API o Gateway, acepta el acuerdo y copia tu clave de socio. La configuración no es fácil de cambiar después, así que confirma tu elección antes de aceptar el acuerdo. Después, llama a los endpoints anteriores desde tu servidor. ¿Tienes dudas sobre tu configuración? Escríbenos a [e-mail]. ¿Tienes en mente una integración de mayor alcance? Escríbenos a [e-mail].