API REST & webhooks do RNTP

Integração com sistema interno

Cenário: o parceiro tem um ERP/CRM/banco próprio e quer ter os membros RNTP refletidos lá automaticamente. Combine 3 ferramentas:

1. Webhook outbound — cadastrar endpoint em /admin/integrations/endpoints escolhendo os eventos (ex: member.approved, candidacy.approved,card.issued). Toda mudança chega no parceiro com HMAC.
2. Transformer de payload (opcional) — se o parceiro tem schema próprio, configure o template no endpoint. Ex: { "external_id": "{{$.payload.userId}}" }.
3. Backfill / replay — na primeira conexão, dispare Sincronizar membros ativos. Cada membro existente vira um member.snapshot entregue só pra esse endpoint, usando o mesmo template.

Site HTML — widget e selo verificável

Cenário: escola, clínica ou empresa com Chancela RNTP quer mostrar numa página pública que um profissional é certificado. Sem código.

Selo (SVG)

Cache 5 minutos no CDN. Atualiza automaticamente quando o status do membro muda.

<img
  src="https://profissionais.rntp.com.br/api/v1/badges/member/RNTP1234567.svg"
  alt="Profissional verificado RNTP"
  width="320" height="100"
/>

Widget completo (iframe)

Mostra foto, nome, registro e localidade. Embedável em qualquer site.

<iframe
  src="https://profissionais.rntp.com.br/embed/member/RNTP1234567"
  width="100%" height="200"
  style="border: 0;"
  loading="lazy"
></iframe>

Verificação por código (carteirinha)

<iframe
  src="https://profissionais.rntp.com.br/embed/verify/AB12CD34"
  width="100%" height="220"
  style="border: 0;"
></iframe>

Painel parceiro — consulta via API

Cenário: parceiro tem um admin onde lista/valida membros (check-in de evento, qualificação pra escola). Use a API REST autenticada.

curl "https://profissionais.rntp.com.br/api/v1/members?state=SP&specialty=psicanalise&limit=50" \
  -H "Authorization: Bearer rntp_<prefix>.<secret>"

Crie a chave em /admin/api-keys com scope members.read. A API só retorna membros ativos que aceitaram exibição pública (LGPD).

Autenticação e chaves

Endpoints autenticados exigem uma chave gerada em /admin/api-keys. Formato:

rntp_<prefix>.<secret>

Envie em um dos cabeçalhos abaixo:

Authorization: Bearer rntp_<prefix>.<secret>
# ou
X-RNTP-Api-Key: rntp_<prefix>.<secret>

O secret é mostrado UMA vez na criação — guarde em cofre. Caso seja comprometido, rotacione pelo painel admin.

Verificar carteirinha

Público — não exige chave. Use para confirmar que um profissional está registrado e em dia.

curl https://profissionais.rntp.com.br/api/v1/cards/verify/AB12CD34

Resposta (200):

{
  "valid": true,
  "status": "active",
  "name": "Maria da Silva",
  "registrationNumber": "RNTP1234567",
  "issuedAt": "2024-05-01T13:00:00.000Z",
  "expiresAt": "2026-05-01T13:00:00.000Z",
  "revokedAt": null
}

valid é true apenas para carteirinhas com status="active" dentro da validade. Estados possíveis: active, expired, revoked, not_found.

Consultar membros

Scope members.read. Retorna apenas membros com status=active que optaram por perfil público (is_public=true).

GET /v1/members/:rntpNumber

curl https://profissionais.rntp.com.br/api/v1/members/RNTP1234567 \
  -H "Authorization: Bearer rntp_<prefix>.<secret>"

GET /v1/members?state=SP&specialty=psicanalise

Filtros: state (UF), city, specialty (ilike). Paginação: limit (1–100, default 20), offset.

curl "https://profissionais.rntp.com.br/api/v1/members?state=SP&limit=20" \
  -H "X-RNTP-Api-Key: rntp_<prefix>.<secret>"

Publicações (blog)

Público — não exige chave. Retorna posts publicados com visibilidade pública.

curl "https://profissionais.rntp.com.br/api/v1/publications?category=noticias&limit=10"

Regiões

Público — devolve a contagem de membros ativos (com perfil público) por UF. Útil para mapas/landings de parceiros.

curl https://profissionais.rntp.com.br/api/v1/regions

Receber webhooks do portal (outbound)

Crie um endpoint em /admin/integrations/endpoints e escolha os eventos que quer receber (member.registered, candidacy.approved, publication.published, etc.). Cada entrega traz o cabeçalho:

X-RNTP-Signature: v1,t=<timestampMs>,s=<hmacSha256 hex>
X-RNTP-Event: <tipo do evento>
X-RNTP-Delivery: <id único da entrega>

Validação: HMAC_SHA256(secret, "v1." + timestampMs + "." + rawBody). Recomendamos tolerância de até 5 minutos entre o timestamp e o relógio do servidor. Tentativas falhas são repetidas com backoff (30s, 2min, 10min, 30min, 2h, 6h) até 6 tentativas.

Transformer opcional: cada endpoint pode mandar o envelope cru ou aplicar um template JSON com {{$.payload.email}} pra entregar no schema esperado pelo parceiro. Backfill: pra parceiros novos use Sincronizar membros — cada membro existente vira um member.snapshot entregue só nesse endpoint.

Enviar webhooks para o portal (inbound)

Cadastre uma integração em /admin/integrations/inbound. Cada integração recebe um slug único e um secret. URL pública:

POST https://profissionais.rntp.com.br/api/integrations/inbound/<slug>

Autenticação à sua escolha:

• HMAC SHA-256 — mesmo esquema do outbound; envie X-RNTP-Signature.
• Bearer — Authorization: Bearer <secret>. Mais simples para Make/Zapier.

Para generic_inbound você define regras de mapeamento que convertem o payload externo em eventos tipados do portal (members, candidacy, publications…). Use {{$.path.to.value}} em templates.

Códigos de erro

• 400 bad_request — parâmetro ausente ou malformado.
• 401 api_key_malformed | unknown | mismatch | expired | revoked | disabled — autenticação falhou.
• 403 scope_missing — chave válida, mas sem o scope exigido pelo endpoint.
• 404 not_found — recurso não existe ou foi filtrado por visibilidade pública.
• 422 payload_validation_failed — webhook inbound com mapping resultando em payload inválido para o DomainEvent.
• 429 rate_limited — exceto Retry-After no cabeçalho.