API de ColoringBookify

Inicio rápido

Exporta tu clave API a una variable de entorno y verifícala con el endpoint de la cuenta.

URL base

export COLORINGBOOKIFY_API_KEY="cbf_your_api_key"

curl --fail-with-body \
  --header "Authorization: Bearer $COLORINGBOOKIFY_API_KEY" \
  https://coloringbookify.com/api/v1/me

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $COLORINGBOOKIFY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: page-$(uuidgen)" \
  --data '{"page":{"title":"A fox exploring a mushroom village"}}' \
  https://coloringbookify.com/api/v1/pages

Autenticación

Crea una clave para la cuenta desde la sección API y envíala en el encabezado Authorization como token Bearer. Las cookies de sesión del navegador no autentican solicitudes a la API.

Créditos y encabezados de respuesta

Cada respuesta autenticada indica el saldo después de la solicitud y los créditos realmente consumidos por esa llamada HTTP. La tabla de endpoints y el campo x-credit-cost de OpenAPI declaran los costes antes de usarla.

X-ColoringBookify-Credits-Available: 247
X-ColoringBookify-Credits-Consumed: 1

Una repetición idempotente indica cero consumidos porque no vuelve a cobrar, mientras que la operación conserva el importe cobrado originalmente.

De la idea al libro imprimible

Los planes permanecen en el cliente. Esto evita borradores obsoletos en el servidor y mantiene al usuario al mando antes de gastar créditos.

1. Crea un plan sin persistencia con POST /book_plans y muestra las escenas y la estimación exacta de créditos.
2. Permite revisar o editar generation_request y envíala a POST /books con una nueva clave de idempotencia.
3. Consulta la operación hasta que termine. Importa o reemplaza arte corregido externamente cuando sea necesario.
4. Consulta GET /print_formats y descarga el libro completo desde GET /books/{id}/pdf.

Generación, reintentos y operaciones

Envía un encabezado Idempotency-Key único con cada solicitud de generación. Reintentar el mismo método, ruta y contenido con la misma clave devuelve la respuesta original sin generar ni cobrar de nuevo; reutilizarla para otra solicitud devuelve 409.

La generación devuelve 202 con un recurso y una operación. Consulta la URL de la operación hasta que su estado sea succeeded, partially_succeeded o failed. Las respuestas no terminales incluyen Retry-After.

Proporciones y tamaños PDF

Consulta GET /api/v1/print_formats en vez de codificar los tamaños. El formato PDF debe coincidir con la proporción del libro; las imágenes importadas se normalizan sin recorte cuando solo necesitan un pequeño ajuste.

Endpoints

Consulta, crea, actualiza, genera, organiza y elimina recursos de la cuenta autenticada.

Paginación

Los endpoints de lista aceptan limit de 1 a 100, con 25 por defecto, y un cursor after opaco devuelto como meta.next_cursor. Trata los IDs de recursos y los cursores como cadenas opacas.

curl --get https://coloringbookify.com/api/v1/pages \
  --header "Authorization: Bearer $COLORINGBOOKIFY_API_KEY" \
  --data-urlencode "limit=25" \
  --data-urlencode "after=next_cursor_value"

Respuestas y errores

Los errores JSON usan una estructura estable con un código legible por máquina, un mensaje seguro y el ID de la solicitud. Las respuestas incluyen la versión de la API y nunca se almacenan en caché públicamente.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "request-id"
  }
}

400

Paginación o parámetros de solicitud no válidos.

401

Falta el token Bearer o no es válido.

402

La cuenta no tiene suficientes créditos para la generación.

403

La cuenta no tiene actualmente un plan Business activo.

404

El recurso no existe o no pertenece a la cuenta.

409

La clave de idempotencia entra en conflicto con otra solicitud o ya hay una generación activa.

422

La solicitud no supera la validación o se alcanzó un límite de la cuenta.

429

Se hicieron demasiadas solicitudes de planificación en poco tiempo.

503

La planificación de libros no está disponible temporalmente.

Seguridad y alcance actual

• Todas las respuestas de la API usan Cache-Control private, no-store.
• Las descargas de imágenes vuelven a comprobar la propiedad en cada solicitud.
• Nunca se exponen imágenes fuente ni URLs permanentes de almacenamiento.
• Los errores omiten detalles de excepciones del proveedor y URLs internas.

Los endpoints de generación requieren claves de idempotencia, registran transacciones de créditos inmutables y solo muestran errores de operación seguros.