Conecta tu software y emite boletas, facturas y notas de crédito con una solicitud HTTP. Envías los datos de la venta en JSON. Boletura arma el XML UBL 2.1, lo firma, lo envía a SUNAT y avisa a tu sistema cuando hay respuesta.
Para sistemas que emiten para una o varias empresas. El acceso se coordina con nosotros: no hay alta automática.
No armas XML ni usas los catálogos de SUNAT, salvo el código de unidad de medida: NIU para bienes y ZZ para servicios. Boletura calcula el IGV y los totales, y responde con el número, los importes y los enlaces al PDF y al XML.
POST /v1/documents
Authorization: Bearer dk_test_...
Idempotency-Key: 7f2c1d0e-4b7a-4e0f-9d2b-6a1c3e5f7a9b
Content-Type: application/json
{
"type": "boleta",
"company_id": "01a1a1f8-e872-7b28-b045-9faa12911ebc",
"items": [
{
"description": "Servicio de instalación",
"quantity": 1,
"unit": "ZZ",
"unit_price": 59.00
}
],
"external_id": "venta-00024"
}201, resumida{
"id": "01a1a1fa-077d-7ed1-a119-4c18efec1648",
"environment": "test",
"full_number": "B001-2",
"issue_date": "2026-11-03",
"totals": {
"taxable": 50.00,
"igv": 9.00,
"total": 59.00,
"amount_in_words": "CINCUENTA Y NUEVE CON 00/100 SOLES"
},
"sunat_status": "pending",
"sunat": {
"deadline_at": "2026-11-11T04:59:59.000000Z"
},
"links": {
"pdf": "/v1/documents/01a1a1fa-077d-7ed1-a119-4c18efec1648/pdf",
"xml": "/v1/documents/01a1a1fa-077d-7ed1-a119-4c18efec1648/xml",
"cdr": null
},
"external_id": "venta-00024"
}Respuesta real del ambiente de pruebas, con datos de ejemplo. La dirección del servidor se entrega con tu acceso. El envío a SUNAT ocurre después de responder, por eso sunat_status empieza en pending.
Cuando cambia el estado de un comprobante, Boletura avisa a tu sistema con un POST firmado. Si tu receptor no responde con un 2xx en 10 segundos, se reintenta durante 24 horas. También puedes consultar con GET /v1/documents/{id} o traer los cambios con el filtro updated_from de GET /v1/documents.
sunat_status | Qué significa |
|---|---|
pending | Emitido, todavía sin informar a SUNAT. |
submitted | Enviado, a la espera de respuesta. Si la respuesta se perdió, Boletura la consulta sin reenviar el comprobante. |
accepted | Aceptado por SUNAT. |
accepted_with_observations | Aceptado, con observaciones que conviene revisar. |
rejected | Rechazado. El número no se reutiliza: corriges los datos y emites un comprobante nuevo. |
deadline_missed | Se confirmó que no hubo un envío válido dentro del plazo. |
POST https://tu-sistema.example/webhooks/boletura
X-Devkora-Event: document.accepted
X-Devkora-Delivery: 0192f2c4-...
X-Devkora-Timestamp: 1791606641
X-Devkora-Environment: test
X-Devkora-Signature: v1=5f1a9c...La firma es un HMAC-SHA256 del texto {timestamp}.{cuerpo} con el secreto de tu endpoint. Rechaza los avisos con más de 5 minutos de diferencia de reloj.
Eventos: document.accepted, document.accepted_with_observations, document.rejected, document.voided, document.void_rejected y document.deadline_missed.
Cada emisión lleva la cabecera Idempotency-Key. Si repites la solicitud con la misma clave y los mismos bytes, por ejemplo después de un corte de red, recibes la respuesta guardada con Idempotent-Replayed: true y no se emite otro comprobante. Si la primera sigue en curso, responde 409: espera y reintenta. La clave vale 24 horas desde la respuesta final.
Pasado ese plazo, busca el comprobante por tu identificador: GET /v1/documents?external_id=venta-00024.
Cada RUC es una empresa de tu cuenta, con sus establecimientos y series. Indicas la empresa con company_id en cada emisión, y GET /v1/companies te da las empresas y sus series.
Las claves van por ambiente: dk_test_ para pruebas y dk_live_ para producción. También puedes guardar datos de tu sistema en metadata, un JSON de hasta 4 KB.
El ambiente de pruebas firma con un certificado de prueba y envía a SUNAT beta, sin valor fiscal. No necesitas certificado digital ni clave SOL. Para ensayar los casos difíciles, usa uno de estos valores como razón social del cliente. En producción no hay simulación.
customer.name | Qué pasa con una factura |
|---|---|
SIMULAR RECHAZO | Queda rejected y llega el webhook document.rejected. |
SIMULAR OBSERVACIONES | Queda accepted_with_observations, con una nota de SUNAT. |
SIMULAR TIMEOUT | Queda submitted y por conciliar, como una respuesta perdida. |
SIMULAR VENCIMIENTO | Queda deadline_missed y llega el webhook document.deadline_missed. |
El contrato de /v1 es público: openapi/v1.json. Los SDK para Java y TypeScript se generan desde ese contrato. Todavía no están publicados en Maven ni en npm, así que los coordinamos durante la integración.
Revisamos cada RUC y sus operaciones. El alcance actual cubre boletas, facturas y notas de crédito, en soles y al contado, con envío directo a SUNAT. Revisa qué necesita cada empresa en SOL y los precios.
Cuéntanos qué sistema quieres integrar, cuántos RUC emiten y cuántos comprobantes al mes.