claude-plugins/automacao/skills/moloni-api/references/api-reference.md

Moloni API v2 - Reference

Empresa Descomplicar

Campo	Valor
Company ID	69473
Empresa	Evidente Despertar, Lda
Client ID	evidentedespertar
NIF	516557498
MCP Server	/opt/moloni/ em mcp-hub
Service	moloni.service (systemd)
.env	/opt/moloni/.env
Token storage	/opt/moloni/.moloni/69473/.token_metadata.json

Sandbox (Desenvolvimento/Testes)

Para testar integrações sem afectar dados reais: https://www.moloni.pt/dev/sandbox/

A sandbox fornece um ambiente isolado com dados fictícios. Usar sempre que:

• Desenvolver novas integrações
• Testar criação/modificação de documentos
• Depurar erros de formato ou validação

Autenticacao

Password Grant (GET, nao POST!)

r = requests.get('https://api.moloni.pt/v2/grant/', params={
    'grant_type': 'password',
    'client_id': 'evidentedespertar',
    'client_secret': 'aa48e86bd574bf81ca2d7f624c8b5de0284fb97d',
    'username': 'contabilidade@descomplicar.pt',
    'password': '6EMVh^RHA)d5k!%s'
})
token = r.json()['access_token']

Refresh Token

r = requests.get('https://api.moloni.pt/v2/grant/', params={
    'grant_type': 'refresh_token',
    'client_id': 'evidentedespertar',
    'client_secret': 'aa48e86bd574bf81ca2d7f624c8b5de0284fb97d',
    'refresh_token': '<refresh_token>'
})

Regras de Autenticacao

• Grant endpoint e GET (nao POST)
• Password contem %s - em Python usar: '6EMVh^RHA)d5k!%s' (string literal, sem f-string)
• Token expira em 3600 segundos (1 hora)
• Refresh token nao expira mas so pode ser usado uma vez

Formato das Chamadas API

Regra Fundamental

access_token -> QUERY STRING (params)
dados        -> POST BODY (data, form-urlencoded)

Exemplo Correcto

r = requests.post('https://api.moloni.pt/v2/invoices/getAll/',
    params={'access_token': token},           # token na query string
    data={'company_id': '69473', 'qty': '50'} # dados no body
)

Exemplo INCORRECTO (causa 403 Forbidden)

# ERRADO - token no body causa 403!
r = requests.post('https://api.moloni.pt/v2/invoices/getAll/',
    data={'company_id': '69473', 'access_token': token, 'qty': '50'}
)

Endpoints Case-Sensitive

Correcto (camelCase)	ERRADO (lowercase)
creditNotes/	creditnotes/
invoiceReceipts/	invoicereceipts/
documentSets/	documentsets/
paymentMethods/	paymentmethods/
simplifiedInvoices/	simplifiedinvoices/
debitNotes/	debitnotes/
billsOfLading/	billsoflading/
deliveryNotes/	deliverynotes/
proFormaInvoices/	proformainvoices/

Endpoints simples (lowercase OK): invoices/, receipts/, customers/, products/, taxes/

Todos os endpoints precisam de trailing slash: /v2/invoices/getAll/

Arrays Aninhados (Form-Encoded)

Formato Correcto

data = {
    'company_id': '69473',
    'associated_documents[0][associated_id]': '595002190',
    'associated_documents[0][value]': '2361.60',
    'payments[0][payment_method_id]': '400878',
    'payments[0][date]': '2026-02-05',
    'payments[0][value]': '2361.60',
}

Multiplos Items

data = {
    'products[0][product_id]': '123',
    'products[0][qty]': '2',
    'products[0][price]': '50.00',
    'products[1][product_id]': '456',
    'products[1][qty]': '1',
    'products[1][price]': '100.00',
}

NUNCA Usar JSON.dumps()

# ERRADO - Moloni nao aceita JSON strings dentro de form data
data = {
    'associated_documents': json.dumps([{'associated_id': 123, 'value': 50}])
}

Restricoes de Datas

• Moloni tem data minima para criacao de documentos (periodo de comunicacao AT)
• Actualmente: >= 2025-10-28
• Para documentos com datas antigas, usar a data actual no recibo/documento
• Erro retornado: ["12 date >= 2025-10-28"]

Series Documentais

ID	Nome	Uso
630300	D	Serie principal (facturas, recibos, NC)
118898	(antiga)	Recibos antigos KCCG

Metodos de Pagamento

ID	Nome
400868	Numerario
400873	Cheque
400878	Transferencia Bancaria
400883	Multibanco
1569000	Paypal

Endpoints por Tipo de Documento

Cada tipo de documento suporta: count, getAll, getOne, insert, update, delete

Facturas (invoices/)

POST /v2/invoices/getAll/   - Listar (qty, offset, document_set_id, customer_id, year)
POST /v2/invoices/getOne/   - Detalhe (document_id OU document_set_id+number)
POST /v2/invoices/insert/   - Criar

