Este guia explica como conectar seu produto ao asaph: exibir um QR Code (ou Base64) para parear um computador com uma organização, ativar a conexão e consumir ordens de culto e arquivos pela API /partner.
Antes da integração funcionar, envie ao time asaph estes dois itens. Eles são configurados uma vez na conta do seu produto:
| Item | Detalhe |
|---|---|
| URL do webhook | Endpoint HTTPS no seu backend que receberá POST { "token", "payload" } quando um pareamento for iniciado. Deve ser público, estável e responder 2xx. Veja Seu webhook. |
| Chave de assinatura HMAC | Segredo fixo e de longa duração, combinado entre você e o asaph. No seu app, use essa chave para gerar o sig do QR/Base64 sobre {ts};{device};{token}. O asaph usa a mesma chave para validar. Não é por sessão nem por organização — é uma chave do parceiro. Veja Assinatura HMAC. |
| Termo | Significado |
|---|---|
| Organização | Igreja ou conta no asaph com a qual o computador será vinculado. |
| Dispositivo (device) | Conexão entre o seu produto e uma organização no asaph. Status: pending → active → revoked. |
| Token de identidade | JWT permanente do parceiro (seção Credenciais). Vai no header Authorization: Bearer … em todas as rotas /partner/*. |
Token de sessão (token) | Código gerado pelo seu app para identificar aquele computador/sessão. Entra no QR Code / Base64 e é ecoado no webhook para você saber a quem entregar o código do dispositivo. |
Código do dispositivo (payload) | Código assinado gerado pelo asaph. Deve ser enviado como X-Device-Code no handshake e em todas as demais rotas /partner/*. |
O vínculo começa no seu app (QR Code ou string Base64) e termina quando você ativa o dispositivo com o handshake. Depois disso, as rotas listadas abaixo ficam disponíveis.
A URL do webhook é um dos itens que você fornece ao asaph na configuração. Depois de validar o QR/Base64, o asaph notifica o seu sistema com um POST HTTPS. Exemplo:
POST /seu/webhook
Content-Type: application/json
{
"token": "<mesmo token do QR/Base64>",
"payload": "<código assinado do dispositivo>"
}token do webhook não é o token de identidade (JWT). É o código de sessão do computador que você colocou no QR. Use-o para entregar o payload à instância certa do app. O payload vira o header X-Device-Code.2xx) se aceitou o payload.payload com segurança — ele autentica o dispositivo.Todo pareamento exige assinatura. A chave HMAC é fixa e de longa duração: você a fornece ao asaph uma vez e a usa no seu app para assinar cada QR/Base64. No JSON, o campo sig é o HMAC-SHA256 em hexadecimal da mensagem abaixo.
Calcule assim:
mensagem = "{ts};{device};{token}"
sig = hex(HMAC-SHA256(chave_compartilhada, mensagem))| Campo no QR | Descrição |
|---|---|
ts | Unix time em segundos no momento da geração. |
device | Nome do computador (ex.: MacBook). |
token | Código da sessão/computador (ecoado no webhook). |
sig | HMAC em hexadecimal (minúsculo). |
; importam: ts, depois device, depois token. Qualquer diferença invalida a assinatura./partnerTodas as rotas exigem:
| Header | Valor |
|---|---|
Authorization | Bearer <token de identidade> (o JWT desta página) |
X-Device-Code | O payload recebido no webhook (código assinado completo) |
Authorization: Bearer <token de identidade>
X-Device-Code: <payload do webhook>
Content-Type: application/jsonO handshake ativa o dispositivo. Depois disso, as demais rotas exigem status active.
Use os painéis Try it com o token e o device code de Credenciais. As chamadas passam pelo servidor desta documentação.
Ativa o dispositivo (pending → active). Chame assim que receber o payload no webhook.
Corpo: nenhum (o código vai no header).
Resposta: 204 No Content em sucesso.
curl -X POST "$BASE_URL/partner/handshake" \
-H "Authorization: Bearer $PARTNER_TOKEN" \
-H "X-Device-Code: $DEVICE_CODE"Retorna a organização vinculada ao dispositivo ativo.
{
"id": "uuid-da-organizacao",
"name": "Igreja Exemplo",
"avatar_url": "https://…"
}Lista ordens de culto próximas da organização vinculada.
| Query | Padrão | Descrição |
|---|---|---|
query | — | Filtro textual opcional. |
take | 20 | Quantidade (1–50). |
[
{
"id": "uuid-da-ordem",
"service": {
"id": "uuid-do-culto",
"name": "Culto de domingo",
"description": null,
"date": "2026-09-07T00:00:00Z"
},
"time": "2026-09-07T18:00:00Z"
}
]Retorna os itens da ordem de culto (músicas, arquivos, referências bíblicas, cabeçalhos, etc.).
[
{
"index": 0,
"type": "song",
"name": null,
"notes": null,
"duration": null,
"song": {
"name": "Grande é o Senhor",
"artists": "Adoradores",
"source_song": {
"name": "Grande é o Senhor",
"artists": "Adoradores",
"isrc": null,
"origin": "…",
"data": {}
}
},
"file": null,
"bible_reference": null
},
{
"index": 1,
"type": "file",
"song": null,
"file": {
"id": "uuid-interno",
"file_id": "id-externo-storage",
"name": "letra.pdf",
"mime_type": "application/pdf",
"kind": "file",
"md5": "…",
"size": 20480,
"provider": "google_drive",
"download_session_url": "/partner/orders/{order_id}/file/{file_id}/download_session"
},
"bible_reference": null
}
]Tipos de item comuns: header, item, song, bible, media, file.
Cria uma sessão temporária de download para um arquivo da ordem. Use o file_id retornado em file.file_id (não o UUID interno).
{
"access_token": "…",
"url": "https://…"
}Revoga o dispositivo atual (active → revoked). Depois disso, as rotas protegidas passam a falhar até um novo pareamento.
Resposta: 204 No Content.
Authorization ou X-Device-Code válidos, a requisição é rejeitada antes da lógica de negócio.revoked não pode fazer handshake de novo; é preciso um novo pareamento.X-Device-Code em logs públicos.{ ts, device, token, sig } → receber webhook { token, payload } → POST /partner/handshake → GET /partner/me retorna a organização esperada → listar ordens.