A API do Novadesko

Gere as suas credenciais a partir do seu espaço Novadesko em web.novadesko.com/integrations/api. Dois tipos de credenciais, revogáveis em qualquer momento:

• nvk_… — Chave de utilizador: abrange todas as empresas da sua conta.
• nvt_… — Token de empresa: limitado a uma única empresa.

https://web.novadesko.com/api/v1

São aceites três formatos de autenticação:

// 1. Bearer
Authorization: Bearer CLE.SECRET

// 2. Basic
Authorization: Basic base64(CLE:SECRET)

// 3. Cabeçalhos dedicados
X-Api-Key: CLE
X-Api-Secret: SECRET

O segredo só é apresentado uma vez, na criação. A revogação é imediata a partir da mesma página. Os antigos tokens Sanctum e as chaves nsk_ continuam a ser aceites.

Exemplo

curl https://web.novadesko.com/api/v1/me \
  -H "Authorization: Bearer nvk_xxx.SECRET"

Identifique quem faz o pedido e liste as empresas acessíveis com a sua credencial.

curl https://web.novadesko.com/api/v1/me \
  -H "Authorization: Bearer nvk_xxx.SECRET"

{
  "user": { "id": 1, "name": "John Doe", "email": "john@doe.com" },
  "credential": { "kind": "user_key", "name": "Zapier", "shop_id": null },
  "companies": [
    {
      "id": 1,
      "name": "Demo SPRL",
      "vat_number": "BE0123456789",
      "email": "info@demo.com",
      "phone": "+32 2 123 45 67",
      "city": "Bruxelles",
      "country": "Belgique"
    }
  ]
}

Indicadores-chave de uma empresa num período: volume de negócios com IVA, notas de crédito, compras, resultado bruto, dívidas de clientes e de fornecedores, contadores.

Datas no formato YYYY-MM-DD. Por predefinição: ano em curso.

curl "https://web.novadesko.com/api/v1/companies/1/stats?from=2026-01-01" \
  -H "Authorization: Bearer nvk_xxx.SECRET"

{
  "company": { "id": 1, "name": "Demo SPRL" },
  "period": { "from": "2026-01-01", "to": "2026-08-17" },
  "revenue_ttc": 17077.46,
  "credit_notes_ttc": 250.00,
  "net_revenue_ttc": 16827.46,
  "purchases_ttc": 6420.35,
  "gross_result_ttc": 10407.11,
  "invoices_count": 34,
  "purchases_count": 21,
  "estimates_count": 8,
  "unpaid_invoices": { "count": 6, "total_ttc": 11769.28, "overdue_count": 6 },
  "unpaid_purchases": { "count": 2, "total_ttc": 840.50 },
  "customers_count": 57,
  "products_count": 112
}

Pesquise e consulte os documentos de cada empresa, todos os tipos incluídos.

Filtros disponíveis:

?type=&paid=&from=&to=&q=&page=&per_page=

Tipos de documentos:

invoice · purchase · estimate · order · credit_note · proforma · receipt

