Atenção: este recurso está em fase beta. O funcionamento, schema e cadência podem sofrer ajustes durante o período de validação. Clientes interessados em ativar devem alinhar previamente com o time da Linkana.

Os pipelines de dados são a forma da Linkana entregar dados de fornecedores de maneira recorrente e estruturada para os sistemas de BI, dashboards ou data warehouses do cliente. Em vez de depender de extrações manuais, o pipeline exporta automaticamente os dados para um bucket ou container na cloud do cliente (Google Cloud Storage ou Azure Blob Storage), de onde o time de dados consome com a ferramenta que preferir — BigQuery, Databricks, Power BI, Synapse, Python, entre outras.

O objetivo é que os dados da Linkana estejam disponíveis de forma confiável e padronizada dentro dos fluxos analíticos que já existem na empresa, sem trabalho manual recorrente.

Como funciona

O fluxo de um pipeline tem três etapas:

Extração — a Linkana extrai os dados da base, filtrados pelo cliente
Exportação — o arquivo CSV ou Parquet é depositado no bucket GCS do cliente
Consumo — o cliente acessa o bucket e integra os dados aos seus sistemas

Cada pipeline é executado automaticamente na recorrência acordada. O arquivo gerado sobrescreve a versão anterior no bucket, garantindo que o cliente sempre tenha acesso à versão mais recente dos dados.

Tabelas disponíveis

Atualmente, os pipelines cobrem as tabelas abaixo, que representam as principais dimensões da gestão de fornecedores:

Tabela	O que contém
suppliers	Fornecedores cadastrados
documents	Documentos ativos dos fornecedores (formulários, bases públicas e consultas)
form_fields	Respostas de perguntas de formulários
setting_risks	Configurações de risco dos documentos por categoria
qualifications	Homologações do fornecedor por categoria
approval_steps	Níveis de aprovadores das etapas de aprovação
performances	Respostas de avaliações de performance por ciclo
cnpj_records	Dados cadastrais do CNPJ do fornecedor (base pública da Receita)
tags	Marcadores aplicados ao fornecedor pelo comprador

O cliente contrata as tabelas de acordo com o caso de uso. Novas tabelas são comunicadas conforme forem disponibilizadas.

Formato e schema

Os arquivos são entregues em CSV ou Parquet, conforme a preferência do cliente definida na ativação. Nos arquivos CSV: encoding UTF-8, vírgula como delimitador, datas no padrão ISO 8601 e a primeira linha com os nomes dos campos.

Os dados refletem os valores originais do sistema — campos de estado, por exemplo, aparecem como clear, not_clear, in_progress. Não são aplicadas transformações de negócio customizadas, agregações ou cálculos derivados. O pipeline entrega os dados granulares da Linkana no nível mais detalhado disponível.

Dicionário de dados

Cada tabela tem um schema fixo. O dicionário abaixo descreve cada campo, seu tipo e os valores possíveis para campos enumerados.

suppliers (Fornecedores cadastrados)

Campo	Tipo	Descrição
`id`	uuid	ID único do fornecedor
`name`	string	Razão Social
`identifier`	string	CNPJ, CPF ou TIN
`legal_entity`	string	Tipo de pessoa. Valores: `pj` (Pessoa Jurídica / CNPJ), `pf` (Pessoa Física / CPF), `internacional` (pessoa ou empresa internacional)
`country`	string	País do fornecedor
`state`	string	Estado do fornecedor no fluxo. Valores: `pending_docs` (Aguardando fornecedor), `on_review` (Aguardando revisão), `no_pending_issues` (Sem pendências)
`created_at`	datetime	Data de criação do registro
`updated_at`	datetime	Data da última atualização do registro

documents (Documentos ativos dos fornecedores)

Campo	Tipo	Descrição
`id`	uuid	ID único do documento
`documentable_id`	uuid	ID do objeto associado (BankInformation, FormGroup, Certificate ou Check)
`expires_on`	date	Data de validade do documento
`renew_at`	datetime	Data da próxima renovação
`reviewed_at`	datetime	Data de revisão
`reviewed_by`	string	E-mail do revisor
`reviewer_refusal_reason`	string	Motivo da reprovação
`sender_email`	string	E-mail de quem enviou o documento
`sent_at`	datetime	Data de envio/geração
`setting_document_id`	uuid	Referência às configurações do documento
`state`	string	Situação do documento. Valores: `processing` (Pendente), `clear` (Aprovado), `not_clear` (Reprovado), `pending_review` (Aguardando revisão), `informative` (Informativo)
`supplier_id`	uuid	ID do fornecedor
`display_name`	string	Nome de exibição do documento
`grouper_display_name`	string	Grupo de revisão
`created_at`	datetime	Data de criação
`updated_at`	datetime	Data de atualização

