Autenticação

Há dois tipos de credencial, com as mesmas regras de escopo, limite e auditoria. Toda chamada usa HTTPS e o cabeçalho Authorization: Bearer <token>.

Credencial	Para quem	Como obter	Validade
Token da loja	Integração de uma loja: ERP local, integrador, planilha, BI.	O proprietário cria no painel, escolhendo escopos e ambiente.	Não expira; pode ser revogado a qualquer momento.
App parceiro ou assistente de IA (OAuth 2.1)	Produto usado por muitas lojas (ERPs SaaS, emissores de NF-e, logística) e assistentes de IA via MCP.	O lojista instala o app e autoriza os escopos na tela de consentimento.	Access token de 1 h e refresh token de 30 dias, com rotação.

Assistentes de IA (MCP) usam OAuth 2.1

Claude, ChatGPT e IDEs se conectam ao servidor MCP com este mesmo fluxo — sem tokens estáticos. O cliente descobre os endereços pelos metadados abaixo e se registra sozinho (CIMD ou DCR). Passo a passo em Assistentes de IA (MCP).

Tokens da loja

Criados em Aplicativos e API → Tokens pelo proprietário da loja, com verificação em duas etapas.
O prefixo indica o ambiente: tfs_live_ para produção e tfs_test_ para testes (veja Sandbox e testes).
O segredo completo aparece uma única vez. A TF guarda só um hash; a lista mostra o prefixo, os 4 últimos caracteres e a data do último uso.
Cada token pertence a uma loja. A loja é deduzida do token: não envie store_id nem tenant em parâmetros.
Revogar é imediato: a próxima chamada recebe 401 unauthorized. Para mudar escopos, crie outro token e revogue o antigo.

http

Authorization: Bearer tfs_live_3fK9wQm2Lx7…

Nunca coloque um token em código de navegador, app móvel ou repositório. Se vazar, revogue no painel na hora.

OAuth 2.1 com PKCE

Servidor de autorização da TF, no mesmo host da plataforma: authorization code com PKCE (S256), iss nas respostas e refresh token com rotação. Os escopos vão no parâmetro scope (para apps parceiros, limitados aos aprovados no cadastro); o lojista aprova o pedido inteiro ou recusa. Os endereços abaixo são os que os metadados publicam.

Metadados (RFC 8414 / RFC 9728): https://tfshopcloud.com.br/.well-known/oauth-authorization-server · https://tfshopcloud.com.br/.well-known/oauth-protected-resource
Autorização: GET https://tfshopcloud.com.br/oauth/authorize
Token: POST https://tfshopcloud.com.br/oauth/token
Registro dinâmico (DCR): POST https://tfshopcloud.com.br/oauth/register
Revogação: POST https://tfshopcloud.com.br/oauth/revoke

GET /oauth/authorize

Gere um code_verifier aleatório (43 a 128 caracteres) e o code_challenge = BASE64URL(SHA-256(code_verifier)). Redirecione o lojista para a autorização:

url

https://tfshopcloud.com.br/oauth/authorize
  ?response_type=code
  &client_id=app_fluxo_erp
  &redirect_uri=https%3A%2F%2Fapp.exemplo.com.br%2Foauth%2Ftfshop
  &scope=orders%3Aread%20orders%3Awrite%20invoices%3Awrite%20fulfillments%3Awrite
  &state=8f1c2e7a90b4
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

Tela de consentimento

O lojista entra no painel da loja e vê a tela de consentimento em português, com cada escopo explicado e os dados pessoais destacados. Ao aprovar, voltamos ao seu redirect_uri com code e state. Confira o state.

POST /oauth/token

No servidor, troque o código por tokens em até 10 minutos, enviando o code_verifier:

bash

curl -X POST https://tfshopcloud.com.br/oauth/token \
  -d grant_type=authorization_code \
  -d code=SplxlOBeZQQYbYS6WxSbIA \
  --data-urlencode "redirect_uri=https://app.exemplo.com.br/oauth/tfshop" \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

200 OK

A resposta traz um access token de curta duração (expires_in, em segundos) e um refresh token. Guarde o par por loja (store_id).

json

{
  "access_token": "tfs_live_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_…",
  "scope": "orders:read orders:write invoices:write fulfillments:write",
  "store_id": "st_volt"
}

grant_type=refresh_token

Renove antes de expirar. Cada renovação devolve um novo refresh token e invalida o anterior:

bash

curl -X POST https://tfshopcloud.com.br/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET

O redirect_uri precisa ser HTTPS e idêntico a um endereço cadastrado no app.
O access token de um app tem o formato tfs_live_… e segue as mesmas regras dos tokens da loja.
Clientes públicos (assistentes de IA, apps nativos) não têm client_secret: enviam só client_id e code_verifier (token_endpoint_auth_method=none). Apps parceiros confidenciais enviam também o client_secret do cadastro.
Quando o lojista desinstala o app, os tokens são revogados e você recebe app.uninstalled. Pare as chamadas e apague os dados pessoais da loja em até 30 dias, exceto o que a lei fiscal obriga a guardar.

Análise dos apps pela TF

