facta-dte/api — PHP SDK

Versión en español

A PHP client for the Facta API. It issues, queries, invalidates and downloads without you assembling headers, repeating requests by hand or writing the retry code. It never signs and never computes tax: the correlative, totals, VAT, the signature and the transmission to Hacienda stay on the server, exactly as with the TypeScript client.

This first version covers everything that needs only HTTP: issuing, prepare and sign as two steps, queries, listing, downloading the Archivo DTE and the PDF, invalidation, return events, delivery by e-mail and WhatsApp, Facta Storage and reading and writing the catalog. What needs the unlock key and local storage is listed in What this version does not include yet. The Spanish page is the fuller reference; both are checked against the same list of methods and error codes.

Requirements

• PHP 7.4 or later, with no deprecation notices through PHP 8.5. Ordinary shared hosting is enough.
• No required extension beyond PHP core (json and hash), and no Composer dependency.
• HTTP: it uses ext-curl when present. Without it, it falls back to PHP streams (allow_url_fopen, plus ext-openssl for HTTPS). If you already have a PSR-18 client, hand it over with the transport option.
• ext-openssl will also be used to open the local vault in future versions; today it is only needed for HTTPS without cURL.
• TLS verification is never disabled. There is no option to skip it. If the server has an outdated certificate store, the way out is caBundle: the path of a current certificate bundle.
• An API key (facta_test_… or facta_live_…) and, to issue and invalidate, the signing key (factask_…). Both are minted in the app, under Cuenta → API.

Installation

There are two ways, and they give you the same client.

With Composer (Packagist)

This is the main path. The facta-dte/api package is on Packagist:

composer require facta-dte/api

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

Without Composer: the ZIP, by FTP

For shared hosting, cPanel or any server without a shell. Download facta-api-php-vX.Y.Z.zip from the repository's releases page, unzip it and upload the facta-api-php/ folder by FTP next to your script (or anywhere PHP can read). Then:

require_once __DIR__ . '/facta-api-php/autoload.php';

Nothing else to install. If you only have Composer on another machine, run composer require facta-dte/api there and upload the vendor/ folder it generates.

Credentials and options

use Facta\Api\Facta;

$facta = new Facta([
    'apiKey'  => getenv('FACTA_API_KEY'),   // facta_test_… (environment 00) or facta_live_… (01)
    'signKey' => getenv('FACTA_SIGN_KEY'),  // factask_…, sent only to the routes that sign
]);

Every method also accepts per-call options as its last argument: timeoutMs and headers; the writing ones also idempotencyKey. An option the method does not know throws InvalidArgumentException, so a typo is not silently ignored. The same goes for an unknown constructor option.

Answers come back as associative arrays with the API's own field names (estado, codigoGeneracion, numeroControl…). Requests are arrays too: a list becomes a JSON array, an associative array a JSON object, and new \stdClass() is the empty object {}.

Your first invoice

require_once __DIR__ . '/facta-api-php/autoload.php';

use Facta\Api\Facta;
use Facta\Api\FactaError;

$facta = new Facta([
    'apiKey'  => getenv('FACTA_API_KEY'),
    'signKey' => getenv('FACTA_SIGN_KEY'),
]);

try {
    $result = $facta->issue(
        [
            'tipoDte' => '01',
            'items'   => [['descripcion' => 'Service', 'cantidad' => 1, 'precioUni' => 11.30]],
        ],
        ['idempotencyKey' => 'order-00417']   // yours: the same sale, the same key
    );

    if ($result['estado'] === 'sellado') {
        echo $result['numeroControl'], ' ', $result['selloRecibido'], "\n";
    } else {
        echo "Contingency: accepted, Hacienda's seal is still missing.\n";
    }
} catch (FactaError $e) {
    echo $e->getErrorCode(), ' (HTTP ', $e->getStatus(), '): ', $e->getMessage(), "\n";
    if ($e->isRejection()) {
        print_r($e->mhObservations());
    }
}

The idempotencyKey belongs to your system (the order number, the till ticket): if the process dies in the middle of the call and you repeat it, the server recognises the same operation and does not issue twice. Read estado before reading the seal, because a contingency document does not have one yet. And decide on the failure by its code, not by its message.

Client methods

Each method says which key scope it requires, what it returns and which errors are its own. The errors common to all of them (key, scope, limits, network) are under FactaError. A method that spends a correlative carries the client's Idempotency-Key; see Idempotency and retries.

Configuration and status

environment()

Makes no request. Returns "00" for a facta_test_… key and "01" for a facta_live_… key.

region()

