Conecte sites, aplicativos e sistemas externos ao GuilderHub por uma interface governada, versionada e multi-tenant, preservando isolamento, rastreabilidade e controle sobre os dados da associação.
curl -X POST "https://guilderhub.com.br/api/v1/associados/verificar" \
-H "Content-Type: application/json" \
-H "X-Guilder-Token: gsh_live_••••••••" \
-d '{"documento":"00000000000"}'
{
"success": true,
"data": {
"associado_ref": "assoc_••••••••",
"primeiro_nome": "Maria",
"matricula": "A-047",
"status_cadastro": "ativo",
"financeiro_regular": true,
"acesso_liberado": true,
"elegivel": true,
"validade_cadastro": "2027-03-31"
},
"request_id": "req_••••••••"
}A API GuilderHub é a camada oficial de integração da plataforma. Cada credencial é vinculada a uma única associação e possui permissões explícitas. Uma integração externa não recebe acesso irrestrito ao cadastro dos associados, credenciais, senhas, sessões ou recursos internos da GSI.
O GuilderHub aplica isolamento por tenant, princípio do menor privilégio, minimização de dados, rastreabilidade e limites de requisição. O tratamento e o compartilhamento de informações devem observar a finalidade autorizada, as responsabilidades aplicáveis à associação e à integração e a Lei Geral de Proteção de Dados Pessoais — LGPD.
A página pública vive em /api.
Os sistemas consomem endpoints versionados em
/api/v1.
Envie a credencial exclusivamente no header
X-Guilder-Token. O token é vinculado ao
tenant e armazenado de forma não recuperável.
X-Guilder-Token: gsh_live_••••••••
Consulta pontual por documento. A resposta pode incluir
somente primeiro_nome para personalização da
experiência; não entrega nome completo, CPF, e-mail,
telefone ou ID interno. CPF com máscara é aceito, mas o
formato recomendado é somente com os 11 dígitos.
POST /api/v1/associados/verificar
{
"documento": "00000000000"
}Valida login e senha dentro do tenant autorizado. A senha nunca é retornada ou registrada em log.
POST /api/v1/associados/autenticar
{
"login": "A-047",
"senha": "••••••••"
}Permite validar a associação e os escopos vinculados ao token sem consultar dados de associados.
GET /api/v1/meelegivel como decisão consolidada.
Para um associado localizado, a API retorna HTTP 200
mesmo quando ele não está apto a acessar o serviço
externo. O campo elegivel é a fonte de
verdade para a decisão de acesso. HTTP 403 é reservado
para indisponibilidade do tenant ou ausência de escopo
da integração.
financeiro_regular representa exclusivamente
a situação financeira. validade_cadastro
representa a vigência cadastral e pode ser
null quando a origem não definiu uma data.
Quando houver uma data, ela é válida até o próprio dia
inclusive; se estiver vencida, elegivel será
false, ainda que
financeiro_regular seja true.
acesso_liberado representa somente o estado
técnico de acesso do cadastro
(status_acesso = liberado). Ele não garante,
isoladamente, cadastro ativo, usuário ativo, regularidade
financeira ou validade vigente. elegivel
consolida essas condições e deve ser usado pela integração
como decisão final de autorização.
No POST /api/v1/associados/verificar, quando o
documento é localizado, primeiro_nome pode ser
retornado para personalização simples da interface. O nome
completo continua fora do contrato público. Documento não
localizado permanece em 404 member_not_found,
sem exposição de dados pessoais.
Valores atualmente previstos para
status_cadastro: em_analise,
pendente, pendente_pagto,
ativo, inativo e
rejeitado. Para regras de autorização, não
dependa apenas desse campo: use elegivel.
A v1 base não disponibiliza exportação em massa da base de associados. Recursos adicionais exigem finalidade, autorização e escopo próprios.
Integrações recebem associado_ref opaco.
O ID primário interno do GuilderHub não é contrato
público.
O campo matricula representa o número
associativo da pessoa dentro daquela associação.
Ele não substitui a referência pública da API.
Endpoints da API não retornam páginas HTML em caso de
erro. Cada resposta inclui um request_id
para rastreabilidade técnica.
Documento válido, mas inexistente no tenant, retorna HTTP 404.
{
"success": false,
"error": {
"code": "member_not_found",
"message": "Nenhum associado foi localizado para esta associação."
},
"request_id": "req_..."
}
associados/verificar: 120 req/min por token.
associados/autenticar: 20 req/min por token.
/me: 120 req/min por token.
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1790000000
Retry-After: 42 # somente quando HTTP 429Retry-After no
contrato atual. Utilize backoff exponencial no cliente.
A API v1 não exige IP fixo nem allowlist de origem no
contrato atual. A autenticação é feita pelo
X-Guilder-Token, vinculado ao tenant e aos
escopos autorizados. O token deve permanecer no backend
da integração e nunca ser exposto em JavaScript ou no
navegador do usuário.
Use webhooks quando seu sistema precisa reagir a mudanças relevantes sem consultar a API continuamente. O GuilderHub envia apenas o estado público mínimo do associado, sem CPF, e-mail, telefone, senha ou ID interno.
Cada associação possui um segredo próprio. Valide a assinatura antes de processar o evento.
X-Guilder-Event-Id: evt_...
X-Guilder-Event: associado.status_atualizado
X-Guilder-Timestamp: 1788510000
X-Guilder-Delivery-Attempt: 1
X-Guilder-Signature: v1=<hmac_sha256>timestamp + "." + corpo_json_bruto.
Valide também a janela de tempo do timestamp
antes de aceitar a entrega.
Responda HTTP 2xx somente depois de aceitar o evento.
O mesmo event_id pode aparecer novamente
em uma tentativa posterior e deve ser tratado de forma
idempotente.
associado.criado
associado.status_atualizado
associado.matricula_atualizada
associado.regularidade_atualizada
associado.acesso_atualizado
associado.validade_atualizada
webhook.test
O objeto changes informa somente os
campos públicos que mudaram naquele evento.
{
"id": "evt_...",
"type": "associado.regularidade_atualizada",
"api_version": "v1",
"created_at": "2026-09-04T14:10:00Z",
"data": {
"associado": {
"associado_ref": "assoc_...",
"matricula": "A-047",
"status_cadastro": "ativo",
"financeiro_regular": true,
"acesso_liberado": true,
"elegivel": true,
"validade_cadastro": "2027-03-31"
},
"changes": {
"financeiro_regular": {
"from": false,
"to": true
}
}
}
}O GuilderHub aceita somente endpoints HTTPS na porta 443 e bloqueia destinos locais, privados ou reservados. Redirecionamentos não são seguidos. A associação pode rotacionar o segredo, testar e desativar o webhook pela área de Integração API.