form_fields (Respostas de perguntas de formulários)

Campo	Tipo	Descrição
`id`	uuid	ID único
`answer`	string	Resposta da pergunta
`form_group_id`	uuid	Referência ao grupo de formulário. Para cruzar com `documents`, usar `form_group_id = documentable_id`
`display_name`	string	Nome da pergunta
`field_type`	string	Tipo de resposta
`hint`	string	Dica para a resposta
`optional`	boolean	Se a resposta é opcional
`created_at`	datetime	Data de criação
`updated_at`	datetime	Data de atualização

setting_risks (Configurações de risco do documento por categoria)

Campo	Tipo	Descrição
`id`	uuid	ID único
`risk`	integer	Pontuação de risco do documento
`category_id`	uuid	Referência à categoria
`setting_document_id`	uuid	Referência às configurações do documento
`created_at`	datetime	Data de criação
`updated_at`	datetime	Data de atualização

qualifications (Homologações do fornecedor por categoria)

Campo	Tipo	Descrição
`id`	uuid	ID único da homologação
`decision_at`	datetime	Data da decisão
`decision_score`	integer	Score de risco no momento da decisão
`initiated_by_email`	string	E-mail do usuário que iniciou a homologação
`renew_at`	datetime	Data da próxima renovação da homologação
`state`	string	Situação da homologação. Valores: `approved` (Aprovada), `in_progress` (Em andamento), `refused` (Reprovada)
`category_id`	uuid	Referência à categoria
`category_display_name`	string	Categoria
`supplier_id`	uuid	ID do fornecedor
`created_at`	datetime	Data de criação
`updated_at`	datetime	Data de atualização

approval_steps (Níveis de aprovadores das etapas de aprovação)

Campo	Tipo	Descrição
`id`	uuid	ID único
`approver_user_email`	string	E-mail do usuário aprovador
`decision_at`	datetime	Data da decisão
`decision_reason`	string	Motivo padronizado (opcional para aprovação, obrigatório para reprovação)
`display_name`	string	Nome do nível de aprovação
`state`	string	Situação do nível. Valores: `pending` (Pendente), `approved` (Aprovado), `refused` (Reprovado)
`approval_step_last_decision_at`	datetime	Data da última decisão tomada na etapa
`qualification_id`	uuid	Referência à homologação
`approval_step_requester_user_email`	string	E-mail do usuário que acionou a etapa, se condição de aprovação por exceção
`approval_step_skipped`	boolean	Se a etapa foi substituída por uma de aprovação por exceção
`approval_step_state`	string	Situação da etapa. Valores: `pending` (Pendente), `approved` (Aprovado), `refused` (Reprovado)
`approval_step_display_name`	string	Nome da etapa
`created_at`	datetime	Data de criação
`updated_at`	datetime	Data de atualização

performances (Respostas de avaliações de performance por ciclo)

Campo	Tipo	Descrição
`id`	uuid	ID único
`answer`	string	Resposta da pergunta
`criterion`	string	Critério. Valores: `scale_1_to_5` (Escala de 1 a 5), `yes_or_no` (Sim ou Não)
`display_name`	string	Nome da pergunta
`score`	integer	Score calculado
`skipped`	boolean	Se a pergunta foi ignorada
`weight`	integer	Peso da pergunta
`pillar_display_name`	string	Nome do pilar
`pillar_score`	integer	Score do pilar
`pillar_weight`	integer	Peso do pilar
`evaluation_display_name`	string	Nome da avaliação
`evaluation_identifier`	string	Identificador único interno do cliente
`evaluation_score`	integer	Score da avaliação
`evaluation_state`	string	Situação da avaliação. Valores: `pending` (Pendente), `answering` (Parcialmente respondida), `answered` (Respondida)
`supplier_id`	uuid	ID do fornecedor
`evaluation_user_email`	string	E-mail do usuário que iniciou a avaliação
`cycle_active`	boolean	Se é o ciclo atual do cliente
`cycle_display_name`	string	Nome do ciclo
`created_at`	datetime	Data de criação
`updated_at`	datetime	Data de atualização