Makes no request. Returns the region sent as x-region, or null if you disabled it with region => false. Unlike the TypeScript client it does not ask /v1/status to discover it: a PHP process lives for one web request, and a discovery call per request would cost more than it saves.

servedRegion()

Returns the region that served the latest answer (the x-sb-edge-region header), or null before the first answer or when the header is absent.

status($options = [])

GET /v1/status. No scope, no signing key. Confirms the key works and returns, as an array, ok, version, ambiente, emisor, llave (with alcances, tiposDte and catalogMode), firma, sincronizacion and limites. Call it first; the route has its own rate window and does not spend the quota it reports.

diagnose($options = [])

Reads /v1/status and /v1/storage/status and answers whether this key is ready. It does not open vaults, reserve a correlative or issue. Options: expectedEnvironment ("00" or "01"), requiredScopes (a list) and dteType (for example "01"). Returns overall, canIssue, canQuery, canDownload, canIssueAndArchive, the checks list (each with id, state and message), storageReady, catalogMode, region and servedRegion. If the status cannot be read it does not throw: it returns a blocked report carrying the error's safe code.

canIssueAndArchive is always false in this version because the local archive does not exist yet, and the checks that would depend on local storage are reported as unknown with that reason.

Issuing

issue($request, $options = [])

POST /v1/dte. Requires the issue scope and sends the signing key. Prepares, signs and transmits in one operation; the normal path. $request carries tipoDte, the receptor and the items, with the API's field names; the server computes everything. It returns the sealed document (estado "sellado", with selloRecibido, totales and archivoDte) or, if Hacienda did not answer, a contingency document (estado "contingencia", no seal yet) — a 202 is not an error. The answer also carries codigoGeneracion, numeroControl, representacionGrafica (the PDF in base64), entrega, storage and advertencias when present.

Per-call options: idempotencyKey (yours; otherwise the client mints one per call and reuses it on every retry), deliver (see Delivery), timeoutMs and headers.

Typical own errors: mh_rejected (Hacienda read and refused it; it spent a correlative), validation_failed (it did not), amount_limit, sign_key_required, sign_key_invalid, idempotency_key_reuse.

prepare($request, $options = [])

POST /v1/dte/prepare. Requires issue; it does not open the signing vault, so it does not send the signing key. Reserves the correlative and returns the canonical unsigned document with its prepareToken. Use it when you need to show or review the document before signing. documento stays the decoded \stdClass tree on purpose, so an empty object {} inside it is not turned into [] on the way back. Treat it as opaque and pass it to sign() untouched; if you store it in between, use json_encode and json_decode($text) (objects), never json_decode($text, true).

sign($prepared, $options = [])

POST /v1/dte/sign. Requires issue and sends the signing key. Signs and transmits what prepare() returned. Pass the result unchanged: the server checks a MAC over the canonical document, so one altered cent is refused (prepare_token_invalid) instead of signed. A result without its prepareToken or documento throws InvalidArgumentException before anything is sent. Returns the same shape as issue().

Delivery by e-mail and WhatsApp

Issuing never waits for delivery; they are separate requests. issue() only marks channels, through the deliver option:

$result = $facta->issue($sale, [
    'idempotencyKey' => 'order-00417',
    'deliver' => [
        'email'    => true,   // or an address; true uses receptor.correo
        'whatsapp' => ['number' => '+50370001234', 'consent' => true],
    ],
]);
$token = $result['entrega']['token'];   // valid five minutes: a secret, keep it on your server

consent => true attests that the receiver agreed to WhatsApp delivery; the client makes you write it out. A sealed answer carries entrega with a token valid for five minutes and the initial state of each channel. A contingency document gets no token.

deliverEmail($generationCode, $token, $options = [])

POST /v1/dte/{codigoGeneracion}/entrega/correo. Requires issue (or entrega:correo) and the token the issue returned. Answers the channel's final state or en_proceso; a second call returns the current state without a second message. A channel that cannot be delivered is a state (fallido, sin_consentimiento…), not an exception. An expired token is entrega_vencida, a wrong one entrega_token_invalido; the client strips the token from the message and details if the server echoed it.

deliverWhatsApp($generationCode, $token, $options = [])

POST /v1/dte/{codigoGeneracion}/entrega/whatsapp. Requires issue (or entrega:whatsapp). Same as e-mail; it is charged to the company's prepaid wallet (sin_credito with no balance).

getDelivery($generationCode, $options = [])

GET /v1/dte/{codigoGeneracion}/entrega. Requires query (or either delivery scope). Reads each channel's state under canales; it keeps working after the token expired.

waitForDelivery($generationCode, $options = [])

