Integração com o ERP

A API de integração permite que o sistema da sua empresa (o ERP) envie para o TkCotação os fornecedores e os produtos, em lote, sem digitação. Este artigo é para quem faz a integração.

Para que serve

Manter a base de fornecedores e de produtos da plataforma igual à do ERP. É por essa importação que os fornecedores entram na sua base: a tela Fornecedores só lista e convida.

O que a API faz

Há dois endpoints de importação, ambos com POST e corpo em JSON (uma lista de itens):

• Cada item é identificado pelo seu código (code). Se o código já existe, o item é atualizado; se não, é criado.
• Cada produto aponta para o seu fornecedor pelo supplier_code. É assim que a plataforma sabe quem recebe a cotação de cada produto.
• O que for importado entra na empresa da chave de API usada.
• O limite é de 500 itens por requisição, no envio de fornecedores. Para mais, envie em lotes.

A referência técnica completa, com todos os campos e exemplos, está em api.sync.tkcotacao.com.br/reference.

Autenticar com a chave de API

Toda requisição leva a chave no cabeçalho X-API-KEY. Crie a chave em Configurações → API Keys (veja Chaves de API).

curl -X POST "https://api.sync.tkcotacao.com.br/api/analytics/suppliers/import" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: SUA_CHAVE_AQUI" \
  -d '[
    {
      "code": "FOR-001",
      "name": "Distribuidora Alfa Ltda",
      "document": "11.111.111/0001-91",
      "contact_name": "Carlos Alfa",
      "email": "alfa@exemplo.com.br",
      "phone": "(11) 91111-0001"
    }
  ]'

Sem chave, ou com chave inválida, a resposta é 401.

Importar fornecedores

Campos de cada fornecedor:

Importar produtos

curl -X POST "https://api.sync.tkcotacao.com.br/api/analytics/products/import" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: SUA_CHAVE_AQUI" \
  -d '[
    {
      "code": "PROD-001",
      "name": "Farinha de trigo 25 kg",
      "unit": "SC",
      "stock": 50,
      "price": 120.00,
      "supplier_code": "FOR-001",
      "is_active": true
    }
  ]'

Campos de cada produto: code, name e supplier_code são obrigatórios; unit, stock, price, description e is_active completam o cadastro.

A resposta

Quando a importação funciona, a resposta é 200 com o resumo:

{ "status": 200, "sent": 1, "saved": 1, "updated": 0, "unsaved": 0, "unsaved_items": [] }

• sent: quantos itens você enviou;
• saved: quantos foram criados;
• updated: quantos já existiam e foram atualizados;
• unsaved e unsaved_items: os itens recusados, com o index da linha e a lista de erros de cada um.

Se só algumas linhas forem recusadas, o restante é importado e as recusadas voltam em unsaved_items. Os erros da API estão em Erros da API.

Perguntas frequentes

Importei duas vezes o mesmo fornecedor. Duplicou?

Não. O code identifica o fornecedor: na segunda vez, updated vira 1 e os dados são atualizados.

Para quais empresas a importação vale?

Para a empresa da chave. Se você tem mais de uma empresa, crie uma chave para cada uma.

Posso excluir um fornecedor ou um produto pela API?

Os endpoints de importação criam e atualizam. Eles não oferecem exclusão.

Artigos relacionados

• Chaves de API
• Erros da API