API para socios

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": "user@example.com"}'

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": "user@example.com"
}

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 help@firecrawl.com. ¿Tienes en mente una integración de mayor alcance? Escríbenos a partnerships@firecrawl.dev.

Uso de la API

Endpoints de búsqueda

Endpoints de scraping

Endpoints de interacción / sandbox del navegador

Endpoints de Research Index

Endpoints de developer index

Endpoints de mapeo

Endpoints de procesamiento

Endpoints de rastreo

Supervisar endpoints

Endpoints de agentes

Endpoints de comentarios

Endpoints de depuración con agentes

Endpoints de cuenta

Cargas útiles de webhook

API de socios

Descripción general

URL base

Autenticación

Requisitos de seguridad

Endpoints

Crear usuario

Comportamiento

Solicitud

Respuesta

Errores

Validar la clave de API

Notas importantes

Solicitud

Respuesta

Errores

Rotar la clave de API

Solicitud

Respuesta

Errores

Empieza a usarlo

​Descripción general

​URL base

​Autenticación

​Requisitos de seguridad

​Endpoints

​Crear usuario

​Comportamiento

​Solicitud

​Respuesta

​Errores

​Validar la clave de API

​Notas importantes

​Solicitud

​Respuesta

​Errores

​Rotar la clave de API

​Solicitud

​Respuesta

​Errores

​Empieza a usarlo

Descripción general

URL base

Autenticación

Requisitos de seguridad

Endpoints

Crear usuario

Comportamiento

Solicitud

Respuesta

Errores

Validar la clave de API

Notas importantes

Solicitud

Respuesta

Errores

Rotar la clave de API

Solicitud

Respuesta

Errores

Empieza a usarlo