cnpj_records (Dados cadastrais do CNPJ)

Informações consultadas em dados públicos da Receita Federal. Fornecedores Pessoa Física ou internacionais não têm registro nesta tabela.

Campo	Tipo	Descrição
`id`	uuid	ID único do registro
`supplier_id`	uuid	ID do fornecedor
`cnpj`	string	CNPJ do fornecedor
`razao_social`	string	Razão social
`nome_fantasia`	string	Nome fantasia
`mf`	string	Indicador matriz/filial (1 = matriz)
`cod_situacao_cadastral`	string	Código da situação cadastral
`data_situacao_cadastral`	date	Data da situação cadastral
`cod_porte_empresa`	integer	Código do porte da empresa
`cod_natureza_juridica`	integer	Código da natureza jurídica
`cnae_fiscal`	string	CNAE fiscal principal
`cnaes_secundarios`	string	CNAEs secundários, separados por vírgula
`data_inicio_atividade`	date	Data de início de atividade
`capital_social`	integer	Capital social em centavos (dividir por 100 para reais)
`forma_tributacao`	string	Regime tributário da empresa. Valores: `simples_nacional` (Simples Nacional), `simei` (Simples Nacional / MEI), `lucro_presumido` (Lucro Presumido), `lucro_real` (Lucro Real), `lucro_arbitrado` (Lucro Arbitrado), `imune` (Imune), `isento` (Isento), `null` (Não identificado)
`desc_tipo_logradouro`	string	Tipo de logradouro (Rua, Avenida, etc.)
`logradouro`	string	Logradouro
`numero`	string	Número do endereço
`complemento`	string	Complemento do endereço
`bairro`	string	Bairro
`descricao_municipio`	string	Município
`uf`	Unidade federativa
`cep`	string	CEP
`correio_eletronico`	string	E-mail de contato
`ddd1`	string	DDD do telefone principal
`telefone1`	string	Telefone principal
`created_at`	datetime	Data de criação
`updated_at`	datetime	Data de atualização

tags (Marcadores do fornecedor)

Marcadores que o comprador aplica ao fornecedor para organização e segmentação da base.

Campo	Tipo	Descrição
`id`	uuid	ID único do marcador
`supplier_id`	uuid	ID do fornecedor
`display_name`	string	Nome do marcador
`created_at`	datetime	Data de criação
`updated_at`	datetime	Data de atualização

Como cruzar as tabelas

As tabelas podem ser combinadas para responder perguntas de negócio mais completas. Alguns exemplos práticos:

Risco de um documento por categoria: cruzar documents com setting_risks pelo setting_document_id. O category_id em setting_risks indica a qual categoria a pontuação se aplica.
Resposta de um formulário e sua situação: cruzar documents com form_fields ligando documentable_id (de documents) a form_group_id (de form_fields). O answer traz a resposta e o state de documents a situação (ex.: clear = aprovado).
Quem aprovou ou reprovou na homologação: usar approval_steps — approver_user_email, decision_at e decision_reason — ligando à homologação por qualification_id.
Desempenho de um fornecedor: agrupar performances por supplier_id; evaluation_score traz o score consolidado e pillar_score o score por pilar.
Dados cadastrais e marcadores: cruzar cnpj_records e tags com suppliers pelo supplier_id.

Links diretos para objetos na Linkana

Com os IDs dos dados exportados, é possível montar links diretos para os objetos na plataforma:

Objeto	URL	Campo utilizado
Fornecedor	`https://app.linkana.com/srm/suppliers/{supplier_id}/panel`	`supplier_id` (ou `id` de suppliers)
Documento	`https://app.linkana.com/srm/documents/{document_id}`	`id` de documents

Recorrência

A recorrência padrão de atualização é diária para todas as tabelas.

Acesso aos dados

Os dados são disponibilizados num bucket ou container dedicado por cliente, na cloud de sua preferência (Google Cloud Storage ou Azure Blob Storage). O acesso é sempre somente leitura e permanece sob controle do cliente.

Google Cloud Storage

O acesso é controlado via Service Account do Google Cloud com permissão apenas de leitura, em duas opções:

Opção preferencial: o cliente fornece uma Service Account própria e a Linkana concede permissão de leitura (storage.objectViewer) ao bucket. Recomendada porque o cliente mantém controle total sobre as credenciais e pode integrá-las diretamente aos seus pipelines.

