Programadores

API REST e webhooks do ChurchBright

Conecte o seu site, cartões de contacto, programa de contabilidade ou armazém de dados à conta da sua igreja. JSON simples sobre HTTPS, chaves com permissões detalhadas e webhooks assinados em tempo real.

Obter uma chave de APIIr para os endpoints

Início rápido

  1. Na conta da sua igreja, abra Configurações → API e webhooks e crie uma chave. Copie-a — só é mostrada uma vez.
  2. Chame a API a partir do seu servidor com a chave no cabeçalho Authorization.
  3. Adicione um webhook para ser notificado das alterações no momento em que acontecem, em vez de fazer consultas periódicas.

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"

Autenticação

Cada pedido precisa de uma chave de API. As chaves têm o formato cb_live_ seguido de 32 letras e dígitos. Envie-a como bearer token:

Authorization: Bearer cb_live_…

Cada chave tem permissões por recurso — por exemplo people:read, people:write, contributions:read ou messages:write — e pode ser limitada a uma filial e às filiais abaixo dela. Uma chave limitada a uma filial só vê e cria registos nessas filiais.

Se a sua ferramenta não conseguir definir cabeçalhos, pode passar ?api_key=… em alternativa, mas os cabeçalhos são mais seguros porque os URLs acabam nos registos. As chaves devem ficar apenas em servidores: nunca em JavaScript no navegador, em aplicações móveis ou em repositórios públicos. Revogue uma chave assim que suspeitar de que foi divulgada.

Pedidos e respostas

  • Envie JSON com Content-Type: application/json (corpos codificados como formulário também funcionam).
  • Todas as respostas são JSON com "ok". As respostas bem-sucedidas têm "data" (e "meta" nas listas).
  • As marcas temporais estão em UTC no formato ISO 8601 (2026-09-28T09:14:03Z). As datas de calendário, como given_on ou dob, estão no formato YYYY-MM-DD no fuso horário da própria igreja.
  • Os valores são números inteiros em subunidades: 150050 significa 1,500.50 na moeda indicada. amount_base está sempre na moeda da igreja.
  • Envie um cabeçalho Idempotency-Key (qualquer cadeia única até 120 caracteres) nos pedidos POST. Repetir com a mesma chave devolve a primeira resposta em vez de criar um duplicado — importante para contribuições.
{
    "ok": true,
    "data": {
        "id": 42,
        "first_name": "Ngozi",
        "…": "…"
    },
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 214,
        "total_pages": 9,
        "has_more": true
    }
}

Paginação e filtros

As listas devolvem 25 registos por página por predefinição. Use ?page= e ?per_page= (até 100). meta indica o total e se existe outra página.

Para manter outro sistema sincronizado, guarde a data da última sincronização e peça apenas o que mudou desde então com ?updated_since=2026-09-01T00:00:00Z. Para pessoas, adicione include_deleted=1 para também saber das remoções.

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"

Erros

Os erros usam códigos de estado HTTP normais e um corpo com "ok": false, um "error" legível por máquina e uma "message" legível por humanos. Os erros de validação acrescentam "errors" com uma mensagem por campo.

EstadoerroSignificado
400invalid_json, invalid_updated_since, invalid_status…O pedido está mal formado — verifique a mensagem.
401unauthorized, invalid_api_keySem chave, ou a chave está errada ou foi revogada.
403insufficient_scope, api_disabled, church_inactive, plan_limit_reachedA chave é válida, mas não tem permissão para fazer isto.
404not_found, unknown_resourceO registo não existe ou está fora da filial da chave.
405method_not_allowedEsse método HTTP não é suportado neste URL.
409duplicate_reference, idempotency_key_reusedEntra em conflito com um pedido anterior.
422validation_failed, send_failed, recipient_skippedOs dados não são válidos; "errors" lista cada campo.
429rate_limitedDemasiados pedidos — aguarde os segundos indicados em Retry-After.
500resource_errorAlgo correu mal do nosso lado. Tente novamente mais tarde.
 
{
    "ok": false,
    "error": "validation_failed",
    "message": "Alguns campos não são válidos.",
    "errors": {
        "email": "Introduza um endereço de e-mail válido."
    }
}

Limites de pedidos

