# NovaCRM API v1

Public documentation for integrating stores, clients, products, inventory, orders, coupons, analytics and webhooks.

- Public documentation: https://console.novacrm.com.br/docs/api
- OpenAPI 3.1: https://console.novacrm.com.br/api/v1/openapi.json
- Base URL: `https://console.novacrm.com.br/api/v1`

## Authentication

Except for `GET /openapi.json`, requests require a Bearer API key:

```http
Authorization: Bearer ncrm_live.MERCHANT_ID.KEY_ID.SECRET
```

Use `ncrm_test` keys for sandbox data and `ncrm_live` keys for production.

## Standard success response

```json
{
  "success": true,
  "data": {},
  "meta": {
    "apiVersion": "v1",
    "requestId": "request-id",
    "timestamp": "2026-08-15T12:00:00.000Z"
  }
}
```

## Standard error response

```json
{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Existem campos inválidos.",
    "details": {}
  },
  "meta": {
    "apiVersion": "v1",
    "requestId": "request-id",
    "timestamp": "2026-08-15T12:00:00.000Z"
  }
}
```

## Pagination

List endpoints accept `limit` (1–100) and `offset`. Responses include `total`, `count`, `hasMore` and `nextOffset`.

## Clients

| Method | Path | Scope | Description |
|---|---|---|---|
| GET | `/clients` | `clients:read` | List clients |
| POST | `/clients` | `clients:write` | Create client |
| GET | `/clients/:id` | `clients:read` | Get client |
| PATCH | `/clients/:id` | `clients:write` | Update client |
| DELETE | `/clients/:id` | `clients:write` | Archive client |
| DELETE | `/clients/:id?permanent=true` | `dangerous:delete` | Permanently delete client |
| POST | `/clients/upsert` | `clients:write` | Create or update by phone/email |
| POST | `/imports/clients` | `clients:write` | Import up to 500 clients |

## Products

| Method | Path | Scope | Description |
|---|---|---|---|
| GET | `/products` | `products:read` | List products |
| POST | `/products` | `products:write` | Create product |
| GET | `/products/:id` | `products:read` | Get product |
| PATCH | `/products/:id` | `products:write` | Update product |
| DELETE | `/products/:id` | `products:write` | Archive product |
| DELETE | `/products/:id?permanent=true` | `dangerous:delete` | Permanently delete product |
| POST | `/products/bulk` | `products:write` | Create up to 100 products |
| POST | `/imports/products` | `products:write` | Import up to 500 products |

## Inventory

| Method | Path | Scope | Description |
|---|---|---|---|
| GET | `/inventory` | `inventory:read` | Current inventory |
| GET | `/inventory/alerts?threshold=5` | `inventory:read` | Low stock products |
| GET | `/inventory/movements` | `inventory:read` | Inventory movement history |
| POST | `/inventory/adjustments` | `inventory:write` | Adjust product stock |

Adjustment example:

```json
{
  "productId": "PRODUCT_ID",
  "quantityDelta": -2,
  "reason": "external_sale"
}
```

## Orders

| Method | Path | Scope | Description |
|---|---|---|---|
| GET | `/orders` | `orders:read` | List orders |
| POST | `/orders` | `orders:write` | Create order |
| GET | `/orders/:id` | `orders:read` | Get order |
| PATCH | `/orders/:id/status` | `orders:write` | Update order status |
| POST | `/orders/:id/cancel` | `orders:write` | Cancel order |

Allowed statuses: `pending_payment`, `new`, `processing`, `completed`, `cancelled`.

## Coupons

| Method | Path | Scope | Description |
|---|---|---|---|
| GET | `/coupons` | `coupons:read` | List coupons |
| POST | `/coupons` | `coupons:write` | Create coupon |
| PATCH | `/coupons/:id` | `coupons:write` | Update coupon |
| DELETE | `/coupons/:id` | `coupons:write` | Delete coupon |
| POST | `/coupons/validate` | `coupons:read` | Validate and calculate discount |

## Store

| Method | Path | Scope | Description |
|---|---|---|---|
| GET | `/store` | `store:read` | Store configuration |
| PATCH | `/store` | `store:write` | Update store configuration |
| GET | `/store/status` | `store:read` | Open/published status |
| PATCH | `/store/status` | `store:write` | Open, close or publish store |
| GET | `/store/delivery` | `store:read` | Delivery settings |
| PATCH | `/store/delivery` | `store:write` | Update delivery settings |

## Analytics

| Method | Path | Scope | Description |
|---|---|---|---|
| GET | `/analytics` | `analytics:read` | General summary |
| GET | `/analytics/revenue` | `analytics:read` | Revenue and average ticket |
| GET | `/analytics/orders` | `analytics:read` | Orders by status |
| GET | `/analytics/products` | `analytics:read` | Top-selling and low stock products |
| GET | `/analytics/clients` | `analytics:read` | LTV and top clients |
| GET | `/analytics/inventory` | `analytics:read` | Inventory indicators |

## Webhooks

| Method | Path | Scope | Description |
|---|---|---|---|
| GET | `/webhooks` | `webhooks:read` | List webhooks |
| POST | `/webhooks` | `webhooks:write` | Create webhook |
| PATCH | `/webhooks/:id` | `webhooks:write` | Update webhook |
| DELETE | `/webhooks/:id` | `webhooks:write` | Delete webhook |
| GET | `/webhooks/:id/deliveries` | `webhooks:read` | Delivery history |
| POST | `/webhooks/:id/test` | `webhooks:write` | Test webhook |

Events: `client.created`, `client.updated`, `client.deleted`, `product.created`, `product.updated`, `product.deleted`, `inventory.adjusted`, `inventory.low`, `order.created`, `order.status_updated`, `order.cancelled`.

Webhook requests include:

```http
X-NovaCRM-Event: order.created
X-NovaCRM-Delivery: delivery-id
X-NovaCRM-Attempt: 1
X-NovaCRM-Signature: sha256=hex-signature
```

The signature is HMAC-SHA256 over the raw request body. Deliveries retry up to three times.

## Exports

| Method | Path | Scope | Description |
|---|---|---|---|
| POST | `/exports` | `exports:write` | Create JSON or CSV export |
| GET | `/exports/:id` | `exports:read` | Download export |

## Rate limits

- Free: 100 requests/month and 10 requests/minute
- Pro: 10,000 requests/month and 60 requests/minute
- Enterprise: 100,000 requests/month and 300 requests/minute

Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-Request-Id`.

## HTTP status codes

- `200` Success
- `201` Created
- `202` Accepted
- `400` Invalid request
- `401` Invalid or missing API key
- `403` Insufficient scope
- `404` Resource or route not found
- `422` Validation error
- `429` Rate limit exceeded
- `500` Internal error
- `503` Service unavailable