README

SDK oficial en PHP para consumir la API de Nextpyme (DIAN, facturacion electronica, nomina y servicios asociados).

Requisitos

• PHP >=7.4
• Composer

Instalacion

composer require nextpyme/sdk-php

Inicializacion del cliente

<?php

require __DIR__ . '/vendor/autoload.php';

use Nextpyme\Sdk\NextpymeClient;

$nextpyme = new NextpymeClient([
    'token' => getenv('NEXTPYME_TOKEN'),
    'environment' => 'sandbox', // production|sandbox|custom
    // 'baseUrl' => 'https://mi-api.local/api', // requerido si environment=custom
    'debug' => false,
    'timeoutMs' => 30000,
    'maxRetries' => 2,
    'userAgent' => '@nextpyme/sdk-php',
]);

Opciones por request

Los metodos que reciben opts aceptan:

• retry (bool): habilita reintentos para esa solicitud.
• timeoutMs (int): timeout puntual.
• headers (array): headers adicionales.

Ejemplo:

$result = $nextpyme->invoice()->create($payload, [
    'retry' => true,
    'timeoutMs' => 60000,
]);

Ejemplos por servicio

1) Invoice

// Factura
$invoice = $nextpyme->invoice()->create([
    'number' => 990000001,
    'type_document_id' => 1,
    'customer' => [/* ... */],
    'legal_monetary_totals' => [/* ... */],
    'invoice_lines' => [/* ... */],
], ['retry' => true]);

// Nota credito
$creditNote = $nextpyme->invoice()->creditNote([
    'billing_reference' => [/* ... */],
    'legal_monetary_totals' => [/* ... */],
    'credit_note_lines' => [/* ... */],
]);

// Nota debito
$debitNote = $nextpyme->invoice()->debitNote([
    'billing_reference' => [/* ... */],
    'legal_monetary_totals' => [/* ... */],
    'debit_note_lines' => [/* ... */],
]);

2) Payroll

// Nomina electronica
$payroll = $nextpyme->payroll()->create([
    'consecutive' => '1001',
    'prefix' => 'NI',
    'period' => [/* ... */],
    'accrued' => [/* ... */],
    'deductions' => [/* ... */],
]);

// Nota de ajuste de nomina
$adjust = $nextpyme->payroll()->adjustNote([
    'type_note' => 1,
    'predecessor' => [/* ... */],
    'period' => [/* ... */],
]);

3) Support Document

// Documento soporte
$support = $nextpyme->supportDocument()->create([
    'number' => 123,
    'seller' => [/* ... */],
    'legal_monetary_totals' => [/* ... */],
    'invoice_lines' => [/* ... */],
]);

// Nota credito documento soporte
$sdCredit = $nextpyme->supportDocument()->creditNote([
    'billing_reference' => [/* ... */],
    'seller' => [/* ... */],
    'credit_note_lines' => [/* ... */],
]);

4) Events

// Evento RADIAN con datos
$eventData = $nextpyme->events()->sendWithData([
    'event_id' => 1,
    'type_rejection_id' => null,
    'document_reference' => ['cufe' => '...'],
]);

// Evento RADIAN con XML adjunto base64
$eventXml = $nextpyme->events()->sendWithXml([
    'event_id' => 1,
    'base64_attacheddocument_name' => 'evento.xml',
    'base64_attacheddocument' => 'PD94bWwgdmVyc2lvbj0iMS4wIiA/Pg==',
]);

// Acuse de recibo por IMAP
$imap = $nextpyme->events()->imapReceipt([
    'start_date' => '2025-01-01',
    'end_date' => '2025-01-31',
]);

5) Status

$documentStatus = $nextpyme->status()->document('uuid-o-cufe');
$eventStatus = $nextpyme->status()->events('uuid-o-cufe');
$documentInfo = $nextpyme->status()->documentInfo('uuid-o-cufe');

6) Reports

$software = $nextpyme->reports()->software();
$company = $nextpyme->reports()->company();
$resolutions = $nextpyme->reports()->resolutions();

$dashboard = $nextpyme->reports()->dashboard([
    'date_between' => true,
    'start_date' => '2025-01-01 00:00:00',
    'end_date' => '2025-12-31 23:59:59',
]);

$masterTables = $nextpyme->reports()->masterTables([
    'tables' => [
        ['table' => 'municipalities'],
        ['table' => 'departments'],
    ],
]);

$certificates = $nextpyme->reports()->certificates('900123456');

7) Config

$logo = $nextpyme->config()->logo([
    'logo' => '/9j/4AAQSkZJRgABAQAAAQABAAD...', // base64
]);

$environment = $nextpyme->config()->environment([
    'type_environment_id' => 2,
]);

$resolution = $nextpyme->config()->resolution([
    'type_document_id' => 1,
    'prefix' => 'SETP',
    'resolution' => '18764000001',
    'resolution_date' => '2019-01-19',
    'technical_key' => 'fc8e...',
    'from' => 990000000,
    'to' => 995000000,
    'date_from' => '2019-01-19',
    'date_to' => '2030-01-19',
]);

