Documentação da API

Integre sua aplicação com nossa plataforma via REST API.

Autenticação: Todas as requisições devem incluir o header Authorization: Bearer SEU_TOKEN.
Gere sua chave de API em Configurações → Integrações → API no painel.
Base URL https://elephantfy.com.br/api/v1
GET

Visão geral

GET /api/v1/{recurso}

Todas as requisições à API da Elephantfy precisam de um Bearer token no header **Authorization**.

```
Authorization: Bearer ef_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Gere sua chave em **Painel → Configurações → Integrações → API Keys**.

**Escopos disponíveis:**
- `read` — leitura (GET)
- `write` — escrita (POST, PATCH, PUT, DELETE)

**Rate limiting:** até 1.000 requisições por hora por chave.

Erro de autenticação:
```json
{"status":"error","code":401,"message":"Missing or invalid Authorization header"}
```

Exemplo de Resposta
{
    "status": "error",
    "code": 401,
    "message": "Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"
}
GET

Listar clientes

GET /api/v1/customers

Retorna a lista paginada de clientes da loja.

Cada item já inclui o array `addresses` com os endereços do cliente e o campo `metadata` (conteúdo de `custom_fields` decodificado como objeto JSON).

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Número da página (padrão: 1)
per_page integer opcional Itens por página, máx 100 (padrão: 20)
search string opcional Busca por nome, e-mail ou telefone
status integer opcional 1 = ativo, 0 = inativo
lifecycle_stage string opcional Filtrar por estágio: lead, prospect, active, inactive, lost
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": [
        {
            "id": "1042",
            "name": "Ana Lima",
            "email": "ana.lima@exemplo.com",
            "phone": "(11) 99123-4567",
            "document": "123.456.789-09",
            "birth_date": null,
            "company_name": null,
            "lifecycle_stage": "lead",
            "status": "1",
            "metadata": null,
            "created_at": "2026-01-15 09:30:00",
            "addresses": []
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    }
}
GET

Detalhe do cliente

GET /api/v1/customers/{id}

Retorna os dados completos de um cliente, incluindo o array `addresses` (endereços da tabela `customer_addresses`) e o campo `metadata` (objeto JSON decodificado de `custom_fields`).

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do cliente
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": {
        "id": "1042",
        "name": "Ana Lima",
        "email": "ana.lima@exemplo.com",
        "phone": "(11) 99123-4567",
        "document": "123.456.789-09",
        "company_name": null,
        "website": null,
        "instagram_handle": null,
        "lifecycle_stage": "lead",
        "source": null,
        "birth_date": null,
        "do_not_call": 0,
        "do_not_email": 0,
        "status": "1",
        "metadata": null,
        "created_at": "2026-01-15 09:30:00",
        "updated_at": "2026-01-15 09:30:00",
        "addresses": []
    }
}
POST

Criar cliente

POST /api/v1/customers

Cria um novo cliente na loja.

Campo obrigatório: `name`.

Endereços devem ser adicionados separadamente via `POST /customers/{id}/addresses`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "name": "Carlos Mendes",
    "email": "carlos@exemplo.com",
    "phone": "11988887777",
    "document": "987.654.321-00",
    "company_name": null,
    "website": null,
    "instagram_handle": null,
    "lifecycle_stage": "lead",
    "source": "instagram",
    "birth_date": "1990-04-15",
    "do_not_call": 0,
    "do_not_email": 0,
    "custom_fields": {
        "origem_campanha": "black_friday",
        "vendedor": "joao"
    }
}
Exemplo de Resposta
{
    "status": "success",
    "code": 201,
    "message": "Customer created",
    "data": {
        "id": 42,
        "name": "Carlos Mendes",
        "email": "carlos@exemplo.com",
        "phone": "11988887777",
        "document": "987.654.321-00",
        "company_name": null,
        "lifecycle_stage": "lead",
        "status": "1",
        "metadata": {
            "origem_campanha": "black_friday",
            "vendedor": "joao"
        },
        "created_at": "2026-05-08 10:00:00",
        "addresses": []
    }
}
PUT

Atualizar cliente

PUT /api/v1/customers/{id}

Atualiza os dados de um cliente existente.

Envie apenas os campos que deseja alterar. Campos aceitos: `name`, `email`, `phone`, `document`, `company_name`, `website`, `instagram_handle`, `lifecycle_stage`, `source`, `birth_date`, `internal_notes`, `custom_fields`, `do_not_call`, `do_not_email`, `status`.

Escopo necessário: `write`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do cliente
Exemplo de Requisição
{
    "phone": "11977776666",
    "lifecycle_stage": "active",
    "do_not_email": 1,
    "custom_fields": {
        "origem_campanha": "black_friday",
        "vendedor": "maria"
    }
}
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "message": "Customer updated",
    "data": {
        "id": 42,
        "name": "Carlos Mendes",
        "phone": "11977776666",
        "lifecycle_stage": "active",
        "do_not_email": 1,
        "metadata": {
            "origem_campanha": "black_friday",
            "vendedor": "maria"
        },
        "updated_at": "2026-05-08 10:05:00"
    }
}
GET

Listar endereços

GET /api/v1/customers/{id}/addresses

Retorna todos os endereços cadastrados para o cliente, ordenados por `is_default DESC, id ASC`.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do cliente
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": [
        {
            "id": 1,
            "label": "Casa",
            "recipient_name": "Ana Lima",
            "phone": null,
            "cep": "01310100",
            "address1": "Rua das Flores",
            "number": "100",
            "complement": null,
            "neighborhood": "Bela Vista",
            "city": "São Paulo",
            "state": "SP",
            "is_default": 1,
            "created_at": "2026-01-15 09:30:00",
            "updated_at": "2026-01-15 09:30:00"
        },
        {
            "id": 2,
            "label": "Trabalho",
            "recipient_name": null,
            "phone": "11988887777",
            "cep": "01311100",
            "address1": "Av. Paulista",
            "number": "900",
            "complement": "Sala 12",
            "neighborhood": "Bela Vista",
            "city": "São Paulo",
            "state": "SP",
            "is_default": 0,
            "created_at": "2026-01-15 10:00:00",
            "updated_at": "2026-01-15 10:00:00"
        }
    ]
}
POST

Criar endereço

POST /api/v1/customers/{id}/addresses

Adiciona um novo endereço ao cliente.

Campos obrigatórios: `address1`, `city`, `cep`.

Se `is_default: 1`, os demais endereços do cliente terão `is_default` removido automaticamente.

Escopo necessário: `write`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do cliente
Exemplo de Requisição
{
    "label": "Trabalho",
    "recipient_name": "Carlos Mendes",
    "phone": "11988887777",
    "cep": "01311100",
    "address1": "Av. Paulista",
    "number": "900",
    "complement": "Sala 12",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "is_default": 0
}
Exemplo de Resposta
{
    "status": "success",
    "code": 201,
    "message": "Address created",
    "data": {
        "id": 3,
        "label": "Trabalho",
        "recipient_name": "Carlos Mendes",
        "phone": "11988887777",
        "cep": "01311100",
        "address1": "Av. Paulista",
        "number": "900",
        "complement": "Sala 12",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "is_default": 0,
        "created_at": "2026-05-08 10:10:00",
        "updated_at": "2026-05-08 10:10:00"
    }
}
DELETE

Deletar endereço

DELETE /api/v1/customers/{id}/addresses/{aid}

Remove um endereço específico do cliente.

Escopo necessário: `write`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do cliente
aid integer obrigatório ID do endereço a ser removido
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "message": "Address deleted",
    "data": null
}
GET

Listar produtos

GET /api/v1/products

Retorna a lista paginada de produtos ativos da loja.

Produtos do tipo `variable` retornam o array `variants` com as variações disponíveis.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Número da página (padrão: 1)
per_page integer opcional Itens por página, máx 100 (padrão: 20)
search string opcional Busca por nome, SKU ou marca
category integer opcional Filtrar por ID da categoria
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": [
        {
            "id": 1,
            "name": "Camiseta Básica",
            "sku": "CAM-001",
            "slug": "camiseta-basica",
            "brand": "Nike",
            "category": 5,
            "price": "89.90",
            "promotional_price": "69.90",
            "quantity": 150,
            "active": 1,
            "type": "variable",
            "variants": [
                {
                    "id": 12,
                    "sku": "CAM-001-P-PRETO",
                    "title": "P \/ Preto",
                    "price": "89.90",
                    "stock_qty": 30,
                    "attributes": [
                        {
                            "attribute": "Tamanho",
                            "value": "P"
                        },
                        {
                            "attribute": "Cor",
                            "value": "Preto"
                        }
                    ]
                }
            ]
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    }
}
GET

Detalhe do produto

GET /api/v1/products/{id}

Retorna todos os dados de um produto, incluindo descrição completa, dimensões, peso e todas as variações ativas.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do produto
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": {
        "id": 1,
        "name": "Camiseta Básica",
        "sku": "CAM-001",
        "slug": "camiseta-basica",
        "details": "<p>Algodão premium 100%...<\/p>",
        "short_description": "Camiseta 100% algodão",
        "brand": "Nike",
        "category": 5,
        "price": "89.90",
        "promotional_price": "69.90",
        "quantity": 150,
        "unit": "un",
        "weight": "0.30",
        "length": "30.00",
        "width": "20.00",
        "height": "2.00",
        "active": 1,
        "type": "variable",
        "variants": [
            {
                "id": 12,
                "sku": "CAM-001-P-PRETO",
                "barcode": "7891234560001",
                "title": "P \/ Preto",
                "price": "89.90",
                "promotional_price": "69.90",
                "cost_price": "35.00",
                "stock_qty": 30,
                "min_stock": 5,
                "active": 1,
                "attributes": [
                    {
                        "attribute": "Tamanho",
                        "value": "P"
                    },
                    {
                        "attribute": "Cor",
                        "value": "Preto"
                    }
                ]
            },
            {
                "id": 13,
                "sku": "CAM-001-M-PRETO",
                "barcode": "7891234560002",
                "title": "M \/ Preto",
                "price": "89.90",
                "promotional_price": "69.90",
                "cost_price": "35.00",
                "stock_qty": 25,
                "min_stock": 5,
                "active": 1,
                "attributes": [
                    {
                        "attribute": "Tamanho",
                        "value": "M"
                    },
                    {
                        "attribute": "Cor",
                        "value": "Preto"
                    }
                ]
            }
        ]
    }
}
POST

Criar produto

POST /api/v1/products

Cria um novo produto na loja.

Campo obrigatório: `name`.

Para produtos com variações (cores, tamanhos), use `type: "variable"` e adicione as variantes depois via `POST /products/{id}/variants`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "name": "Tênis Runner Pro",
    "sku": "TEN-001",
    "type": "simple",
    "price": "299.90",
    "promotional_price": "249.90",
    "cost_price": "120.00",
    "quantity": 50,
    "unit": "par",
    "weight": "0.700",
    "category": 8,
    "active": 1
}
Exemplo de Resposta
{
    "status": "success",
    "code": 201,
    "message": "Product created",
    "data": {
        "id": 99,
        "name": "Tênis Runner Pro",
        "sku": "TEN-001",
        "type": "simple",
        "price": "299.90",
        "promotional_price": "249.90",
        "quantity": 50,
        "active": 1,
        "created_at": "2026-05-06 10:00:00"
    }
}
PUT

Atualizar produto

PUT /api/v1/products/{id}

Atualiza os dados de um produto existente.

Envie apenas os campos que deseja alterar.

Escopo necessário: `write`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do produto
Exemplo de Requisição
{
    "price": "279.90",
    "promotional_price": "229.90",
    "quantity": 35
}
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "message": "Product updated",
    "data": {
        "id": 99,
        "price": "279.90",
        "promotional_price": "229.90",
        "quantity": 35,
        "updated_at": "2026-05-06 10:10:00"
    }
}
GET

Listar variantes

GET /api/v1/products/{id}/variants

Retorna todas as variantes ativas de um produto do tipo `variable`.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do produto
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": [
        {
            "id": 12,
            "sku": "CAM-001-P-PRETO",
            "barcode": "7891234560001",
            "title": "P \/ Preto",
            "price": "89.90",
            "promotional_price": "69.90",
            "stock_qty": 30,
            "min_stock": 5,
            "active": 1,
            "attributes": [
                {
                    "attribute": "Tamanho",
                    "value": "P"
                },
                {
                    "attribute": "Cor",
                    "value": "Preto"
                }
            ]
        },
        {
            "id": 13,
            "sku": "CAM-001-M-PRETO",
            "barcode": "7891234560002",
            "title": "M \/ Preto",
            "price": "89.90",
            "promotional_price": "69.90",
            "stock_qty": 25,
            "min_stock": 5,
            "active": 1,
            "attributes": [
                {
                    "attribute": "Tamanho",
                    "value": "M"
                },
                {
                    "attribute": "Cor",
                    "value": "Preto"
                }
            ]
        }
    ]
}
POST

Criar variante

POST /api/v1/products/{id}/variants

Adiciona uma nova variante a um produto do tipo `variable`.

Campo obrigatório: `title`.

Escopo necessário: `write`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do produto
Exemplo de Requisição
{
    "title": "GG \/ Preto",
    "sku": "CAM-001-GG-PRETO",
    "barcode": "7891234560003",
    "price": "89.90",
    "promotional_price": "69.90",
    "cost_price": "35.00",
    "stock_qty": 20,
    "min_stock": 3,
    "active": 1
}
Exemplo de Resposta
{
    "status": "success",
    "code": 201,
    "message": "Variant created",
    "data": {
        "id": 14,
        "title": "GG \/ Preto",
        "sku": "CAM-001-GG-PRETO",
        "price": "89.90",
        "stock_qty": 20,
        "active": 1
    }
}
GET

Listar categorias

GET /api/v1/categories

Retorna todas as categorias de produtos da loja.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Número da página (padrão: 1)
per_page integer opcional Itens por página (padrão: 20)
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": [
        {
            "id": 1,
            "name": "Roupas",
            "slug": "roupas",
            "status": 1
        },
        {
            "id": 2,
            "name": "Calçados",
            "slug": "calcados",
            "status": 1
        },
        {
            "id": 3,
            "name": "Acessórios",
            "slug": "acessorios",
            "status": 1
        }
    ]
}
POST

Criar categoria

POST /api/v1/categories

Cria uma nova categoria de produtos.

Campo obrigatório: `name`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "name": "Esportes",
    "parent_id": null
}
Exemplo de Resposta
{
    "status": "success",
    "code": 201,
    "message": "Category created",
    "data": {
        "id": 10,
        "name": "Esportes",
        "slug": "esportes",
        "status": 1
    }
}
GET

Listar pedidos

GET /api/v1/orders

Retorna a lista paginada de pedidos da loja.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Número da página (padrão: 1)
per_page integer opcional Itens por página, máx 100 (padrão: 20)
search string opcional Busca por número do pedido
customer_id integer opcional Filtrar por cliente
status string opcional pending | approved | canceled | completed
payment_status string opcional pending | partial | paid
fulfillment_status string opcional pending | processing | shipped | delivered | canceled
date_from string opcional Data inicial (YYYY-MM-DD)
date_to string opcional Data final (YYYY-MM-DD)
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": [
        {
            "id": 1,
            "order_number": "EF-20260101-0001",
            "customer_id": 1,
            "customer_name": "Ana Lima",
            "status": "approved",
            "payment_status": "paid",
            "fulfillment_status": "processing",
            "total": "199.80",
            "shipping_amount": "15.00",
            "created_at": "2026-01-01 10:00:00"
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    }
}
GET

Detalhe do pedido

GET /api/v1/orders/{id}

Retorna os dados completos de um pedido, incluindo itens, endereço de entrega e histórico de status.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do pedido
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": {
        "id": 1,
        "order_number": "EF-20260101-0001",
        "customer_id": 1,
        "customer_name": "Ana Lima",
        "customer_email": "ana@exemplo.com",
        "status": "approved",
        "payment_status": "paid",
        "fulfillment_status": "processing",
        "subtotal": "184.80",
        "discount_amount": "0.00",
        "shipping_amount": "15.00",
        "total": "199.80",
        "paid_amount": "199.80",
        "notes": "Embrulho para presente",
        "shipping_address": {
            "name": "Ana Lima",
            "address": "Rua das Flores, 100",
            "city": "São Paulo",
            "state": "SP",
            "postal_code": "01310-100"
        },
        "items": [
            {
                "id": 1,
                "product_id": 1,
                "variant_id": 12,
                "name": "Camiseta Básica — P \/ Preto",
                "sku": "CAM-001-P-PRETO",
                "qty": 2,
                "unit_price": "89.90",
                "line_total": "179.80"
            },
            {
                "id": 2,
                "product_id": 5,
                "variant_id": null,
                "name": "Meia Esportiva",
                "sku": "MEI-001",
                "qty": 1,
                "unit_price": "5.00",
                "line_total": "5.00"
            }
        ],
        "created_at": "2026-01-01 10:00:00",
        "updated_at": "2026-01-01 12:00:00"
    }
}
POST

Criar pedido

POST /api/v1/orders

Cria um novo pedido na loja.

Campos obrigatórios: `customer_id`, `items` (array com ao menos 1 item).

Escopo necessário: `write`

Exemplo de Requisição
{
    "customer_id": 1,
    "notes": "Embrulho para presente",
    "shipping_address_id": 1,
    "items": [
        {
            "product_id": 1,
            "variant_id": 12,
            "qty": 2,
            "unit_price": 89.9
        },
        {
            "product_id": 5,
            "variant_id": null,
            "qty": 1,
            "unit_price": 5
        }
    ],
    "shipping_amount": 15,
    "discount_amount": 0
}
Exemplo de Resposta
{
    "status": "success",
    "code": 201,
    "message": "Order created",
    "data": {
        "id": 88,
        "order_number": "EF-20260506-0088",
        "customer_id": 1,
        "status": "pending",
        "payment_status": "pending",
        "fulfillment_status": "pending",
        "subtotal": "184.80",
        "shipping_amount": "15.00",
        "total": "199.80",
        "created_at": "2026-05-06 10:00:00"
    }
}
PATCH

Atualizar status

PATCH /api/v1/orders/{id}/status

Atualiza o status de um pedido.

Envie apenas os campos que deseja alterar.

**status**: `pending` | `approved` | `canceled` | `completed`
**payment_status**: `pending` | `partial` | `paid`
**fulfillment_status**: `pending` | `processing` | `shipped` | `delivered` | `canceled`

Escopo necessário: `write`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do pedido
Exemplo de Requisição
{
    "status": "approved",
    "payment_status": "paid",
    "fulfillment_status": "processing"
}
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "message": "Order status updated",
    "data": {
        "id": 88,
        "status": "approved",
        "payment_status": "paid",
        "fulfillment_status": "processing",
        "updated_at": "2026-05-06 10:30:00"
    }
}
POST

Cancelar pedido

POST /api/v1/orders/{id}/cancel

Cancela um pedido. Somente pedidos com status `pending` ou `approved` podem ser cancelados.

O estoque dos itens é revertido automaticamente.

Escopo necessário: `write`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do pedido
Exemplo de Requisição
{
    "reason": "Solicitação do cliente"
}
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "message": "Order canceled",
    "data": {
        "id": 88,
        "status": "canceled",
        "updated_at": "2026-05-06 11:00:00"
    }
}
POST

Registrar envio

POST /api/v1/orders/{id}/shipments

Registra os dados de envio do pedido. Ao informar o `tracking_code`, o `fulfillment_status` é atualizado automaticamente para `shipped`.

Escopo necessário: `write`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do pedido
Exemplo de Requisição
{
    "carrier": "Correios",
    "service": "PAC",
    "tracking_code": "BR123456789BR",
    "tracking_url": "https:\/\/rastreamento.correios.com.br\/BR123456789BR",
    "posted_at": "2026-05-07 08:00:00"
}
Exemplo de Resposta
{
    "status": "success",
    "code": 201,
    "message": "Shipment created",
    "data": {
        "id": 1,
        "order_id": 88,
        "carrier": "Correios",
        "tracking_code": "BR123456789BR",
        "tracking_url": "https:\/\/rastreamento.correios.com.br\/BR123456789BR",
        "status": "shipped",
        "posted_at": "2026-05-07 08:00:00"
    }
}
GET

Consultar rastreamento

GET /api/v1/orders/{id}/shipments

Retorna os dados de envio e rastreamento do pedido.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do pedido
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": {
        "id": 1,
        "order_id": 88,
        "carrier": "Correios",
        "service": "PAC",
        "tracking_code": "BR123456789BR",
        "tracking_url": "https:\/\/rastreamento.correios.com.br\/BR123456789BR",
        "status": "shipped",
        "posted_at": "2026-05-07 08:00:00",
        "delivered_at": null
    }
}
GET

Consultar estoque

GET /api/v1/stock

Retorna o saldo de estoque de todos os produtos ativos.

Produtos do tipo `variable` têm o saldo distribuído nas variantes.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Número da página (padrão: 1)
per_page integer opcional Itens por página (padrão: 20)
search string opcional Busca por nome ou SKU
category integer opcional Filtrar por categoria
low_stock integer opcional Retorna apenas produtos com estoque ≤ este valor
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": [
        {
            "id": 1,
            "name": "Camiseta Básica",
            "sku": "CAM-001",
            "type": "variable",
            "stock_qty": 0,
            "variants_total": 55,
            "category": "Roupas"
        },
        {
            "id": 5,
            "name": "Meia Esportiva",
            "sku": "MEI-001",
            "type": "simple",
            "stock_qty": 200,
            "category": "Acessórios"
        }
    ],
    "meta": {
        "total": 2,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    }
}
GET

Estoque de um produto

GET /api/v1/stock/{product_id}

Retorna o saldo de estoque de um produto específico.

Se o produto for do tipo `variable`, inclui o saldo de cada variante ativa.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
product_id integer obrigatório ID do produto
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": {
        "id": 1,
        "name": "Camiseta Básica",
        "sku": "CAM-001",
        "type": "variable",
        "stock_qty": 0,
        "variants": [
            {
                "id": 12,
                "title": "P \/ Preto",
                "sku": "CAM-001-P-PRETO",
                "stock_qty": 30,
                "min_stock": 5
            },
            {
                "id": 13,
                "title": "M \/ Preto",
                "sku": "CAM-001-M-PRETO",
                "stock_qty": 25,
                "min_stock": 5
            }
        ]
    }
}
POST

Registrar movimentação

POST /api/v1/stock/movements

Registra uma movimentação de estoque.

Tipos:
- `entry` — adiciona ao estoque atual
- `exit` — subtrai do estoque atual
- `adjustment` — define o valor absoluto (inventário)

Campos obrigatórios: `product_id`, `qty`, `movement_type`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "product_id": 5,
    "variant_id": null,
    "qty": 100,
    "movement_type": "entry",
    "reference": "NF-2026\/001"
}
Exemplo de Resposta
{
    "status": "success",
    "code": 201,
    "message": "Stock movement created",
    "data": {
        "id": 80,
        "product_id": 5,
        "variant_id": null,
        "movement_type": "ENTRY",
        "qty": "100",
        "stock_before": "200",
        "stock_after": "300",
        "reference": "NF-2026\/001",
        "created_at": "2026-05-06 10:00:00"
    }
}
GET

Histórico de movimentações

GET /api/v1/stock/movements

Retorna o histórico de movimentações de estoque.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Número da página (padrão: 1)
per_page integer opcional Itens por página (padrão: 20)
product_id integer opcional Filtrar por produto
movement_type string opcional ENTRY, EXIT ou ADJUSTMENT
date_from string opcional Data inicial (YYYY-MM-DD)
date_to string opcional Data final (YYYY-MM-DD)
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": [
        {
            "id": 80,
            "product_id": 5,
            "product_name": "Meia Esportiva",
            "product_sku": "MEI-001",
            "variant_id": null,
            "movement_type": "ENTRY",
            "qty": "100",
            "stock_before": "200",
            "stock_after": "300",
            "reference": "NF-2026\/001",
            "created_at": "2026-05-06 10:00:00"
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    }
}
GET

Listar pagamentos do pedido

GET /api/v1/orders/{id}/payments

Retorna todos os registros de pagamento de um pedido.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do pedido
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": [
        {
            "id": 1,
            "order_id": 88,
            "method": "pix",
            "method_name": "PIX",
            "amount": "199.80",
            "status": "paid",
            "paid_at": "2026-05-06 10:15:00",
            "note": "Confirmado via webhook"
        }
    ]
}
POST

Registrar pagamento

POST /api/v1/orders/{id}/payments

Registra um pagamento para o pedido.

O `paid_amount` e o `payment_status` do pedido são atualizados automaticamente após o registro.

Campo obrigatório: `amount` (valor > 0).

Escopo necessário: `write`

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do pedido
Exemplo de Requisição
{
    "amount": 199.8,
    "method": "pix",
    "method_name": "PIX",
    "paid_at": "2026-05-06 10:15:00",
    "note": "Confirmado via extrato"
}
Exemplo de Resposta
{
    "status": "success",
    "code": 201,
    "message": "Payment recorded",
    "data": {
        "id": 1,
        "order_id": 88,
        "method": "pix",
        "method_name": "PIX",
        "amount": "199.80",
        "status": "paid",
        "paid_at": "2026-05-06 10:15:00"
    }
}
POST

Gerar PIX

POST /api/v1/payments/pix

Gera um QR Code PIX para um pedido.

O QR Code expira em 30 minutos. O status do pagamento é atualizado automaticamente via webhook ao receber a confirmação do gateway.

Campos obrigatórios: `order_id`, `amount`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "order_id": 88,
    "amount": 199.8
}
Exemplo de Resposta
{
    "status": "success",
    "code": 201,
    "data": {
        "transaction_id": "pix_20260506_001",
        "order_id": 88,
        "amount": "199.80",
        "qr_code": "00020126580014br.gov.bcb.pix...",
        "qr_code_image": "https:\/\/api.elephantfy.com.br\/qrcode\/pix_20260506_001.png",
        "expires_at": "2026-05-06 10:45:00"
    }
}
POST

Gerar Boleto

POST /api/v1/payments/boleto

Gera um boleto bancário para um pedido.

O boleto vence em 3 dias úteis por padrão. O status do pagamento é atualizado automaticamente via webhook ao receber a confirmação.

Campos obrigatórios: `order_id`, `amount`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "order_id": 88,
    "amount": 199.8,
    "due_days": 5
}
Exemplo de Resposta
{
    "status": "success",
    "code": 201,
    "data": {
        "transaction_id": "bol_20260506_001",
        "order_id": 88,
        "amount": "199.80",
        "barcode": "34191.75001 00000.002282 90000.141409 9 97690000019980",
        "boleto_url": "https:\/\/boleto.elephantfy.com.br\/bol_20260506_001",
        "due_date": "2026-05-13"
    }
}
GET

Consultar status do pagamento

GET /api/v1/payments/{transaction_id}

Consulta o status de uma transação de pagamento gerada pela API.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
transaction_id string obrigatório ID da transação retornado na criação
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": {
        "transaction_id": "pix_20260506_001",
        "order_id": 88,
        "method": "pix",
        "amount": "199.80",
        "status": "paid",
        "paid_at": "2026-05-06 10:18:00"
    }
}
POST

Calcular frete

POST /api/v1/shipping/calculate

Calcula as opções de frete disponíveis para um conjunto de itens e um CEP de destino.

Retorna todas as transportadoras ativas configuradas na loja com prazo e valor estimados.

Campos obrigatórios: `postal_code`, `items`.

Escopo necessário: `read`

Exemplo de Requisição
{
    "postal_code": "01310-100",
    "items": [
        {
            "product_id": 1,
            "variant_id": 12,
            "qty": 2,
            "weight": 0.3,
            "length": 30,
            "width": 20,
            "height": 2
        }
    ]
}
Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": [
        {
            "carrier": "Correios",
            "service": "PAC",
            "price": "18.50",
            "deadline_days": 7,
            "deadline_label": "Até 7 dias úteis"
        },
        {
            "carrier": "Correios",
            "service": "SEDEX",
            "price": "32.90",
            "deadline_days": 2,
            "deadline_label": "Até 2 dias úteis"
        },
        {
            "carrier": "Jadlog",
            "service": "Package",
            "price": "22.00",
            "deadline_days": 4,
            "deadline_label": "Até 4 dias úteis"
        }
    ]
}
GET

Listar transportadoras

GET /api/v1/shipping/carriers

Retorna as transportadoras ativas configuradas na loja.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "code": 200,
    "data": [
        {
            "id": 1,
            "name": "Correios",
            "services": [
                "PAC",
                "SEDEX",
                "SEDEX 10"
            ],
            "active": 1
        },
        {
            "id": 2,
            "name": "Jadlog",
            "services": [
                "Package",
                "Econômico"
            ],
            "active": 1
        }
    ]
}
POST

Gerar etiqueta

POST /api/v1/shipping/labels

Solicita a geração de etiqueta de envio para um pedido junto à transportadora configurada.

Campos obrigatórios: `order_id`, `carrier_id`, `service`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "order_id": 88,
    "carrier_id": 1,
    "service": "PAC"
}
Exemplo de Resposta
{
    "status": "success",
    "code": 201,
    "message": "Label generated",
    "data": {
        "order_id": 88,
        "carrier": "Correios",
        "service": "PAC",
        "tracking_code": "BR123456789BR",
        "label_url": "https:\/\/api.elephantfy.com.br\/labels\/88_pac.pdf"
    }
}