Endpoints da API pública

TLDR: Catálogo dos endpoints expostos pelo citrg-api para integração com sistemas externos (Apolo, trg-club, checkout, área do membro), com a forma de autenticação de cada um. As mensagens de erro seguem a resposta multilíngue.

Origem em produção: https://api.cbtrg.com/.

Visão geral

Método e rota Autenticação Papel
GET /api/v1/memberships pública diretório público de filiações ativas com carteira emitida
GET /api/v1/memberships/:register_number pública dados públicos de uma filiação pelo número de registro
GET /api/v1/user_profiles/:register_number pública perfil público + filiação, pelo número de registro
GET /api/v1/apolo_membership?email= header apolo-access-token validade da filiação para o Apolo — ver R-001
POST /api/v1/auth/sign_in pública login (devise_token_auth)
POST /api/v1/me pública login via Apolo, devolve os headers de autenticação
GET /api/v1/me headers do Apolo dados do usuário logado, perfil privado, filiação e países
PUT /api/v1/me/:id headers do Apolo atualiza o perfil e anexa documentos
POST /api/v1/webhook auth_token_verification webhook de pagamento do checkout — cria/atualiza filiação
POST /api/v1/webhook_email token de integração webhook de e-mail
POST /api/v2/auth/sign_in pública login v2
POST /api/v2/webhook auth_token_verification (mesmo token do v1) webhook de compra no formato de evento da Hotmart (PURCHASE_APPROVED/PURCHASE_REFUNDED/PURCHASE_DELAYED) — cria/atualiza filiação, ver contrato abaixo
GET /api/v2/therapist/search/:term pública busca de terapeutas
GET /api/v2/therapist/card/:token pública carteira do terapeuta por token
GET /api/v2/user/onboarding token do Apolo onboarding corrente do usuário
POST /api/v2/user/onboarding token do Apolo cria/avança onboarding
GET /api/v2/user/memberships token do Apolo histórico de filiações — ver R-003
GET /api/v2/user/memberships/current token do Apolo filiação corrente
POST /api/v2/user/memberships/validate token do Apolo validação de filiação

Rotas administrativas (/admin, ActiveAdmin) e o painel do GoodJob (/good_job, restrito a admin) ficam fora deste catálogo.

Contratos

GET /api/v1/memberships/:register_number

Dados públicos de uma filiação: número de registro e validade. Nenhum outro dado é retornado, por proteção de dados do filiado. Endpoint público, sem autenticação.

A busca considera apenas filiação paid, com carteira emitida ou em emissão, e vigência em andamento (valid_until >= hoje).

json { "register_number": "0001", "valid_until": "12/2027" }

Erro:

json { "error": "Não encontrado" }

POST /api/v1/auth/sign_in

Login do usuário. Endpoint público, sem autenticação.

Corpo:

json { "email": "email", "password": "pass" }

Resposta:

json { "data": { "email": "email@exemplo.com", "uid": "email@exemplo.com", "id": 1, "name": "Nome", "doc_number": "", "person_type": "", "phone_number": "", "admin": true, "provider": "email" } }

Os headers da resposta trazem access-token, token-type, uid, expiry e client.

Erro:

json { "success": false, "errors": ["E-mail ou senha inválidos."] }

POST /api/v1/webhook — exemplo do Apolo ao gerar certificado

POST https://api.cbtrg.com/api/v1/webhook?auth_token_verification={TOKEN}

json { "payment": { "id": "payment_92839288432", "status": "paid", "billing_type": "APOLO_FREE_TRG", "checkout_id": 75, "installment_count": 1, "customer": { "id": 123, "email": "pessoa@exemplo.com", "doc_number": "05278901462" } } }

email e doc_number são obrigatórios — sem CPF o webhook falha com Campos mínimos enviados: status, checkout_id, user.doc_number, user.email. checkout_id determina o MembershipGroup.

O processamento está descrito em fluxo de ativação de filiação.

POST /api/v2/webhook — payload de compra no formato de evento (Hotmart)

Segunda origem para o mesmo fluxo de ativação/atualização de filiação, usada por um produto vendido fora do checkout-api (Hotmart, enviado por outro sistema — não a Hotmart diretamente). Autentica com o mesmo auth_token_verification do v1.

POST https://api.cbtrg.com/api/v2/webhook?auth_token_verification={TOKEN}

json { "event": "PURCHASE_APPROVED", "data": { "purchase": { "transaction": "f4708f72-89a0-4976-a51a-5068c481f296", "payment": { "type": "PIX", "installments_number": 1 }, "offer": { "code": "6cikhiz8", "name": "Formação Completa" } }, "buyer": { "id": 9021, "name": "Maria Aparecida Silva", "email": "maria@example.com", "checkout_phone": "+5511999998888", "document": "123.456.789-00" } } }

event determina o status da filiação — só estes três são tratados, qualquer outro responde 200 sem processar:

event status da filiação
PURCHASE_APPROVED paid (cria a filiação se não existir)
PURCHASE_REFUNDED refunded (só atualiza filiação existente)
PURCHASE_DELAYED overdue (só atualiza filiação existente)

data.purchase.transaction vira o payment_reference da filiação (mesmo papel do id no v1). data.purchase.offer.code determina o MembershipGroup, no lugar do checkout_id do v1 — precisa haver um MembershipGroup com esse gateway_product_id cadastrado. data.buyer.document/data.buyer.checkout_phone são normalizados para conter só dígitos antes de seguir pro mesmo fluxo do v1.

Referências

  • config/routes.rb — tabela de rotas completa
  • app/controllers/api/ — implementação
  • app/models/membership.rb — public_serialize
  • app/models/membership/process_purchase_webhook.rb — tradução do payload de compra (v2) e delegação para WebhookMembershipService
  • Respostas de erro multilíngues