Desarrolladores

API REST y webhooks de ChurchBright

Conecte su sitio web, tarjetas de conexión, sistema contable o almacén de datos a la cuenta de su iglesia. JSON simple sobre HTTPS, claves con permisos detallados y webhooks firmados en tiempo real.

Obtener una clave de APIIr a los endpoints

Inicio rápido

  1. En la cuenta de su iglesia, abra Configuración → API y webhooks y cree una clave. Cópiela — solo se muestra una vez.
  2. Llame a la API desde su servidor con la clave en el encabezado Authorization.
  3. Agregue un webhook para recibir avisos de los cambios en cuanto ocurren, en lugar de consultar periódicamente.

URL base: https://churchbright.com/api/v1

export CHURCHBRIGHT_API_KEY=cb_live_your_key_here

curl "https://churchbright.com/api/v1/people?per_page=5&status=first_timer" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

Autenticación

Cada solicitud necesita una clave de API. Las claves tienen el formato cb_live_ seguido de 32 letras y dígitos. Envíela como token bearer:

Authorization: Bearer cb_live_…

Cada clave tiene permisos por recurso — por ejemplo people:read, people:write, contributions:read o messages:write — y puede limitarse a una filial y las filiales que dependen de ella. Una clave limitada a una filial solo ve y crea registros en esas filiales.

Si su herramienta no puede enviar encabezados, puede pasar ?api_key=… en su lugar, pero los encabezados son más seguros porque las URL terminan en los registros. Las claves deben estar solo en servidores: nunca en JavaScript del navegador, aplicaciones móviles ni repositorios públicos. Revoque una clave en cuanto crea que se ha filtrado.

Solicitudes y respuestas

  • Envíe JSON con Content-Type: application/json (también funcionan los cuerpos codificados como formulario).
  • Cada respuesta es JSON con "ok". Las respuestas exitosas incluyen "data" (y "meta" en las listas).
  • Las marcas de tiempo están en UTC con formato ISO 8601 (2026-09-28T09:14:03Z). Las fechas de calendario como given_on o dob están en formato YYYY-MM-DD en la zona horaria de la propia iglesia.
  • Los montos son enteros en unidades menores: 150050 significa 1,500.50 en la moneda indicada. amount_base siempre está en la moneda de la iglesia.
  • Envíe un encabezado Idempotency-Key (cualquier cadena única de hasta 120 caracteres) en las solicitudes POST. Al reintentar con la misma clave se devuelve la primera respuesta en lugar de crear un duplicado — importante para las ofrendas.
{
    "ok": true,
    "data": {
        "id": 42,
        "first_name": "Ngozi",
        "…": "…"
    },
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 214,
        "total_pages": 9,
        "has_more": true
    }
}

Paginación y filtros

Las listas devuelven 25 registros por página de forma predeterminada. Use ?page= y ?per_page= (hasta 100). meta le indica el total y si hay otra página.

Para mantener otro sistema sincronizado, recuerde cuándo sincronizó por última vez y pida solo lo que cambió desde entonces con ?updated_since=2026-09-01T00:00:00Z. Para personas, agregue include_deleted=1 para enterarse también de las eliminaciones.

curl "https://churchbright.com/api/v1/people?updated_since=2026-09-01T00:00:00Z&include_deleted=1&per_page=100&page=2" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

Errores

Los errores usan los códigos de estado HTTP habituales y un cuerpo con "ok": false, un "error" legible por máquina y un "message" legible por personas. Los errores de validación agregan "errors" con un mensaje por campo.

EstadoerrorSignificado
400invalid_json, invalid_updated_since, invalid_status…La solicitud tiene un formato incorrecto — revise el mensaje.
401unauthorized, invalid_api_keyNo hay clave, o la clave es incorrecta o fue revocada.
403insufficient_scope, api_disabled, church_inactive, plan_limit_reachedLa clave es válida, pero no tiene permiso para hacer esto.
404not_found, unknown_resourceEl registro no existe o está fuera de la filial de la clave.
405method_not_allowedEse método HTTP no es compatible con esta URL.
409duplicate_reference, idempotency_key_reusedEntra en conflicto con una solicitud anterior.
422validation_failed, send_failed, recipient_skippedLos datos no son válidos; "errors" enumera cada campo.
429rate_limitedDemasiadas solicitudes — espere los segundos indicados en Retry-After.
500resource_errorAlgo salió mal de nuestro lado. Vuelva a intentarlo más tarde.
 