Polls getDelivery() until every awaited channel is in a final state (anything but pendiente or en_proceso). Options: channels (by default those the server reports), timeoutMs (60000) and intervalMs (2000). On timeout it does not throw: it returns the last read with settled => false, because delivery never changes the fiscal result.

Querying and listing

getDocumentStatus($generationCode, $options = [])

GET /v1/dte/{codigoGeneracion}. Requires query. It also answers for rejected documents. Returns the estado (sellado, firmado, rechazado, contingencia, invalidado, reservado, liberado, descartado), numeroControl, tipoDte, ambiente, fecEmi, selloRecibido, totales and, when present, retornos and disponible. A document of another company answers not_found, exactly like one that does not exist.

listDocuments($filters = [], $options = [])

GET /v1/dte. Requires query (and download if you ask for include). One page at a time. Filters: desde, hasta, estado, tipoDte, limit, cursor and include => ['dte'], which adds the Archivo DTE to every row. Returns documentos and siguiente; pass siguiente back as cursor for the next page, until it is null. An unknown filter throws InvalidArgumentException. With include a page holds at most 25; above that the server answers include_limit_exceeded.

downloadDocument($generationCode, $kind = 'json', $options = [])

GET /v1/dte/{codigoGeneracion}/file. Requires download. Returns the exact bytes the server sent, never re-serialized. kind is "json" (the Archivo DTE the receiver gets, the default), "pdf" or "ticket" (a roll receipt drawn on the server). The result is an array with codigoGeneracion, kind, bytes, contentType and filename and, when the server says so, storageSource (managed, holding or archive), jsonFormat (archivo-dte or raw) and paperWidthMm.

Options: raw => true (json only: the stored original, needed for a contingency document, which has no Archivo DTE yet and otherwise answers not_sealed); source => 'managed' (json and pdf only: require the Facta Storage copy, with no fallback to temporary retention); paperWidthMm (ticket only, 40 to 120, 80 by default). An invalid combination throws InvalidArgumentException before anything is sent. The PDF is drawn by the server with the company's template; this client draws none.

Invalidating and returning

invalidate($generationCode, $request, $options = [])

POST /v1/dte/{codigoGeneracion}/invalidate. Requires issue and sends the signing key. Invalidates a sealed document; it is irreversible. $request carries tipoAnulacion (1, 2 or 3), motivo, codigoGeneracionReemplazo where it applies, and responsable and solicita, each with nombre, tipoDocumento and numDocumento. Returns estado "invalidado" and the event, or yaEstabaInvalidado => true. A document with return events answers has_return_events.

registerReturn($generationCode, $request, $options = [])

POST /v1/dte/{codigoGeneracion}/return. Requires issue and sends the signing key. Registers a return event over an invoice, export invoice or excluded-subject document this API issued (guide). $request carries items — each with its linea (counted from 1) and exactly one of cantidad or noGravado — and, optionally, fechaEvento (YYYY-MM-DD). The client checks those rules locally and throws InvalidArgumentException if the server would refuse them anyway. Irreversible once sealed.

A 202 with estado "firmado" means Hacienda did not answer: repeat with the same idempotencyKey and the same body to resend the same signed event. Refusals are return_exceeds_available, return_window_closed and return_type_not_allowed.

Facta Storage

These three methods concern the storage managed by Facta (JSON and PDF), not your own destinations.

getStorageStatus($options = [])

GET /v1/storage/status. Requires download. Returns capabilityVersion, managed (coverage, capacity and readiness), byos (whether a verified own destination is ready) and the supportedKinds and unsupportedKinds lists. No fiscal work. If the server does not publish the route it throws storage_unsupported; if the answer breaks the contract, storage_contract_invalid.

getDocumentCopies($options = [])

GET /v1/storage/copies. Requires download. Lists the receipts of the managed JSON and PDF copies for this company and environment, pending and failed ones included, with state, bytes and sha256. The generationCode option limits it to one document. No document content and no storage paths. A receipt for another environment or another document is treated as storage_contract_invalid.

retryDocumentStorage($generationCode, $options = [])

POST /v1/storage/copies/{codigoGeneracion}/repair. Requires download and issue. Repairs the copies of an already sealed document: it does not sign, reissue or spend a correlative. Returns the storage receipt (destination, environment, json, pdf, operationId). If the original bytes no longer exist it fails explicitly rather than inventing them.

Fiscal success and copy success are independent. If the receipt attached to an issue breaks the contract, the client drops it and leaves storageErrorCode: "storage_contract_invalid" in the result, keeping the sealed document.

Retention and contract

listHolding($limit = 50)

GET /v1/dte/holding. Requires download. Inspects the holding area — documents the server keeps for a while when no other durable copy exists. It downloads no bytes. Returns documentos.

