Facturas

Una factura se emite con la misma operación que una boleta, POST /v1/documents, y se envía a SUNAT una por una, apenas se emite. Usa la misma empresa de Primeros pasos, con una serie test de factura activa y por defecto. Para este ensayo el RUC y la razón social del cliente son ficticios; en live usa los del cliente real, que son obligatorios en una factura.

FACTURA_KEY=$(python -c 'import uuid; print(uuid.uuid4())')
FACTURA_EXTERNAL_ID="guia-factura-$(python -c 'import uuid; print(uuid.uuid4())')"
cat > factura.json <<JSON
{
  "type": "factura",
  "company_id": "$COMPANY_ID",
  "customer": {
    "document_type": "ruc",
    "document_number": "20000000001",
    "name": "Cliente de Prueba S.A.C."
  },
  "items": [{
    "description": "Estacionamiento 2 horas",
    "quantity": 1,
    "unit": "ZZ",
    "unit_price": 12.00
  }],
  "external_id": "$FACTURA_EXTERNAL_ID"
}
JSON
printf '%s\n' "$FACTURA_KEY" > factura-idempotencia.txt
curl -sS -D factura.headers -o factura-respuesta.json -w '%{http_code}\n' \
  -H "Authorization: Bearer $BOLETURA_API_KEY" \
  -H "Idempotency-Key: $FACTURA_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @factura.json "$BOLETURA_BASE_URL/v1/documents"
python -m json.tool factura-respuesta.json

Espera 201. Si hay un error, léelo antes de seguir. Con éxito, consulta su estado:

FACTURA_ID=$(campo factura-respuesta.json id)
curl -sS -o factura-estado.json -w '%{http_code}\n' \
  -H "Authorization: Bearer $BOLETURA_API_KEY" \
  "$BOLETURA_BASE_URL/v1/documents/${FACTURA_ID:?}"
python -m json.tool factura-estado.json

Espera 200. Repite esta consulta hasta conocer el resultado: en unos segundos la factura pasa de pending a la respuesta de SUNAT beta. Si sigue pending varios minutos, escribe a soporte@boletura.com con su X-Request-Id. Descarga sus archivos con las mismas rutas de estados y archivos, con FACTURA_ID en lugar del UUID de la boleta. Conserva factura.json y factura-idempotencia.txt: una recuperación usa esos datos, como en reintentos, sin generar otra operación.

Factura sujeta a detracción

Si un servicio está sujeto a detracción, decláralo: la plataforma no lo decide, y SUNAT tampoco avisa si falta. Por ahora se admiten 022, otros servicios empresariales, y 037, demás servicios gravados con el IGV; una operación con otro código del Anexo 3 no se emite por la plataforma. Antes, registra la cuenta de detracciones del Banco de la Nación en los datos generales de la empresa, en el back office. Agrega a la factura:

"detraction": { "code": "022" }

El total, con IGV, debe superar S/ 700 y todos los ítems deben ser gravados. La plataforma calcula el 12 % del total e imprime en el PDF lo que tu cliente necesita para depositar: código, porcentaje, monto y cuenta. El depósito lo hace tu cliente en el Banco de la Nación, fuera de la plataforma. Una nota de crédito sobre esa factura se emite igual que las demás, sin detraction. Los errores de la detracción están en la referencia de la emisión.

Factura al crédito

Si tu cliente paga el total o una parte después de la fecha de emisión, la factura es al crédito. Decláralo: la plataforma no lo decide, y emitirla al contado deja una forma de pago falsa que una nota de crédito no corrige. Solo las facturas admiten crédito.

"payment_terms": {
  "type": "credito",
  "installments": [
    { "amount": 500.00, "due_date": "2026-12-15" },
    { "amount": 500.00, "due_date": "2027-01-15" }
  ]
}

Cada cuota lleva un monto mayor que cero y una fecha posterior a la emisión. La suma de las cuotas es el monto neto pendiente de pago: no lo envíes aparte. No puede superar el total menos la detracción, así que una factura de S/ 1 000.00 con detracción de S/ 120.00 admite hasta S/ 880.00 en cuotas. Puede ser menor si tu cliente retiene IGV u otras deducciones: esas la plataforma no las conoce, y el neto lo calculas tú.

Si algo no cuadra, la solicitud responde 422 antes de numerar y no consume ningún número. El PDF imprime el neto y las cuotas; la respuesta de la API no los devuelve. Revisa bien las cuotas antes de emitir: corregirlas después exige una nota de crédito de tipo 13, que corrige el monto neto pendiente o las cuotas, y que la plataforma todavía no emite.