Opção alternativa: caso o cliente não possua uma Service Account própria, a Linkana cria uma dedicada e compartilha a chave (JSON) de forma segura por link temporário. Em caso de rotação ou perda da chave, o cliente solicita uma nova via suporte.

Microsoft Azure — Blob Storage

Os dados ficam num container do Azure Blob Storage. Para conceder acesso de forma segura, o cliente cria uma identidade no Microsoft Entra ID autorizada a ler o container — mantendo controle total para rotacionar credenciais ou revogar o acesso a qualquer momento, sem depender da Linkana.

Pré-requisitos: conta Azure com permissão para criar App Registrations no Entra ID do tenant do cliente e acesso a portal.azure.com.

Passo a passo, do lado do cliente:

Criar uma App Registration — no portal Azure, abra Microsoft Entra ID → App registrations → New registration. Preencha: Name linkana-data-access (ou outro de preferência); Supported account types = "Accounts in any organizational directory (Any Microsoft Entra ID tenant — Multitenant)" (sem isso a configuração não funciona); Redirect URI em branco. Clique em Register.
Coletar IDs — na aba Overview da App Registration, copie o Application (client) ID e o Directory (tenant) ID.
Gerar um Client Secret — em Certificates & secrets → New client secret, gere o segredo e guarde o valor com segurança.
Enviar para a Linkana — envie apenas o Application (client) ID e o Tenant ID. Não envie o Client Secret: ele fica somente com o cliente. A Linkana nunca precisa do segredo, só dos dois identificadores.

Do lado da Linkana: fazemos o admin consent do app no nosso tenant (provisiona uma referência da identidade do cliente no nosso diretório) e atribuímos a role Storage Blob Data Reader sobre o container, concedendo acesso somente leitura.

Atenção: se vocês usam outro provedor de cloud, entrem em contato com o gestor de conta da Linkana para análise de viabilidade técnica.

Estrutura das pastas no bucket

gs://{bucket}/lk-{cliente}/exports/
    suppliers/
    documents/
    form_fields/
    setting_risks/
    qualifications/
    approval_steps/
    performances/
    cnpj_records/
    tags/

A mesma estrutura de pastas se aplica ao container do Azure Blob Storage. As pastas com prefixo _dlt (como _dlt_loads, _dlt_pipeline_state, _dlt_version) são de controle interno do pipeline de exportação e podem ser ignoradas na integração.

Processo de ativação

A ativação é imediata: todas as tabelas são disponibilizadas assim que o cliente responder:

Qual o provedor de cloud? (Google Cloud ou Microsoft Azure)
Se for Google Cloud, o cliente fornece a Service Account ou precisa que a Linkana crie uma?
Prefere receber os dados em CSV ou Parquet?

Com essas respostas e o acesso configurado (conforme a seção "Acesso aos dados"), o pipeline entra em operação.

Alterações de schema e SLA

A Linkana comunica alterações no schema com no mínimo 30 dias de antecedência, garantindo tempo hábil para que o time de dados ajuste suas integrações antes da aplicação.

Em caso de falha na exportação, o time da Linkana é notificado automaticamente. O pipeline é reprocessado e o cliente é informado sobre eventuais atrasos.

Perguntas frequentes

Os dados são incrementais ou full load?

Sempre full load. Cada exportação contém todos os registros válidos no momento da extração.

Posso pedir campos customizados?

Em geral, não. O schema de cada pipeline segue os campos padrão disponíveis na Linkana. Se um campo novo for adicionado à plataforma e for relevante para o seu caso de uso, ele pode ser incluído no pipeline mediante alinhamento prévio.

Posso usar com BigQuery, Databricks, Power BI ou ferramentas do Azure?

Sim. O bucket (Google Cloud Storage) ou o container (Azure Blob Storage) é acessível por qualquer ferramenta que suporte leitura desses storages. No Google Cloud, o BigQuery cria tabelas externas diretamente sobre os arquivos; no Azure, ferramentas como Synapse, Databricks e Power BI leem o container diretamente.

Como sei se o pipeline foi executado com sucesso?

A presença do arquivo atualizado no bucket indica que a execução foi bem-sucedida. Em caso de falha, o time da Linkana é notificado automaticamente e comunica o cliente sobre o status.

Com quem eu falo sobre problemas no pipeline?

Pelo canal de suporte habitual da Linkana (e-mail ou plataforma), referenciando o nome do pipeline e a data do arquivo.

Como funcionam os pipelines de dados? (Beta)