{
  "data": [
    {
      "id": 123,
      "number": "FAC-2026-0042",
      "type": "invoice",
      "date": "2026-06-12",
      "due_date": "2026-07-12",
      "customer": "ACME SRL",
      "amount_ttc": 1200.00,
      "is_paid": false
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 34 }
}

{
  "id": 123,
  "number": "FAC-2026-0042",
  "type": "invoice",
  "amount_ttc": 1200.00,
  "is_paid": false,
  "customer": {
    "id": 7,
    "name": "ACME SRL",
    "vat_number": "BE0987654321"
  },
  "lines": [
    {
      "product_name": "Abonnement Pro",
      "quantity": 2,
      "unit_amount": 495.87,
      "tax_rate": 21
    }
  ]
}

Consulte as fichas de clientes e o catálogo de produtos de cada empresa, com pesquisa e paginação.

{
  "data": [
    {
      "id": 7,
      "name": "ACME SRL",
      "email": "contact@acme.be",
      "phone": "+32 2 555 12 34",
      "city": "Bruxelles"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 57 }
}

{
  "data": [
    {
      "id": 42,
      "name": "Abonnement Pro",
      "reference": "ABO-PRO",
      "sale_price": 49.99,
      "tax_included": true,
      "stock_quantity": 0
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 112 }
}

Faturas por pagar de uma empresa, agrupadas por cliente, com atrasos e total.

{
  "count": 6,
  "total_ttc": 11769.28,
  "invoices": [
    {
      "id": 118,
      "number": "FAC-2026-0031",
      "customer": "ACME SRL",
      "date": "2026-03-02",
      "due_date": "2026-04-01",
      "amount_ttc": 3025.00,
      "overdue": true
    }
  ]
}

Pagamentos e movimentos de caixa de uma empresa num período (500 no máximo).

{
  "period": { "from": "2026-01-01", "to": "2026-08-17" },
  "count": 1,
  "data": [
    {
      "id": 88,
      "date": "2026-06-12",
      "amount": 1200.00,
      "type": "payment",
      "direction": "in",
      "source": "bank"
    }
  ]
}

Endpoints históricos associados a uma empresa: crie e modifique todos os tipos de documentos (slugs: invoices, quotes, orders…). A numeração é automática na criação.

Exemplo: Faturas

curl -H "Authorization: Bearer nvk_xxx.SECRET" \
  https://web.novadesko.com/api/v1/documents/invoices

[
  {
    "id": 123,
    "number": "FAC-2026-0042",
    "date": "2026-06-12",
    "client": { "id": 1, "name": "ACME Sarl" },
    "total": 1200.00,
    "status": "paid"
  }
]

{
  "client_id": 1,
  "date": "2026-06-12",
  "lines": [
    { "product_id": 15, "qty": 2, "price": 100 }
  ]
}

Faça a gestão da sua base de clientes: criação, consulta e atualização.

curl -H "Authorization: Bearer nvk_xxx.SECRET" \
  https://web.novadesko.com/api/v1/customers

{
  "name": "Société Demo",
  "email": "contact@demo.com",
  "phone": "+32 2 123 45 67"
}

{
  "id": 2,
  "name": "Société Demo",
  "email": "contact@demo.com",
  "created_at": "2026-06-12T16:10:00Z"
}

Faça a gestão dos seus fornecedores e das respetivas informações.

curl -H "Authorization: Bearer nvk_xxx.SECRET" \
  https://web.novadesko.com/api/v1/suppliers

{
  "company": "Fournisseur SARL",
  "vat_number": "FR123456789",
  "email": "info@fournisseur.com"
}

{
  "id": 5,
  "company": "Fournisseur SARL",
  "created_at": "2026-06-12T16:22:00Z"
}

Faça a gestão do seu catálogo de produtos.

curl -H "Authorization: Bearer nvk_xxx.SECRET" \
  https://web.novadesko.com/api/v1/products

{
  "name": "Abonnement Pro",
  "price": 49.99,
  "category_id": 1
}

{
  "id": 42,
  "name": "Abonnement Pro",
  "price": 49.99
}

Lista dos tipos de documentos ativos e dos respetivos slugs a utilizar nos endpoints /documents/{slug}.

curl -H "Authorization: Bearer nvk_xxx.SECRET" \
  https://web.novadesko.com/api/v1/document-types

[
  { "id": 2, "name": "Factures", "slug": "invoices", "prefix": "FAC" },
  { "id": 6, "name": "Devis", "slug": "quotes", "prefix": "DEV" }
]

Ligue o Claude aos seus dados Novadesko: faça as suas perguntas em linguagem natural, o Claude acede em leitura às suas empresas (números, documentos, clientes, dívidas por cobrar).

1. 1 Gere um URL secreto a partir do seu espaço Novadesko em web.novadesko.com/integrations/claude.
2. 2 No claude.ai: Definições › Conectores › Adicionar um conector personalizado, e cole o URL.
3. 3 O Claude pode então consultar as suas empresas em modo só de leitura, diretamente nas suas conversas.

Protocolo MCP (JSON-RPC: initialize, tools/list, tools/call) · 9 ferramentas disponíveis, incluindo get_company_overview.

// JSON-RPC (MCP)
{ "jsonrpc": "2.0", "method": "tools/call",
  "params": { "name": "get_company_overview", "arguments": { "company_id": 1 } },
  "id": 1 }