Cada chave pode fazer 120 pedidos por minuto (e cada endereço IP 600). Acima disso, recebe HTTP 429 com um cabeçalho Retry-After. Use updated_since e webhooks em vez de consultas periódicas (polling).

Endpoints

A sua chave

GET /api/v1

Verifique a sua chave · necessidades qualquer chave válida

Devolve a igreja, as permissões da chave e todos os recursos a que tem acesso. Use-o para testar a sua configuração.

curl "https://churchbright.com/api/v1" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Resposta de exemplo
{
    "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"
            }
        ]
    }
}
Pessoas

GET /api/v1/people

Listar pessoas · necessidades people:read

Membros, visitantes e novos visitantes, dos mais antigos para os mais recentes. As pessoas eliminadas são excluídas, a menos que include_deleted=1.

Parâmetro de consultaDescrição
statusUm estado ou uma lista separada por vírgulas: first_timer, visitor, new_convert, regular, member, worker, leader, inactive, transferred, deceased
branch_idApenas esta filial e as suas subfiliais
family_idApenas esta família
qPesquisar nome, e-mail ou número de membro
emailCorrespondência exata de e-mail
phoneCorrespondência exata de telefone (qualquer formato)
updated_sinceAlterado a esta hora ou depois (ISO 8601)
created_sinceAdicionado a esta hora ou depois
include_deleted1 para incluir pessoas removidas (com deleted_at definido) — útil para sincronização
sortid, -id, updated_at, -updated_at, last_name
curl "https://churchbright.com/api/v1/people" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Resposta de exemplo
{
    "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}

Obter uma pessoa · necessidades people:read

curl "https://churchbright.com/api/v1/people/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Resposta de exemplo
{
    "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

Criar uma pessoa · necessidades people:write

first_name é obrigatório. As datas usam o formato YYYY-MM-DD e os números de telefone são convertidos para o formato internacional com base no país da igreja. Envie "dedupe": true para receber a pessoa existente (HTTP 200, meta.duplicate = true) quando o e-mail ou o telefone já estiverem registados.

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}'
Resposta de exemplo
{
    "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}

Atualizar uma pessoa · necessidades people:write

Envie apenas os campos a alterar. PUT e POST para o mesmo URL também funcionam. Os campos personalizados são combinados.

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"}}'
Resposta de exemplo
{
    "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
    }
}
Famílias

GET /api/v1/families

Listar famílias · necessidades families:read

Parâmetro de consultaDescrição
qPesquisar por nome
branch_idApenas esta filial
updated_sinceAlterado desde
curl "https://churchbright.com/api/v1/families" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Resposta de exemplo
{
    "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}

Obter uma família com os seus membros · necessidades families:read

curl "https://churchbright.com/api/v1/families/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Resposta de exemplo
{
    "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

Criar uma família · necessidades 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}'
Resposta de exemplo
{
    "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"
    }
}
Filiais e fundos

GET /api/v1/branches

Listar filiais · necessidades branches:read

A árvore completa: parent_id liga uma filial à que está acima dela.

curl "https://churchbright.com/api/v1/branches" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Resposta de exemplo
{
    "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 fundos · necessidades funds:read

Parâmetro de consultaDescrição
active1 = apenas fundos ativos, 0 = apenas inativos
curl "https://churchbright.com/api/v1/funds" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Resposta de exemplo
{
    "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
    }
}
Contribuições

GET /api/v1/contributions

Listar contribuições · necessidades contributions:read

Os valores são inteiros em unidades menores (kobo, cêntimos). meta.sum_amount_base soma todas as contribuições correspondentes na moeda da igreja.

Parâmetro de consultaDescrição
fromContribuído a partir de (YYYY-MM-DD)
toContribuído até
fund_idUm fundo
person_idUm doador
methodcash, bank_transfer, pos, online, ach, cheque, ussd, mobile_money, text, in_kind, other
sourcemanual, online, import, api, …
statusposted (predefinido), void ou all
branch_idEsta filial e as suas subfiliais
updated_sinceAlterado desde
sortid, -id, given_on, -given_on
curl "https://churchbright.com/api/v1/contributions" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Resposta de exemplo
{
    "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}

Obter uma contribuição · necessidades contributions:read

curl "https://churchbright.com/api/v1/contributions/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Resposta de exemplo
{
    "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

Registar uma contribuição · necessidades contributions:write

amount é obrigatório, em unidades menores. Por predefinição, fund_id é o fundo predefinido da igreja, given_on é a data de hoje e method é online. Uma referência já registada através da API devolve 409. Envie um cabeçalho Idempotency-Key para que as novas tentativas nunca registem uma contribuição duas vezes.

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"}'
Resposta de exemplo
{
    "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"
    }
}
Mensagens

POST /api/v1/messages

Enviar uma mensagem · necessidades messages:write

channel é sms, email, whatsapp ou push. Envie para person_id, até 100 person_ids, ou para um número de telefone/e-mail direto em "to". As etiquetas de personalização como {first_name} funcionam. As anulações de subscrição são respeitadas e as unidades de SMS são cobradas normalmente.

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!"}'
Resposta de exemplo
{
    "ok": true,
    "data": {
        "id": 5521,
        "person_id": 42,
        "status": "sent",
        "error": null,
        "channel": "sms"
    }
}

GET /api/v1/messages

Registo de mensagens · necessidades messages:read

Parâmetro de consultaDescrição
channelsms, email, whatsapp, voice, push
statussent, delivered, failed, skipped
person_idUma pessoa
sourceDe onde veio, por ex. api, followup
updated_sinceAlterado desde
curl "https://churchbright.com/api/v1/messages" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Resposta de exemplo
{
    "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
    }
}
Mais recursos
Estes recursos vêm das funcionalidades que a sua igreja ativou. Seguem as mesmas regras de autenticação, paginação e erros.

GET /api/v1/prayer_requests

Listar Pedidos de oração · necessidades prayer_requests:read

Fornecido pelo módulo Cuidado pastoral e oração.

Parâmetro de consultaDescrição
pageNúmero da página
per_pageAté 100
updated_sinceAlterado desde (quando suportado)
curl "https://churchbright.com/api/v1/prayer_requests" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

GET /api/v1/prayer_requests/{id}

Obter um registo de Pedidos de oração · necessidades prayer_requests:read

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

POST /api/v1/prayer_requests

Criar Pedidos de oração · necessidades 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 Contribuições · necessidades gifts:read

Fornecido pelo módulo Contribuições.

Parâmetro de consultaDescrição
pageNúmero da página
per_pageAté 100
updated_sinceAlterado desde (quando suportado)
curl "https://churchbright.com/api/v1/gifts" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

GET /api/v1/gifts/{id}

Obter um registo de Contribuições · necessidades gifts:read

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

GET /api/v1/sermons

Listar Pregações · necessidades sermons:read

Fornecido pelo módulo Multimédia.

Parâmetro de consultaDescrição
pageNúmero da página
per_pageAté 100
updated_sinceAlterado desde (quando suportado)
curl "https://churchbright.com/api/v1/sermons" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

GET /api/v1/sermons/{id}

Obter um registo de Pregações · necessidades sermons:read

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

Webhooks

Adicione endpoints em Configurações → API e webhooks → Webhooks e escolha os eventos que pretende. Quando um deles acontece, enviamos um POST HTTPS com um corpo 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" tem a mesma estrutura que o recurso REST correspondente. Os eventos de atualização incluem também "previous" com os valores anteriores à alteração. Cada pedido inclui estes cabeçalhos:

X-ChurchBright-EventO nome do evento, p. ex. person.created
X-ChurchBright-Event-IdÚnico por evento — guarde-o para ignorar duplicados, porque uma reentrega reutiliza-o.
X-ChurchBright-DeliveryO id da tentativa de entrega mostrado no seu registo de entregas.
X-ChurchBright-Signaturet=<unix time>,v1=<HMAC-SHA256 of "<t>.<raw body>" com o seu segredo de assinatura, em hex>
  • Responda com qualquer estado 2xx dentro de 10 segundos. Faça o trabalho demorado depois de responder.
  • Qualquer outra resposta leva a mais 4 tentativas com intervalos crescentes (2, 4, 8 e 16 minutos). Pode reenviar qualquer evento a partir do registo de entregas.
  • Os endpoints que falhem 20 entregas seguidas são pausados e os administradores são notificados. Volte a ativá-los depois de corrigidos.
  • Use “Enviar evento de teste” para receber um evento ping enquanto constrói o seu endpoint.

Verificação de assinaturas

Calcule o HMAC-SHA256 do carimbo de data/hora, de um ponto e do corpo bruto do pedido com o seu segredo de assinatura (a string whsec_… completa), compare-o com v1 em tempo constante e rejeite carimbos de data/hora com mais de cinco minutos.

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 principais mais os eventos das funcionalidades instaladas nesta plataforma. Subscreva com nomes exatos ou caracteres universais como person.*
EventoDeQuando é enviado
pingNúcleoEnviado apenas quando prime “Enviar evento de teste”.
ai.output_createdBright AIBright AI wrote something in the writing studio (title and template only).
api.key_createdAPI e webhooksAn API key was created (the key itself is never included).
api.key_revokedAPI e webhooksAn API key was revoked.
api.webhook_goneAPI e webhooksEmitido por esta funcionalidade.
attendance.checkinFrequência e check-inEmitido por esta funcionalidade.
attendance.children_picked_upFrequência e check-inEmitido por esta funcionalidade.
attendance.pickup_flaggedFrequência e check-inEmitido por esta funcionalidade.
attendance.recordedNúcleoFoi registada a frequência de um culto ou reunião.
automations.run_completedAutomaçõesA person finished an automation journey (the run and the automation).
billing.downgrade_scheduledPlano e faturaçãoEmitido por esta funcionalidade.
billing.enterprise_enquiryPlano e faturaçãoEmitido por esta funcionalidade.
billing.extras_pausedPlano e faturaçãoEmitido por esta funcionalidade.
billing.extras_restoredPlano e faturaçãoEmitido por esta funcionalidade.
billing.plan_changedPlano e faturaçãoEmitido por esta funcionalidade.
billing.plan_expiredPlano e faturaçãoEmitido por esta funcionalidade.
billing.sms_purchasedPlano e faturaçãoEmitido por esta funcionalidade.
billing.subscription_activatedPlano e faturaçãoEmitido por esta funcionalidade.
care.pathway_completedCuidado pastoral e oraçãoEmitido por esta funcionalidade.
care.prayer_request_createdCuidado pastoral e oraçãoEmitido por esta funcionalidade.
compete.badge_awardedCompetiçõesEmitido por esta funcionalidade.
compete.quiz_completedCompetiçõesEmitido por esta funcionalidade.
contribution.recordedNúcleoFoi registada uma contribuição — online, manual, importada ou através da API.
contribution.voidedNúcleoUma contribuição foi anulada.
dashboard.setup_completedPainelEmitido por esta funcionalidade.
dashboard.setup_step_donePainelEmitido por esta funcionalidade.
events.checked_inEventosEmitido por esta funcionalidade.
events.registeredEventosEmitido por esta funcionalidade.
finance.expense_approvedFinançasEmitido por esta funcionalidade.
finance.remittance_paidFinançasEmitido por esta funcionalidade.
followup.guest_capturedNovos visitantes e acompanhamentoEmitido por esta funcionalidade.
followup.stage_changedNovos visitantes e acompanhamentoEmitido por esta funcionalidade.
followup.task_completedNovos visitantes e acompanhamentoEmitido por esta funcionalidade.
forms.submittedFormuláriosEmitido por esta funcionalidade.
giving.batch_depositedContribuiçõesEmitido por esta funcionalidade.
giving.gift_receivedContribuiçõesEmitido por esta funcionalidade.
giving.pledge_createdContribuiçõesEmitido por esta funcionalidade.
giving.recurring_cancelledContribuiçõesEmitido por esta funcionalidade.
giving.recurring_createdContribuiçõesEmitido por esta funcionalidade.
groups.join_requestedGrupos e célulasEmitido por esta funcionalidade.
groups.member_addedGrupos e célulasEmitido por esta funcionalidade.
groups.members_bulk_addedGrupos e célulasEmitido por esta funcionalidade.
groups.message_postedGrupos e célulasEmitido por esta funcionalidade.
groups.report_submittedGrupos e célulasEmitido por esta funcionalidade.
imports.completedImportaçõesEmitido por esta funcionalidade.
imports.undoneImportaçõesEmitido por esta funcionalidade.
integrations.feed_createdIntegraçõesA Google Sheets feed was created.
integrations.feed_revokedIntegraçõesA Google Sheets feed was revoked.
integrations.hook_subscribedIntegraçõesA Zapier or Make trigger subscribed to an event.
integrations.hook_unsubscribedIntegraçõesA Zapier or Make trigger unsubscribed.
media.live_endedMultimédiaEmitido por esta funcionalidade.
media.live_startedMultimédiaEmitido por esta funcionalidade.
media.sermon_deletedMultimédiaEmitido por esta funcionalidade.
media.sermon_publishedMultimédiaEmitido por esta funcionalidade.
media.studio_publishedMultimédiaA sermon studio section (notes, questions or devotional) was published to the sermon page.
media.studio_unpublishedMultimédiaA sermon studio section was taken off the sermon page.
member.app_installedAplicação de membrosEmitido por esta funcionalidade.
member.post_publishedAplicação de membrosEmitido por esta funcionalidade.
member.push_sentAplicação de membrosEmitido por esta funcionalidade.
member.registeredAplicação de membrosEmitido por esta funcionalidade.
member.testimony_approvedAplicação de membrosEmitido por esta funcionalidade.
member.testimony_submittedAplicação de membrosEmitido por esta funcionalidade.
message.sentNúcleoFoi enviada uma mensagem por SMS, e-mail, WhatsApp, voz ou push.
messaging.campaign_sentMensagensEmitido por esta funcionalidade.
messaging.inbox_receivedMensagensEmitido por esta funcionalidade.
messaging.unsubscribedMensagensEmitido por esta funcionalidade.
nativeapp.device_registeredAplicações nativasA phone registered for push notifications in the native app.
payment.failedNúcleoUm pagamento online falhou.
payment.succeededNúcleoUm pagamento online foi concluído com êxito.
people.importedPessoasEmitido por esta funcionalidade.
person.createdNúcleoFoi adicionada uma pessoa.
person.deletedNúcleoFoi removida uma pessoa.
person.mergedNúcleoDois registos duplicados foram fundidos ("data" é mantido, "previous" foi removido).
person.mergingPessoasEmitido por esta funcionalidade.
person.status_changedNúcleoO estado de uma pessoa mudou, p. ex. novo visitante → membro.
person.tag_addedAutomaçõesA tag was added to a person (the person and the tag).
person.tag_removedAutomaçõesA tag was removed from a person (the person and the tag).
person.updatedNúcleoOs dados de uma pessoa foram alterados ("previous" contém os valores antigos).
platform.announcement_publishedAdministrador da plataformaEmitido por esta funcionalidade.
platform.church_plan_changedAdministrador da plataformaEmitido por esta funcionalidade.
platform.church_status_changedAdministrador da plataformaEmitido por esta funcionalidade.
platform.sender_id_decidedAdministrador da plataformaEmitido por esta funcionalidade.
print.generatedCartas, etiquetas e crachásEmitido por esta funcionalidade.
reports.emailedRelatóriosAn executive summary was emailed (scheduled or on demand).
school.attendance_closedEscola DominicalA class closed a Sunday school session (the session and the class).
school.promotion_appliedEscola DominicalPromotion Sunday was applied (the promotion and how many moved).
serve.assignment_acceptedServirEmitido por esta funcionalidade.
site.lead_receivedSite de marketingEmitido por esta funcionalidade.
user.invitedNúcleoFoi convidado um membro da equipa.
ussd.pay_requestedUSSDEmitido por esta funcionalidade.
ussd.session_endedUSSDEmitido por esta funcionalidade.
website.message_receivedSiteEmitido por esta funcionalidade.
website.page_publishedSiteEmitido por esta funcionalidade.
website.template_appliedSiteEmitido por esta funcionalidade.
website.translation_createdSiteEmitido por esta funcionalidade.
x.yAPI e webhooksEmitido por esta funcionalidade.

Controlo de versões: esta é a versão 1. Adicionamos campos e endpoints sem aviso prévio, por isso ignore os campos que não conhece; qualquer alteração que possa quebrar uma integração virá numa nova versão.