README

A universal PHP package for making requests to the DUPR Partner API. This package provides a clean and intuitive interface for interacting with all DUPR Partner API endpoints.

Installation

Install the package via Composer:

composer require infoesportes/dupr-partner-api

Requirements

• PHP 8.0 or higher
• ext-json
• guzzlehttp/guzzle ^7.0

Quick Start

<?php

require 'vendor/autoload.php';

use InfoEsportes\Dupr\PartnerApi\Client;

// Initialize the client with environment (UAT or production)
$client = new Client(
    clientKey: 'your-client-key',
    clientSecret: 'your-client-secret',
    environment: Client::ENV_UAT, // or Client::ENV_PRODUCTION
    version: 'v1' // Optional, defaults to v1
);

// Now you can make API calls directly - authentication is handled automatically!
$userInfo = $client->users()->getUserInfo('DUPR_ID_HERE');

Authentication

Authentication is handled automatically by the client! You don't need to manually generate access tokens. The client will:

1. Automatically fetch an access token when making the first API request
2. Reuse the token for subsequent requests
3. Automatically refresh the token when it expires

Just initialize the client and start making API calls:

$client = new Client('your-key', 'your-secret', Client::ENV_UAT);

// No need to call auth()->generateToken()
// Just make your API calls directly
$user = $client->users()->getUserInfo('DUPR_ID');

Manual Token Generation (Optional)

If you need to manually generate a token for some reason, you can still do so:

$tokenResponse = $client->auth()->generateToken();

You can also set a token manually if you have one:

$client->setAccessToken('your-access-token');

Usage Examples

Players

Get Player Ratings

$ratings = $client->players()->getRatings([
    'duprIds' => ['DUPR_ID_1', 'DUPR_ID_2'],
    'sortBy' => 'rating'
]);

Get DUPR ID by Email

$result = $client->players()->getDuprIdByEmail('player@example.com');

Player Ratings

Subscribe to Rating Changes

$client->playerRatings()->subscribe(['DUPR_ID_1', 'DUPR_ID_2']);

Get Rating Subscriptions

$subscriptions = $client->playerRatings()->getSubscriptions();

Unsubscribe from Rating Changes

$client->playerRatings()->unsubscribe(['DUPR_ID_1', 'DUPR_ID_2']);

Get Player Rating History

$history = $client->playerRatings()->getHistory(
    duprId: 'DUPR_ID',
    offset: 0,
    limit: 25
);

Users

Get User Information

$user = $client->users()->getUserInfo('DUPR_ID');

Get Extended User Details

$details = $client->users()->getUserDetails('DUPR_ID');

Get User's Club Memberships

$clubs = $client->users()->getUserClubs('DUPR_ID');

Search Users

$searchResults = $client->users()->search([
    'query' => 'John Doe',
    'offset' => 0,
    'limit' => 25,
    'filters' => [
        'gender' => 'male',
        'location' => [
            'lat' => 37.7749,
            'lng' => -122.4194,
            'address' => 'San Francisco, CA, USA',
            'radiusInMeters' => 40233.6
        ],
        'rating' => [
            'min' => 3.0,
            'max' => 5.0,
            'type' => 'DOUBLES',
            'reliable' => true
        ],
        'age' => [
            'min' => 18,
            'max' => 45
        ]
    ]
]);

Provisional Ratings

// Get provisional rating
$rating = $client->users()->getProvisionalRating('DUPR_ID');

// Create provisional rating
$client->users()->createProvisionalRating([
    'duprId' => 'DUPR_ID',
    'provisionalSinglesRating' => 3.5,
    'provisionalDoublesRating' => 4.0,
    'coach' => [
        'id' => '12345',
        'metadata' => [
            'name' => 'Coach Name'
        ]
    ]
]);

// Update provisional rating
$client->users()->updateProvisionalRating([
    'duprId' => 'DUPR_ID',
    'provisionalSinglesRating' => 3.8,
    'provisionalDoublesRating' => 4.2
]);

// Delete provisional rating
$client->users()->deleteProvisionalRating('DUPR_ID');

