API v1
API e webhooks da TF Shop Cloud
Uma única API REST pública e webhooks para ligar lojas TF Shop Cloud a ERPs, emissores de NF-e, logística e sistemas próprios. ERPs externos, os conectores da TF (Bling e Tiny) e o TF ERP usam os mesmos endpoints, escopos e limites: não existe canal privado.
O essencial
- URL base
https://api.tfshop.cloud/v1- Autenticação
Authorization: Bearer tfs_live_…- Formato
- JSON em
snake_case, UTF-8 - Valores
- Inteiros em centavos:
15990= R$ 159,90 - Datas
- ISO 8601 em UTC:
2026-10-29T13:05:12Z - Testes
- Tokens
tfs_test_veem só pedidos de teste
Primeira chamada em 3 passos
Crie um token
No painel da loja, abra Aplicativos e API → Tokens e crie um token com o escopo orders:read. O token completo aparece uma única vez: guarde-o num cofre de segredos.
Liste os pedidos
Envie o token no cabeçalho Authorization. A loja vem do próprio token: você nunca informa store_id.
export TFSHOP_TOKEN="tfs_live_…" # shown once, when you create it
curl "https://api.tfshop.cloud/v1/orders?limit=2" \
-H "Authorization: Bearer $TFSHOP_TOKEN"Leia a resposta
Listas vêm como { data, next_cursor }. Para a próxima página, envie cursor com o valor de next_cursor; quando ele vier null, acabou.
{
"data": [
{
"id": "o_1011",
"number": 1011,
"status": "paid",
"test": false,
"total": 19990,
"created_at": "2026-10-26T12:00:00.000Z",
"updated_at": "2026-10-26T12:00:00.000Z"
}
],
"next_cursor": "eyJ1IjoiMjAyNi0xMC0yNlQxMjowMDowMC4wMDBaIiwiaSI6Im9fMTAxMSJ9"
}Quem usa esta API
ERPs externos
Omie, sistemas locais e integradores, como app parceiro (OAuth) ou com um token da loja.
Conectores da TF
Bling e Tiny são apps comuns desta API, mantidos pela TF.
TF ERP
O ERP da TF é um app de primeira parte: mesmos endpoints, escopos, limites e webhooks.
Integrações próprias
Planilhas, BI e scripts do lojista, com tokens criados no painel.
Regras da plataforma
- A loja é a fonte da verdade de produtos, preços e estoque. Apps leem e escrevem pelos endpoints padrão, e cada escrita fica atribuída ao app.
- Um único emissor de NF-e por loja: o TF Fiscal da loja ou o ERP.
POST /orders/{order_id}/invoicessó é aceito quando o emissor da loja é o ERP. - Pedidos e pagamentos nascem na loja. O dinheiro cai direto na conta C6 do lojista; nenhum app marca pedido como pago nem faz reembolso.
- Apps parceiros passam pela análise da TF antes de aparecer para os lojistas. O lojista também pode criar os próprios tokens.