madeby.CLOUD API Documentation

API REST per l'integrazione con la piattaforma ERP madeby.CLOUD

Base URL

https://madebycloud.it/erp

Formato

application/json

Autenticazione

Bearer Token

Autenticazione

Tutte le API richiedono un token Bearer ottenuto tramite SSO login.

POST /sso/login

Ottieni un token di autenticazione

Request Body

{
    "email": "utente@esempio.it",
    "password": "password"
}

Response

{
    "success": true,
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "expires_at": "2026-01-29T12:00:00Z",
        "user": {
            "email": "utente@esempio.it",
            "first_name": "Mario",
            "last_name": "Rossi"
        },
        "available_roles": ["customer", "agent", "erp"]
    }
}

Includi il token in tutte le richieste successive: Authorization: Bearer YOUR_TOKEN

Clienti

GET /customers

ERP/Agent

Lista clienti con paginazione e filtri

Parametri Query

Nome	Tipo	Descrizione
`page`	int	Pagina corrente (default: 1)
`per_page`	int	Elementi per pagina (default: 20)
`search`	string	Ricerca per nome/codice
`credit_status`	string	regular/attention/blocked

GET /customers/{id}

ERP/Agent

Dettaglio singolo cliente

POST /customers

ERP

Crea nuovo cliente

Prodotti

GET /products

ERP/Portal

Catalogo prodotti con filtri avanzati

Parametri Query

Nome	Tipo	Descrizione
`search`	string	Ricerca per SKU/nome
`category`	string	Filtra per categoria
`base_type`	string	Filtra per tipo base
`b2b`	0/1	Solo prodotti B2B
`b2c`	0/1	Solo prodotti B2C
`in_stock`	0/1	Solo disponibili

Ordini

POST /orders

ERP/Agent

Crea un nuovo ordine

Request Body

{
    "customer_id": 123,
    "shipping_address_id": 45,
    "notes": "Note ordine",
    "items": [
        {
            "product_id": 1,
            "quantity": 10,
            "unit_price": 85.00,
            "discount_percent": 5
        }
    ]
}

Stati Ordine

Stato	Descrizione
`draft`	Bozza
`pending`	In attesa conferma
`confirmed`	Confermato
`processing`	In lavorazione
`shipped`	Spedito
`delivered`	Consegnato
`cancelled`	Annullato

Fornitori — API ERP

Gestione anagrafica fornitori (accesso ERP interno).

GET /suppliers

ERP

Lista fornitori attivi con paginazione e ricerca

Parametri Query

Nome	Tipo	Descrizione
`page`	int	Pagina corrente (default: 1)
`per_page`	int	Max 100 (default: 20)
`search`	string	Ricerca per codice o ragione sociale

GET /suppliers/{id}

ERP

Dettaglio fornitore con ultimi 10 ordini di acquisto

POST /suppliers

ERP

Crea nuovo fornitore

Request Body

{
    "supplier_code": "FOR001",        // obbligatorio
    "name": "Acme Srl",              // obbligatorio
    "contact_email": "info@acme.it",
    "pec": "acme@pec.it",
    "sdi_code": "XXXXXXX",
    "contact_phone": "+39 02 1234567",
    "address": "Via Roma 1",
    "city": "Milano",
    "country": "IT",
    "vat_number": "IT01234567890",
    "fiscal_code": "ACMXXX00A00X000Y",
    "default_lead_time_days": 14,
    "payment_terms_id": 2
}

PUT /suppliers/{id}

ERP

Aggiorna fornitore (campi modificabili: name, contact_email, pec, sdi_code, contact_phone, address, city, country, default_lead_time_days, rating, vat_number, fiscal_code, payment_terms_id)

Portale Fornitori

API dedicate al portale self-service per i fornitori. Autenticazione tramite token SSO (/sso/login con ruolo supplier) oppure via legacy /supplier-portal/login.

Autenticazione

POST /supplier-portal/login

Pubblico

{
    "vat_number": "IT01234567890",
    "password": "password"
}

Response

{
    "success": true,
    "data": {
        "token": "abc123...",
        "expires_at": "2026-01-29T20:00:00",
        "supplier": {
            "id": 5,
            "supplier_code": "FOR001",
            "name": "Acme Srl",
            "vat_number": "IT01234567890",
            "company_name": "OML Srl",
            "overall_rating": 4.2
        },
        "password_must_change": false
    }
}

GET /supplier-portal/me

Supplier

Dati del fornitore autenticato

Dashboard

GET /supplier-portal/stats

Supplier

KPI dashboard: ordini da confermare, RFQ pendenti, NC aperte, fatturato mese

{
    "success": true,
    "data": {
        "orders_to_confirm": 3,
        "orders_confirmed": 8,
        "orders_partial": 2,
        "rfq_pending": 1,
        "nc_open": 0,
        "revenue_month": 12500.00,
        "rating": 4.2
    }
}

Ordini di Acquisto

GET /supplier-portal/orders

Supplier

Lista ordini di acquisto del fornitore

Nome	Tipo	Descrizione
`status`	string	sent / confirmed / partial / received / invoiced / cancelled
`page`	int	Pagina (default: 1)
`per_page`	int	10–50 (default: 20)

GET /supplier-portal/orders/{id}

Supplier

