Introdução
Bem-vindo à documentação da API de E-commerce. Nossa API oferece um conjunto completo de endpoints para gerenciar todos os aspectos de sua plataforma de comércio eletrônico, incluindo:
- Gerenciamento de produtos e categorias
- Processamento de pedidos e carrinho de compras
- Gestão de clientes e endereços
- Controle de estoque e preços
- Processamento de pagamentos
- Gestão de promoções e cupons
A API segue os princípios REST e utiliza JSON para comunicação, permitindo uma integração simples e eficiente com sua plataforma de e-commerce.
Swagger UI
Para facilitar o teste e a integração com nossa API, disponibilizamos uma interface Swagger UI onde você pode:
- Visualizar todos os endpoints disponíveis
- Testar as requisições diretamente pelo navegador
- Verificar os schemas de request e response
- Autenticar-se e testar endpoints protegidos
Acesse o Swagger UI em:
https://api-integracao.agileecommerce.com.br/swaggerPara utilizar o Swagger UI:
- Acesse a URL do Swagger
- Clique no botão "Authorize" e insira seu token de acesso
- Escolha o endpoint que deseja testar
- Preencha os parâmetros necessários
- Clique em "Execute" para fazer a requisição
Autenticação
A API utiliza o protocolo OAuth 2.0 para autenticação e autorização. O processo inclui autenticação inicial e refresh token para manter a sessão ativa.
Obtendo Access Token e Refresh Token
Para obter os tokens iniciais, faça uma requisição POST com as credenciais do usuário:
POST /api/usuario/login
Content-Type: application/json
{
"client_id": "client_id",
"client_secret": "client_secret"
}
Resposta de sucesso:
{
"Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"RefreshToken": "def502009a3439...",
"Expiration": 3600
}
Usando o Access Token
Inclua o token em todas as requisições no header de autorização:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Renovando o Access Token
Quando o access token expirar, use o endpoint de refresh com o token anterior e o refresh token:
POST /api/usuario/refresh
Content-Type: application/json
{
"Token": "token_anterior_expirado",
"RefreshToken": "refresh_token_atual"
}
Resposta do refresh:
{
"Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"RefreshToken": "def502009a3439...",
"Expiration": 3600
}
Erros de Autenticação
{
"status": "error",
"code": "INVALID_CREDENTIALS",
"message": "Credenciais inválidas ou token expirado"
}Boas Práticas de Segurança
- Armazene os tokens de forma segura
- Renove o access token antes da sua expiração
- Use HTTPS para todas as comunicações
- Nunca compartilhe ou exponha os tokens
- Implemente tratamento de erros para falhas de autenticação
Exemplo de Endpoints
Coleções
Listar Coleções
GET /api/integracao/colecoes?fields=nome,id,ativo&page=2
Parâmetros de Query:
page: Número da página (default: 1)limit: Itens por página (default: 50, max: 250)sort: Campo para ordenação (ex: "nome")fields: Campos para consulta (ex: "id,nome,codigo,ean")
Resposta:
{
"meta": {
"page": 2,
"pages": 2,
"perPage": 50,
"total": 53,
"sort": "ASC",
"field": ""
},
"data": [
{
"nome": "Produtos em promoção",
"id": "col_promo_3",
"ativo": true
},
{
"nome": "Produtos em promoção",
"id": "col_promo_4",
"ativo": true
},
{
"nome": "Produtos em promoção",
"id": "col_promo_99",
"ativo": true
}
]
}
Criar/Atualizar Coleção
POST /api/integracao/colecoes
{
"nome": "nome da coleção",
"metadata": null,
"imagem": "",
"id_filial": "2",
"id": "1",
"ativo": false,
"link": "",
"codigo": "1",
"imagem_mobile": "",
"id_empresa": "1698203521854804",
"descricao": "",
"restrito": true,
"target": "_self",
"selo": ""
}
Resposta:
{
"success":{
"controller":"Integracao",
"code":"800",
"message":"sucesso"
},
"data":[
{
"nome": "nome da coleção",
"metadata": null,
"imagem": "",
"id_filial": "2",
"id": "1",
"ativo": false,
"link": "",
"codigo": "1",
"imagem_mobile": "",
"id_empresa": "1698203521854804",
"descricao": "",
"restrito": true,
"target": "_self",
"selo": ""
}
]
}
Deletar Coleção
DELETE /api/integracao/colecoes
[
{
"id": "1"
}
]
Resposta:
{
"success": {
"controller": "Integracao",
"code": "800",
"message": null
},
"data": null
}
Clientes
Listar Clientes
GET api/integracao/clientes?nome_fantasia:like=Ricardo&fields=nome_fantasia,id&limit=5
Resposta:
{
"meta": {
"page": 1,
"pages": 6,
"perPage": 5,
"total": 30,
"sort": "ASC",
"field": ""
},
"data": [
{
"nome_fantasia": "AÇOUGUE DO RICARDO",
"id": "12635609000116"
},
{
"nome_fantasia": "BAR DO RICARDO",
"id": "07797348000109"
},
{
"nome_fantasia": "BAR DO RICARDO",
"id": "09787970784"
},
{
"nome_fantasia": "BAR DO RICARDO ",
"id": "17530196000129"
},
{
"nome_fantasia": "BAR DO RICARDO",
"id": "27767544000130"
}
]
}
Pedidos
Listar Pedidos
GET api/integracao/pedidos?data:between=2023-10-08,2024-10-08&page=1&campos=id,valor,canal,aprovado&limit=5
Resposta:
{
"meta": {
"page": 1,
"pages": 5924,
"perPage": 5,
"total": 29619,
"sort": "ASC",
"field": ""
},
"data": [
{
"id": "1000065449",
"canal": "app",
"aprovado": true
},
{
"id": "1000064707",
"canal": "app",
"aprovado": false
},
{
"id": "1000065589",
"canal": "mobile",
"aprovado": false
},
{
"id": "1000065577",
"canal": "app",
"aprovado": false
},
{
"id": "1000065592",
"canal": "app",
"aprovado": false
}
]
}
Códigos de Status HTTP
A API utiliza os seguintes códigos de status HTTP:
- 200: Sucesso
- 201: Criado com sucesso
- 400: Requisição inválida
- 401: Não autorizado
- 403: Acesso proibido
- 404: Recurso não encontrado
- 429: Muitas requisições
- 500: Erro interno do servidor
Mensagens de Erro
Em caso de erro, a API retornará uma resposta no seguinte formato:
{
"error": {
"controller": "Integracao",
"code": "800",
"message": "Tabela não foi encontrada"
},
"data": null
}
Limites e Paginação
- Taxa limite: 100 requisições por minuto por IP
- Paginação máxima: 100 itens por página
-
Header de taxa limite:
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1705146000
Para paginar resultados, use os parâmetros page e limit nas requisições GET. A resposta incluirá metadata de paginação no objeto pagination.
Boas Práticas
- Sempre inclua o header
Content-Type: application/json - Armazene o token de forma segura
- Implemente retry com backoff exponencial para erros 429
- Utilize os parâmetros de paginação para grandes conjuntos de dados
- Use o Swagger UI para testar e validar suas integrações antes de ir para produção