{ "openapi": "3.1.0", "info": { "title": "Bilnex Partner API", "description": "REST API for embedding Bilnex e-invoicing into an ERP: send invoices as PDF-by-email, Estonian operator-channel e-invoices or Peppol; receive purchase invoices; confirm ERP imports.\n\nAuthenticate with `Authorization: Bearer `. Provision a sandbox key with no account at POST /partner/v1/sandbox, then iterate until GET /partner/v1/sandbox/verification reports readyForProduction.", "version": "2026-08-01" }, "servers": [ { "url": "https://sandbox.bilnex.io", "description": "Sandbox — self-serve keys, simulated rails" }, { "url": "https://api.app.bilnex.io", "description": "Production — real rails, keys issued by Bilnex" } ], "security": [ { "BearerAuth": [] }, { "PartnerApiKey": [] } ], "tags": [ { "name": "Partner — Account", "description": "Key identity, companies and quotas" }, { "name": "Partner — Purchase invoices", "description": "Receive incoming documents and confirm ERP import" }, { "name": "Partner — Docs", "description": "Agent-facing documentation and skill discovery" }, { "name": "Partner — Sandbox", "description": "Self-serve test environment and integration verification" }, { "name": "Partner — Invoices", "description": "Create, read and send sales invoices" }, { "name": "Partner — Customers", "description": "Recipient reachability lookups" } ], "paths": { "/partner/v1/sandbox": { "get": { "tags": [ "Partner — Sandbox" ], "summary": "Describe this sandbox: companies, fixtures, quotas and expiry", "operationId": "state", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SandboxStateResponse" } } } } } }, "post": { "tags": [ "Partner — Sandbox" ], "summary": "Provision a sandbox with an API key, a company pair and test counterparties", "operationId": "provision", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionSandboxRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ProvisionSandboxResponse" } } } } } } }, "/partner/v1/sandbox/trigger": { "post": { "tags": [ "Partner — Sandbox" ], "summary": "Make an inbound document arrive, or an emailed invoice be opened", "operationId": "trigger", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxTriggerRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "object", "additionalProperties": {} } } } } } } }, "/partner/v1/sandbox/reset": { "post": { "tags": [ "Partner — Sandbox" ], "summary": "Delete all documents, emails and verification progress, keeping the key", "operationId": "reset", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SandboxStateResponse" } } } } } } }, "/partner/v1/sandbox/claim": { "post": { "tags": [ "Partner — Sandbox" ], "summary": "Extend this sandbox's lifetime once", "operationId": "claim", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SandboxStateResponse" } } } } } } }, "/partner/v1/purchase-invoices/{purchaseInvoiceId}/mark-exported": { "post": { "tags": [ "Partner — Purchase invoices" ], "summary": "Confirm the ERP has imported this document", "operationId": "markExported", "parameters": [ { "name": "purchaseInvoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerPurchaseInvoiceDto" } } } } } } }, "/partner/v1/invoices": { "get": { "tags": [ "Partner — Invoices" ], "summary": "List sales invoices, newest first", "operationId": "list", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "customerRegCode", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerPageDtoPartnerInvoiceDto" } } } } } }, "post": { "tags": [ "Partner — Invoices" ], "summary": "Create a sales invoice; the server computes all totals", "operationId": "create", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerInvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerInvoiceDto" } } } } } } }, "/partner/v1/invoices/{invoiceId}/send": { "post": { "tags": [ "Partner — Invoices" ], "summary": "Send the invoice as an e-invoice, a Peppol document or an email", "operationId": "send", "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerSendRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerSendResponse" } } } } } } }, "/partner/v1/sandbox/verification": { "get": { "tags": [ "Partner — Sandbox" ], "summary": "Check which integration behaviours have been proven, and what is missing", "operationId": "verification", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/VerificationReportDto" } } } } } } }, "/partner/v1/sandbox/emails": { "get": { "tags": [ "Partner — Sandbox" ], "summary": "Read the outbound emails this sandbox captured instead of delivering", "operationId": "emails", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxEmailDto" } } } } } } } }, "/partner/v1/purchase-invoices": { "get": { "tags": [ "Partner — Purchase invoices" ], "summary": "List incoming documents, newest first, optionally since a cursor", "operationId": "list_1", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerPageDtoPartnerPurchaseInvoiceDto" } } } } } } }, "/partner/v1/purchase-invoices/{purchaseInvoiceId}": { "get": { "tags": [ "Partner — Purchase invoices" ], "summary": "Read one incoming document", "operationId": "get", "parameters": [ { "name": "purchaseInvoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerPurchaseInvoiceDto" } } } } } } }, "/partner/v1/purchase-invoices/{purchaseInvoiceId}/original": { "get": { "tags": [ "Partner — Purchase invoices" ], "summary": "Get a short-lived download URL for the document as it was received", "operationId": "original", "parameters": [ { "name": "purchaseInvoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "object", "additionalProperties": {} } } } } } } }, "/partner/v1/openapi.json": { "get": { "tags": [ "Partner — Docs" ], "summary": "OpenAPI 3.1 description of the Partner API", "operationId": "openApi", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "string" } } } } } } }, "/partner/v1/me": { "get": { "tags": [ "Partner — Account" ], "summary": "Describe the calling API key, its companies and its remaining quota", "operationId": "me", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerMeResponse" } } } } } } }, "/partner/v1/invoices/{invoiceId}": { "get": { "tags": [ "Partner — Invoices" ], "summary": "Read one sales invoice", "operationId": "get_1", "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PartnerInvoiceDto" } } } } } } }, "/partner/v1/invoices/{invoiceId}/pdf": { "get": { "tags": [ "Partner — Invoices" ], "summary": "Get a short-lived download URL for the invoice PDF", "operationId": "pdf", "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "object", "additionalProperties": {} } } } } } } }, "/partner/v1/customers/{regCode}/e-invoice-capability": { "get": { "tags": [ "Partner — Customers" ], "summary": "Check whether a recipient can receive e-invoices, and on which rail", "operationId": "capability", "parameters": [ { "name": "regCode", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CapabilityResponse" } } } } } } } }, "components": { "schemas": { "ProvisionSandboxRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 320, "minLength": 0 }, "erpName": { "type": "string", "maxLength": 100, "minLength": 0 }, "ref": { "type": "string", "maxLength": 100, "minLength": 0 } }, "required": [ "email", "erpName" ] }, "PartnerCompanyDto": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "regCode": { "type": "string" }, "role": { "type": "string" }, "peppolId": { "type": "string" } } }, "PartnerLimitsDto": { "type": "object", "properties": { "requestsPerMinute": { "type": "integer", "format": "int32" }, "requestsPerDay": { "type": "integer", "format": "int32" }, "sendsPerDay": { "type": "integer", "format": "int32" }, "maxInvoices": { "type": "integer", "format": "int32" }, "maxEmails": { "type": "integer", "format": "int32" } } }, "ProvisionSandboxResponse": { "type": "object", "properties": { "apiKey": { "type": "string" }, "keyId": { "type": "string", "format": "uuid" }, "keyPrefix": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "companies": { "$ref": "#/components/schemas/SandboxCompaniesDto" }, "fixtures": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxFixtureDto" } }, "limits": { "$ref": "#/components/schemas/PartnerLimitsDto" }, "urls": { "$ref": "#/components/schemas/SandboxUrlsDto" } } }, "SandboxCompaniesDto": { "type": "object", "properties": { "sender": { "$ref": "#/components/schemas/PartnerCompanyDto" }, "receiver": { "$ref": "#/components/schemas/PartnerCompanyDto" } } }, "SandboxFixtureDto": { "type": "object", "properties": { "name": { "type": "string" }, "regCode": { "type": "string" }, "behavior": { "type": "string" }, "description": { "type": "string" } } }, "SandboxUrlsDto": { "type": "object", "properties": { "docs": { "type": "string" }, "verification": { "type": "string" }, "openapi": { "type": "string" }, "claim": { "type": "string" } } }, "SandboxTriggerRequest": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "INBOUND_EINVOICE", "INBOUND_PEPPOL", "INVOICE_SEEN" ] }, "invoiceId": { "type": "string", "format": "uuid" } }, "required": [ "event" ] }, "PartnerUsageDto": { "type": "object", "properties": { "requestsToday": { "type": "integer", "format": "int64" }, "sendsToday": { "type": "integer", "format": "int64" }, "emailsCaptured": { "type": "integer", "format": "int64" } } }, "SandboxStateResponse": { "type": "object", "properties": { "sandboxId": { "type": "string", "format": "uuid" }, "erpName": { "type": "string" }, "status": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "claimed": { "type": "boolean" }, "companies": { "$ref": "#/components/schemas/SandboxCompaniesDto" }, "fixtures": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxFixtureDto" } }, "limits": { "$ref": "#/components/schemas/PartnerLimitsDto" }, "usage": { "$ref": "#/components/schemas/PartnerUsageDto" }, "urls": { "$ref": "#/components/schemas/SandboxUrlsDto" } } }, "PartnerPurchaseInvoiceDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "source": { "type": "string" }, "senderName": { "type": "string" }, "invoiceNumber": { "type": "string" }, "date": { "type": "string", "format": "date-time" }, "dueDate": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "totalAmount": { "type": "number" }, "receivedAt": { "type": "string", "format": "date-time" } } }, "Customer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "regCode": { "type": "string", "minLength": 1 }, "email": { "type": "string" }, "address": { "type": "string" } }, "required": [ "name", "regCode" ] }, "LineItem": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1 }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "price": { "type": "number" }, "vatRate": { "type": "number" } }, "required": [ "description", "price", "quantity", "vatRate" ] }, "PartnerInvoiceRequest": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" }, "date": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "language": { "type": "string" }, "number": { "type": "string" }, "reference": { "type": "string" }, "note": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/LineItem" }, "minItems": 1 } }, "required": [ "customer", "items" ] }, "PartnerInvoiceDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "category": { "type": "string" }, "customerName": { "type": "string" }, "customerRegCode": { "type": "string" }, "date": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "totalAmount": { "type": "number" } } }, "PartnerSendRequest": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "E_INVOICE", "PEPPOL", "EMAIL" ] }, "to": { "type": "string" }, "message": { "type": "string" } }, "required": [ "channel" ] }, "PartnerSendResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "category": { "type": "string" }, "channel": { "type": "string" }, "sentAt": { "type": "string", "format": "date-time" } } }, "VerificationCheckDto": { "type": "object", "properties": { "id": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "detail": { "type": "string" }, "fixHint": { "type": "string" }, "docsUrl": { "type": "string" } } }, "VerificationReportDto": { "type": "object", "properties": { "checks": { "type": "array", "items": { "$ref": "#/components/schemas/VerificationCheckDto" } }, "readyForProduction": { "type": "boolean" }, "nextSteps": { "type": "array", "items": { "type": "string" } } } }, "SandboxEmailDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "to": { "type": "string" }, "cc": { "type": "string" }, "from": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "attachmentName": { "type": "string" }, "sentAt": { "type": "string", "format": "date-time" } } }, "PartnerPageDtoPartnerPurchaseInvoiceDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerPurchaseInvoiceDto" } }, "page": { "type": "integer", "format": "int32" }, "pageSize": { "type": "integer", "format": "int32" }, "total": { "type": "integer", "format": "int64" }, "hasMore": { "type": "boolean" }, "nextSince": { "type": "string", "format": "date-time" } } }, "PartnerMeResponse": { "type": "object", "properties": { "environment": { "type": "string" }, "keyId": { "type": "string", "format": "uuid" }, "keyExpiresAt": { "type": "string", "format": "date-time" }, "actingCompany": { "$ref": "#/components/schemas/PartnerCompanyDto" }, "companies": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerCompanyDto" } }, "limits": { "$ref": "#/components/schemas/PartnerLimitsDto" }, "usage": { "$ref": "#/components/schemas/PartnerUsageDto" } } }, "PartnerPageDtoPartnerInvoiceDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerInvoiceDto" } }, "page": { "type": "integer", "format": "int32" }, "pageSize": { "type": "integer", "format": "int32" }, "total": { "type": "integer", "format": "int64" }, "hasMore": { "type": "boolean" }, "nextSince": { "type": "string", "format": "date-time" } } }, "CapabilityResponse": { "type": "object", "properties": { "regCode": { "type": "string" }, "name": { "type": "string" }, "eInvoiceCapable": { "type": "boolean" }, "operator": { "type": "string" }, "peppolCapable": { "type": "boolean" }, "peppolId": { "type": "string" }, "recommendedChannel": { "type": "string" }, "checkedAt": { "type": "string", "format": "date-time" } } } }, "securitySchemes": { "PartnerApiKeyHeader": { "type": "apiKey", "description": "Alternative to the Authorization header.", "name": "X-API-Key", "in": "header" }, "PartnerApiKey": { "type": "http", "description": "Your Partner API key, e.g. blx_sbx_… or blx_live_…", "scheme": "bearer" }, "BearerAuth": { "type": "http", "in": "header", "scheme": "bearer", "bearerFormat": "JWT" } } } }