Na v1 não há publicação self-service no catálogo. Para publicar um app parceiro, envie à TF (parceiros@tfshop.cloud):

Nome, descrição, categoria e site do app; contato técnico e de segurança.
Escopos pedidos e o motivo de cada um; para orders.pii:read, o uso exato dos dados pessoais.
Endereços de redirecionamento (HTTPS) e eventos de webhook.
Política de privacidade e uma conta de teste ou um vídeo de demonstração.

A equipe da TF confere se os escopos são mínimos e se o uso de dados pessoais é justificado. Aprovado, o app aparece no catálogo dos lojistas. A TF pode suspender um app a qualquer momento: todas as instalações são revogadas na hora e as chamadas passam a ser recusadas.

Credencial

Para quem

Como obter

Validade

Token da loja

Integração de uma loja: ERP local, integrador, planilha, BI.

O proprietário cria no painel, escolhendo escopos e ambiente.

Não expira; pode ser revogado a qualquer momento.

App parceiro ou assistente de IA (OAuth 2.1)

Produto usado por muitas lojas (ERPs SaaS, emissores de NF-e, logística) e assistentes de IA via MCP.

O lojista instala o app e autoriza os escopos na tela de consentimento.

Access token de 1 h e refresh token de 30 dias, com rotação.

Tokens da loja

Criados em Aplicativos e API → Tokens pelo proprietário da loja, com verificação em duas etapas.
O prefixo indica o ambiente: tfs_live_ para produção e tfs_test_ para testes (veja Sandbox e testes).
O segredo completo aparece uma única vez. A TF guarda só um hash; a lista mostra o prefixo, os 4 últimos caracteres e a data do último uso.
Cada token pertence a uma loja. A loja é deduzida do token: não envie store_id nem tenant em parâmetros.
Revogar é imediato: a próxima chamada recebe 401 unauthorized. Para mudar escopos, crie outro token e revogue o antigo.

http

Authorization: Bearer tfs_live_3fK9wQm2Lx7…

Nunca coloque um token em código de navegador, app móvel ou repositório. Se vazar, revogue no painel na hora.

OAuth 2.1 com PKCE

Metadados (RFC 8414 / RFC 9728): https://tfshopcloud.com.br/.well-known/oauth-authorization-server · https://tfshopcloud.com.br/.well-known/oauth-protected-resource
Autorização: GET https://tfshopcloud.com.br/oauth/authorize
Token: POST https://tfshopcloud.com.br/oauth/token
Registro dinâmico (DCR): POST https://tfshopcloud.com.br/oauth/register
Revogação: POST https://tfshopcloud.com.br/oauth/revoke

GET /oauth/authorize

Gere um code_verifier aleatório (43 a 128 caracteres) e o code_challenge = BASE64URL(SHA-256(code_verifier)). Redirecione o lojista para a autorização:

url

https://tfshopcloud.com.br/oauth/authorize
  ?response_type=code
  &client_id=app_fluxo_erp
  &redirect_uri=https%3A%2F%2Fapp.exemplo.com.br%2Foauth%2Ftfshop
  &scope=orders%3Aread%20orders%3Awrite%20invoices%3Awrite%20fulfillments%3Awrite
  &state=8f1c2e7a90b4
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

Tela de consentimento

POST /oauth/token

No servidor, troque o código por tokens em até 10 minutos, enviando o code_verifier:

bash

curl -X POST https://tfshopcloud.com.br/oauth/token \
  -d grant_type=authorization_code \
  -d code=SplxlOBeZQQYbYS6WxSbIA \
  --data-urlencode "redirect_uri=https://app.exemplo.com.br/oauth/tfshop" \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

200 OK

A resposta traz um access token de curta duração (expires_in, em segundos) e um refresh token. Guarde o par por loja (store_id).

json

{
  "access_token": "tfs_live_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_…",
  "scope": "orders:read orders:write invoices:write fulfillments:write",
  "store_id": "st_volt"
}

grant_type=refresh_token

Renove antes de expirar. Cada renovação devolve um novo refresh token e invalida o anterior:

bash

curl -X POST https://tfshopcloud.com.br/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET

O redirect_uri precisa ser HTTPS e idêntico a um endereço cadastrado no app.
O access token de um app tem o formato tfs_live_… e segue as mesmas regras dos tokens da loja.
Clientes públicos (assistentes de IA, apps nativos) não têm client_secret: enviam só client_id e code_verifier (token_endpoint_auth_method=none). Apps parceiros confidenciais enviam também o client_secret do cadastro.
Quando o lojista desinstala o app, os tokens são revogados e você recebe app.uninstalled. Pare as chamadas e apague os dados pessoais da loja em até 30 dias, exceto o que a lei fiscal obriga a guardar.

Análise dos apps pela TF

Na v1 não há publicação self-service no catálogo. Para publicar um app parceiro, envie à TF (parceiros@tfshop.cloud):

Nome, descrição, categoria e site do app; contato técnico e de segurança.
Escopos pedidos e o motivo de cada um; para orders.pii:read, o uso exato dos dados pessoais.
Endereços de redirecionamento (HTTPS) e eventos de webhook.
Política de privacidade e uma conta de teste ou um vídeo de demonstração.