Documentação da API

Guia completo para integração com a plataforma Tajir. Nossa API RESTful permite que você integre suas aplicações de forma simples e eficiente.

Introdução

Bem-vindo à documentação da API do Tajir! Nossa API RESTful permite que você integre suas aplicações com nossa plataforma de e-commerce, possibilitando automações, sincronização com ERPs, e construção de experiências personalizadas para seus clientes.

💡 Para quem é esta API?

• Desenvolvedores que desejam integrar sistemas externos com o Tajir
• Empresas que precisam sincronizar dados com ERPs (Tiny, Bling, etc.)
• Agências que constroem soluções customizadas para seus clientes

URL Base da API

https://api.tajir.com.br/api/v1

Todas as requisições devem usar HTTPS.

Primeiros Passos

Obtenha suas credenciais

Acesse o painel do Tajir em Integrações → Credenciais da API e crie uma nova chave de API. Guarde-a em local seguro — você só verá a chave completa uma vez!

Anote seus IDs

Você precisará do companyId para a maioria das requisições. Esses identificadores estão disponíveis na mesma página de Integrações.

Faça sua primeira requisição

Teste sua integração listando os orçamentos da sua loja:

bash

curl -X GET "https://api.tajir.com.br/api/v1/quotes?storefrontId=SEU_STOREFRONT_ID" \
  -H "x-api-key: SUA_API_KEY"

Formato das Requisições

Item	Descrição
Protocolo	HTTPS (obrigatório)
Content-Type	`application/json` para POST/PUT/PATCH
Autenticação	Header `x-api-key`
Encoding	UTF-8

Formato das Respostas

Todas as respostas da API seguem um formato padronizado em JSON:

✅ Resposta de Sucesso

json

{
  "status": "success",
  "data": { ... },
  "meta": {
    "timestamp": "2026-01-05T18:30:00Z",
    "requestId": "req_abc123"
  }
}

❌ Resposta de Erro

json

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": { ... }
  }
}

Autenticação

A API do Tajir utiliza API Keys para autenticar requisições e proteger seus dados. Cada chave está vinculada à sua empresa e permite acesso apenas aos recursos que pertencem a ela.

🔑 Como usar sua API Key

Inclua sua chave em todas as requisições através do header x-api-key:

bash

curl -X GET "https://api.tajir.com.br/api/v1/quotes?storefrontId=seu_id" \
  -H "x-api-key: tjr_sk_xxxxxxxxxxxxxxxxxxxxxxx"

Sobre sua API Key

🏢

Vinculada à empresa

Cada chave está associada a uma empresa específica e só acessa recursos dela.

🔒

Visível apenas uma vez

Por segurança, a chave completa só é exibida no momento da criação.

♻️

Revogável a qualquer momento

Você pode criar novas chaves e revogar as antigas quando necessário.

Endpoints Públicos vs Protegidos

Alguns endpoints são públicos e podem ser acessados sem autenticação — esses são destinados aos visitantes da sua loja. Os demais requerem uma API Key válida.

Endpoints Públicos

Sem autenticação • Para visitantes da loja

/storefront/info—Informações da loja
/storefront/banners—Banners promocionais
/storefront/collections—Coleções de produtos
/storefront/custom-forms—Formulários customizados

Endpoints Protegidos

Requerem API Key • Dados sensíveis

/quotes—Orçamentos
/customers—Clientes
/listings—Anúncios
/storefront/orders—Pedidos
E todos os outros endpoints...

Identificadores de Recursos

Além da API Key, você precisará fornecer identificadores para especificar qual recurso deseja acessar:

Identificador	Descrição	Onde encontrar
`companyId`	Identificador único da sua empresa	Integrações → Credenciais
`storefrontId`	Identificador único da sua loja virtual	Integrações → Credenciais
`customerId`	Identificador do cliente	Retornado pela API ao criar/listar

Segurança da API Key

Nunca exponha sua chave em código client-side (JavaScript do navegador, apps mobile, etc.)
Use variáveis de ambiente para armazenar a chave no seu servidor
Revogue imediatamente chaves que foram expostas acidentalmente
Crie chaves separadas para produção e desenvolvimento

Erros de Autenticação

Se a autenticação falhar, você receberá um dos seguintes erros:

401 Unauthorized

API Key não fornecida, inválida ou expirada.

403 Forbidden

API Key válida, mas sem permissão para acessar este recurso.

Códigos de Erro

A API utiliza códigos de status HTTP convencionais para indicar sucesso ou falha das requisições.

Código	Descrição
`200`	Sucesso - A requisição foi processada com êxito
`201`	Created - Recurso criado com sucesso
`400`	Bad Request - Parâmetros inválidos ou faltando
`401`	Unauthorized - API Key inválida ou não fornecida
`404`	Not Found - O recurso solicitado não foi encontrado
`422`	Validation Error - Dados inválidos no corpo da requisição
`500`	Internal Server Error - Erro interno do servidor

Formato de Resposta

Todas as respostas seguem um formato padronizado:

Resposta de Sucesso:

json

{
  "status": "success",
  "data": { ... },
  "meta": {
    "timestamp": "2026-01-05T18:30:00Z",
    "requestId": "req_abc123"
  }
}

Resposta de Erro:

json

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": { "email": ["E-mail inválido"] }
  },
  "meta": {
    "timestamp": "2026-01-05T18:30:00Z"
  }
}

Listings

Gerenciamento de anúncios e produtos publicados

Customers

Gerenciamento de clientes da loja

Products

Gerenciamento do catálogo de produtos

Quotes

Gerenciamento de orçamentos e cotações

Storefront

Informações e operações da loja virtual

Users

Gerenciamento de usuários da empresa

Storefronts

Listagem de lojas por empresa