README

El cliente PHP oficial para la API de firma electrónica de pdf-signer: un objeto Configuration, un ApiClient por el que pasan todas las peticiones, una clase Api por recurso, y clases Model tipadas para requests/responses.

Una versión en HTML con estilos de esta página vive en docs/index.html — ábrela directamente en el navegador.

Quickstart

1. Requisitos

PHP 8.2+ y Composer
Un servidor pdf-signer-api corriendo — desde la raíz de codepad/, ./dev.sh start lo levanta junto con todo lo demás

2. Instalar

El paquete todavía no está en Packagist, así que se apunta como un path repository local:

{
  "repositories": [
    { "type": "path", "url": "../pdf-signer-sdk" }
  ]
}

composer require pdf-signer/php-sdk:@dev

guzzlehttp/guzzle viene como dependencia — nada más que instalar.

3. Hacer tu primera llamada

require 'vendor/autoload.php';

use PdfSigner\ESign\Api\ContractsApi;
use PdfSigner\ESign\Api\EnvelopesApi;
use PdfSigner\ESign\Client\ApiClient;
use PdfSigner\ESign\Client\Configuration;

$apiClient = new ApiClient(Configuration::default()); // http://127.0.0.1:8000/api
$contracts = new ContractsApi($apiClient);
$envelopes = new EnvelopesApi($apiClient);

$contract = $contracts->createContract([
    'contract_number' => 'C-0001',
    'title' => 'Contrato de prestación de servicios',
    'created_by' => 1,
    'signers' => [
        ['name' => 'Ana Gómez', 'email' => 'ana@example.com', 'role' => 'empleado'],
    ],
]);

$envelope = $envelopes->createEnvelope($contract->id);

echo $envelope->status; // "sent"

Esa es toda la superficie de integración: construís un ApiClient una vez, instanciás la clase Api del recurso que necesites, llamás un método, y te devuelve un objeto tipado. Las secciones de abajo cubren opciones de configuración, manejo de errores, y cada clase Api/Model disponible en detalle.

Este SDK habla HTTP puro vía Guzzle — no importa ninguna clase de framework ni fija una versión de Laravel. Funciona igual desde una app Laravel, Symfony, un script plano, o cualquier otro backend que hable con pdf-signer-api.

Configurar el cliente

Cada petición pasa por un ApiClient, construido a partir de un Configuration — Configuration guarda a dónde mandar las peticiones, ApiClient es cómo.

use PdfSigner\ESign\Client\Configuration;
use PdfSigner\ESign\Client\ApiClient;

$config = new Configuration(
    host: 'http://127.0.0.1:8000/api', // URL base de pdf-signer-api
    timeout: 10.0,
);

$apiClient = new ApiClient($config);

Configuration::default() (usado en el Quickstart) es un atajo para ese mismo host/timeout — útil para desarrollo local.

Método	Para qué sirve
`getHost()` / `setHost(string $host)`	URL base contra la que se resuelve cada petición
`getTimeout()` / `setTimeout(float $seconds)`	Timeout de la petición Guzzle
`addDefaultHeader(string $name, string $value)`	Header enviado en cada petición (ver Autenticación)

Autenticación

pdf-signer-api todavía no tiene un concepto de cuenta multi-tenant — es un servidor local único, así que hoy no hace falta ningún paso de autenticación para llamarlo.

Si más adelante pdf-signer-api exige una API key o un bearer token, se conecta como un header por defecto, seteado una vez, aplicado a cada petición siguiente — no hay que tocar nada más en el SDK:

$config->addDefaultHeader('Authorization', 'Bearer '.$accessToken);

Clases Api disponibles

Cada recurso tiene su propia clase Api, todas construidas igual: new AlgunaApi($apiClient).

Clase	Método	Llama a
`ContractsApi`	`createContract(array $payload): Contract`	`POST /contracts`
	`getContract(int $contractId): Contract`	`GET /contracts/{id}`
	`listContracts(): Contract[]`	`GET /contracts`
`EnvelopesApi`	`createEnvelope(int $contractId): Envelope`	`POST /contracts/{id}/envelopes`
	`getEnvelope(string $envelopeId): Envelope`	`GET /envelopes/{id}`
`WebhooksApi`	`simulate(array $payload, ?string $eventId = null): array`	`POST /signing/webhook` — solo para tests, ver abajo

WebhooksApi existe únicamente para que una app cliente pueda simular que un firmante completó un envelope sin necesitar a una persona real haciendo clic. Ver SigningDemoController en pdf-signer-client para cómo se usa en la práctica.

Clases Model

Contract, ContractSigner, Envelope, y Recipient (namespace PdfSigner\ESign\Model) son DTOs tipados simples — cada método de una clase Api devuelve uno (o un arreglo de uno), construido a partir del JSON de respuesta vía un fromArray() estático. Envelope::isComplete(): bool es el único método de conveniencia más allá del acceso directo a propiedades, equivalente a comparar status === 'completed' vos mismo.

Manejo de errores

Las peticiones fallidas lanzan PdfSigner\ESign\ApiException, con el status HTTP y el cuerpo de respuesta ya decodificado, para poder leer los errores de validación directamente en vez de parsear un mensaje genérico:

use PdfSigner\ESign\ApiException;

try {
    $contract = $contracts->createContract($payload);
} catch (ApiException $e) {
    $e->getStatusCode();        // p. ej. 422
    $e->getValidationErrors();  // p. ej. ['contract_number' => ['The contract number has already been taken.']]
}

getValidationErrors() asume el formato {campo: [mensajes]} porque es lo que pdf-signer-api devuelve hoy, no porque el SDK dependa de Laravel — si el backend cambiara de formato, solo ese método necesitaría ajustarse.

Ver también

pdf-signer-api — el servidor con el que habla este SDK; sus rutas son la fuente de verdad de cada método Api documentado acá.
pdf-signer-client — una app Laravel de ejemplo que consume este SDK a través de un DocuSignService, mostrando una forma de encapsular el SDK detrás de una clase de servicio de la app.
system-tests — tests de integración que ejercitan este SDK de punta a punta contra un pdf-signer-api corriendo.

pdf-signer / php-sdk

Maintainers

Package info

Statistics

Security