{
    "ok": false,
    "error": "validation_failed",
    "message": "Algunos campos no son válidos.",
    "errors": {
        "email": "Ingrese un correo electrónico válido."
    }
}

Límites de solicitudes

Cada clave puede hacer 120 solicitudes por minuto (y cada dirección IP, 600). Por encima de ese límite recibirá HTTP 429 con un encabezado Retry-After. Use updated_since y webhooks en lugar de consultar periódicamente (polling).

Endpoints

Su clave

GET /api/v1

Verifique su clave · requiere cualquier clave válida

Devuelve la iglesia, los permisos de la clave y cada recurso al que puede acceder. Úselo para probar su configuración.

curl "https://churchbright.com/api/v1" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Respuesta de ejemplo
{
    "ok": true,
    "data": {
        "church": {
            "id": 1,
            "name": "Grace Assembly",
            "slug": "grace",
            "country": "NG",
            "currency": "NGN",
            "timezone": "Africa/Lagos"
        },
        "key": {
            "id": 3,
            "name": "Website forms",
            "prefix": "cb_live_Ab3d",
            "scopes": [
                "people:read",
                "people:write"
            ],
            "branch_id": null,
            "created_at": "2026-09-01T10:00:00Z"
        },
        "resources": [
            {
                "name": "people",
                "url": "https://churchbright.com/api/v1/people",
                "allowed": [
                    "read",
                    "write"
                ],
                "module": "core"
            }
        ]
    }
}
Personas

GET /api/v1/people

Listar personas · requiere people:read

Miembros, visitantes y nuevos visitantes, del más antiguo al más reciente. Las personas eliminadas se excluyen salvo que se indique include_deleted=1.