$template = $nextpyme->config()->changeTemplate([
    'template_name' => 'one',
]);

8) Downloads

Convenciones de nombre de archivo por tipo de documento:

// Descargar archivo (PDF, XML, ZIP, etc.)
$result = $nextpyme->downloads()->download('900123456', 'FES-SETP990000001.pdf');
file_put_contents('factura.pdf', $result['data']);

// Descargar en base64
$result = $nextpyme->downloads()->download('900123456', 'FES-SETP990000001.pdf', ['base64' => true]);

// Obtener XML directamente desde la DIAN por UUID/CUFE
$xml = $nextpyme->downloads()->xmlFromDian('uuid-del-documento');

// Unir múltiples PDFs en uno solo
$joined = $nextpyme->downloads()->joinPdfs([
    'name_joined_pdfs' => 'facturas-enero',
    'pdfs' => [
        ['type_document_id' => 1, 'prefix' => 'SETP', 'number' => '990000001'],
        ['type_document_id' => 1, 'prefix' => 'SETP', 'number' => '990000002'],
    ],
]);

9) Email

$email = $nextpyme->email()->send([
    'prefix' => 'SETP',
    'number' => '990000001',
    'alternate_email' => 'cliente@example.com',
]);

10) Plans

$userInfo = $nextpyme->plans()->userInfo();
$listPackages = $nextpyme->plans()->listPackages();

$assignPackage = $nextpyme->plans()->assignPackage([
    'user_identification_number' => 900123456,
    'absolut_start_plan_date' => '2025-01-01',
    'absolut_documents' => 1000,
]);

11) Dian

$statusDocument = $nextpyme->dian()->statusDocument('cufe-o-uuid');

$numberingRange = $nextpyme->dian()->numberingRange([
    'IDSoftware' => 'tu-id-software',
]);

$rutRues = $nextpyme->dian()->rutRues([
    'identification_number' => 900123456,
    'type_document_identification_id' => 6,
    'rues' => true,
]);

$invoiceData = $nextpyme->dian()->invoiceData([
    'qr_cufe' => 'cufe-documento',
]);

Manejo de errores

<?php

use Nextpyme\Sdk\Exceptions\AuthException;
use Nextpyme\Sdk\Exceptions\ValidationException;
use Nextpyme\Sdk\Exceptions\ServerException;
use Nextpyme\Sdk\Exceptions\NextpymeException;

try {
    $result = $nextpyme->invoice()->create($payload, ['retry' => true]);
} catch (ValidationException $e) {
    print_r($e->toArray());
} catch (AuthException $e) {
    print_r($e->toArray());
} catch (ServerException $e) {
    print_r($e->toArray());
} catch (NextpymeException $e) {
    print_r($e->toArray());
}

Ejemplo Laravel

1) Variables de entorno

NEXTPYME_TOKEN=tu_token_bearer
NEXTPYME_ENVIRONMENT=sandbox
NEXTPYME_BASE_URL=
NEXTPYME_DEBUG=false
NEXTPYME_TIMEOUT_MS=30000
NEXTPYME_MAX_RETRIES=2

2) Config (config/nextpyme.php)

<?php

return [
    'token' => env('NEXTPYME_TOKEN'),
    'environment' => env('NEXTPYME_ENVIRONMENT', 'production'),
    'baseUrl' => env('NEXTPYME_BASE_URL'),
    'debug' => (bool) env('NEXTPYME_DEBUG', false),
    'timeoutMs' => (int) env('NEXTPYME_TIMEOUT_MS', 30000),
    'maxRetries' => (int) env('NEXTPYME_MAX_RETRIES', 2),
    'userAgent' => '@nextpyme/sdk-php',
];

3) Binding en contenedor (AppServiceProvider)

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Nextpyme\Sdk\NextpymeClient;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(NextpymeClient::class, function () {
            return new NextpymeClient(config('nextpyme'));
        });
    }
}

4) Uso en controlador

<?php

namespace App\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Nextpyme\Sdk\NextpymeClient;
use Nextpyme\Sdk\Exceptions\NextpymeException;

class InvoiceController extends Controller
{
    private NextpymeClient $nextpyme;

    public function __construct(NextpymeClient $nextpyme)
    {
        $this->nextpyme = $nextpyme;
    }

    public function store(Request $request): JsonResponse
    {
        try {
            $result = $this->nextpyme->invoice()->create(
                $request->all(),
                ['retry' => true]
            );

            return response()->json($result);
        } catch (NextpymeException $e) {
            $payload = $e->toArray();
            $status = isset($payload['status']) ? (int) $payload['status'] : 500;

            return response()->json($payload, $status);
        }
    }
}

5) Ruta

use App\Http\Controllers\InvoiceController;

Route::post('/facturas', [InvoiceController::class, 'store']);