Primeros pasos — XmlPeruDev Docs

En 3 pasos emites tu primera factura firmada en el entorno demo.

1. Obtén un token de empresa

Desde el panel, en tu empresa → Tokens API, genera un token (permiso cpe:sign). Cópialo: solo se muestra una vez.

export TOKEN="pega-aqui-tu-token"

2. Prepara el comprobante en JSON

Guarda una factura mínima como factura.json (ejemplo resumido):

{
  "tipoDoc": "01",
  "serie": "F001",
  "correlativo": "123",
  "tipoMoneda": "PEN",
  "emisor": {
    "ruc": "20123456789",
    "razonSocial": "MI EMPRESA SAC",
    "establecimiento": {
      "ubigeo": "150101", "departamento": "LIMA", "provincia": "LIMA",
      "distrito": "LIMA", "direccion": "AV. EJEMPLO 123"
    }
  },
  "cliente": { "tipoDoc": "6", "numDoc": "20111111111", "nombre": "CLIENTE SAC" },
  "items": [
    { "descripcion": "Servicio", "cantidad": 1, "valorUnitario": 100, "afectacionIgv": "10", "porcentajeIgv": 18 }
  ]
}

3. Emite

curl -X POST https://api.xmlperu.dev/v1/cpe \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: fac-F001-123" \
  -H "Content-Type: application/json" \
  -d @factura.json

Respuesta:

{ "success": true, "estado": "ACEPTADO", "external_id": "…", "hash": "a3f1…9e2c" }

Tip · En demo (environment = 01) no se consume cupo ni se inicia la vigencia del certificado. Cuando estés listo, pasa la empresa a producción (02).

¿Prefieres Postman?

Descarga la colección Postman del API v1 e impórtala (File → Import). Solo tienes que rellenar token_cuenta y token_empresa en las variables de la colección: external_id se rellena solo al emitir, así que puedes emitir y consultar sin copiar nada a mano.

Trae 61 peticiones, cada una con su comprobación, y una casuística real por caso: factura y boleta, exonerada, inafecta, exportación, dólares, descuento global, detracción, retención, pago al contado y en cuotas, los trece motivos de nota de crédito, los seis de nota de débito y las guías de remisión —remitente en transporte público y privado, vehículo M1/L y guía del transportista—. Los payloads van en español y están validados contra el mismo generador que firma en producción, así que son ejemplos que funcionan, no plantillas.

Siguiente: Autenticación · Emitir en detalle · Errores y respuestas