Maventa-integraatio

Maventa on suomalainen verkkolaskuoperaattori, jonka kautta Kirjapro lähettää Finvoice 3.0 -verkkolaskuja.

Arkkitehtuuri

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Kirjapro      │────▶│  Supabase Edge   │────▶│   Maventa API   │
│   Frontend      │     │    Functions     │     │  (ax.maventa)   │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │                         │
                               ▼                         ▼
                        ┌──────────────────┐     ┌─────────────────┐
                        │    Supabase      │◀────│    Webhooks     │
                        │    Database      │     │  (status)       │
                        └──────────────────┘     └─────────────────┘

OAuth2-autentikointi

Access Token

POST https://ax.maventa.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={vendor_api_key}
&client_secret={user_api_key}
&scope=eui
&company_uuid={company_uuid}

Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

API-endpointit

Laskun lähetys

POST https://ax.maventa.com/v1/invoices
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "format": "FINVOICE30",
  "invoice": "{base64-encoded-finvoice-xml}",
  "recipient": {
    "eia": "003798765432",
    "operator": "003721291126"
  }
}

Response:

{
  "id": "invoice-uuid",
  "status": "PENDING",
  "created_at": "2024-01-15T10:30:00Z"
}

Laskun tilan kysely

GET https://ax.maventa.com/v1/invoices/{invoice_id}
Authorization: Bearer {access_token}

Webhook-tapahtumat

Toimitusilmoitukset

Maventa lähettää webhook-kutsun kun laskun tila muuttuu:

{
  "event": "invoice.delivered",
  "invoice_id": "invoice-uuid",
  "status": "DELIVERED",
  "timestamp": "2024-01-15T11:00:00Z"
}

Tilakoodit

Status	Merkitys
PENDING	Odottaa lähetystä
SENT	Lähetetty operaattorille
DELIVERED	Toimitettu vastaanottajalle
FAILED	Lähetys epäonnistui
REJECTED	Vastaanottaja hylkäsi

Webhook-varmistus

const signature = req.headers.get('X-Maventa-Signature');
const expectedSignature = createHmac('sha256', WEBHOOK_SECRET)
  .update(JSON.stringify(payload))
  .digest('hex');

if (signature !== expectedSignature) {
  return new Response('Invalid signature', { status: 401 });
}

Virhekäsittely

Yleiset virheet

Koodi	Virhe	Ratkaisu
401	Invalid credentials	Tarkista API-avaimet
400	Invalid Finvoice	Validoi XML-rakenne
404	Recipient not found	Tarkista verkkolaskuosoite
429	Rate limited	Odota ja yritä uudelleen

Retry-logiikka

Kirjapro yrittää uudelleen epäonnistuneet lähetykset:

Ensimmäinen yritys heti
Toinen yritys 5 min kuluttua
Kolmas yritys 30 min kuluttua
Merkitään epäonnistuneeksi

Testausympäristö

Test-tili

Rekisteröidy: testing.maventa.com
Pyydä vendor_api_key osoitteesta integrations@maventa.com
Testaa lähettämällä lasku testiosoitteeseen

Test-verkkolaskuosoite

EIA: 003700000000
Operator: 003721291126