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://crislibrazil.com/api/v1
GET

Visão geral

GET /api/v1/{resource}

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

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

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

Exemplo de header:
```
Authorization: Bearer erpgx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Resposta de erro quando não autenticado:
```json
{"status":"error","message":"Invalid or missing API key"}
```

Exemplo de Resposta
{
    "status": "error",
    "message": "Invalid or missing API key"
}
GET

Listar clientes

GET /api/v1/customers

Retorna uma lista paginada de todos os clientes do negócio.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Número da página (default: 1)
per_page integer opcional Registros por página, máx 100 (default: 20)
search string opcional Busca por nome, e-mail ou telefone
status integer opcional Filtro de status: 1 = ativo, 0 = inativo
lifecycle_stage string opcional Estágio: lead, prospect, customer, churned
Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "name": "João Silva",
            "email": "joao@exemplo.com",
            "phone": "11999990000",
            "city": "São Paulo",
            "status": 1,
            "created_at": "2025-01-10 09:00:00"
        }
    ],
    "total": 1,
    "page": 1,
    "per_page": 20,
    "last_page": 1
}
GET

Detalhe do cliente

GET /api/v1/customers/{id}

Retorna os dados completos de um cliente.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 1,
        "name": "João Silva",
        "email": "joao@exemplo.com",
        "phone": "11999990000",
        "document": "123.456.789-00",
        "address": "Rua das Flores, 100",
        "city": "São Paulo",
        "state": "SP",
        "postal_code": "01310-100",
        "country": "BR",
        "company_name": null,
        "lifecycle_stage": "customer",
        "source": "manual",
        "birth_date": "1990-05-15",
        "status": 1,
        "created_at": "2025-01-10 09:00:00",
        "updated_at": "2025-01-10 09:00:00"
    }
}
POST

Criar cliente

POST /api/v1/customers

Cria um novo cliente.

Escopo necessário: `write`

Exemplo de Requisição
{
    "name": "Maria Souza",
    "email": "maria@exemplo.com",
    "phone": "11988887777",
    "document": "987.654.321-00",
    "city": "Campinas",
    "state": "SP",
    "postal_code": "13010-100",
    "lifecycle_stage": "lead",
    "source": "api"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Customer created",
    "data": {
        "id": 42,
        "name": "Maria Souza",
        "email": "maria@exemplo.com",
        "phone": "11988887777",
        "lifecycle_stage": "lead",
        "status": 1,
        "created_at": "2026-04-14 10:00:00"
    }
}
PUT

Atualizar cliente

PUT /api/v1/customers/{id}

Atualiza os dados de um cliente existente.

Envie apenas os campos que deseja alterar.

Escopo necessário: `write`

Exemplo de Requisição
{
    "lifecycle_stage": "customer",
    "company_name": "Souza LTDA"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Customer updated",
    "data": {
        "id": 42,
        "name": "Maria Souza",
        "lifecycle_stage": "customer",
        "company_name": "Souza LTDA",
        "updated_at": "2026-04-14 10:05:00"
    }
}
DELETE

Excluir cliente

DELETE /api/v1/customers/{id}

Desativa um cliente (soft delete — altera status para 0).

Escopo necessário: `write`

Exemplo de Resposta
{
    "status": "success",
    "message": "Customer deleted"
}
GET

Listar endereços

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

Retorna todos os endereços cadastrados para o cliente.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "label": "Casa",
            "address1": "Rua das Flores, 100",
            "city": "São Paulo",
            "state": "SP",
            "cep": "01310-100",
            "is_default": 1
        }
    ]
}
POST

Criar endereço

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

Adiciona um novo endereço ao cliente.

Campos obrigatórios: `address` e `city`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "label": "Trabalho",
    "address1": "Av. Paulista, 900",
    "number": "900",
    "city": "São Paulo",
    "state": "SP",
    "cep": "01311-100",
    "is_default": 0
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Address created",
    "data": {
        "id": 3,
        "label": "Trabalho",
        "address1": "Av. Paulista, 900",
        "city": "São Paulo",
        "state": "SP",
        "cep": "01311-100",
        "is_default": 0
    }
}
DELETE

Excluir endereço

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

Remove um endereço do cliente.

Escopo necessário: `write`

Exemplo de Resposta
{
    "status": "success",
    "message": "Address deleted"
}
GET

Listar produtos

GET /api/v1/products

Retorna uma lista paginada de produtos.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Número da página (default: 1)
per_page integer opcional Registros por página, máx 100 (default: 20)
search string opcional Busca por nome, SKU ou marca
category integer opcional ID da categoria
type string opcional Tipo do produto: simple ou variable
is_sell integer opcional 1 = produto para venda (default)
is_buy integer opcional 1 = produto para compra
active integer opcional 1 = ativo (default), 0 = inativo
Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "name": "Camiseta Branca",
            "sku": "CAM-001",
            "type": "simple",
            "price": "59.90",
            "quantity": 120,
            "active": 1
        }
    ],
    "total": 1,
    "page": 1,
    "per_page": 20,
    "last_page": 1
}
GET

Detalhe do produto

GET /api/v1/products/{id}

Retorna os dados completos de um produto, incluindo variantes quando `type = variable`.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 1,
        "name": "Camiseta Branca",
        "sku": "CAM-001",
        "type": "simple",
        "price": "59.90",
        "cost_price": "25.00",
        "promotional_price": null,
        "quantity": 120,
        "unit": "un",
        "weight": "0.200",
        "active": 1,
        "is_sell": 1,
        "is_buy": 0,
        "category": 3,
        "variants": [],
        "created_at": "2025-01-01 08:00:00"
    }
}
POST

Criar produto

POST /api/v1/products

Cria um novo produto.

Campo obrigatório: `name`.

Para produto com variantes, use `type: "variable"` e crie as variantes depois via `POST /products/{id}/variants`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "name": "Tênis Running",
    "sku": "TEN-001",
    "type": "simple",
    "price": "299.90",
    "cost_price": "120.00",
    "quantity": 50,
    "unit": "par",
    "weight": "0.600",
    "category": 5,
    "is_sell": 1,
    "active": 1
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Product created",
    "data": {
        "id": 99,
        "name": "Tênis Running",
        "sku": "TEN-001",
        "type": "simple",
        "price": "299.90",
        "quantity": 50,
        "active": 1,
        "created_at": "2026-04-14 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`

Exemplo de Requisição
{
    "price": "279.90",
    "promotional_price": "249.90",
    "quantity": 40
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Product updated",
    "data": {
        "id": 99,
        "price": "279.90",
        "promotional_price": "249.90",
        "quantity": 40,
        "updated_at": "2026-04-14 10:10:00"
    }
}
DELETE

Excluir produto

DELETE /api/v1/products/{id}

Desativa um produto (soft delete — altera `active = 0`).

Escopo necessário: `write`

Exemplo de Resposta
{
    "status": "success",
    "message": "Product deleted"
}
GET

