Supplydrive API for Laravel

darvis/supplydrive-api is a Laravel client for the Supplydrive API. Supplydrive is a Dutch PEPPOL access point and EDI provider: you send them an invoice, they deliver it to the receiver. This package sends the invoice and asks their portal what happened to it.

It is for a Laravel developer whose application sends invoices through Supplydrive and wants to show, record or act on the delivery.

What it does

  • Sending. SupplydriveSender::send() posts a UBL document to the send endpoint and gives you back the message id Supplydrive answered with, the key for its status history. Nothing is retried: a document sent twice is delivered twice.
  • Login. The portal account is exchanged for an access token (OAuth password grant). The token is kept encrypted in the cache until sixty seconds before it expires, and the client logs in again once when the portal refuses it.
  • Six lookups: byFunctionalId() (your invoice number), byMessageId() (the id Supplydrive answered with), byDebtorKvk(), byDebtorGln(), byDebtorVat() and messageStatus() for any combination of filters.
  • Typed results: a Message per item, and a MessageStatus enum for the eight statuses Supplydrive documents, with isDelivered(), isFailed() and isPending() and a description in English or Dutch.
  • Failures you can act on: a SupplydriveException with the HTTP status in $e->status(); a 404 is simply an empty list.
  • The password stays out of sight: never in a URL, and removed from error messages before they are thrown, logged or printed.
  • Two connection tests: php artisan supplydrive:status and php artisan supplydrive:send.
  • An MCP server for Claude and other AI agents, with lookup-message-status and explain-statuses, registered when laravel/mcp is installed.

What it does not do

  • No building of UBL. The document you send comes from darvis/ubl-peppol or another UBL 2.1 builder.
  • No Eloquent models, no migrations and no database tables. You get Message objects back and store what you need yourself.
  • No polling, no scheduler and no queue jobs. When and how often you ask Supplydrive is up to your application.
  • No webhooks and no routes. The MCP server only reads.
  • No retry for a 5xx or a timeout, and none at all for a send.
  • No facade.

Requirements

  • PHP 8.2+
  • Laravel 11, 12 or 13
  • A Supplydrive portal account with the role for the status endpoint, and the send account with its URL for sending; ask Supplydrive for both

Install 

composer require darvis/supplydrive-api

SUPPLYDRIVE_USERNAME=your-username
SUPPLYDRIVE_PASSWORD=your-password

SUPPLYDRIVE_SEND_USERNAME=your-send-username
SUPPLYDRIVE_SEND_PASSWORD=your-send-password

php artisan supplydrive:status --functional-id=F260001

Pages

  • Installation: the steps from composer require to a lookup that works, and how to check it
  • Quick start: one complete example, a scheduled command that records the delivery on the invoice
  • Sending: post a UBL document, keep the message id, and what a timeout means
  • How it works: the login, where the token is kept, the one repeat after a 401, the statuses, timeouts and where the password goes
  • API reference: every public method, the value object, the enum, the exception, the command and the container binding
  • Testing: fake Supplydrive in the tests of your application
  • MCP server: let an AI agent look messages up through php artisan mcp:start supplydrive
  • Troubleshooting: every message the package gives, with its cause and its fix
  • FAQ: short answers to the questions people ask first

This is an unofficial package, not made or endorsed by Supplydrive B.V.