Olist (Tiny)
Integração nativa · Somente leitura (pull) · Sincroniza automaticamente a cada 60 min (configurável) + sob demanda · Conexão via OAuth
O Olist, através do ERP Tiny, é uma plataforma de gestão para varejo e e-commerce. Conectado ao Dunning, ele traz os contatos e as contas a receber do seu Tiny para a operação de cobrança — os títulos em aberto viram cobranças e os contatos viram pessoas na sua carteira.
Pré-requisitos
- Uma conta Olist/Tiny com contatos e contas a receber.
- Um aplicativo OAuth cadastrado no portal de desenvolvedores do Olist/Tiny, apontando para a URL de callback do Dunning (veja a pendência abaixo).
Como conectar
:::note Sem tela dedicada no painel (ainda)
Hoje só o Gateway da Kobana tem tela de conexão pronta no painel. Para este ERP, a conexão é feita pela API (rotas /api/v1/integrations/...) — o passo a passo abaixo descreve o fluxo de autorização; a tela self-service equivalente no painel está no roadmap.
:::
O Olist/Tiny usa OAuth2: você autoriza o acesso na própria plataforma, sem colar tokens à mão.
- No Dunning, abra Configurações → Integrações e clique em Conectar no Olist.
- O Dunning gera um link seguro e redireciona você para o login do Olist/Tiny.
- Faça login e revise a tela de consentimento com os acessos solicitados.
- Autorize o acesso do Dunning.
- O Olist devolve você ao Dunning já conectado — os tokens ficam gravados cifrados e a integração fica ativa, com a primeira sincronização em seguida.
Depois de conectada, o token é renovado automaticamente; você só refaz o "Conectar" se o acesso for revogado.
De → Para: como os campos são mapeados
| Campo no Olist/Tiny | Campo no Dunning |
|---|---|
| Conta a receber | Cobrança |
valor | Valor |
dataVencimento | Vencimento |
data | Data de emissão |
dataPagamento | Data do pagamento |
numeroDocumento | Número do documento |
historico | Descrição |
situacao aberto / prevista / parcial / atrasada / emissão | pending (ou overdue se vencida) |
situacao pago / recebido | paid (baixa + saída da régua) |
situacao cancelado | cancelled |
situacao desconhecida | ignorada |
| Contato | Pessoa na carteira |
cpfCnpj | Documento da pessoa |
nome | Nome da pessoa |
Sincronização
A sincronização é idempotente e roda de forma automática (a cada 60 min por padrão) e manual (botão de sincronizar). Contatos e contas a receber são sincronizados no mesmo ciclo.
O que não faz / limitações
- Não emite títulos nem escreve de volta no Olist/Tiny — é pull-only.
- Sem webhooks. A API v3 não expõe webhooks de contas a receber para aplicativos, então pagamentos e cancelamentos aparecem no máximo no próximo ciclo de sincronização.
- Sem linha digitável/Pix/URL de pagamento vindos da origem — o pagamento é acompanhado pelo status.
Pendência: aplicativo OAuth no Olist
O "Conectar" depende de um aplicativo OAuth cadastrado no portal de desenvolvedores do Olist/Tiny, com a URL de callback do Dunning. As credenciais desse aplicativo (client ID e client secret) podem ser configuradas globalmente no ambiente do Dunning ou por integração. Sem esse aplicativo cadastrado, o fluxo de conexão não abre — é o passo de habilitação a cargo de quem administra o Olist.
Como desconectar ou reautorizar
Se o acesso for revogado (ou você quiser trocar de conta), refaça o "Conectar" para reautorizar. Enquanto a conexão está ativa, o token é renovado automaticamente.
Solução de problemas
- A sincronização está desatualizada. Confira o intervalo (padrão 60 min) e clique em Sincronizar agora.
- A conexão caiu. O acesso pode ter sido revogado no Olist/Tiny — refaça o "Conectar".
- Um contato não apareceu. O sync de contatos roda junto com o de contas a receber; um contato sem título é criado quando o primeiro título dele é sincronizado.
- Uma cobrança aparece duplicada. O Dunning deduplica por
externalId(olist:receivable:{id}); duplicidade real só ocorre com a mesma cobrança vinda de outra origem. - O "Conectar" não abre. Falta o aplicativo OAuth cadastrado no Olist (ou suas credenciais) — veja a pendência acima.
Segurança
O link de autorização carrega um state assinado (anti-CSRF) de uso único, os tokens são cifrados em repouso e as chamadas de token vão para o log com o corpo redigido — código e segredos nunca são registrados.