API pública do Illo

REST com JSON, autenticação por token e a mesma regra de permissão e isolamento da interface. Disponível a partir do plano Pro.

Autenticação

Crie um token em Configurações → API e tokens (só administradores). O token assume um papel (somente leitura, vendedor, financeiro ou estoquista) — nunca administrador — e é mostrado uma única vez. Envie em todas as chamadas:

curl https://demo.useillo.com.br/api/v1/me \
  -H "Authorization: Bearer illo_xxxxxxxx…"

Se a assinatura da empresa estiver em somente leitura, o token também passa a só ler.

Convenções

Dinheiro sempre em centavos (inteiros). Datas em AAAA-MM-DD.
Listas paginadas: ?page=1&limit=50 (limite máximo 200) e busca com ?q=. Resposta: { "data": [...], "total": 123, "page": 1, "limit": 50 }.
Erros: { "error": "mensagem em português" } com status 400 (dados inválidos), 401 (token), 403 (sem permissão ou plano), 404, 409 (conflito) ou 429 (limite).
Limite de 120 chamadas por minuto por token. Os cabeçalhos X-RateLimit-Remaining e Retry-After indicam o saldo.

Recursos

Rota	Métodos	Descrição
/api/v1/me	GET	Empresa, papel do token e plano.
/api/v1/contacts[/id]	GET, POST, PUT	Clientes e fornecedores.
/api/v1/products[/id]	GET, POST, PUT	Produtos.
/api/v1/services[/id]	GET	Serviços (somente leitura).
/api/v1/warehouses[/id]	GET	Depósitos (somente leitura).
/api/v1/orders	GET	Pedidos de venda (filtro `?status=`).
/api/v1/stock	GET	Posição de estoque por produto e depósito.
/api/v1/leads	POST	Captação de leads (usa a chave do CRM em `x-api-key`, não o token).

Os campos de cada recurso estão na especificação OpenAPI 3 (JSON), que você pode importar no Postman, Insomnia ou gerador de clientes.

Exemplos

Listar clientes:

curl "https://demo.useillo.com.br/api/v1/contacts?q=maria&limit=10" \
  -H "Authorization: Bearer $ILLO_TOKEN"

Criar um cliente (precisa de um token com permissão de cadastro):

curl -X POST https://demo.useillo.com.br/api/v1/contacts \
  -H "Authorization: Bearer $ILLO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "personType": "pf", "name": "Maria da Silva", "email": "maria@exemplo.com", "isCustomer": true }'

Atualizar um produto (preço em centavos):

curl -X PUT https://demo.useillo.com.br/api/v1/products/<id> \
  -H "Authorization: Bearer $ILLO_TOKEN" -H "Content-Type: application/json" \
  -d '{ "sku": "CAM-001", "name": "Camiseta", "kind": "simple", "unit": "UN", "priceCents": 4990 }'

Webhooks

Hoje o Illo recebe webhooks (de cobranças). O envio de webhooks do Illo para o seu sistema ainda não existe; use a consulta periódica de /orders e /stock.