getContract()

GET /v1/openapi.json. No scope. The OpenAPI contract the server publishes, as an array.

Customer and product catalog

The catalog is read and written through the API, and what works depends on how the company stores it. A key with catalog:read reads a plain or readable catalog; writing needs catalog:write and the owner having allowed catalog administration from the API (which stores it unencrypted at Facta). Records come back with both spellings of each field, the API's and the stored one (nombre and name, for example). With an encrypted catalog these reads throw unauthorized (details.reason), because reading it would need the local snapshot this version does not include.

A duplicate document number on a customer, or a duplicate code on a product, answers catalog_duplicate; details.id says which one and details.activo whether it is deactivated.

Idempotency and retries

Any method that can spend a correlative needs a stable Idempotency-Key. Pass your own (idempotencyKey) and keep it with the order: that makes the operation idempotent even across a process restart, not just between retries of one call. If you do not, the client mints one per call, once, outside the retry loop, and resends it on every attempt. A fresh key per attempt is exactly the failure the header exists to prevent. The body is encoded once per call too, and every retry resends the same bytes.

The request fingerprint

issue() and prepare() also send X-Facta-Request-Fingerprint: the SHA-256 of the canonical form (RFC 8785) of your request as you wrote it, before the server resolves any catalog id. The server uses it to recognise a retry even if the catalog changed between the attempt and its repetition; without it that repetition would answer idempotency_key_reuse. It travels only on POST /v1/dte and POST /v1/dte/prepare, and you do not compute it.

What is retried

The client retries only where retrying is safe, up to maxRetries more times, with growing waits (250 ms, 500 ms… up to 4 s) or the server's Retry-After when it sends one, and these six codes are the only ones:

• idempotency_in_flight: the first request with that key is still working.
• mh_unreachable
• service_unavailable
• correlative_unavailable
• storage_unavailable
• network_error: the request got no answer (connection failure or timeout).

It is safe because every attempt resends the same bytes with the same Idempotency-Key. A 4xx and a Hacienda rejection are never retried. When the attempts run out the last error is thrown, and any code not in that list is final. A contingency 202 is not an error: it arrives as a result with estado "contingencia", explained in Contingency and uncertain outcomes (Spanish).

FactaError

Every failure is a Facta\Api\FactaError. Decide by the code, never by the message: the text is for whoever reads the log and may be rewritten. The codes are the same as the TypeScript client's.

An error message never contains a configured key, and details omits credential-looking fields. Besides FactaError, the client throws InvalidArgumentException for misuse it can detect before sending (an unknown option, an invalid kind, a return without lines) and Facta\Api\UnsupportedEnvironmentException if that PHP has no way to make HTTP requests.

Error codes

These are the codes the client defines; the server's own are explained in full in the HTTP reference. network_error, operation_outcome_unknown and archive_integrity_error belong to the client and the server never sends them; the last two exist for compatibility with TypeScript and this version never throws them.

What this version does not include yet

This is the first stage. The functions that need the unlock key (factauk_…) and local storage are missing, and they have not been left half-done: they are simply not there.

• The local snapshot of the encrypted catalog. With an encrypted catalog the TypeScript client decrypts customers and products on your machine; this one does not yet. Meanwhile API-readable and plain catalogs work, because the server reads them for you (customerId and productId are resolved on the server), and you can always send the full recipient and lines.
• Your own destinations (BYOS) with the unlock key. Replicating the JSON and PDF to your buckets, and telling Facta about that copy, is not in this version.
• The encrypted local archive and recovery after a restart. There is no equivalent of issueAndArchive() or recoverOperation(). To survive a restart, use your own idempotencyKey and store it with the order: repeating the call returns the same document.
• Printing.

The normal path does not need them. With Facta Storage connected, the server keeps each document's JSON and PDF, and getStorageStatus(), getDocumentCopies() and retryDocumentStorage() let you check and repair that. That is the path this version covers.

What this client does not do

1. It does not compute money. No VAT, no retentions, no totals, no control number, no fiscal dates. A client that computed money would be a second tax engine, and two engines drift apart. An architecture test in the package fails if signing primitives or fiscal field construction appear in the code.
2. It does not sign. The certificate never passes through here. What does travel, and only on the routes that sign, is X-Facta-Sign-Key: the password that opens the signing vault on the server.
3. It does not draw the PDF. The PDF and the ticket are drawn by the server with the company's template; downloadDocument() hands you their exact bytes.
4. It does not disable TLS verification. Not even for an old server: that is what caBundle is for.

For direct HTTP without this library, follow the PHP examples.