API de tuimprenta.digital

Emite y gestiona facturas digitales de manera individual o en lotes, descarga PDF/XML, recibe webhooks y consulta historial.

Base URL: https://api.tuimprenta.digital/v1 Sandbox y Producción Versionado: v1

Autenticación

Usa encabezado Authorization: Bearer <API_KEY>. Solicita tu API key desde Soporte.

curl -H "Authorization: Bearer <API_KEY>" https://api.tuimprenta.digital/v1/ping

Límites & Idempotencia

• Rate limit típico: 60 req/min por API key (salvo lotes).
• Para reintentos seguros usa Idempotency-Key único por operación.
• Respuestas incluyen cabeceras X-RateLimit-*.

POST /invoices
Idempotency-Key: 8d8a3b1f-5b8d-4a8c-a2a0-9df...
Authorization: Bearer <API_KEY>
Content-Type: application/json

Esquemas (resumen)

ObjetoInvoice

{
  "id": "inv_123",
  "series": "TD-2025",
  "number": 123,
  "issue_date": "2025-11-07",
  "customer": { "name": "Razón", "tax_id": "J-123...", "email": "..." },
  "items": [ { "sku": "SKU", "description": "Desc", "qty": 1, "unit_price": 12.0, "tax_rate": 0.16 } ],
  "currency": "USD",
  "status": "issued|canceled|draft",
  "totals": { "subtotal": 12.0, "tax": 1.92, "total": 13.92 },
  "links": { "pdf": ".../pdf", "xml": ".../xml" },
  "metadata": { "order_id": "..." },
  "created_at": "2025-11-07T12:34:56Z"
}

ObjetoBatch

{
  "id": "batch_abc",
  "type": "invoice.create",
  "status": "queued|processing|completed|failed|partial",
  "counts": { "queued": 1000, "processed": 980, "failed": 20 },
  "created_at": "2025-11-07T12:00:00Z",
  "result_url": "https://.../batches/batch_abc/result.csv"
}

Facturas individuales

Ruta base: /invoices

POST/invoices

Emite una factura.

curl -X POST https://api.tuimprenta.digital/v1/invoices \
 -H "Authorization: Bearer <API_KEY>" \
 -H "Idempotency-Key: 8d8a3b1f-..." \
 -H "Content-Type: application/json" \
 -d '{
  "series":"TD-2025",
  "issue_date":"2025-11-07",
  "customer":{"name":"Inversiones ABC, C.A.","tax_id":"J-123...","email":"admin@abc.com"},
  "items":[{"sku":"CAT-TARJETAS-300G","description":"Tarjetas 9x5 (100u)","qty":1,"unit_price":12.0,"tax_rate":0.16}],
  "currency":"USD",
  "send_email":true,
  "metadata":{"order_id":"TD-00123"}
}'

const r = await fetch("https://api.tuimprenta.digital/v1/invoices", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json"
  },
  body: JSON.stringify({...})
});
const inv = await r.json();

import requests, uuid
hdr = {"Authorization":"Bearer <API_KEY>","Idempotency-Key":str(uuid.uuid4())}
res = requests.post("https://api.tuimprenta.digital/v1/invoices", headers=hdr, json={...})
inv = res.json()

GET/invoices/{id}

Obtiene una factura.

curl -H "Authorization: Bearer <API_KEY>" \
 https://api.tuimprenta.digital/v1/invoices/inv_123

POST/invoices/{id}/cancel

Cancela o emite nota relacionada (según normativa).

curl -X POST -H "Authorization: Bearer <API_KEY>" \
 https://api.tuimprenta.digital/v1/invoices/inv_123/cancel \
 -d '{"reason":"mistake"}'

Facturas por lotes

Ruta base: /batches

Sube un lote para emitir muchas facturas. Procesamiento asíncrono con jobs, polling y webhooks.

POST/batches

Crea un batch. Soporta application/json (array de facturas) o multipart/form-data (CSV/JSON adjunto).

curl -X POST https://api.tuimprenta.digital/v1/batches \
 -H "Authorization: Bearer <API_KEY>" \
 -H "Content-Type: application/json" \
 -d '{
  "type":"invoice.create",
  "payload":[
    {"series":"TD-2025","customer":{"name":"A","tax_id":"J-1"},"items":[{"description":"Item A","qty":1,"unit_price":10}]},
    {"series":"TD-2025","customer":{"name":"B","tax_id":"J-2"},"items":[{"description":"Item B","qty":2,"unit_price":5}]}
  ],
  "callback_url":"https://tuapp.com/webhooks/tuimprenta"
}'

GET/batches/{id}

Consulta estado: queued → processing → completed|failed|partial.

curl -H "Authorization: Bearer <API_KEY>" \
 https://api.tuimprenta.digital/v1/batches/batch_abc

GET/batches/{id}/result

Descarga resultados (CSV/JSON) con invoice_id, status, errores, etc.

curl -L -H "Authorization: Bearer <API_KEY>" \
 https://api.tuimprenta.digital/v1/batches/batch_abc/result.csv -o result.csv

CSV esperado (multipart)

series,issue_date,customer_name,customer_tax_id,customer_email,item_description,item_qty,item_unit_price,tax_rate,currency,metadata_order_id
TD-2025,2025-11-07,Inversiones ABC,J-123...,admin@abc.com,Tarjetas 9x5,1,12.00,0.16,USD,TD-00123

Descargas

GET/invoices/{id}/pdf

curl -H "Authorization: Bearer <API_KEY>" \
 -o factura.pdf https://api.tuimprenta.digital/v1/invoices/inv_123/pdf

GET/invoices/{id}/xml

curl -H "Authorization: Bearer <API_KEY>" \
 -o factura.xml https://api.tuimprenta.digital/v1/invoices/inv_123/xml

Listados & paginación

Cursor-based

GET /invoices?limit=50&starting_after=inv_abc&status=issued&series=TD-2025&created_from=2025-11-01

Respuesta incluye data y cursores next_cursor/prev_cursor.

{
  "data":[{"id":"inv_123", "...": "..."}],
  "next_cursor":"inv_124",
  "prev_cursor":"inv_122"
}

Webhooks

Recibe eventos en tu endpoint HTTPS. Firma HMAC en cabecera X-Tuimprenta-Signature.

Ejemplo de evento

{
  "id":"evt_123",
  "type":"invoice.issued",
  "data":{"invoice_id":"inv_123","series":"TD-2025","number":123,"total":13.92},
  "created_at":"2025-11-07T12:34:56Z",
  "signature":"sha256=..."
}

Reintentos & respuestas

• Responde 2xx en < 10 s.
• Reintentos exponenciales hasta 24 h.
• Valida la firma con tu Webhook Secret.

Errores comunes

Formato de error

{
  "error": {
    "type": "validation_error",
    "message": "El campo tax_id es requerido",
    "field": "customer.tax_id",
    "code": "E1001"
  }
}

Códigos

401 No autorizado / API key inválida
402 Rechazado por validación fiscal
404 Recurso no encontrado
409 Conflicto / idempotencia duplicada
422 Error de validación
429 Rate limit
5xx Error del servidor

OpenAPI (descarga)

Incluiremos el archivo /assets/api/openapi.yaml para importarlo en Postman/Insomnia/Swagger UI.

Descargar YAML

* La denominación y proceso de timbrado/cancelación varían por país (CFDI, Facturae, e-Invoice). Configura tu entorno con soporte.