Listar variantes

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

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

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 10,
            "title": "M \/ Azul",
            "sku": "CAM-VAR-M-AZ",
            "price": "89.90",
            "stock_qty": 30,
            "active": 1,
            "attributes": [
                {
                    "attribute": "Tamanho",
                    "value": "M"
                },
                {
                    "attribute": "Cor",
                    "value": "Azul"
                }
            ]
        }
    ]
}
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`

Exemplo de Requisição
{
    "title": "G \/ Vermelho",
    "sku": "CAM-VAR-G-VM",
    "price": "89.90",
    "cost_price": "35.00",
    "stock_qty": 20,
    "active": 1
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Variant created",
    "data": {
        "id": 15,
        "title": "G \/ Vermelho",
        "sku": "CAM-VAR-G-VM",
        "price": "89.90",
        "stock_qty": 20,
        "active": 1
    }
}
PUT

Atualizar variante

PUT /api/v1/products/{id}/variants/{vid}

Atualiza uma variante existente.

Envie apenas os campos que deseja alterar.

Escopo necessário: `write`

Exemplo de Requisição
{
    "price": "94.90",
    "stock_qty": 15
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Variant updated",
    "data": {
        "id": 15,
        "price": "94.90",
        "stock_qty": 15
    }
}
DELETE

Excluir variante

DELETE /api/v1/products/{id}/variants/{vid}

Desativa uma variante (soft delete — altera `active = 0`).

Escopo necessário: `write`

Exemplo de Resposta
{
    "status": "success",
    "message": "Variant deleted"
}
GET

Listar categorias

GET /api/v1/categories

Retorna todas as categorias do negócio.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
type string opcional Tipo da categoria (ex: product, expense, income)
Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "name": "Roupas",
            "slug": "roupas",
            "type": "product",
            "status": 1
        },
        {
            "id": 2,
            "name": "Calçados",
            "slug": "calcados",
            "type": "product",
            "status": 1
        }
    ]
}
GET

Detalhe da categoria

GET /api/v1/categories/{id}

Retorna os dados de uma categoria.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 1,
        "name": "Roupas",
        "slug": "roupas",
        "type": "product",
        "status": 1
    }
}
POST

Criar categoria

POST /api/v1/categories

Cria uma nova categoria.

Campo obrigatório: `name`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "name": "Esportes",
    "type": "product"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Category created",
    "data": {
        "id": 10,
        "name": "Esportes",
        "slug": "esportes",
        "type": "product",
        "status": 1
    }
}
PUT

Atualizar categoria

PUT /api/v1/categories/{id}

Atualiza uma categoria existente.

Escopo necessário: `write`

Exemplo de Requisição
{
    "name": "Esportes e Fitness"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Category updated",
    "data": {
        "id": 10,
        "name": "Esportes e Fitness",
        "slug": "esportes-e-fitness"
    }
}
DELETE

Excluir categoria

DELETE /api/v1/categories/{id}

Remove permanentemente uma categoria.

⚠️ Produtos vinculados não são afetados.

Escopo necessário: `write`

Exemplo de Resposta
{
    "status": "success",
    "message": "Category deleted"
}
GET

Consultar estoque

GET /api/v1/stock

Retorna o saldo de estoque de todos os produtos ativos.

Produtos do tipo `variable` retornam `stock_qty = 0` (o saldo fica nas variantes).

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Página (default: 1)
per_page integer opcional Registros por página, máx 100 (default: 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",
    "data": [
        {
            "id": 1,
            "name": "Camiseta Branca",
            "sku": "CAM-001",
            "type": "simple",
            "stock_qty": 120,
            "price": "59.90",
            "category_name": "Roupas"
        }
    ],
    "total": 1,
    "page": 1,
    "per_page": 20,
    "last_page": 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.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 2,
        "name": "Camiseta Colorida",
        "sku": "CAM-002",
        "type": "variable",
        "stock_qty": 0,
        "variants": [
            {
                "id": 10,
                "title": "M \/ Azul",
                "sku": "CAM-VAR-M-AZ",
                "stock_qty": 30,
                "min_stock": 5,
                "active": 1
            },
            {
                "id": 11,
                "title": "G \/ Vermelho",
                "sku": "CAM-VAR-G-VM",
                "stock_qty": 15,
                "min_stock": 5,
                "active": 1
            }
        ]
    }
}
GET

Listar 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 Página (default: 1)
per_page integer opcional Registros por página, máx 100 (default: 20)
product_id integer opcional Filtrar por produto
movement_type string opcional Tipo: 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",
    "data": [
        {
            "id": 50,
            "product_id": 1,
            "product_name": "Camiseta Branca",
            "product_sku": "CAM-001",
            "variant_id": null,
            "movement_type": "ENTRY",
            "qty": "20.000",
            "stock_before": "100.000",
            "stock_after": "120.000",
            "reference": "NF-1234",
            "created_at": "2026-04-10 08:00:00"
        }
    ],
    "total": 1,
    "page": 1,
    "per_page": 20,
    "last_page": 1
}
POST

Registrar movimentação

POST /api/v1/stock/movements

Registra uma movimentação de estoque (entrada, saída ou ajuste).

Tipos de movimentação:
- `entry` — adiciona ao estoque atual
- `exit` — subtrai do estoque atual
- `adjustment` — define o valor absoluto do estoque

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

Escopo necessário: `write`

Exemplo de Requisição
{
    "product_id": 1,
    "qty": 50,
    "movement_type": "adjustment",
    "reference": "Inventário Abril\/2026"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Stock movement created",
    "data": {
        "id": 51,
        "business_id": 1,
        "product_id": 1,
        "variant_id": null,
        "movement_type": "ADJUSTMENT",
        "qty": "50",
        "stock_before": "120",
        "stock_after": "50",
        "reference": "Inventário Abril\/2026",
        "created_at": "2026-04-14 10:00:00"
    }
}
GET

Listar pedidos

GET /api/v1/orders

Retorna uma lista paginada de pedidos.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Página (default: 1)
per_page integer opcional Registros por página, máx 100 (default: 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 | completed | canceled
Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "order_number": "ORD-20260101-0001",
            "customer_id": 1,
            "customer_name": "João Silva",
            "status": "approved",
            "payment_status": "paid",
            "fulfillment_status": "pending",
            "total": "199.80",
            "created_at": "2026-01-01 10:00:00"
        }
    ],
    "total": 1,
    "page": 1,
    "per_page": 20,
    "last_page": 1
}
GET

Detalhe do pedido

GET /api/v1/orders/{id}

Retorna os dados completos de um pedido, incluindo itens e pagamentos registrados.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 1,
        "order_number": "ORD-20260101-0001",
        "customer_id": 1,
        "customer_name": "João Silva",
        "status": "approved",
        "payment_status": "paid",
        "fulfillment_status": "pending",
        "subtotal": "199.80",
        "discount_amount": "0.00",
        "tax_amount": "0.00",
        "shipping_amount": "0.00",
        "total": "199.80",
        "paid_amount": "199.80",
        "items": [
            {
                "id": 1,
                "product_id": 10,
                "name": "Camiseta Branca",
                "sku": "CAM-001",
                "qty": "2.000",
                "unit_price": "59.90",
                "line_total": "119.80"
            },
            {
                "id": 2,
                "product_id": 12,
                "name": "Meias",
                "sku": "MEI-001",
                "qty": "2.000",
                "unit_price": "39.90",
                "line_total": "79.80"
            }
        ],
        "created_at": "2026-01-01 10:00:00"
    }
}
POST

Criar pedido

POST /api/v1/orders

Cria um novo pedido.

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

Escopo necessário: `write`

Exemplo de Requisição
{
    "customer_id": 1,
    "ordered_at": "2026-04-14 09:00:00",
    "notes_internal": "Pedido via API",
    "items": [
        {
            "product_id": 10,
            "qty": 2,
            "unit_price": 59.9
        },
        {
            "product_id": 12,
            "qty": 2,
            "unit_price": 39.9
        }
    ]
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Order created",
    "data": {
        "id": 55,
        "order_number": "ORD-20260414-0055",
        "customer_id": 1,
        "status": "pending",
        "payment_status": "pending",
        "fulfillment_status": "pending",
        "total": "199.80",
        "created_at": "2026-04-14 09:00:00"
    }
}
PATCH

Atualizar status

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

Atualiza o status de um pedido.

Envie apenas os campos de status que deseja alterar.

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

Escopo necessário: `write`

Exemplo de Requisição
{
    "status": "approved",
    "payment_status": "paid",
    "fulfillment_status": "processing"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Order status updated",
    "data": {
        "id": 55,
        "status": "approved",
        "payment_status": "paid",
        "fulfillment_status": "processing",
        "updated_at": "2026-04-14 10:00:00"
    }
}
GET

Listar pagamentos

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

Retorna todos os registros de pagamento de um pedido.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "order_id": 55,
            "payment_method_name": "PIX",
            "payment_type": "pix",
            "status": "paid",
            "amount": "199.80",
            "paid_at": "2026-04-14 10:02:00"
        }
    ]
}
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.

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

Escopo necessário: `write`

Exemplo de Requisição
{
    "amount": 199.8,
    "payment_method_name": "PIX",
    "payment_method": "pix",
    "paid_at": "2026-04-14 10:02:00",
    "note": "Confirmado via extrato"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Payment recorded",
    "data": {
        "id": 1,
        "order_id": 55,
        "payment_method_name": "PIX",
        "amount": "199.80",
        "status": "paid",
        "paid_at": "2026-04-14 10:02:00"
    }
}
GET

Listar envios

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

Retorna os dados de envio do pedido.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "order_id": 55,
            "carrier": "Correios",
            "tracking_code": "BR123456789",
            "tracking_url": "https:\/\/rastreamento.correios.com.br\/...",
            "status": "posted",
            "posted_at": "2026-04-15 08:00:00",
            "delivered_at": null
        }
    ]
}
POST

Registrar envio

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

Cria ou atualiza os dados de envio do pedido.

Quando `tracking_code` é informado, o `fulfillment_status` do pedido é atualizado automaticamente para `processing`.

⚠️ Cada pedido pode ter apenas um registro de envio (upsert).

Escopo necessário: `write`

Exemplo de Requisição
{
    "carrier": "Correios",
    "tracking_code": "BR123456789",
    "tracking_url": "https:\/\/rastreamento.correios.com.br\/BR123456789",
    "delivery_mode": "transportadora",
    "status": "posted",
    "posted_at": "2026-04-15 08:00:00"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Shipment created",
    "data": {
        "id": 1,
        "order_id": 55,
        "carrier": "Correios",
        "tracking_code": "BR123456789",
        "status": "posted",
        "posted_at": "2026-04-15 08:00:00"
    }
}
GET

Listar fornecedores

GET /api/v1/suppliers

Retorna uma lista paginada de fornecedores.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Página (default: 1)
per_page integer opcional Registros por página, máx 100 (default: 20)
search string opcional Busca por nome, email, telefone ou CNPJ/CPF
city string opcional Filtrar por cidade
Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "name": "Distribuidora ABC",
            "trade_name": "ABC Ltda",
            "document": "12.345.678\/0001-90",
            "phone": "11999990000",
            "email": "contato@abc.com.br",
            "city": "São Paulo",
            "created_at": "2025-06-01 08:00:00"
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    }
}
GET

Detalhe do fornecedor

GET /api/v1/suppliers/{id}

Retorna os dados completos de um fornecedor.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 1,
        "name": "Distribuidora ABC",
        "trade_name": "ABC Ltda",
        "document": "12.345.678\/0001-90",
        "state_registration": "123456789",
        "phone": "11999990000",
        "email": "contato@abc.com.br",
        "contact_name": "Carlos Oliveira",
        "contact_phone": "11988880000",
        "website": "https:\/\/abc.com.br",
        "payment_terms": "30\/60\/90 dias",
        "pix_key": "cnpj",
        "bank_name": "Bradesco",
        "address": "Rua dos Atacadistas, 500",
        "city": "São Paulo",
        "postal_code": "01310-100",
        "notes": "Entrega às terças e quintas",
        "created_at": "2025-06-01 08:00:00"
    }
}
POST

Criar fornecedor

POST /api/v1/suppliers

Cria um novo fornecedor.

Campo obrigatório: `name`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "name": "Distribuidora XYZ",
    "trade_name": "XYZ Ltda",
    "document": "98.765.432\/0001-10",
    "phone": "11977770000",
    "email": "vendas@xyz.com.br",
    "city": "Campinas",
    "payment_terms": "30 dias"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Supplier created",
    "data": {
        "id": 10,
        "name": "Distribuidora XYZ",
        "document": "98.765.432\/0001-10",
        "phone": "11977770000",
        "email": "vendas@xyz.com.br",
        "city": "Campinas",
        "created_at": "2026-04-14 10:00:00"
    }
}
PUT

Atualizar fornecedor

PUT /api/v1/suppliers/{id}

Atualiza os dados de um fornecedor.

Envie apenas os campos que deseja alterar.

Escopo necessário: `write`

Exemplo de Requisição
{
    "payment_terms": "28 dias",
    "pix_key": "98765432000110",
    "bank_name": "Itaú"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Supplier updated",
    "data": {
        "id": 10,
        "name": "Distribuidora XYZ",
        "payment_terms": "28 dias",
        "pix_key": "98765432000110",
        "updated_at": "2026-04-14 10:10:00"
    }
}
GET

Listar pedidos de compra

GET /api/v1/purchases

Retorna uma lista paginada de pedidos de compra.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Página (default: 1)
per_page integer opcional Registros por página (default: 20)
search string opcional Busca por número do PO ou nome do fornecedor
status string opcional draft | sent | approved | partially_received | received | canceled
payment_status string opcional pending | partial | paid
vendor_id integer opcional Filtrar por fornecedor
date_from string opcional Data inicial (YYYY-MM-DD)
date_to string opcional Data final (YYYY-MM-DD)
Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "po_number": "PO-2026-0001",
            "vendor_id": 1,
            "vendor_name": "Distribuidora ABC",
            "status": "approved",
            "payment_status": "pending",
            "order_date": "2026-04-01",
            "total": "5800.00",
            "created_at": "2026-04-01 09:00:00"
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    }
}
GET

Detalhe do pedido de compra

GET /api/v1/purchases/{id}

Retorna os dados completos de um pedido de compra, incluindo itens.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 1,
        "po_number": "PO-2026-0001",
        "vendor_id": 1,
        "vendor_name": "Distribuidora ABC",
        "vendor_email": "contato@abc.com.br",
        "status": "approved",
        "payment_status": "pending",
        "order_date": "2026-04-01",
        "expected_date": "2026-04-10",
        "subtotal": "5800.00",
        "discount_amount": "0.00",
        "tax_amount": "0.00",
        "shipping_amount": "0.00",
        "total": "5800.00",
        "paid_amount": "0.00",
        "payment_terms": "30 dias",
        "notes": "",
        "items": [
            {
                "id": 1,
                "product_id": 10,
                "product_name": "Camiseta Branca",
                "description": "Camiseta Branca M",
                "qty_ordered": "100.000",
                "unit_cost": "58.00",
                "line_total": "5800.00"
            }
        ],
        "created_at": "2026-04-01 09:00:00"
    }
}
POST

Criar pedido de compra

POST /api/v1/purchases

Cria um novo pedido de compra com status inicial `draft`.

Campo obrigatório: `vendor_id`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "vendor_id": 1,
    "order_date": "2026-04-14",
    "expected_date": "2026-04-21",
    "payment_terms": "30 dias",
    "notes": "Urgente — reposição de estoque",
    "items": [
        {
            "product_id": 10,
            "description": "Camiseta Branca M",
            "unit": "un",
            "qty_ordered": 100,
            "unit_cost": 58,
            "line_total": 5800
        }
    ],
    "total": 5800
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Purchase order created",
    "data": {
        "id": 5,
        "po_number": "PO-2026-0005",
        "vendor_id": 1,
        "vendor_name": "Distribuidora ABC",
        "status": "draft",
        "payment_status": "pending",
        "total": "5800.00",
        "created_at": "2026-04-14 10:00:00"
    }
}
PATCH

Atualizar status do pedido

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

Atualiza o status de um pedido de compra.

**Fluxo sugerido:** `draft` → `sent` → `approved` → `partially_received` → `received`

Escopo necessário: `write`

Exemplo de Requisição
{
    "status": "approved"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Purchase order status updated",
    "data": {
        "id": 5,
        "po_number": "PO-2026-0005",
        "status": "approved",
        "updated_at": "2026-04-14 10:05:00"
    }
}
GET

Listar contas a receber

GET /api/v1/receivables

Retorna uma lista paginada de contas a receber.

Status automático: títulos `pending` com `due_date` anterior a hoje são exibidos como `overdue`.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Página (default: 1)
per_page integer opcional Registros por página (default: 20)
status string opcional pending | partial | received | overdue
customer_id integer opcional Filtrar por cliente
date_from string opcional Vencimento a partir de (YYYY-MM-DD)
date_to string opcional Vencimento até (YYYY-MM-DD)
search string opcional Busca por descrição
Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "description": "Venda ORD-20260414-0001",
            "amount": "199.80",
            "discount_amount": "0.00",
            "net_amount": "199.80",
            "received_amount": "0.00",
            "status": "pending",
            "due_date": "2026-05-14",
            "customer_id": 1,
            "customer_name": "João Silva",
            "created_at": "2026-04-14 10:00:00"
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    }
}
GET

Detalhe da conta a receber

GET /api/v1/receivables/{id}

Retorna os dados completos de uma conta a receber, incluindo recebimentos registrados.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 1,
        "description": "Venda ORD-20260414-0001",
        "amount": "199.80",
        "discount_amount": "0.00",
        "net_amount": "199.80",
        "received_amount": "100.00",
        "status": "partial",
        "due_date": "2026-05-14",
        "issue_date": "2026-04-14",
        "customer_id": 1,
        "origin": "order",
        "payments": [
            {
                "id": 1,
                "receivable_id": 1,
                "amount": "100.00",
                "payment_date": "2026-04-20",
                "notes": "Entrada"
            }
        ],
        "created_at": "2026-04-14 10:00:00"
    }
}
POST

Criar conta a receber

POST /api/v1/receivables

Cria uma nova conta a receber manualmente.

Campos obrigatórios: `description`, `amount`, `due_date`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "description": "Consultoria de abril\/2026",
    "amount": 3500,
    "due_date": "2026-04-30",
    "customer_id": 5,
    "issue_date": "2026-04-14",
    "document_number": "NF-0042",
    "notes": "Serviço prestado em 10\/04"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Receivable created",
    "data": {
        "id": 20,
        "description": "Consultoria de abril\/2026",
        "amount": "3500.00",
        "net_amount": "3500.00",
        "status": "pending",
        "due_date": "2026-04-30",
        "created_at": "2026-04-14 10:00:00"
    }
}
POST

Registrar recebimento

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

Registra um pagamento parcial ou total para a conta a receber.

O campo `status` da conta é atualizado automaticamente (`partial` ou `received`).

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

Escopo necessário: `write`

Exemplo de Requisição
{
    "amount": 3500,
    "payment_date": "2026-04-30",
    "payment_method_id": 2,
    "notes": "TED confirmada"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Payment recorded",
    "data": {
        "id": 5,
        "receivable_id": 20,
        "amount": "3500.00",
        "payment_date": "2026-04-30",
        "notes": "TED confirmada"
    }
}
GET

Listar contas a pagar

GET /api/v1/payables

Retorna uma lista paginada de contas a pagar.

Status automático: títulos `pending` com `due_date` anterior a hoje são exibidos como `overdue`.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Página (default: 1)
per_page integer opcional Registros por página (default: 20)
status string opcional pending | partial | paid | overdue
supplier_id integer opcional Filtrar por fornecedor
date_from string opcional Vencimento a partir de (YYYY-MM-DD)
date_to string opcional Vencimento até (YYYY-MM-DD)
search string opcional Busca por descrição
Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "description": "Aluguel abril\/2026",
            "amount": "2800.00",
            "discount_amount": "0.00",
            "net_amount": "2800.00",
            "paid_amount": "0.00",
            "status": "pending",
            "due_date": "2026-04-10",
            "supplier_id": null,
            "supplier_name": null,
            "created_at": "2026-04-01 08:00:00"
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    }
}
GET

Detalhe da conta a pagar

GET /api/v1/payables/{id}

Retorna os dados completos de uma conta a pagar, incluindo pagamentos registrados.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 1,
        "description": "Aluguel abril\/2026",
        "amount": "2800.00",
        "net_amount": "2800.00",
        "paid_amount": "0.00",
        "status": "overdue",
        "due_date": "2026-04-10",
        "issue_date": "2026-04-01",
        "supplier_id": null,
        "origin": "manual",
        "barcode": null,
        "payments": [],
        "created_at": "2026-04-01 08:00:00"
    }
}
POST

Criar conta a pagar

POST /api/v1/payables

Cria uma nova conta a pagar.

Campos obrigatórios: `description`, `amount`, `due_date`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "description": "Internet — maio\/2026",
    "amount": 299.9,
    "due_date": "2026-05-10",
    "supplier_id": 3,
    "document_number": "FAT-2026-05",
    "barcode": "03399.12345 67890.123456 78901.234567 8 92340000029990"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Payable created",
    "data": {
        "id": 15,
        "description": "Internet — maio\/2026",
        "amount": "299.90",
        "net_amount": "299.90",
        "status": "pending",
        "due_date": "2026-05-10",
        "created_at": "2026-04-14 10:00:00"
    }
}
POST

Registrar pagamento

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

Registra um pagamento para a conta a pagar.

O `status` é atualizado automaticamente (`partial` ou `paid`).

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

Escopo necessário: `write`

Exemplo de Requisição
{
    "amount": 299.9,
    "payment_date": "2026-05-10",
    "payment_method_id": 1,
    "notes": "Débito automático"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Payment recorded",
    "data": {
        "id": 8,
        "payable_id": 15,
        "amount": "299.90",
        "payment_date": "2026-05-10",
        "notes": "Débito automático"
    }
}
GET

Listar serviços

GET /api/v1/services

Retorna uma lista paginada dos serviços ativos.

Requer o módulo **Agendamentos** (`core.appointments`) ativo no plano.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Página (default: 1)
per_page integer opcional Registros por página (default: 20)
active integer opcional 1 = ativo (default), 0 = inativo
category_id integer opcional Filtrar por categoria de serviço
search string opcional Busca por nome ou descrição
Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "name": "Corte de Cabelo",
            "slug": "corte-de-cabelo",
            "duration": 30,
            "price_type": "fixed",
            "price": "50.00",
            "active": 1,
            "online_booking": 1,
            "category_id": 1,
            "category_name": "Cabelo",
            "color": "#667eea"
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    }
}
GET

Detalhe do serviço

GET /api/v1/services/{id}

Retorna os dados completos de um serviço.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 1,
        "name": "Corte de Cabelo",
        "slug": "corte-de-cabelo",
        "short_description": "Corte masculino e feminino",
        "duration": 30,
        "buffer_time": 5,
        "max_simultaneous": 1,
        "price_type": "fixed",
        "price": "50.00",
        "price_from": null,
        "commission_type": "percentage",
        "commission_value": "10.00",
        "active": 1,
        "online_booking": 1,
        "requires_confirmation": 0,
        "category_id": 1,
        "category_name": "Cabelo",
        "color": "#667eea"
    }
}
GET

Listar agendamentos

GET /api/v1/appointments

Retorna uma lista paginada de agendamentos.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Página (default: 1)
per_page integer opcional Registros por página (default: 20)
status string opcional pending | confirmed | cancelled | completed | no_show
professional_id integer opcional Filtrar por profissional
date_from string opcional Data inicial (YYYY-MM-DD)
date_to string opcional Data final (YYYY-MM-DD)
search string opcional Busca por nome, telefone ou email do cliente
Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "appointment_date": "2026-04-20",
            "start_time": "09:00:00",
            "end_time": "09:30:00",
            "status": "confirmed",
            "customer_name": "Ana Paula",
            "customer_phone": "11988880000",
            "price": "50.00",
            "service_id": 1,
            "service_name": "Corte de Cabelo",
            "professional_id": 2,
            "professional_name": "Carlos Lima",
            "created_at": "2026-04-14 10:00:00"
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    }
}
GET

Detalhe do agendamento

GET /api/v1/appointments/{id}

Retorna os dados completos de um agendamento.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 1,
        "appointment_date": "2026-04-20",
        "start_time": "09:00:00",
        "end_time": "09:30:00",
        "status": "confirmed",
        "source": "api",
        "customer_id": 1,
        "customer_name": "Ana Paula",
        "customer_email": "ana@email.com",
        "customer_phone": "11988880000",
        "price": "50.00",
        "notes": null,
        "service_id": 1,
        "service_name": "Corte de Cabelo",
        "service_duration": 30,
        "professional_id": 2,
        "professional_name": "Carlos Lima",
        "created_at": "2026-04-14 10:00:00"
    }
}
POST

Criar agendamento

POST /api/v1/appointments

Cria um novo agendamento.

Campos obrigatórios: `service_id`, `professional_id`, `appointment_date`, `start_time`, `customer_name`.

⚠️ A API não valida disponibilidade de horário — use os endpoints públicos de booking para obter slots disponíveis.

Escopo necessário: `write`

Exemplo de Requisição
{
    "service_id": 1,
    "professional_id": 2,
    "customer_id": 1,
    "customer_name": "Ana Paula",
    "customer_phone": "11988880000",
    "customer_email": "ana@email.com",
    "appointment_date": "2026-04-20",
    "start_time": "09:00",
    "end_time": "09:30",
    "price": 50,
    "status": "confirmed",
    "notes": "Cliente prefere tesoura reta"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Appointment created",
    "data": {
        "id": 25,
        "appointment_date": "2026-04-20",
        "start_time": "09:00:00",
        "status": "confirmed",
        "customer_name": "Ana Paula",
        "service_name": "Corte de Cabelo",
        "professional_name": "Carlos Lima",
        "created_at": "2026-04-14 10:00:00"
    }
}
PATCH

Atualizar status do agendamento

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

Atualiza o status de um agendamento.

**status**: `pending` | `confirmed` | `cancelled` | `completed` | `no_show`

Quando `status = cancelled`, o campo `cancel_reason` é opcional.

Escopo necessário: `write`

Exemplo de Requisição
{
    "status": "completed"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Appointment status updated",
    "data": {
        "id": 25,
        "status": "completed",
        "appointment_date": "2026-04-20",
        "service_name": "Corte de Cabelo",
        "professional_name": "Carlos Lima"
    }
}
GET

Listar negócios

GET /api/v1/deals

Retorna uma lista paginada de negócios do pipeline de CRM.

Por padrão, retorna apenas negócios com `status = active`.

Requer o addon **CRM** (`addon.crm`) ativo no plano.

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Página (default: 1)
per_page integer opcional Registros por página (default: 20)
stage string opcional Etapa do pipeline (ex: new, qualified, proposal, won, lost)
status string opcional active (default) | won | lost
customer_id integer opcional Filtrar por cliente
search string opcional Busca por título
Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "title": "Renovação de contrato anual",
            "stage": "proposal",
            "status": "active",
            "value": "24000.00",
            "probability": "70",
            "expected_revenue": "16800.00",
            "expected_close_date": "2026-05-31",
            "customer_id": 1,
            "customer_name": "João Silva",
            "created_at": "2026-03-10 09:00:00"
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    }
}
GET

Detalhe do negócio

GET /api/v1/deals/{id}

Retorna os dados completos de um negócio.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 1,
        "title": "Renovação de contrato anual",
        "stage": "proposal",
        "status": "active",
        "value": "24000.00",
        "probability": "70",
        "expected_revenue": "16800.00",
        "expected_close_date": "2026-05-31",
        "customer_id": 1,
        "customer_name": "João Silva",
        "owner_user_id": 3,
        "notes": "Cliente solicitou desconto de 5%",
        "created_at": "2026-03-10 09:00:00",
        "updated_at": "2026-04-10 14:00:00"
    }
}
POST

Criar negócio

POST /api/v1/deals

Cria um novo negócio no pipeline.

Campos obrigatórios: `title`, `customer_id`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "title": "Proposta de sistema ERP",
    "customer_id": 5,
    "stage": "qualified",
    "value": 18000,
    "probability": 60,
    "expected_close_date": "2026-06-30",
    "notes": "Demonstração marcada para 25\/04"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Deal created",
    "data": {
        "id": 12,
        "title": "Proposta de sistema ERP",
        "stage": "qualified",
        "status": "active",
        "value": "18000.00",
        "probability": "60",
        "expected_revenue": "10800.00",
        "expected_close_date": "2026-06-30",
        "customer_name": "Empresa Modelo",
        "created_at": "2026-04-14 10:00:00"
    }
}
PUT

Atualizar negócio

PUT /api/v1/deals/{id}

Atualiza os dados de um negócio, incluindo etapa, probabilidade ou status.

`expected_revenue` é recalculado automaticamente com base em `value × probability / 100`.

Escopo necessário: `write`

Exemplo de Requisição
{
    "stage": "proposal",
    "probability": 75,
    "value": 17000,
    "notes": "Proposta formal enviada por email"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Deal updated",
    "data": {
        "id": 12,
        "stage": "proposal",
        "value": "17000.00",
        "probability": "75",
        "expected_revenue": "12750.00",
        "updated_at": "2026-04-14 10:15:00"
    }
}
GET

Listar profissionais

GET /api/v1/professionals

Retorna uma lista paginada de profissionais cadastrados.

Requer o módulo **Agendamentos** (`core.appointments`).

Escopo necessário: `read`

Parâmetros
Nome Tipo Obrigatório Descrição
page integer opcional Página (default: 1)
per_page integer opcional Registros por página (default: 20)
active integer opcional 1 = ativo (default), 0 = inativo
search string opcional Busca por nome ou especialidade
Exemplo de Resposta
{
    "status": "success",
    "data": [
        {
            "id": 1,
            "name": "Carlos Lima",
            "email": "carlos@email.com",
            "phone": "11977770000",
            "speciality": "Cabeleireiro",
            "color": "#4e9af1",
            "active": 1
        },
        {
            "id": 2,
            "name": "Mariana Costa",
            "email": "mariana@email.com",
            "phone": "11966660000",
            "speciality": "Manicure",
            "color": "#f1a84e",
            "active": 1
        }
    ],
    "meta": {
        "total": 2,
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    }
}
GET

Detalhe do profissional

GET /api/v1/professionals/{id}

Retorna os dados completos de um profissional.

Escopo necessário: `read`

Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 1,
        "name": "Carlos Lima",
        "email": "carlos@email.com",
        "phone": "11977770000",
        "speciality": "Cabeleireiro",
        "color": "#4e9af1",
        "active": 1
    }
}
GET

Listar saldos de cashback

GET /api/v1/cashback

Retorna a lista de clientes com seu saldo atual de cashback. Requer o addon.cashback ativo.

Parâmetros
Nome Tipo Obrigatório Descrição
search string opcional Busca por nome, email ou telefone
has_balance boolean opcional 1 para retornar apenas clientes com saldo positivo
page integer opcional Página (default 1)
per_page integer opcional Itens por página (máx 100, default 20)
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "items": [
            {
                "customer_id": 12,
                "customer_name": "Ana Silva",
                "email": "ana@email.com",
                "phone": "11999990000",
                "balance": 47.5,
                "last_movement": "2024-03-10 14:22:00"
            }
        ],
        "total": 1,
        "page": 1,
        "per_page": 20
    }
}
GET

Saldo de cashback de um cliente

GET /api/v1/cashback/{customer_id}

Retorna o saldo de cashback disponível de um cliente específico.

Parâmetros
Nome Tipo Obrigatório Descrição
customer_id integer obrigatório ID do cliente (path param)
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "customer_id": 12,
        "balance": 47.5
    }
}
GET

Transações de cashback de um cliente

GET /api/v1/cashback/{customer_id}/transactions

Retorna o extrato de movimentações de cashback de um cliente específico.

Parâmetros
Nome Tipo Obrigatório Descrição
customer_id integer obrigatório ID do cliente (path param)
type string opcional Filtro: credit | debit | transfer_in | transfer_out
status string opcional Filtro: approved | used | expired | cancelled
date_start date opcional Data inicial (YYYY-MM-DD)
date_end date opcional Data final (YYYY-MM-DD)
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "items": [
            {
                "id": 55,
                "customer_id": 12,
                "customer_name": "Ana Silva",
                "type": "credit",
                "amount": 25,
                "status": "approved",
                "description": "Cashback pedido #1001",
                "created_at": "2024-03-10 14:22:00"
            }
        ],
        "total": 1,
        "page": 1,
        "per_page": 20
    }
}
POST

Ajuste manual de cashback

POST /api/v1/cashback/adjust

Credita ou debita cashback manualmente para um cliente. Requer escopo write.

Parâmetros
Nome Tipo Obrigatório Descrição
customer_id integer obrigatório ID do cliente
type string obrigatório credit | debit
amount number obrigatório Valor positivo (ex: 15.00)
description string opcional Descrição do ajuste
Exemplo de Requisição
{
    "customer_id": 12,
    "type": "credit",
    "amount": 15,
    "description": "Compensação promocional"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Adjustment applied",
    "data": {
        "transaction_id": 78
    }
}
GET

Listar saldos de pontos

GET /api/v1/loyalty

Retorna a lista de clientes com seu saldo atual de pontos de fidelidade. Requer o addon.loyalty ativo.

Parâmetros
Nome Tipo Obrigatório Descrição
search string opcional Busca por nome, email ou telefone
has_points boolean opcional 1 para retornar apenas clientes com pontos
page integer opcional Página
per_page integer opcional Itens por página (máx 100, default 20)
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "items": [
            {
                "customer_id": 12,
                "customer_name": "Ana Silva",
                "email": "ana@email.com",
                "phone": "11999990000",
                "balance": 350,
                "last_movement": "2024-03-10 14:22:00"
            }
        ],
        "total": 1,
        "page": 1,
        "per_page": 20
    }
}
GET

Saldo de pontos de um cliente

GET /api/v1/loyalty/{customer_id}

Retorna o saldo atual de pontos de fidelidade de um cliente.

Parâmetros
Nome Tipo Obrigatório Descrição
customer_id integer obrigatório ID do cliente (path param)
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "customer_id": 12,
        "points": 350
    }
}
GET

Transações de pontos de um cliente

GET /api/v1/loyalty/{customer_id}/transactions

Retorna o extrato de movimentos de pontos de fidelidade de um cliente.

Parâmetros
Nome Tipo Obrigatório Descrição
customer_id integer obrigatório ID do cliente (path param)
type string opcional Filtro: earned | redeemed | adjusted | expired
status string opcional Filtro: active | used | expired
date_start date opcional Data inicial
date_end date opcional Data final
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "items": [
            {
                "id": 30,
                "customer_id": 12,
                "type": "earned",
                "points": 100,
                "description": "Pontos pedido #1001",
                "status": "active",
                "reward_name": null,
                "created_at": "2024-03-10 14:22:00"
            }
        ],
        "total": 1,
        "page": 1,
        "per_page": 20
    }
}
POST

Ajuste manual de pontos

POST /api/v1/loyalty/adjust

Credita ou debita pontos manualmente para um cliente. Requer escopo write.

Parâmetros
Nome Tipo Obrigatório Descrição
customer_id integer obrigatório ID do cliente
type string obrigatório credit | debit
points integer obrigatório Quantidade de pontos (inteiro positivo)
description string opcional Descrição do ajuste
Exemplo de Requisição
{
    "customer_id": 12,
    "type": "credit",
    "points": 50,
    "description": "Bônus campanha março"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Adjustment applied",
    "data": {
        "transaction_id": 31
    }
}
GET

Listar garantias emitidas

GET /api/v1/warranties

Retorna a lista de garantias emitidas para pedidos. Requer o addon.warranty ativo.

Parâmetros
Nome Tipo Obrigatório Descrição
customer_id integer opcional Filtrar por cliente
order_id integer opcional Filtrar por pedido
status string opcional Filtro: active | expired | void
date_start date opcional Data de emissão inicial
date_end date opcional Data de emissão final
page integer opcional
per_page integer opcional
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "items": [
            {
                "id": 5,
                "order_number": "PED-240101-0001",
                "customer_name": "Carlos Melo",
                "item_name": "Notebook X500",
                "warranty_type": "balcao",
                "issued_at": "2024-01-01",
                "expires_at": "2025-01-01",
                "status": "active"
            }
        ],
        "total": 1,
        "page": 1,
        "per_page": 20
    }
}
GET

Buscar garantia por ID

GET /api/v1/warranties/{id}

Retorna o detalhe completo de uma garantia emitida.

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID da garantia (path param)
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 5,
        "order_number": "PED-240101-0001",
        "customer_name": "Carlos Melo",
        "customer_email": "carlos@email.com",
        "item_name": "Notebook X500",
        "qty": 1,
        "warranty_type": "balcao",
        "serial_number": "SN123456",
        "issued_at": "2024-01-01",
        "expires_at": "2025-01-01",
        "status": "active"
    }
}
PATCH

Atualizar garantia

PATCH /api/v1/warranties/{id}

Atualiza campos de uma garantia (status, notas, motivo de anulação). Requer escopo write.

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID da garantia (path param)
status string opcional active | expired | void
notes string opcional
void_reason string opcional
Exemplo de Requisição
{
    "status": "void",
    "void_reason": "Produto devolvido"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Warranty updated"
}
GET

Listar acionamentos de garantia

GET /api/v1/warranty_claims

Retorna a lista de acionamentos (sinistros) de garantia.

Parâmetros
Nome Tipo Obrigatório Descrição
customer_id integer opcional
warranty_id integer opcional
status string opcional open | in_analysis | approved | rejected | in_repair | resolved
date_start date opcional
date_end date opcional
page integer opcional
per_page integer opcional
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "items": [
            {
                "id": 3,
                "customer_name": "Carlos Melo",
                "item_name": "Notebook X500",
                "status": "open",
                "description": "Tela não liga",
                "opened_at": "2024-06-10 10:00:00"
            }
        ],
        "total": 1,
        "page": 1,
        "per_page": 20
    }
}
POST

Abrir acionamento de garantia

POST /api/v1/warranty_claims

Abre um novo acionamento para uma garantia ativa. Requer escopo write.

Parâmetros
Nome Tipo Obrigatório Descrição
warranty_id integer obrigatório ID da garantia
customer_id integer obrigatório ID do cliente
description string opcional Descrição do problema
technician_notes string opcional
Exemplo de Requisição
{
    "warranty_id": 5,
    "customer_id": 12,
    "description": "Tela não liga após atualização"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Claim opened",
    "data": {
        "id": 3
    }
}
GET

Buscar acionamento por ID

GET /api/v1/warranty_claims/{id}

Retorna o detalhe completo de um acionamento de garantia.

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do acionamento (path param)
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 3,
        "customer_name": "Carlos Melo",
        "item_name": "Notebook X500",
        "warranty_type": "balcao",
        "status": "in_analysis",
        "description": "Tela não liga",
        "technician_notes": null,
        "opened_at": "2024-06-10 10:00:00",
        "resolved_at": null
    }
}
PATCH

Atualizar acionamento

PATCH /api/v1/warranty_claims/{id}

Atualiza o status e notas de um acionamento de garantia. Requer escopo write.

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID do acionamento (path param)
status string opcional open | in_analysis | approved | rejected | in_repair | resolved
technician_notes string opcional
resolution string opcional
resolution_type string opcional
Exemplo de Requisição
{
    "status": "resolved",
    "resolution": "Placa substituída",
    "resolution_type": "repair"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Claim updated"
}
GET

Listar ordens de produção

GET /api/v1/production_orders

Retorna a lista de ordens de produção (OPs). Requer o addon.producao ativo.

Parâmetros
Nome Tipo Obrigatório Descrição
status string opcional rascunho | aguardando | em_producao | pausada | concluida | cancelada
search string opcional Busca por número da OP, produto ou SKU
date_from date opcional
date_to date opcional
page integer opcional
per_page integer opcional
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "items": [
            {
                "id": 7,
                "op_number": "OP-240310-0001",
                "product_name": "Bolo de Cenoura 1kg",
                "product_sku": "BOLO-001",
                "qty_planned": 50,
                "qty_produced": 0,
                "status": "aguardando",
                "priority": "normal",
                "due_date": "2024-03-15",
                "created_at": "2024-03-10 09:00:00"
            }
        ],
        "total": 1,
        "page": 1,
        "per_page": 20
    }
}
POST

Criar ordem de produção

POST /api/v1/production_orders

Cria uma nova ordem de produção. Requer escopo write.

Parâmetros
Nome Tipo Obrigatório Descrição
product_id integer obrigatório ID do produto a produzir
qty_planned number obrigatório Quantidade planejada
bom_id integer opcional ID da ficha técnica (BOM). Se informado, pré-popula os insumos.
unit_id integer opcional ID da unidade de produção
due_date date opcional
priority string opcional low | normal | high | urgent
responsible_id integer opcional
notes string opcional
lot_number string opcional
Exemplo de Requisição
{
    "product_id": 42,
    "qty_planned": 100,
    "bom_id": 3,
    "priority": "high",
    "due_date": "2024-03-20",
    "notes": "Lote para evento"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Production order created",
    "data": {
        "id": 8
    }
}
GET

Buscar ordem de produção por ID

GET /api/v1/production_orders/{id}

Retorna o detalhe de uma OP incluindo seus itens (insumos).

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID da OP (path param)
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 7,
        "op_number": "OP-240310-0001",
        "product_name": "Bolo de Cenoura 1kg",
        "qty_planned": 50,
        "qty_produced": 0,
        "status": "aguardando",
        "items": [
            {
                "product_name": "Farinha de Trigo",
                "qty_planned": 25,
                "qty_consumed": 0,
                "unit_abbr": "kg"
            }
        ]
    }
}
PATCH

Atualizar status da OP

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

Atualiza o status de uma ordem de produção. Requer escopo write. Não é possível alterar OPs concluídas ou canceladas.

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID da OP (path param)
status string obrigatório rascunho | aguardando | em_producao | pausada | concluida | cancelada
cancel_reason string opcional Motivo (obrigatório se status=cancelada)
Exemplo de Requisição
{
    "status": "em_producao"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Status updated"
}
GET

Listar fichas técnicas (BOMs)

GET /api/v1/production_boms

Retorna a lista de fichas técnicas de produção cadastradas.

Parâmetros
Nome Tipo Obrigatório Descrição
search string opcional Busca por nome ou SKU do produto
product_id integer opcional Filtrar por produto
active integer opcional 1 = ativas, 0 = inativas
page integer opcional
per_page integer opcional
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "items": [
            {
                "id": 3,
                "product_name": "Bolo de Cenoura 1kg",
                "product_sku": "BOLO-001",
                "batch_size": 1,
                "cost_total": 8.5,
                "active": 1
            }
        ],
        "total": 1,
        "page": 1,
        "per_page": 20
    }
}
GET

Buscar ficha técnica por ID

GET /api/v1/production_boms/{id}

Retorna os detalhes de uma ficha técnica incluindo todos os insumos.

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID da BOM (path param)
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "id": 3,
        "product_name": "Bolo de Cenoura 1kg",
        "batch_size": 1,
        "cost_total": 8.5,
        "active": 1,
        "items": [
            {
                "product_name": "Farinha de Trigo",
                "qty": 0.5,
                "loss_pct": 2,
                "unit_abbr": "kg",
                "cost_price": 4
            }
        ]
    }
}
GET

Listar atividades de um cliente

GET /api/v1/crm_activities

Retorna o histórico de atividades (ligações, e-mails, reuniões etc.) de um cliente. Requer o addon.crm ativo.

Parâmetros
Nome Tipo Obrigatório Descrição
customer_id integer obrigatório ID do cliente (query param obrigatório)
page integer opcional
per_page integer opcional
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "items": [
            {
                "id": 9,
                "type": "call",
                "subject": "Apresentação de proposta",
                "description": "Cliente interessado no plano anual",
                "outcome": "positive",
                "occurred_at": "2024-03-05 10:00:00",
                "user_name": "João Vendas"
            }
        ],
        "total": 1,
        "page": 1,
        "per_page": 20
    }
}
POST

Registrar atividade

POST /api/v1/crm_activities

Registra uma nova atividade no CRM de um cliente. Requer escopo write.

Parâmetros
Nome Tipo Obrigatório Descrição
customer_id integer obrigatório
type string obrigatório call | email | meeting | note | whatsapp | sms | other
subject string opcional
description string opcional
outcome string opcional positive | neutral | negative
occurred_at datetime opcional Data/hora (default: agora)
next_action_at datetime opcional
Exemplo de Requisição
{
    "customer_id": 12,
    "type": "call",
    "subject": "Follow-up proposta",
    "outcome": "positive",
    "description": "Cliente confirmou interesse"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Activity created",
    "data": {
        "id": 10
    }
}
PATCH

Atualizar atividade

PATCH /api/v1/crm_activities/{id}

Atualiza os dados de uma atividade do CRM. Requer escopo write.

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID da atividade (path param)
type string opcional
subject string opcional
description string opcional
outcome string opcional
occurred_at datetime opcional
next_action_at datetime opcional
Exemplo de Requisição
{
    "outcome": "neutral",
    "description": "Cliente pediu mais prazo para decidir"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Activity updated"
}
GET

Listar tarefas de um cliente

GET /api/v1/crm_tasks

Retorna as tarefas do CRM associadas a um cliente.

Parâmetros
Nome Tipo Obrigatório Descrição
customer_id integer obrigatório ID do cliente (query param obrigatório)
page integer opcional
per_page integer opcional
Exemplo de Resposta
{
    "status": "success",
    "data": {
        "items": [
            {
                "id": 4,
                "title": "Enviar contrato",
                "status": "pending",
                "priority": "high",
                "due_date": "2024-03-15",
                "assigned_user_name": "João Vendas"
            }
        ],
        "total": 1,
        "page": 1,
        "per_page": 20
    }
}
POST

Criar tarefa

POST /api/v1/crm_tasks

Cria uma nova tarefa no CRM para um cliente. Requer escopo write.

Parâmetros
Nome Tipo Obrigatório Descrição
customer_id integer obrigatório
title string obrigatório
description string opcional
status string opcional pending | in_progress | done | cancelled (default: pending)
priority string opcional low | normal | high | urgent (default: normal)
due_date date opcional
assigned_to integer opcional ID do usuário responsável
Exemplo de Requisição
{
    "customer_id": 12,
    "title": "Enviar contrato revisado",
    "priority": "high",
    "due_date": "2024-03-15",
    "assigned_to": 3
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Task created",
    "data": {
        "id": 5
    }
}
PATCH

Atualizar tarefa

PATCH /api/v1/crm_tasks/{id}

Atualiza uma tarefa do CRM. Marcar como done define automaticamente o completed_at. Requer escopo write.

Parâmetros
Nome Tipo Obrigatório Descrição
id integer obrigatório ID da tarefa (path param)
title string opcional
description string opcional
status string opcional pending | in_progress | done | cancelled
priority string opcional
due_date date opcional
completed_at datetime opcional
Exemplo de Requisição
{
    "status": "done"
}
Exemplo de Resposta
{
    "status": "success",
    "message": "Task updated"
}