Recibos (receipts/)

POST /v2/receipts/getAll/   - Listar
POST /v2/receipts/getOne/   - Detalhe
POST /v2/receipts/insert/   - Criar (requer: date, document_set_id, customer_id, net_value, associated_documents, payments)

Insert fields:

• company_id (int, required)
• date (YYYY-MM-DD, required)
• document_set_id (int, required)
• customer_id (int, required)
• net_value (float, required) - valor total do recibo
• associated_documents[] - array com associated_id e value
• payments[] - array com payment_method_id, date, value
• status (0=rascunho, 1=fechado)
• notes (string, opcional)

Notas de Credito (creditNotes/)

POST /v2/creditNotes/getAll/
POST /v2/creditNotes/getOne/
POST /v2/creditNotes/insert/

Clientes (customers/)

POST /v2/customers/getAll/
POST /v2/customers/getOne/
POST /v2/customers/getBySearch/
POST /v2/customers/getByVat/

Produtos (products/)

POST /v2/products/getAll/
POST /v2/products/getBySearch/
POST /v2/products/getByReference/

Codigos de Erro Comuns

Codigo	Significado
200 + {"valid": 1}	Sucesso
200 + ["12 date >= ..."]	Data anterior ao periodo AT
200 + ["10 associated_id"]	Documento associado invalido ou ja reconciliado
200 + ["2 value 0 null"]	Valor invalido ou em falta
401	Token expirado ou invalido
403	App sem permissoes (access_token no body em vez de query string)
404	Endpoint nao encontrado (verificar case-sensitivity e trailing slash)

Campos de Resposta (Documentos)

Campo	Tipo	Descricao
document_id	int	ID unico do documento
number	int	Numero sequencial na serie
net_value	float	Total COM IVA (Desk total). Para base sem IVA: net_value / 1.23. ATENCAO: nome enganador, NAO e base!
reconciled_value	float	Valor ja reconciliado/pago
status	int	0=rascunho, 1=fechado
customer_id	int	ID do cliente Moloni
document_set_id	int	ID da serie documental
associated_documents	array	Documentos associados (facturas num recibo)
reverse_associated_documents	array	Documentos que referenciam este (recibos de uma factura)
payments	array	Pagamentos registados
entity_name	string	Nome do cliente
entity_vat	string	NIF do cliente

MCP Tools Disponiveis

O MCP Moloni expoe todas as operacoes via ferramentas prefixadas mcp__moloni__moloni_:

mcp__moloni__moloni_documents_invoices_getall
mcp__moloni__moloni_documents_invoices_getone
mcp__moloni__moloni_documents_receipts_insert
mcp__moloni__moloni_documents_credit_notes_getall
mcp__moloni__moloni_entities_customers_getall
mcp__moloni__moloni_settings_paymentmethods_getall
mcp__moloni__moloni_settings_documentsets_getall

Nota: O MCP server ja coloca o access_token na query string automaticamente. Quando usar via MCP, nao e necessario gerir tokens manualmente.

Mapeamento Clientes Moloni-Desk

Moloni customer_id	Nome Moloni	Desk client_id	Nome Desk
75731733	Missao Pertinente	10	MIP
84748539	KCCG - Karate Clube de Gaia	2	KCG
90214681	IgnitionVortex	14	IGV
90360913	Prestigebrokers	176	Prestigebrokers
90861853	Cristina Pinto Santos Lda	17	SNT Sintricare
96914420	Vasco Miguel Neves, Unipessoal	21	Solar FV
97615615	TECIRRIGATION	22	TECIRRIGATION
98881975	Miguel Carril	23	MCR
99321870	Espiral Senior	24	Espiral Senior
99581273	Alegria Todo o Dia	25	Alegria Todo o Dia
100711528	ROSSANA FERREIRA	26	Family Clinic
105780051	AQUISEVENDE	28	AQUISEVENDE
128784439	Carstuff Artigos Para Carrocaria	139	CTF Carstuff

Sincronizacao Desk-Moloni (Estado 2026-02-05)

Tipo	Total Serie D	Sincronizados
Facturas	107	107 importadas no Desk
Notas de Credito	3	3 importadas no Desk
Recibos	112	91 existentes + 21 criados
Pagamentos	113	110 serie D + 3 serie 118898
PDFs	220	107 FT + 110 RC + 3 NC (330 registos: invoice+customer)

Status facturas:

• Paid: 98 | Partially Paid: 2 (D/36, D/84) | Unpaid: 3 (D/98, D/105, D/106)
• Cancelled: 2 (D/56, D/88) | Draft: 2 (D/18, D/66)

Excluidas da sincronizacao:

• FT D/8, D/56, D/88 - anuladas por notas de credito
• FT D/98, D/105, D/106 - nao cobradas
• FT D/18, D/66 - rascunhos
• FT D/3, D/4, D/5 - recibos na serie 118898 (nao D)