Leia antes:
../conectores.md(state map) andfichas.md(index of datasheets).
O que é#
Reads orders, products, and customers from your Tray store's web_api and loads them into the Bronze layer.
Supported ingestion modes:
- Nós buscamos — Nós buscamos os dados na sua fonte.
Para que serve#
Bring Tray Commerce data into your datalake and make it available to the Bronze/Silver/Gold layers, BI models, and the natural language question wizard.
Quando usar / quando não usar#
Use quando you need to consolidate this source into the datalake on a scheduled basis, with isolation per workspace.
Remember that the first run with a real credential is followed by our team before the connector is fully released.
Plano e permissões#
- Plano: core product (connectors are part of all plans; the limit is the number of sources allowed by the plan).
- Acesso: requires an active workspace — if the subscription is overdue, suspended, or cancelled, the run is blocked.
- Desligamento: ingestion runs can be turned off temporarily (maintenance or incident). When that happens, the screen indicates the resource is unavailable at the moment.
Pré-requisitos#
- A Tray Commerce account with access to the data you want to ingest.
- In the Tray dashboard, install/authorize an integration app: Tray returns an access_token (valid for about 1 day) and a refresh_token. Paste your store URL and the access_token here. When it expires, generate another in the dashboard (or via the refresh_token) and update the connection — automatic renewal is not yet available in this connector.
Credenciais#
Authentication method: Access token pasted by you. It is encrypted (AES-256-GCM) and never shown again, nor appears in logs or error messages.
Sensitive fields. They are encrypted (AES-256-GCM) and are never stored in the connection config, pipeline definition, export, or DAG. By default the encrypted value is stored in the database; moving the credential of this connection to an external secrets vault is an explicit choice made per connection after saving — see ../../administracao/credenciais-e-rotacao.md.
- Access token (
accessToken) — Tray API access token (expires in about 1 day — renew and update here).
Secrets are never re-displayed and are redacted in every error/log (raw token, URL-encoded, and in JSON).
Campos do formulário#
| Campo | Rótulo | Tipo | Obrigatório | Observação |
|---|---|---|---|---|
urlLoja | URL da loja | texto | sim | Endereço da loja na Tray; acrescentamos /web_api sozinhos se faltar. |
accessToken 🔒 | Access token | senha/segredo | sim | segredo (cifrado; cofre externo opcional); Token de acesso da API da Tray (expira em cerca de 1 dia — renove e atualize aqui). |
Passo a passo#
- No menu Dados → Conexões, use Nova conexão.
- Escolha Tray Commerce no catálogo.
- Preencha os campos do formulário (veja a tabela acima).
- Use Testar conexão. The result is shown broken down into Conectividade, Autenticação and Listagem/leitura — each with OK, Failed, Not applicable or Not tested. A capability with no test of its own for this connector shows as Not applicable, and Not applicable never counts as success.
- Use Salvar conexão. Salvar NÃO inicia ingestão nenhuma.
- No cartão da connection, use Montar extração (ou vá em Orquestração → Pipelines e use Conectar fonte). O pipeline aponta para a saved connection — a credencial não é copiada.
- Na revisão, Publicar (agenda desligada) cria a versão 1 sem executar nada. Depois, Ativar agenda e Executar agora são ações separadas.
Exemplo — teste de conexão#
Configuração de exemplo (todos os valores são fictícios; segredos aparecem mascarados):
# Exemplo sintético (valores fictícios — não são credenciais reais)
urlLoja = <urlLoja>
accessToken = •••••• (cifrado — nunca exibido)Resultado esperado#
Testar conexão returns the list of discovered tables/resources. After the first load, the rows appear in your workspace's Bronze layer, ready for the pipeline.
Limites e custos#
- Paginação: hard cap per run (default 10.000 páginas / 5.000.000 linhas); anti-loop guard.
- Carga SaaS: default
batchSize5.000,maxRows200.000 per resource. - Volume estimado: ~0.3 GB/month (catalog estimate, not measurement).
- Custo: the extraction itself is not charged by the platform; the Bronze load consumes datalake processing (billable).
Segurança#
- Escopo por workspace: each customer reads and writes only to their own datalake (
<prefixo>_bronze/_silver/_gold); there is never leakage between workspaces. - Segredos cifrados: sensitive material is encrypted with AES-256-GCM before being persisted. The external credentials vault is optional and enabled per connection; without it, the encrypted value is stored in the database. Changing the value here DOES NOT revoke the credential at the source.
- Redaction: every error/log is passed through secret redaction (raw, URL-encoded, and in JSON).
- Produção não finge: a path that would fall into a mock triggers the production guard (explicit failure instead of simulating success).
Erros comuns#
- Credencial recusada (401/403) — the provider rejected the credential: expired, revoked, or lacking required permission. Reconnect the source (the source and history are preserved; do not recreate the source).
- Limite de requisições (429) — the provider asked to wait. The extraction respects
Retry-Afterand retries; if it repeats, wait and reduce the schedule frequency. - Recurso não encontrado — check the resource identifier (account, object, report) and the granted permissions.
- Cursor de paginação travado — the extraction stops when the API cursor does not advance (anti-loop guard). If it happens in consecutive runs, open a support ticket indicating the connector and resource.
- Caminho de registros vazio — the response arrived without records in the expected path. Check the selected resource and filters (period, account, status) before assuming there is no data.
Troubleshooting#
- Use Testar conexão to isolate credential/network issues before scheduling.
- Monitor runs in the connector observability (error rate, p50/p95, freshness).
- A schema change in the source is signaled by schema drift (new column = info; removed column/type changed = attention).
Relacionados#
../conectores.md— catálogo de conectores por estado../ingestao-incremental-backfill.md— full, incremental by watermark, backfill and checkpoint../pipeline-medalhao.md— Bronze/Silver/Gold layers and quality../agendamento-retry-dlq.md— scheduling, retry/backoff and DLQ../custo-limites-seguranca.md— cost, limits and workspace security
Última revisão: 2026-10-04. Ficha gerada automaticamente do catálogo de conectores do produto.