Inicio rápido

Esta guía usa una clave de prueba (asu_test_) y el ambiente beta de SUNAT, así que nada de lo que emitas tiene validez tributaria.

1. 1

   Genera una clave API

   En apisunat.net, entra a tu workspace en modo API y crea una clave de prueba. Guárdala en una variable de entorno de tu servidor:

   bashCopy

   export APISUNAT_KEY="asu_test_..."

   La clave da acceso completo a tu workspace. Úsala solo desde tu servidor, nunca en una app web o móvil.

2. 2

   Comprueba la conexión

   bashCopy

   curl https://api.apisunat.net/api/v1/issuer/ping \
     -H "X-API-Key: $APISUNAT_KEY"

   jsonCopy

   {
     "workspace": { "id": "8a1f...", "name": "Mi Empresa" },
     "keyType": "test",
     "plan": "gratis"
   }

3. 3

   Registra tu RUC

   Si todavía no lo hiciste desde el panel (en modo Prueba), registra el RUC con tu clave de prueba como se explica en Emisores. Queda como RUC de prueba: solo lo ven tus claves asu_test_. Sube su certificado digital y su clave, y valídalo en beta. No necesitas usuario ni clave SOL.

4. 4

   Emite una boleta

   bashCopy

   curl https://api.apisunat.net/api/v1/issuer/documents \
     -H "X-API-Key: $APISUNAT_KEY" \
     -H "Idempotency-Key: boleta-0001" \
     -H "Content-Type: application/json" \
     -d '{
       "documentType": "03",
       "currency": "PEN",
       "issueDate": "2026-10-27",
       "customer": {
         "documentType": "1",
         "documentNumber": "12345678",
         "name": "Juan Pérez"
       },
       "items": [
         { "description": "Polo talla M", "quantity": 2, "unitPrice": 59 }
       ]
     }'

   La API responde 202 con el documento:

   jsonCopy

   {
     "id": "3f8c1d2e-6b1a-4c55-9d0e-2a7b3c4d5e6f",
     "type": "03",
     "series": "B001",
     "number": 90000001,
     "fullNumber": "B001-90000001",
     "status": "accepted",
     "environment": "beta",
     "issuerRuc": "20123456789",
     "issueDate": "2026-10-27",
     "currency": "PEN",
     "total": 118,
     "customer": { "documentType": "1", "documentNumber": "12345678", "name": "Juan Pérez" },
     "sunat": {
       "ticket": null,
       "responseCode": "0",
       "description": "La Boleta numero B001-90000001, ha sido aceptada",
       "errorCode": null,
       "errorMessage": null,
       "attempts": 1
     },
     "links": {
       "self": "/api/v1/issuer/documents/3f8c1d2e-6b1a-4c55-9d0e-2a7b3c4d5e6f",
       "pdf": "/api/v1/issuer/documents/3f8c1d2e-6b1a-4c55-9d0e-2a7b3c4d5e6f/pdf",
       "xml": "/api/v1/issuer/documents/3f8c1d2e-6b1a-4c55-9d0e-2a7b3c4d5e6f/xml",
       "zip": "/api/v1/issuer/documents/3f8c1d2e-6b1a-4c55-9d0e-2a7b3c4d5e6f/zip",
       "cdr": "/api/v1/issuer/documents/3f8c1d2e-6b1a-4c55-9d0e-2a7b3c4d5e6f/cdr"
     },
     "createdAt": "2026-10-27T15:04:05.000Z",
     "updatedAt": "2026-10-27T15:04:06.000Z"
   }

   La serie y el número se asignaron solos: las pruebas usan su propia numeración desde 90000001. Los precios incluyen IGV por defecto y la afectación es 10 (gravado).

5. 5

   Descarga el PDF

   bashCopy

   curl -o B001-90000001.pdf \
     "https://api.apisunat.net/api/v1/issuer/documents/3f8c1d2e-6b1a-4c55-9d0e-2a7b3c4d5e6f/pdf?format=ticket80" \
     -H "X-API-Key: $APISUNAT_KEY"

Siguientes pasos

• Documentos: todos los campos de factura, boleta y notas.
• Estados: qué significa cada estado y cuándo consultar SUNAT.
• Webhooks: recibe los cambios de estado sin consultar.
• Para emitir comprobantes reales, registra el mismo RUC con una clave asu_live_ (en el panel, en modo Producción), guarda sus credenciales completas, haz la prueba real y habilita producción. Los RUC de prueba y de producción son independientes: sin producción habilitada la clave live responde 403 PRODUCTION_NOT_ENABLED.