REST API

Cada ação na interface do Celerp é um endpoint REST – a mesma API que a interface usa internamente. Automatize fluxos de trabalho, ligue outros sistemas ou crie as suas próprias ferramentas. A API corre localmente com os seus dados; nada é enviado para a cloud.

Autenticação

O Celerp usa JSON Web Tokens de curta duração. Inicie sessão com o seu e-mail e palavra-passe do Celerp para obter um token de acesso, depois envie-o como cabeçalho Bearer em cada pedido.

1. Iniciar sessão

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

A resposta contém dois tokens:

{
  "access_token": "eyJhbGciOiJI...",
  "refresh_token": "eyJhbGciOiJI..."
}

2. Chamar a API com o token

curl http://localhost:8000/items \
  -H "Authorization: Bearer eyJhbGciOiJI..."

• O token identifica o seu utilizador, a sua função e a sua empresa, pelo que os pedidos são automaticamente limitados a essa empresa – sem necessidade de cabeçalhos adicionais.
• Os tokens de acesso duram até 24 horas. Quando um expira, obtenha um par novo enviando por POST o seu refresh_token para /auth/token/refresh.
• Pertence a mais de uma empresa? Liste-as com GET /auth/my-companies, depois obtenha um token para outra com POST /auth/switch-company/{company_id}.

Fazer pedidos

Todos os endpoints estão no endereço do seu servidor de API (http://localhost:8000 numa instalação com pip, como nos exemplos abaixo) e devolvem JSON. Os endpoints de listagem devolvem um array items e uma contagem total:

curl "http://localhost:8000/items?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"

{
  "items": [
    { "id": "item:...", "sku": "WIDGET-001", "name": "Widget", "quantity": 42 }
  ],
  "total": 142
}

Paginação: passe ?limit= (predefinição: 50) e ?offset=. A maioria dos endpoints de listagem aceita também um termo de pesquisa q= e filtros por coluna (por exemplo, ?status=available).

Criar dados

Envie JSON por POST para criar registos. As escritas devolvem o id da nova entidade (e o event_id subjacente – todas as alterações no Celerp são eventos).

curl -X POST http://localhost:8000/crm/contacts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "[email protected]",
    "contact_type": "customer",
    "idempotency_key": "acme-2026-06-21"
  }'

Convenções

• Erros as respostas não 2xx devolvem {"detail": "..."} com um código de estado HTTP padrão.
• Limites de pedidos 60 pedidos/minuto por IP por predefinição; o início de sessão está limitado a 10/minuto. Exceder um limite devolve 429.
• Permissões os endpoints são controlados pela sua função: viewer → operator → manager → admin → owner.
• Âmbito da empresa cada pedido atua sobre a empresa indicada no seu token; mude de empresa para atuar sobre outra.

Endpoints comuns

Uma pequena amostra para começar. Cada módulo adiciona os seus – a lista completa está no esquema OpenAPI abaixo.

Referência completa por área

Todos os endpoints disponibilizados pela API em execução, agrupados por área. Cada página indica o método, o caminho, os parâmetros, os formatos do pedido e da resposta e um exemplo de chamada.

Explorar a API completa

A referência completa e sempre atualizada é o esquema OpenAPI 3.1 gerado pela sua própria instância:

GET http://localhost:8000/openapi.json

Carregue-o em qualquer ferramenta OpenAPI – Postman, Insomnia, Swagger UI ou um gerador de clientes – para navegar por todos os endpoints e modelos, testar pedidos e gerar um cliente tipado na sua linguagem. O Celerp distribui o próprio esquema em vez de uma página de documentação alojada, pelo que a sua superfície de API permanece privada à sua instância.