Autenticação da integração

As chamadas entre os servidores do parceiro e da Granus, nas duas direções, usam HTTPS e HMAC-SHA256. A Granus entrega ao parceiro um parceiro_uuid e um segredo compartilhado por um canal seguro. O UUID identifica a integração; o segredo não é enviado nas requisições.

Headers

Header	Valor
`Authorization`	`HMAC-SHA256 {parceiro_uuid}:{assinatura}`. A assinatura é hexadecimal minúscula.
`X-Request-Timestamp`	Timestamp Unix UTC. Diferença máxima de 300 segundos em relação ao servidor.
`X-Request-Nonce`	Valor aleatório e único por requisição. Um nonce já aceito para a mesma credencial não pode ser reutilizado dentro da janela de 300 segundos.
`Content-Type`	`application/json` quando houver corpo JSON.

String canônica

Calcule o HMAC-SHA256 sobre os bytes UTF-8 da string abaixo, usando o segredo compartilhado. Separe as seis partes por \n, sem quebra de linha adicional no final.

HTTP_METHOD
PATH
CANONICAL_QUERY_STRING
TIMESTAMP
NONCE
SHA256_BODY

Parte	Regra
`HTTP_METHOD`	Método HTTP em letras maiúsculas: `GET`, `POST`, `PUT`, `PATCH` ou `DELETE`.
`PATH`	Caminho da URL iniciado por `/`, sem domínio nem query string.
`CANONICAL_QUERY_STRING`	Parâmetros ordenados pelo nome da chave, codificados como `chave=valor` e unidos por `&`; string vazia quando não houver parâmetros.
`TIMESTAMP`	Mesmo valor de `X-Request-Timestamp`.
`NONCE`	Mesmo valor de `X-Request-Nonce`.
`SHA256_BODY`	SHA-256 hexadecimal dos bytes exatos do corpo. Sem corpo, use `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`.

Exemplo de headers

Authorization: HMAC-SHA256 550e8400-e29b-41d4-a716-446655440000:4b7c...e91a
X-Request-Timestamp: 1790352000
X-Request-Nonce: 01K5ZW6KQ1S5N0X6QXGJ9QZC2A
Content-Type: application/json

Falhas de autenticação

401 indica credencial desconhecida, parceiro inativo, assinatura inválida, timestamp fora da janela aceita ou nonce reutilizado. 403 indica credencial válida sem acesso ao recurso solicitado.

Acesso do usuário à Granus

O usuário clica em “Ver etiquetas” no sistema do parceiro. O servidor do parceiro identifica o usuário autenticado e envia seu user_id em POST /parceiros/sessoes, com assinatura HMAC. A Granus devolve uma redirect_url; o parceiro redireciona o navegador para ela. O ticket da URL é temporário e de uso único. O navegador não envia headers HMAC nessa etapa.

Usuário → parceiro: Ver etiquetas
Parceiro → Granus: POST /parceiros/sessoes (HMAC + user_id)
Granus → parceiro: redirect_url e expires_in
Parceiro → navegador: redirecionamento para redirect_url
Navegador → Granus: GET /parceiros/acesso?token=...
Granus → navegador: painel de etiquetas

O parceiro não precisa conhecer a senha Granus do usuário nem implementar uma tela de login Granus. O ticket inicia o acesso, mas não é credencial para outras APIs. Consulte os detalhes de sessões e acesso na API Granus.