Pular para o conteúdo principal

Quickstart para Fornecedores

Guia de integração em 5 passos.

Pré-requisitos​

  • API key fornecida pelo time IFW.
  • Acesso ao endpoint base (ex: https://servicos.ifollowtech.com.br).

Passo 1 — Emitir o token inicial​

curl -s -X POST https://servicos.ifollowtech.com.br/api/external-auth/token \
  -H "x-api-key: SUA_API_KEY" \
  | jq .

Guarde os campos AccessToken e RefreshToken da resposta.

cuidado

Nunca exponha a API key em código fonte, logs ou variáveis de ambiente compartilhadas. Ela deve ser carregada de um cofre de segredos (Azure Key Vault, AWS Secrets Manager, etc).

Passo 2 — Chamar endpoints de negócio​

ACCESS="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

curl -s https://servicos.ifollowtech.com.br/api/external/ping \
  -H "Authorization: Bearer $ACCESS"

Passo 3 — Renovar o access token​

O access token expira em 15 minutos. Antes (ou após receber 401), use o refresh token:

REFRESH="dGhpcyBpcyBhIHNhbXBsZSByZWZyZXNoIHRva2Vu"

NEW_TOKENS=$(curl -s -X POST https://servicos.ifollowtech.com.br/api/external-auth/refresh \
  -H "Content-Type: application/json" \
  -d "{\"refreshToken\": \"$REFRESH\"}")

NEW_ACCESS=$(echo $NEW_TOKENS | jq -r '.AccessToken')
NEW_REFRESH=$(echo $NEW_TOKENS | jq -r '.RefreshToken')
Rotação obrigatória

Cada /refresh revoga o token anterior. Sempre atualize o RefreshToken armazenado com o novo valor retornado.

Passo 4 — Detectar expiração e renovar automaticamente​

Lógica recomendada em pseudocódigo:

função chamar_api(endpoint):
    se access_token está expirado ou faltam < 60s:
        renovar_tokens()

    resposta = GET endpoint com Authorization: Bearer access_token

    se resposta == 401:
        renovar_tokens()
        resposta = GET endpoint com Authorization: Bearer access_token

    retornar resposta

função renovar_tokens():
    novos = POST /api/external-auth/refresh com refresh_token atual
    se novos == 401:
        erro: "Sessão expirada. Re-autentique com a API key."
    access_token  = novos.AccessToken
    refresh_token = novos.RefreshToken   # SEMPRE atualizar
    salvar(access_token, refresh_token)

Passo 5 — Encerrar a sessão​

curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://servicos.ifollowtech.com.br/api/external-auth/revoke \
  -H "Content-Type: application/json" \
  -d "{\"refreshToken\": \"$REFRESH\"}"
# Saída: 204

Ciclo de vida completo​

API key (permanente, segura)
    │
    └── POST /token ──► access_token (15min) + refresh_token (14d)
                               │                       │
                               │                       └── POST /refresh ──► novo par
                               │                                │
                               └── chamadas de negócio          └── (repete até 14d)
                                   Authorization: Bearer              │
                                                                      └── POST /revoke