Lanctot Invoice API Documentation

This page is written for Elastic integrators. Elastic backend services call this API when an end user clicks an invoice link in Order History.

Quick Start

Use the steps below to validate connectivity and contract behavior.

  1. Set the Base URL to the endpoint provided by Lanctot.
  2. Add the shared x-api-key header value.
  3. Call GET /health to verify service availability.
  4. Call POST /api/pdf with Elastic invoice identifiers.
  5. If the response contains base64 data, select Decode Base64 To PDF.
Recommendation: Use /v1/api/pdf for a versioned integration path.

Elastic Consumer Contract

This section defines the API contract for Elastic integrations.

1) Endpoint

  • Base URL: https://api.rlanctot.com
  • Method: POST
  • Path: /api/pdf
  • Production URL: https://api.rlanctot.com/api/pdf

2) Authentication

  • Mode: API key
  • Required header: x-api-key: <shared-secret>
  • Elastic backend sends this header on each request.

3) Supported Link Types

  • invoiceExternalUrl

4) Request Contract

{ "account_number": "C004380", "erp_order_number": "SO015557", "invoice_number": "PSINV000831", "format": "pdf", "link_type": "invoiceExternalUrl" }

5) Response Contract

Current mode: data (base64 PDF)

{ "success": true, "data": "JVBERi0xLjc...", "encoding": "base64" }

6) Error Contract

{ "errors": [ { "message": "Human readable message", "code": "ERROR_CODE" } ] }

7) Testing And Ops Notes

  • Use only the production endpoint for integrations.
  • No proxy is required while response mode is data.
  • Lanctot will provide timeout expectations, support contact, and environment details.

Authentication

Elastic backend callers authenticate using the mode configured by Lanctot. The current integration mode is API key.

Mode Header Value format
api_key x-api-key <shared secret>
bearer Authorization Bearer <token>
basic Authorization Basic <base64(user:pass)>

GET /health

GET/health

Health and runtime capabilities endpoint.

{ "status": "ok", "supported_link_types": ["invoiceExternalUrl"], "response_mode": "data", "timestamp": 1718550000 }

POST /api/pdf

POST/api/pdf

Primary endpoint Elastic calls to resolve invoice PDF content after user click actions.

Request body

Field Required Type Notes
account_number yes string Customer account identifier
erp_order_number yes string ERP order identifier
invoice_number yes for invoiceExternalUrl string Invoice number or BC invoice GUID
format yes string Must be pdf
link_type yes string invoiceExternalUrl

Example request

{ "account_number": "C004380", "erp_order_number": "SO015557", "invoice_number": "PSINV000831", "format": "pdf", "link_type": "invoiceExternalUrl" }

Success response (data mode)

{ "success": true, "data": "JVBERi0xLjc...", "encoding": "base64" }

Success response (url mode)

{ "success": true, "url": "https://api.rlanctot.com/pdf/abc123" }

Error response

{ "errors": [ { "message": "Human readable message", "code": "ERROR_CODE" } ] }

POST /v1/api/pdf

POST/v1/api/pdf

Versioned alias for /api/pdf. Uses the same request and response contract. Recommended for long-term client integrations.

GET /pdf/{token}

GET/pdf/{token}

Download endpoint used when response mode is url. Tokens expire according to PDF_URL_TTL_SECONDS.

Error Codes

Stable error codes for client handling. Human-readable messages may vary slightly; code semantics are stable.

Code HTTP Typical Trigger Example Message
BAD_REQUEST 400 Invalid payload, missing required fields, unsupported link type invoice_number is required for invoiceExternalUrl
UNAUTHORIZED 401 Missing or invalid inbound credentials Unauthorized: missing x-api-key header
INVOICE_NOT_FOUND 404 Invoice does not exist or has no PDF in BC routes Invoice not found in Business Central
PDF_NOT_FOUND 404 Tokenized PDF download URL expired or missing PDF not found or expired
BC_TIMEOUT 504 Business Central request timeout Business Central request timed out
BC_HTTP_ERROR 502 Business Central returned non-success HTTP response Business Central request failed (HTTP 400)
BC_DATA_ERROR 502 Unexpected BC payload shape Business Central invoice record did not include id
INTERNAL_ERROR 500 Unexpected server configuration/runtime error Internal server error
TOO_MANY_REQUESTS 429 Per-client request rate exceeded in 1-minute window Rate limit exceeded: too many requests. Please retry in 1 minute.

Integration Test Console

Use this console to simulate Elastic backend requests from the browser.

Response will appear here.
cURL preview will appear here.