README

SDK oficial para emitir e-CF (facturación electrónica DGII, RD) con Aura. Sin dependencias externas (usa cURL nativo). PHP ≥ 8.0.

Instalación

composer require nexo-do/aura-ecf-sdk

Inicio rápido

<?php
require 'vendor/autoload.php';

use Aura\Ecf\Client;

$aura = new Client('aura_test_...'); // o aura_live_... para producción
// Default (Cloud): https://aura.nexo.com.do/api/v1
// new Client('aura_...', ['baseUrl' => 'http://localhost:3001/v1']); // self-hosted

// 1) Emitir un e-CF (202 — se procesa async)
$result = $aura->vouchers->issue([
    'clientId'    => '00000000-0000-0000-0000-000000000000',
    'typeId'      => '31',
    'counterpart' => ['rnc' => '131234567', 'legalName' => 'Cliente Demo SRL'],
    'paymentType' => 1,
    'items'       => [
        ['description' => 'Servicio', 'quantity' => 1, 'unitPrice' => 10000, 'itbisRate' => 18],
    ],
], idempotencyKey: bin2hex(random_bytes(16))); // evita doble consumo de NCF en reintentos

echo "{$result['id']} {$result['ncf']} {$result['status']}\n";

// 2) Consultar el estado final (o usa webhooks)
$voucher = $aura->vouchers->retrieve($result['id']);
echo "{$voucher['status']} {$voucher['qrUrl']} {$voucher['securityCode']}\n";

El modo (test/live) sale de la API Key

Manejo de errores

use Aura\Ecf\AuraException;

try {
    $aura->vouchers->issue($params);
} catch (AuraException $e) {
    error_log("{$e->type} {$e->getMessage()} {$e->requestId}"); // p.ej. VALIDATION ...
    if ($e->isRetryable()) {
        // reintentar
    }
}

El cliente reintenta automáticamente errores transitorios (429/5xx/red) en GETs y en emisiones con idempotencyKey, respetando Retry-After.

Verificar webhooks

use Aura\Ecf\Webhook;

$rawBody = file_get_contents('php://input'); // cuerpo CRUDO — no json_decode antes
$headers = getallheaders();

if (!Webhook::isValid($rawBody, $headers, $_ENV['AURA_WEBHOOK_SECRET'])) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true);
// $event['type']: 'voucher.accepted' | 'voucher.rejected' | ...
http_response_code(200);

Autenticación por sesión humana (JWT)

Además de la API Key, el SDK soporta login con email/contraseña. El accessToken se guarda en el cliente y las llamadas siguientes viajan con Authorization: Bearer:

$aura = new Client();                                   // anónimo
$aura->auth->login('owner@acme.com', 'secret', 'acme-corp');
$aura->setMode('live');                                 // header X-Aura-Mode (opcional)

$aura->projects->list();
$aura->billing->usage();
$aura->auth->logout();

Descargas binarias (PDF / XML)

printing, las descargas de XML del set de certificación y downloadArtifact devuelven un array ['content' => <bytes>, 'contentType' => ..., 'filename' => ..., 'status' => ...]:

$ri = $aura->printing->pdf($voucherId);
file_put_contents('factura.pdf', $ri['content']);

API — cobertura completa

El SDK cubre el 100% de la API REST de Aura. Cada grupo es una propiedad del cliente:

Vouchers ($aura->vouchers)

issue($params, $idempotencyKey) · retrieve($id) · list($params) · refresh($id) · void($id, $params) · commercialApproval($id, $params) · voidRanges($params) (ANECF por rangos) · receive($params) (cargar e-CF de terceros)

Clients ($aura->clients)

list() · create($params) · retrieve($id) · update($id, $params) · uploadCertificate($id, $p12Base64, $password) / uploadCertificateFile($id, $path, $password) · listSequences($id) · createSequence($id, $params) · updateSequence($id, $seqId, $params) · deleteSequence($id, $seqId)

Certification ($aura->certification)

progress($clientId) · advance($clientId, $params) · updateUrls($clientId, $params) · signPostulation($clientId, $xml, $filename) / signPostulationFile(...) · runDataSet($clientId, $useOfficialSet) · runTestSet($clientId) · testSetStatus($clientId) · testSetXml($clientId, $ncf) · runApprovals($clientId) · approvalsStatus($clientId) · runSimulation($clientId) · simulationStatus($clientId) · simulationXml($clientId, $ncf) · swornDeclaration($clientId, $params) · verifyRnc($clientId, $params) · uploadArtifact(...) / uploadArtifactFile(...) · listArtifacts($clientId) · downloadArtifact($id) · parsedArtifact($id) · deleteArtifact($id)

Contingency ($aura->contingency)

activate($clientId, $params) · deactivate($clientId) · flush($clientId, $params) · pending($clientId)

DGII Queries ($aura->dgii)

directory($clientId, $rnc) · status($params) · trackIds($clientId, $ncf) · trackStatus($clientId, $trackId) · summary($params) · provinces() · municipalities($province) · districts($params)

Printing ($aura->printing)

pdf($id) · thermal($id) · pdfa($id) · getTemplate($clientId) · updateTemplate($clientId, $params)

Webhooks ($aura->webhooks)

list() · create($params) · update($id, $params) · delete($id) · deliveries($id) · rotateSecret($id) (verificación de firma entrante: Webhook::verify(...))

Notifications ($aura->notifications)

settings() · updateSettings($settings) · updatePreferences($params) · test()

Billing ($aura->billing)

usage() · checkout($params) · portal($params)

Reports ($aura->reports)

technical($params)

Retention ($aura->retention)

previewPurge() · purgeChallenge() · purge($params) · runNow()

Projects / Users / API Keys / Catálogos / Auth

• $aura->projects → list() · create() · retrieve() · update() · delete()
• $aura->users → list() · create() · retrieve() · update() · delete() · changePassword()
• $aura->apiKeys → list() · create() · delete()
• $aura->catalog → ncfTypes() · iscCategories()
• $aura->auth → login() · register() · refresh() · logout() · me()
• $aura->health() · $aura->healthWorkers()

Los únicos endpoints no expuestos son los de servidor-a-servidor que no invoca el integrador: la recepción pública DGII (/fe/..., llamada por terceros emisores) y el webhook inbound de Stripe (/billing/stripe/webhook, llamado por Stripe).