Inicio rápido con la API

Genera la misma factura que en la guía de la app desde tu terminal. Empieza con la plantilla publicada Invoice quickstart de Crea tu plantilla dinámica reutilizable y copia su ID. Tu espacio de trabajo necesita créditos de generación.

1. Crea una clave de API

En tu espacio de trabajo, abre Miembros y claves y crea una clave con documents:create y documents:read. Comprueba que su acceso a recursos incluya tu plantilla. Consulta Autenticación para ver los pasos y las capturas de pantalla.

Define estas variables en tu terminal y reemplaza los valores de ejemplo con tu clave y el ID de tu plantilla publicada:

export SHIPPDF_API_TOKEN='YOUR_API_TOKEN'
export SHIPPDF_TEMPLATE_ID='YOUR_PUBLISHED_TEMPLATE_ID'

Trata la clave como una contraseña. No la guardes en el control de versiones ni en código que se ejecute en el navegador.

2. Genera un documento

Envía el ID de plantilla y los nuevos datos de factura a POST /v1/documents:

curl https://api.shippdf.com/v1/documents \
  -H "Authorization: Bearer $SHIPPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-invoice-INV-1043" \
  -d "{
    \"template_id\": \"$SHIPPDF_TEMPLATE_ID\",
    \"expiry_minutes\": 60,
    \"data\": {
      \"invoice\": {
        \"number\": \"INV-1043\",
        \"customer_name\": \"Northstar\"
      }
    }
  }"

Una solicitud correcta usa un crédito y devuelve un documento antes de que el PDF esté listo. Este ejemplo abreviado muestra los campos que usarás después:

{ "id": "doc_example", "status": "queued", "pdf_url": null }

Copia el id real de tu respuesta. Repetir la misma solicitud con el mismo Idempotency-Key devuelve el documento original sin cobrar de nuevo. Usa una clave nueva cuando quieras otro documento, incluso si cambias los datos.

Esta solicitud establece expiry_minutes en 60, así que cada enlace de descarga del PDF dura una hora. Elige un entero entre 15 y 10080 minutos (7 días), u omite el campo para usar el valor predeterminado del espacio de trabajo, inicialmente 15 minutos. La duración elegida se guarda con el documento; cambiar el valor predeterminado solo afecta a documentos futuros.

3. Espera a que termine

Define el ID de documento que recibiste y consulta su estado:

export SHIPPDF_DOCUMENT_ID='YOUR_RETURNED_DOCUMENT_ID'

curl "https://api.shippdf.com/v1/documents/$SHIPPDF_DOCUMENT_ID" \
  -H "Authorization: Bearer $SHIPPDF_API_TOKEN"

Si status es queued o processing, espera un momento antes de consultar de nuevo. Detente cuando sea completed o failed. Si falla, revisa failure.code y failure.message antes de iniciar otra generación.

Al terminar, la respuesta incluye un pdf_url firmado y su duración guardada:

{
  "id": "doc_example",
  "status": "completed",
  "expiry_minutes": 60,
  "pdf_url": "https://.../document.pdf"
}

4. Descarga tu PDF

Abre el pdf_url real de tu respuesta o descárgalo desde la terminal:

curl --fail --location 'YOUR_RETURNED_PDF_URL' --output invoice-INV-1043.pdf

Comprueba que muestre Invoice INV-1043 y Customer: Northstar. Si el enlace vence, consulta el mismo documento para obtener una URL nueva; no necesitas generar otro documento ni gastar otro crédito. El enlace nuevo usa la misma duración guardada.

También puedes revisar esta generación en la app, en Solicitudes.

Lista documentos recientes

Usa GET /v1/documents con documents:read para encontrar generaciones recientes:

curl 'https://api.shippdf.com/v1/documents?limit=15' \
  -H "Authorization: Bearer $SHIPPDF_API_TOKEN"

La respuesta contiene un array data y next_cursor. Lista los documentos más recientes primero, incluidos resultados queued, processing, completed y failed, dentro del espacio de trabajo y el acceso a recursos de tu clave. Cada elemento incluye created_at; los documentos completados incluyen un pdf_url nuevo con su expiry_minutes guardado. Consulta un documento individual para recuperar sus datos de entrada en data.

El tamaño predeterminado de página es 15; limit acepta entre 1 y 100. Si next_cursor no es null, pásalo como parámetro cursor, codificado para URL, para obtener la página siguiente. Detente cuando next_cursor sea null.

Próximos pasos

Para integraciones automáticas, usa webhook_url para recibir avisos al terminar en lugar de consultar el estado. Consulta la referencia de la API para ver los esquemas completos, el comportamiento de los webhooks y los errores.

También puedes generar con la misma plantilla desde la app o con un asistente de IA.