Invite User

$invitation = $client->users()->invite([
    'fullName' => 'John Doe',
    'email' => 'john.doe@example.com',
    'isoCode' => 'US',
    'phone' => '+19876543210',
    'identifier' => '12345'
]);

Grant Subscription

$client->users()->grantSubscription([
    'user' => [
        'duprId' => 'DUPR_ID'
    ],
    'item' => [
        'productId' => 'product-123',
        'promotionId' => 'promo-456'
    ],
    'metadata' => [
        'key1' => 'value1'
    ]
]);

Webhook Subscriptions

// Subscribe to webhook events
$client->users()->subscribeWebhook([
    'duprIds' => ['DUPR_ID_1', 'DUPR_ID_2'],
    'topic' => 'RATING'
]);

// Unsubscribe from webhook events
$client->users()->unsubscribeWebhook([
    'duprIds' => ['DUPR_ID_1', 'DUPR_ID_2'],
    'topic' => 'RATING'
]);

Matches

Create a Match

$match = $client->matches()->create([
    'location' => 'Newport Beach, CA',
    'matchDate' => '2024-01-15',
    'teamA' => [
        'player1' => 'DUPR_ID_1',
        'player2' => 'DUPR_ID_2',
        'game1' => 11,
        'game2' => 9
    ],
    'teamB' => [
        'player1' => 'DUPR_ID_3',
        'player2' => 'DUPR_ID_4',
        'game1' => 7,
        'game2' => 11
    ],
    'format' => 'DOUBLES',
    'event' => 'Tournament Name',
    'bracket' => 'Main Draw',
    'matchType' => 'RALLY',
    'identifier' => 'unique-match-id-123',
    'clubId' => 7614955351,
    'extras' => [
        'court' => 'Court 1'
    ],
    'matchSource' => 'CLUB'
]);

Create Matches in Bulk

$matches = $client->matches()->createBatch([
    [
        'matchDate' => '2024-01-15',
        'teamA' => ['player1' => 'ID1', 'game1' => 11],
        'teamB' => ['player1' => 'ID2', 'game1' => 9],
        'format' => 'SINGLES',
        'event' => 'Tournament',
        'identifier' => 'match-1'
    ],
    [
        'matchDate' => '2024-01-15',
        'teamA' => ['player1' => 'ID3', 'game1' => 11],
        'teamB' => ['player1' => 'ID4', 'game1' => 7],
        'format' => 'SINGLES',
        'event' => 'Tournament',
        'identifier' => 'match-2'
    ]
]);

Update a Match

$client->matches()->update([
    'matchId' => 12345,
    'location' => 'Los Angeles, CA',
    'matchDate' => '2024-01-15',
    'teamA' => [
        'player1' => 'DUPR_ID_1',
        'game1' => 11
    ],
    'teamB' => [
        'player1' => 'DUPR_ID_2',
        'game1' => 9
    ],
    'format' => 'SINGLES',
    'event' => 'Updated Tournament',
    'identifier' => 'unique-match-id'
]);

Delete a Match

$client->matches()->deleteMatch(
    matchCode: 'match-code-from-creation',
    identifier: 'unique-match-id'
);

Get Match by ID

$match = $client->matches()->getMatch(12345);

Search Match History

$history = $client->matches()->searchHistory([
    'duprId' => 'DUPR_ID',
    'offset' => 0,
    'limit' => 10,
    'eventFormat' => ['SINGLES', 'DOUBLES'],
    'startDate' => 1724099943, // Unix timestamp in seconds
    'endDate' => 1724100043
]);

Clubs

Get Club Members Ratings

$members = $client->clubs()->getMembersRatings(7614955351);

Search Club Matches

$matches = $client->clubs()->searchMatches([
    'clubId' => 7614955351,
    'offset' => 0,
    'limit' => 10,
    'eventFormat' => ['SINGLES', 'DOUBLES'],
    'startDate' => 1724099943,
    'endDate' => 1724100043
]);

Events

Create an Event

