README

The official PHP client for the VatFlow - EU VAT & Company Monitor API on RapidAPI.

VatFlow allows you to instantly validate European VAT numbers via VIES, enrich French company profiles (financials, executives, UBOs), and set up webhooks to monitor businesses for critical status changes.

Requirements

• PHP 7.4 or higher
• Composer
• A RapidAPI account and API key

Installation

You can install the package via Composer:

composer require quicreatdev/vatflow-php

Quick Start

To use the API, you need your RapidAPI key. You can find it in your RapidAPI Studio dashboard after subscribing to the VatFlow API.

require 'vendor/autoload.php';

use VatFlow\VatFlowClient;

// Initialize the client
$client = new VatFlowClient('YOUR_RAPIDAPI_KEY');

Usage

All methods return a standard PHP array decoded from the JSON response. You can check the success key to determine if the API call was successful.

1. Validate and Enrich a VAT Number

The validate method checks a VAT number and retrieves the company data.

Built-in Auto-Retry: By default, this SDK includes a robust auto-retry mechanism. If the government server (VIES) or the network experiences a temporary failure (HTTP 5xx), the client will automatically wait and retry up to 3 times before failing.

$vatNumber = 'FR14652014051';
$maxCacheDays = 7; // Request data no older than 7 days (default)
$autoRetry = true; // Automatically retry on 5xx network errors (default)

$response = $client->validate($vatNumber, $maxCacheDays, $autoRetry);

if ($response['success']) {
    echo "Company Name: " . $response['data']['name'] . "\n";
    echo "Address: " . $response['data']['address'] . "\n";
    echo "Is Valid: " . ($response['data']['is_valid'] ? 'Yes' : 'No') . "\n";
} else {
    echo "Error: " . $response['error'];
}

2. Subscribe to Webhook Alerts

Register a webhook URL to be notified proactively if a company's status or data changes.

$vatNumber = 'FR14652014051';
$webhookUrl = 'https://api.yourdomain.com/webhooks/vatflow';

$response = $client->subscribeWebhook($vatNumber, $webhookUrl);

if ($response['success']) {
    echo "Subscribed! Subscription ID: " . $response['data']['subscription_id'];
}

3. List Active Webhooks

Retrieve a list of all VAT numbers you are currently monitoring.

$response = $client->listWebhooks();

if ($response['success']) {
    echo "You have " . $response['count'] . " active webhooks.\n";
    print_r($response['data']);
}

4. Delete a Webhook

Unsubscribe from alerts for a specific VAT number.

$vatNumber = 'FR14652014051';
$subscriptionId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

$response = $client->deleteWebhook($vatNumber, $subscriptionId);

if ($response['success']) {
    echo "Webhook successfully deleted.";
}

Error Handling

The client handles JSON decoding and basic network exceptions. If a request fails at the API level (e.g., invalid VAT format, missing parameters, or exceeding your RapidAPI quota), the method will return an array with success set to false and an error message.

array(3) {
  ["success"] => bool(false)
  ["error"] => string(60) "The VAT number format is invalid for this country."
  ["status_code"] => int(400) // Provided for network or severe API errors
}

License

This project is licensed under the MIT License.