Dettaglio ordine con righe articolo e consegne associate

POST /supplier-portal/orders/{id}/confirm

Supplier

Conferma ordine (solo se status = sent). Notifica email automatica al buyer.

{
    "notes": "Confermato, consegna prevista 10/03",
    "items": [
        {
            "id": 42,
            "confirmed_quantity": 100,
            "confirmed_delivery_date": "2026-03-10"
        }
    ]
}

POST /supplier-portal/orders/{id}/reject

Supplier

Rifiuta ordine (solo se status = sent). Notifica email automatica al buyer.

{
    "reason": "Materiale non disponibile"
}

Consegne (DDT)

GET /supplier-portal/deliveries

Supplier

Lista consegne registrate con riferimento al PO

POST /supplier-portal/deliveries

Supplier

Registra nuova consegna. Supporta sia application/json che multipart/form-data (per allegare il file DDT). Aggiorna automaticamente lo stato dell'ordine (partial / received).

{
    "purchase_order_id": 12,
    "delivery_number": "DDT-2026-0042",
    "delivery_date": "2026-03-10",
    "carrier": "DHL",
    "tracking_number": "1234567890",
    "notes": "Colli 3",
    "items": [
        {
            "purchase_order_item_id": 42,
            "quantity_delivered": 100
        }
    ]
}

POST /supplier-portal/deliveries/{id}/ddt

Supplier

Carica o sostituisce il file DDT allegato a una consegna esistente. Formato: multipart/form-data, campo ddt. Tipi accettati: PDF, JPG, PNG (max 5 MB).

Richieste di Offerta (RFQ)

GET /supplier-portal/rfq

Supplier

Lista RFQ indirizzate al fornitore

Nome	Tipo	Descrizione
`status`	string	pending / viewed / quoted / declined

GET /supplier-portal/rfq/{id}

Supplier

Dettaglio RFQ con righe articoli e offerte già inviate

POST /supplier-portal/rfq/{id}/view

Supplier

Segna la RFQ come visualizzata (status: pending → viewed)

POST /supplier-portal/rfq/{id}/quote

Supplier

Invia offerta per una RFQ aperta e non scaduta. Notifica email automatica al buyer.

{
    "items": [
        {
            "rfq_item_id": 7,
            "unit_price": 42.50,
            "availability": "full",       // full / partial / unavailable
            "proposed_delivery_date": "2026-04-01",
            "notes": "Prezzo valido 30gg"
        }
    ]
}

Non Conformità

GET /supplier-portal/nc

Supplier

Lista Non Conformità aperte o storiche del fornitore

Nome	Tipo	Descrizione
`status`	string	open / supplier_response / negotiation / resolved / closed

GET /supplier-portal/nc/{id}

Supplier

Dettaglio NC con thread messaggi e allegati. La prima lettura segna automaticamente supplier_viewed_at.

POST /supplier-portal/nc/{id}/message

Supplier

Invia risposta/proposta su una NC aperta. Notifica email automatica al responsabile. Aggiorna status a supplier_response.

{
    "message": "Accettiamo la non conformità e proponiamo nota credito.",
    "message_type": "proposal",           // response | proposal | question
    "proposed_action": "credit_note",
    "proposed_amount": 150.00,
    "accepts_responsibility": true
}

Rating

GET /supplier-portal/rating

Supplier

Rating complessivo e storico ultimi 6 mesi (delivery, quality, price, response score)

{
    "success": true,
    "data": {
        "current_rating": 4.2,
        "history": [
            {
                "period_year": 2026,
                "period_month": 1,
                "delivery_score": 4.5,
                "quality_score": 4.0,
                "price_score": 4.2,
                "response_score": 4.1,
                "overall_score": 4.2,
                "total_orders": 12,
                "on_time_deliveries": 11,
                "late_deliveries": 1,
                "total_nc": 0
            }
        ]
    }
}

Sistema di Supporto

POST /support/chat

Opzionale

Invia messaggio al chatbot AI

{
    "message": "Come posso tracciare il mio ordine?",
    "session_id": "abc123...",
    "context": {
        "portal_type": "customer-portal",
        "language": "it"
    }
}

POST /support/ticket

Opzionale

Crea ticket di supporto

Categorie disponibili

bug - Segnalazione bug
question - Domanda generale
feature_request - Richiesta funzionalità
login_issue - Problema di accesso
order_issue - Problema con ordine
other - Altro

Codici di Errore

Codice	Significato
`200`	OK - Richiesta riuscita
`201`	Created - Risorsa creata
`400`	Bad Request - Parametri non validi
`401`	Unauthorized - Autenticazione richiesta
`403`	Forbidden - Accesso negato
`404`	Not Found - Risorsa non trovata
`422`	Unprocessable Entity - Validazione fallita
`500`	Internal Server Error - Errore server

Formato errore standard

{
    "success": false,
    "error": "Descrizione dell'errore",
    "code": "ERROR_CODE"
}

Esempi di Integrazione

curl -X GET "https://madebycloud.it/erp/customers?page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

const response = await fetch('https://madebycloud.it/erp/customers', {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    }
});
const data = await response.json();

$ch = curl_init('https://madebycloud.it/erp/customers');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
    ]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);

import requests

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}
response = requests.get('https://madebycloud.it/erp/customers', headers=headers)
data = response.json()