$event = $client->events()->create([
    'metadata' => [
        'metadata' => [
            'customKey' => 'customValue'
        ]
    ],
    'data' => [
        'name' => 'Summer Tournament',
        'address' => '123 Main St, City, State',
        'registrationUrl' => 'https://example.com/register',
        'minRating' => 2.5,
        'maxRating' => 5.0,
        'minAge' => 18,
        'maxAge' => 65
    ],
    'text' => [
        'text' => [
            'description' => 'Annual summer tournament'
        ]
    ],
    'date' => [
        'startTime' => '2024-06-01T09:00:00Z',
        'endTime' => '2024-06-03T18:00:00Z'
    ]
]);

Update Events

$client->events()->update([
    'event-id-1' => [
        'metadata' => ['metadata' => []],
        'data' => [
            'name' => 'Updated Tournament',
            'address' => '456 New St',
            'registrationUrl' => 'https://example.com',
            'minRating' => 3.0,
            'maxRating' => 5.0,
            'minAge' => 21,
            'maxAge' => 60
        ],
        'text' => ['text' => []],
        'date' => [
            'startTime' => '2024-07-01T09:00:00Z',
            'endTime' => '2024-07-03T18:00:00Z'
        ]
    ]
]);

Delete Events

$client->events()->deleteEvents(['event-id-1', 'event-id-2']);

Get Events

$events = $client->events()->getEvents(['event-id-1', 'event-id-2']);

API Registration

Register Webhook

$client->apiRegistration()->registerWebhook([
    'clientId' => 'your-client-id',
    'webhookUrl' => 'https://your-domain.com/webhook',
    'topics' => ['RATING', 'MATCH']
]);

Get Available Topics

$topics = $client->apiRegistration()->getTopics();

Error Handling

All methods throw InfoEsportes\Dupr\PartnerApi\Exceptions\DuprApiException on error:

use InfoEsportes\Dupr\PartnerApi\Exceptions\DuprApiException;

try {
    $user = $client->users()->getUserInfo('INVALID_ID');
} catch (DuprApiException $e) {
    echo "Error: " . $e->getMessage();
    echo "Code: " . $e->getCode();
}

API Reference

Client Methods

• auth() - Returns AuthResource
• events() - Returns EventResource
• players() - Returns PlayerResource
• playerRatings() - Returns PlayerRatingResource
• users() - Returns UserResource
• matches() - Returns MatchResource
• clubs() - Returns ClubResource
• apiRegistration() - Returns ApiRegistrationResource
• setAccessToken(string $token) - Manually set access token
• getAccessToken() - Get current access token
• getVersion() - Get API version
• request(string $method, string $path, array $options = []) - Make raw API request

Environment Configuration

The package supports two environments:

UAT (Testing Environment - Default)

use InfoEsportes\Dupr\PartnerApi\Client;

$client = new Client(
    clientKey: 'your-client-key',
    clientSecret: 'your-client-secret',
    environment: Client::ENV_UAT // This is the default
);

Production

use InfoEsportes\Dupr\PartnerApi\Client;

$client = new Client(
    clientKey: 'your-client-key',
    clientSecret: 'your-client-secret',
    environment: Client::ENV_PRODUCTION
);

Environment URLs:

• UAT: https://uat.mydupr.com/api
• Production: https://api.dupr.com/api

PHPDoc Type Hints

All methods that accept arrays or objects as parameters include detailed PHPDoc annotations using @phpstan-param to document the valid keys and types. This provides excellent IDE autocompletion and type checking when using static analysis tools like PHPStan.

Testing

Run tests with PHPUnit:

composer test

Run static analysis with PHPStan:

composer phpstan

License

MIT License - See LICENSE file for details.

Authors

• Luiz Cristino - luiz.cristino@infoesportes.com.br
• Lucas Pinheiro - lucas.pinheiro@infoesportes.com.br

Support

For API documentation and support, visit:

• Official API Documentation: https://uat.mydupr.com/api/swagger-ui/index.html
• DUPR Website: https://mydupr.com

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Repository

GitHub: infoesportes/dupr-partner-api