Parámetro de consultaDescripción
statusUn estado o una lista separada por comas: first_timer, visitor, new_convert, regular, member, worker, leader, inactive, transferred, deceased
branch_idSolo esta filial y sus subfiliales
family_idSolo esta familia
qBuscar nombre, correo electrónico o número de miembro
emailCoincidencia exacta de correo electrónico
phoneCoincidencia exacta de teléfono (cualquier formato)
updated_sinceModificado en esta hora o después (ISO 8601)
created_sinceAgregado en este momento o después
include_deleted1 para incluir a las personas eliminadas (con deleted_at definido) — útil para sincronizar
sortid, -id, updated_at, -updated_at, last_name
curl "https://churchbright.com/api/v1/people" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Respuesta de ejemplo
{
    "ok": true,
    "data": [
        {
            "id": 42,
            "member_no": "GA-00042",
            "title": "Mrs",
            "first_name": "Ngozi",
            "middle_name": null,
            "last_name": "Okafor",
            "full_name": "Ngozi Okafor",
            "gender": "female",
            "dob": "1988-04-12",
            "marital_status": "married",
            "anniversary": "2012-11-24",
            "email": "ngozi@example.com",
            "phone": "+2348031234567",
            "phone2": null,
            "whatsapp": null,
            "address": "4 Admiralty Way",
            "city": "Lekki",
            "state": "Lagos",
            "country": "NG",
            "postal_code": null,
            "occupation": "Pharmacist",
            "employer": null,
            "status": "member",
            "branch_id": 1,
            "family_id": 7,
            "family_role": "spouse",
            "membership_date": "2019-03-03",
            "baptism_date": null,
            "salvation_date": null,
            "first_visit_date": "2018-11-11",
            "source": "invited",
            "sms_opt_in": true,
            "email_opt_in": true,
            "whatsapp_opt_in": true,
            "photo_url": null,
            "custom": {},
            "created_at": "2026-01-14T09:21:00Z",
            "updated_at": "2026-09-02T17:45:10Z",
            "deleted_at": null
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 214,
        "total_pages": 9,
        "has_more": true
    }
}

GET /api/v1/people/{id}

Obtener una persona · requiere people:read

curl "https://churchbright.com/api/v1/people/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Respuesta de ejemplo
{
    "ok": true,
    "data": {
        "id": 42,
        "member_no": "GA-00042",
        "title": "Mrs",
        "first_name": "Ngozi",
        "middle_name": null,
        "last_name": "Okafor",
        "full_name": "Ngozi Okafor",
        "gender": "female",
        "dob": "1988-04-12",
        "marital_status": "married",
        "anniversary": "2012-11-24",
        "email": "ngozi@example.com",
        "phone": "+2348031234567",
        "phone2": null,
        "whatsapp": null,
        "address": "4 Admiralty Way",
        "city": "Lekki",
        "state": "Lagos",
        "country": "NG",
        "postal_code": null,
        "occupation": "Pharmacist",
        "employer": null,
        "status": "member",
        "branch_id": 1,
        "family_id": 7,
        "family_role": "spouse",
        "membership_date": "2019-03-03",
        "baptism_date": null,
        "salvation_date": null,
        "first_visit_date": "2018-11-11",
        "source": "invited",
        "sms_opt_in": true,
        "email_opt_in": true,
        "whatsapp_opt_in": true,
        "photo_url": null,
        "custom": {},
        "created_at": "2026-01-14T09:21:00Z",
        "updated_at": "2026-09-02T17:45:10Z",
        "deleted_at": null
    }
}

POST /api/v1/people

Crear una persona · requiere people:write

first_name es obligatorio. Las fechas usan el formato YYYY-MM-DD; los números de teléfono se convierten a formato internacional según el país de la iglesia. Envíe "dedupe": true para recibir la persona existente (HTTP 200, meta.duplicate = true) cuando el correo electrónico o el teléfono ya estén registrados.

curl -X POST "https://churchbright.com/api/v1/people" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Ngozi","last_name":"Okafor","email":"ngozi@example.com","phone":"0803 123 4567","status":"first_timer","source":"online","dedupe":true}'
Respuesta de ejemplo
{
    "ok": true,
    "data": {
        "id": 42,
        "member_no": "GA-00042",
        "title": "Mrs",
        "first_name": "Ngozi",
        "middle_name": null,
        "last_name": "Okafor",
        "full_name": "Ngozi Okafor",
        "gender": "female",
        "dob": "1988-04-12",
        "marital_status": "married",
        "anniversary": "2012-11-24",
        "email": "ngozi@example.com",
        "phone": "+2348031234567",
        "phone2": null,
        "whatsapp": null,
        "address": "4 Admiralty Way",
        "city": "Lekki",
        "state": "Lagos",
        "country": "NG",
        "postal_code": null,
        "occupation": "Pharmacist",
        "employer": null,
        "status": "member",
        "branch_id": 1,
        "family_id": 7,
        "family_role": "spouse",
        "membership_date": "2019-03-03",
        "baptism_date": null,
        "salvation_date": null,
        "first_visit_date": "2018-11-11",
        "source": "invited",
        "sms_opt_in": true,
        "email_opt_in": true,
        "whatsapp_opt_in": true,
        "photo_url": null,
        "custom": {},
        "created_at": "2026-01-14T09:21:00Z",
        "updated_at": "2026-09-02T17:45:10Z",
        "deleted_at": null
    }
}

PATCH /api/v1/people/{id}

Actualizar una persona · requiere people:write

Envíe solo los campos que desea cambiar. PUT y POST a la misma URL también funcionan. Los campos personalizados se combinan.

curl -X PATCH "https://churchbright.com/api/v1/people/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"member","membership_date":"2026-09-28","custom":{"department":"Choir"}}'
Respuesta de ejemplo
{
    "ok": true,
    "data": {
        "id": 42,
        "member_no": "GA-00042",
        "title": "Mrs",
        "first_name": "Ngozi",
        "middle_name": null,
        "last_name": "Okafor",
        "full_name": "Ngozi Okafor",
        "gender": "female",
        "dob": "1988-04-12",
        "marital_status": "married",
        "anniversary": "2012-11-24",
        "email": "ngozi@example.com",
        "phone": "+2348031234567",
        "phone2": null,
        "whatsapp": null,
        "address": "4 Admiralty Way",
        "city": "Lekki",
        "state": "Lagos",
        "country": "NG",
        "postal_code": null,
        "occupation": "Pharmacist",
        "employer": null,
        "status": "member",
        "branch_id": 1,
        "family_id": 7,
        "family_role": "spouse",
        "membership_date": "2019-03-03",
        "baptism_date": null,
        "salvation_date": null,
        "first_visit_date": "2018-11-11",
        "source": "invited",
        "sms_opt_in": true,
        "email_opt_in": true,
        "whatsapp_opt_in": true,
        "photo_url": null,
        "custom": {},
        "created_at": "2026-01-14T09:21:00Z",
        "updated_at": "2026-09-02T17:45:10Z",
        "deleted_at": null
    }
}
Familias

GET /api/v1/families

Listar familias · requiere families:read

Parámetro de consultaDescripción
qBuscar por nombre
branch_idSolo esta filial
updated_sinceModificado desde
curl "https://churchbright.com/api/v1/families" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Respuesta de ejemplo
{
    "ok": true,
    "data": [
        {
            "id": 7,
            "name": "The Okafor family",
            "address": "4 Admiralty Way, Lekki",
            "phone": null,
            "branch_id": 1,
            "member_count": 4,
            "created_at": "2026-01-14T09:20:00Z",
            "updated_at": null
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 88,
        "total_pages": 4,
        "has_more": true
    }
}

GET /api/v1/families/{id}

Obtener una familia con sus miembros · requiere families:read

curl "https://churchbright.com/api/v1/families/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Respuesta de ejemplo
{
    "ok": true,
    "data": {
        "id": 7,
        "name": "The Okafor family",
        "address": "4 Admiralty Way, Lekki",
        "phone": null,
        "branch_id": 1,
        "member_count": 2,
        "created_at": "2026-01-14T09:20:00Z",
        "updated_at": null,
        "members": [
            {
                "id": 41,
                "first_name": "Chinedu",
                "last_name": "Okafor",
                "family_role": "head",
                "status": "worker"
            },
            {
                "id": 42,
                "first_name": "Ngozi",
                "last_name": "Okafor",
                "family_role": "spouse",
                "status": "member"
            }
        ]
    }
}

POST /api/v1/families

Crear una familia · requiere families:write

curl -X POST "https://churchbright.com/api/v1/families" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"The Mensah family","address":"12 Allen Avenue, Ikeja","branch_id":2}'
Respuesta de ejemplo
{
    "ok": true,
    "data": {
        "id": 89,
        "name": "The Mensah family",
        "address": "12 Allen Avenue, Ikeja",
        "phone": null,
        "branch_id": 2,
        "member_count": 0,
        "members": [],
        "created_at": "2026-09-28T08:00:00Z",
        "updated_at": "2026-09-28T08:00:00Z"
    }
}
Filiales y fondos

GET /api/v1/branches

Listar filiales · requiere branches:read

El árbol completo: parent_id vincula una filial con la que está por encima.

curl "https://churchbright.com/api/v1/branches" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Respuesta de ejemplo
{
    "ok": true,
    "data": [
        {
            "id": 1,
            "parent_id": null,
            "depth": 0,
            "name": "Lekki (Headquarters)",
            "code": null,
            "is_hq": true,
            "level": "Headquarters",
            "pastor_name": null,
            "email": null,
            "phone": null,
            "address": null,
            "city": "Lagos",
            "state": null,
            "country": "NG",
            "currency": "NGN",
            "timezone": "Africa/Lagos",
            "status": "active",
            "created_at": "2026-01-01T00:00:00Z",
            "updated_at": null
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 4,
        "total_pages": 1,
        "has_more": false
    }
}

GET /api/v1/funds

Listar fondos · requiere funds:read

Parámetro de consultaDescripción
active1 = solo fondos activos, 0 = solo inactivos
curl "https://churchbright.com/api/v1/funds" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Respuesta de ejemplo
{
    "ok": true,
    "data": [
        {
            "id": 1,
            "name": "Tithe",
            "slug": "tithe",
            "description": null,
            "kind": "general",
            "target_amount": null,
            "currency": "NGN",
            "is_online": true,
            "is_default": true,
            "is_active": true,
            "created_at": "2026-01-01T00:00:00Z",
            "updated_at": null
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 8,
        "total_pages": 1,
        "has_more": false
    }
}
Contribuciones

GET /api/v1/contributions

Listar ofrendas · requiere contributions:read

Los montos son enteros en unidades menores (kobo, centavos). meta.sum_amount_base suma todas las ofrendas coincidentes en la moneda de la iglesia.

Parámetro de consultaDescripción
fromOfrendado a partir del (AAAA-MM-DD)
toOfrendado hasta el
fund_idUn fondo
person_idUn donante
methodcash, bank_transfer, pos, online, ach, cheque, ussd, mobile_money, text, in_kind, other
sourcemanual, online, import, api, …
statusposted (predeterminado), void o all
branch_idEsta filial y sus subfiliales
updated_sinceModificado desde
sortid, -id, given_on, -given_on
curl "https://churchbright.com/api/v1/contributions" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Respuesta de ejemplo
{
    "ok": true,
    "data": [
        {
            "id": 981,
            "person_id": 42,
            "fund_id": 1,
            "fund_name": "Tithe",
            "branch_id": 1,
            "amount": 5000000,
            "currency": "NGN",
            "amount_display": "₦50,000.00",
            "amount_base": 5000000,
            "method": "bank_transfer",
            "given_on": "2026-09-27",
            "reference": "TRF-88213",
            "note": null,
            "source": "api",
            "payment_id": null,
            "donor_name": null,
            "donor_email": null,
            "donor_phone": null,
            "is_anonymous": false,
            "status": "posted",
            "created_at": "2026-09-27T12:02:11Z",
            "updated_at": "2026-09-27T12:02:11Z"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 1203,
        "total_pages": 49,
        "has_more": true,
        "sum_amount_base": 1843250000,
        "base_currency": "NGN"
    }
}

GET /api/v1/contributions/{id}

Obtener una contribución · requiere contributions:read

curl "https://churchbright.com/api/v1/contributions/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Respuesta de ejemplo
{
    "ok": true,
    "data": {
        "id": 981,
        "person_id": 42,
        "fund_id": 1,
        "fund_name": "Tithe",
        "branch_id": 1,
        "amount": 5000000,
        "currency": "NGN",
        "amount_display": "₦50,000.00",
        "amount_base": 5000000,
        "method": "bank_transfer",
        "given_on": "2026-09-27",
        "reference": "TRF-88213",
        "note": null,
        "source": "api",
        "payment_id": null,
        "donor_name": null,
        "donor_email": null,
        "donor_phone": null,
        "is_anonymous": false,
        "status": "posted",
        "created_at": "2026-09-27T12:02:11Z",
        "updated_at": "2026-09-27T12:02:11Z"
    }
}

POST /api/v1/contributions

Registrar un aporte · requiere contributions:write

amount es obligatorio, en unidades menores. Si se omiten, fund_id toma el fondo predeterminado de la iglesia, given_on la fecha de hoy y method el valor online. Una referencia ya registrada a través de la API devuelve 409. Envíe un encabezado Idempotency-Key para que los reintentos nunca registren una ofrenda dos veces.

curl -X POST "https://churchbright.com/api/v1/contributions" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":5000000,"fund_id":1,"person_id":42,"method":"bank_transfer","given_on":"2026-09-27","reference":"TRF-88213"}'
Respuesta de ejemplo
{
    "ok": true,
    "data": {
        "id": 981,
        "person_id": 42,
        "fund_id": 1,
        "fund_name": "Tithe",
        "branch_id": 1,
        "amount": 5000000,
        "currency": "NGN",
        "amount_display": "₦50,000.00",
        "amount_base": 5000000,
        "method": "bank_transfer",
        "given_on": "2026-09-27",
        "reference": "TRF-88213",
        "note": null,
        "source": "api",
        "payment_id": null,
        "donor_name": null,
        "donor_email": null,
        "donor_phone": null,
        "is_anonymous": false,
        "status": "posted",
        "created_at": "2026-09-27T12:02:11Z",
        "updated_at": "2026-09-27T12:02:11Z"
    }
}
Mensajes

POST /api/v1/messages

Enviar un mensaje · requiere messages:write

channel es sms, email, whatsapp o push. Envíe a un person_id, a hasta 100 person_ids o a un número de teléfono/correo electrónico directo en "to". Las etiquetas de combinación como {first_name} funcionan. Se respetan las bajas y las unidades de SMS se cobran como de costumbre.

curl -X POST "https://churchbright.com/api/v1/messages" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"sms","person_id":42,"body":"Hi {first_name}, thank you for worshipping with us today!"}'
Respuesta de ejemplo
{
    "ok": true,
    "data": {
        "id": 5521,
        "person_id": 42,
        "status": "sent",
        "error": null,
        "channel": "sms"
    }
}

GET /api/v1/messages

Registro de mensajes · requiere messages:read

Parámetro de consultaDescripción
channelsms, email, whatsapp, voice, push
statussent, delivered, failed, skipped
person_idUna persona
sourceDe dónde vino, p. ej. api, followup
updated_sinceModificado desde
curl "https://churchbright.com/api/v1/messages" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Respuesta de ejemplo
{
    "ok": true,
    "data": [
        {
            "id": 5521,
            "channel": "sms",
            "person_id": 42,
            "to": "+2348031234567",
            "subject": null,
            "body": "Hi Ngozi, thank you for worshipping with us today!",
            "status": "delivered",
            "units": 1,
            "error": null,
            "source": "api",
            "sent_at": "2026-09-28T11:02:00Z",
            "delivered_at": "2026-09-28T11:02:09Z",
            "created_at": "2026-09-28T11:02:00Z"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 5521,
        "total_pages": 221,
        "has_more": true
    }
}
Más recursos
Estos recursos provienen de las funciones que su iglesia tiene activadas. Siguen las mismas reglas de autenticación, paginación y errores.

GET /api/v1/prayer_requests

Listar Peticiones de oración · requiere prayer_requests:read

Proporcionado por el módulo Cuidado y oración.

Parámetro de consultaDescripción
pageNúmero de página
per_pageHasta 100
updated_sinceModificado desde (si se admite)
curl "https://churchbright.com/api/v1/prayer_requests" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

GET /api/v1/prayer_requests/{id}

Obtener un registro de Peticiones de oración · requiere prayer_requests:read

curl "https://churchbright.com/api/v1/prayer_requests/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

POST /api/v1/prayer_requests

Crear Peticiones de oración · requiere prayer_requests:write

curl -X POST "https://churchbright.com/api/v1/prayer_requests" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[]'

GET /api/v1/gifts

Listar Ofrendas · requiere gifts:read

Proporcionado por el módulo Ofrendas.

Parámetro de consultaDescripción
pageNúmero de página
per_pageHasta 100
updated_sinceModificado desde (si se admite)
curl "https://churchbright.com/api/v1/gifts" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

GET /api/v1/gifts/{id}

Obtener un registro de Ofrendas · requiere gifts:read

curl "https://churchbright.com/api/v1/gifts/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

GET /api/v1/sermons

Listar Prédicas · requiere sermons:read

Proporcionado por el módulo Multimedia.

Parámetro de consultaDescripción
pageNúmero de página
per_pageHasta 100
updated_sinceModificado desde (si se admite)
curl "https://churchbright.com/api/v1/sermons" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

GET /api/v1/sermons/{id}

Obtener un registro de Prédicas · requiere sermons:read

curl "https://churchbright.com/api/v1/sermons/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

Webhooks

Agregue endpoints en Configuración → API y webhooks → Webhooks y elija los eventos que desea. Cuando ocurre uno, enviamos un POST HTTPS con un cuerpo JSON como este:

{
    "id": "evt_5b1c0f3e9a7d44c2b8e1a0f2",
    "event": "person.created",
    "created_at": "2026-09-28T09:14:03Z",
    "api_version": "v1",
    "church": {
        "id": 1,
        "slug": "grace",
        "name": "Grace Assembly"
    },
    "data": {
        "id": 42,
        "member_no": "GA-00042",
        "title": "Mrs",
        "first_name": "Ngozi",
        "middle_name": null,
        "last_name": "Okafor",
        "full_name": "Ngozi Okafor",
        "gender": "female",
        "dob": "1988-04-12",
        "marital_status": "married",
        "anniversary": "2012-11-24",
        "email": "ngozi@example.com",
        "phone": "+2348031234567",
        "phone2": null,
        "whatsapp": null,
        "address": "4 Admiralty Way",
        "city": "Lekki",
        "state": "Lagos",
        "country": "NG",
        "postal_code": null,
        "occupation": "Pharmacist",
        "employer": null,
        "status": "member",
        "branch_id": 1,
        "family_id": 7,
        "family_role": "spouse",
        "membership_date": "2019-03-03",
        "baptism_date": null,
        "salvation_date": null,
        "first_visit_date": "2018-11-11",
        "source": "invited",
        "sms_opt_in": true,
        "email_opt_in": true,
        "whatsapp_opt_in": true,
        "photo_url": null,
        "custom": {},
        "created_at": "2026-01-14T09:21:00Z",
        "updated_at": "2026-09-02T17:45:10Z",
        "deleted_at": null
    }
}

"data" tiene la misma estructura que el recurso REST correspondiente. Los eventos de actualización también incluyen "previous" con los valores anteriores al cambio. Cada solicitud lleva estos encabezados:

X-ChurchBright-EventEl nombre del evento, p. ej. person.created
X-ChurchBright-Event-IdÚnico por evento — guárdelo para ignorar duplicados, porque un reenvío lo reutiliza.
X-ChurchBright-DeliveryEl ID del intento de entrega que aparece en su registro de entregas.
X-ChurchBright-Signaturet=<unix time>,v1=<HMAC-SHA256 of "<t>.<raw body>" using your signing secret, hex>
  • Responda con cualquier estado 2xx en un plazo de 10 segundos. Haga el trabajo lento después de responder.
  • Cualquier otra respuesta se reintenta 4 veces más con intervalos crecientes (2, 4, 8 y 16 minutos). Puede reenviar cualquier evento desde el registro de entregas.
  • Los endpoints que fallan 20 entregas seguidas se pausan y se notifica a los administradores. Vuelva a activarlos una vez corregidos.
  • Use “Enviar evento de prueba” para recibir un evento ping mientras construye su endpoint.

Verificación de firmas

Calcule el HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo sin procesar de la solicitud con su clave secreta de firma (la cadena whsec_… completa), compárelo con v1 en tiempo constante y rechace las marcas de tiempo con más de cinco minutos de antigüedad.

PHPNode.js
<?php
// Verify a ChurchBright webhook (plain PHP, no libraries needed).
$secret  = getenv('CHURCHBRIGHT_WEBHOOK_SECRET');           // whsec_… from Settings → API & webhooks
$payload = file_get_contents('php://input');                  // the raw body, before json_decode
$header  = $_SERVER['HTTP_X_CHURCHBRIGHT_SIGNATURE'] ?? '';   // "t=1727517600,v1=5f2c…"

$parts = [];
foreach (explode(',', $header) as $item) {
    [$k, $v] = array_pad(explode('=', trim($item), 2), 2, '');
    $parts[$k] = $v;
}
$t = (int)($parts['t'] ?? 0);
$expected = hash_hmac('sha256', $t . '.' . $payload, $secret);

if (!$t || abs(time() - $t) > 300 || !hash_equals($expected, $parts['v1'] ?? '')) {
    http_response_code(400);
    exit('Invalid signature');
}

$event = json_decode($payload, true);
switch ($event['event']) {
    case 'person.created':
        // $event['data'] is the person, shaped like GET /api/v1/people/{id}
        break;
    case 'contribution.recorded':
        // $event['data']['amount'] is in minor units
        break;
}
http_response_code(200); // answer quickly; do slow work in the background
Catálogo de eventos
Eventos principales más los eventos de las funciones instaladas en esta plataforma. Suscríbase con nombres exactos o comodines como person.*
EventoDesdeCuándo se envía
pingPrincipalesSolo se envía cuando presiona “Enviar evento de prueba”.
ai.output_createdBright AIBright AI wrote something in the writing studio (title and template only).
api.key_createdAPI y webhooksAn API key was created (the key itself is never included).
api.key_revokedAPI y webhooksAn API key was revoked.
api.webhook_goneAPI y webhooksEmitido por esta función.
attendance.checkinAsistencia y registroEmitido por esta función.
attendance.children_picked_upAsistencia y registroEmitido por esta función.
attendance.pickup_flaggedAsistencia y registroEmitido por esta función.
attendance.recordedPrincipalesSe registró la asistencia de un culto o reunión.
automations.run_completedAutomatizacionesA person finished an automation journey (the run and the automation).
billing.downgrade_scheduledPlan y facturaciónEmitido por esta función.
billing.enterprise_enquiryPlan y facturaciónEmitido por esta función.
billing.extras_pausedPlan y facturaciónEmitido por esta función.
billing.extras_restoredPlan y facturaciónEmitido por esta función.
billing.plan_changedPlan y facturaciónEmitido por esta función.
billing.plan_expiredPlan y facturaciónEmitido por esta función.
billing.sms_purchasedPlan y facturaciónEmitido por esta función.
billing.subscription_activatedPlan y facturaciónEmitido por esta función.
care.pathway_completedCuidado y oraciónEmitido por esta función.
care.prayer_request_createdCuidado y oraciónEmitido por esta función.
compete.badge_awardedCompetenciasEmitido por esta función.
compete.quiz_completedCompetenciasEmitido por esta función.
contribution.recordedPrincipalesSe registró una ofrenda — en línea, manual, importada o mediante la API.
contribution.voidedPrincipalesSe anuló una ofrenda.
dashboard.setup_completedPanelEmitido por esta función.
dashboard.setup_step_donePanelEmitido por esta función.
events.checked_inEventosEmitido por esta función.
events.registeredEventosEmitido por esta función.
finance.expense_approvedFinanzasEmitido por esta función.
finance.remittance_paidFinanzasEmitido por esta función.
followup.guest_capturedNuevos visitantes y seguimientoEmitido por esta función.
followup.stage_changedNuevos visitantes y seguimientoEmitido por esta función.
followup.task_completedNuevos visitantes y seguimientoEmitido por esta función.
forms.submittedFormulariosEmitido por esta función.
giving.batch_depositedOfrendasEmitido por esta función.
giving.gift_receivedOfrendasEmitido por esta función.
giving.pledge_createdOfrendasEmitido por esta función.
giving.recurring_cancelledOfrendasEmitido por esta función.
giving.recurring_createdOfrendasEmitido por esta función.
groups.join_requestedGrupos y célulasEmitido por esta función.
groups.member_addedGrupos y célulasEmitido por esta función.
groups.members_bulk_addedGrupos y célulasEmitido por esta función.
groups.message_postedGrupos y célulasEmitido por esta función.
groups.report_submittedGrupos y célulasEmitido por esta función.
imports.completedImportacionesEmitido por esta función.
imports.undoneImportacionesEmitido por esta función.
integrations.feed_createdIntegracionesA Google Sheets feed was created.
integrations.feed_revokedIntegracionesA Google Sheets feed was revoked.
integrations.hook_subscribedIntegracionesA Zapier or Make trigger subscribed to an event.
integrations.hook_unsubscribedIntegracionesA Zapier or Make trigger unsubscribed.
media.live_endedMultimediaEmitido por esta función.
media.live_startedMultimediaEmitido por esta función.
media.sermon_deletedMultimediaEmitido por esta función.
media.sermon_publishedMultimediaEmitido por esta función.
media.studio_publishedMultimediaA sermon studio section (notes, questions or devotional) was published to the sermon page.
media.studio_unpublishedMultimediaA sermon studio section was taken off the sermon page.
member.app_installedApp para miembrosEmitido por esta función.
member.post_publishedApp para miembrosEmitido por esta función.
member.push_sentApp para miembrosEmitido por esta función.
member.registeredApp para miembrosEmitido por esta función.
member.testimony_approvedApp para miembrosEmitido por esta función.
member.testimony_submittedApp para miembrosEmitido por esta función.
message.sentPrincipalesSe envió un mensaje por SMS, correo electrónico, WhatsApp, voz o push.
messaging.campaign_sentMensajesEmitido por esta función.
messaging.inbox_receivedMensajesEmitido por esta función.
messaging.unsubscribedMensajesEmitido por esta función.
nativeapp.device_registeredApps nativasA phone registered for push notifications in the native app.
payment.failedPrincipalesFalló un pago en línea.
payment.succeededPrincipalesSe completó un pago en línea.
people.importedPersonasEmitido por esta función.
person.createdPrincipalesSe agregó una persona.
person.deletedPrincipalesSe eliminó una persona.
person.mergedPrincipalesSe fusionaron dos registros duplicados (se conserva "data" y se eliminó "previous").
person.mergingPersonasEmitido por esta función.
person.status_changedPrincipalesCambió el estado de una persona, p. ej., nuevo visitante → miembro.
person.tag_addedAutomatizacionesA tag was added to a person (the person and the tag).
person.tag_removedAutomatizacionesA tag was removed from a person (the person and the tag).
person.updatedPrincipalesCambiaron los datos de una persona ("previous" contiene los valores anteriores).
platform.announcement_publishedAdministrador de la plataformaEmitido por esta función.
platform.church_plan_changedAdministrador de la plataformaEmitido por esta función.
platform.church_status_changedAdministrador de la plataformaEmitido por esta función.
platform.sender_id_decidedAdministrador de la plataformaEmitido por esta función.
print.generatedCartas, etiquetas e insigniasEmitido por esta función.
reports.emailedInformesAn executive summary was emailed (scheduled or on demand).
school.attendance_closedEscuela DominicalA class closed a Sunday school session (the session and the class).
school.promotion_appliedEscuela DominicalPromotion Sunday was applied (the promotion and how many moved).
serve.assignment_acceptedServirEmitido por esta función.
site.lead_receivedSitio web comercialEmitido por esta función.
user.invitedPrincipalesSe invitó a un miembro del equipo.
ussd.pay_requestedUSSDEmitido por esta función.
ussd.session_endedUSSDEmitido por esta función.
website.message_receivedSitio webEmitido por esta función.
website.page_publishedSitio webEmitido por esta función.
website.template_appliedSitio webEmitido por esta función.
website.translation_createdSitio webEmitido por esta función.
x.yAPI y webhooksEmitido por esta función.

Versiones: esta es la versión 1. Agregamos campos y endpoints sin previo aviso, así que ignore los campos que no conozca; cualquier cambio que pueda romper una integración llegará como una nueva versión.