# API v1. Autenticación: Authorization: Bearer . # Fallas comunes: 401 {"reason":"Unauthenticated"} (con WWW-Authenticate: Bearer) · 429 {"reason":"TooManyRequests"} (con Retry-After). @baseUrl = https://faktura-test.cgallardo.me @apiKey = sk_test_000000000000_0000000000000000000000000000000000000000000000000000000000000000 ### Emisor, entorno y estado de credenciales de la clave # 200 {"company":{"id","ruc","legal_name","trade_name","has_certificate","has_sol_credentials"},"api_key":{"prefix","environment"},"sunat_environment"} GET {{baseUrl}}/v1/me Accept: application/json Authorization: Bearer {{apiKey}} ### Series del emisor en el entorno de la clave (catálogo acotado, sin paginar) # 200 {"items":[{"id","document_type","code","branch_code","next_number"}]} GET {{baseUrl}}/v1/series Accept: application/json Authorization: Bearer {{apiKey}} ### Emitir una boleta (201 nuevo · 200 + Idempotent-Replayed si se repite · 409 IdempotencyKeyReused · 422 con reason) POST {{baseUrl}}/v1/receipts Accept: application/json Content-Type: application/json Authorization: Bearer {{apiKey}} Idempotency-Key: pos-0042-000187 { "series": "B001", "customer": { "doc_type": "DNI", "doc_number": "45678912", "name": "MARIA PEREZ" }, "items": [ { "product_code": "CAF-01", "description": "Cafe americano", "quantity": 2, "unit_price": 8.00 }, { "description": "Bolsa plastica", "quantity": 1, "unit_price": 0.10, "icbper": true } ] } ### Emitir una factura al crédito POST {{baseUrl}}/v1/invoices Accept: application/json Content-Type: application/json Authorization: Bearer {{apiKey}} { "series": "F001", "currency": "USD", "price_includes_tax": false, "customer": { "doc_type": "RUC", "doc_number": "20131312955", "name": "CLIENTE DE PRUEBA S.A.C." }, "items": [ { "description": "Consultoria", "quantity": 3, "unit_price": 10.555, "unit_code": "HUR" } ], "payment": { "type": "credito", "installments": [ { "amount": 20.00, "due_date": "2026-12-15" }, { "amount": 17.37, "due_date": "2027-01-15" } ] } } ### Consultar un comprobante (200 · 404 NotFound si es de otro emisor o entorno) @documentId = 00000000-0000-0000-0000-000000000000 GET {{baseUrl}}/v1/documents/{{documentId}} Accept: application/json Authorization: Bearer {{apiKey}} ### Descargar XML firmado (application/xml · 404 si aún no se firmó) GET {{baseUrl}}/v1/documents/{{documentId}}/xml Authorization: Bearer {{apiKey}} ### Descargar CDR de SUNAT (application/zip · 404 si aún no hay respuesta) GET {{baseUrl}}/v1/documents/{{documentId}}/cdr Authorization: Bearer {{apiKey}} ### Nota de crédito por anulación (copia los ítems del comprobante) POST {{baseUrl}}/v1/credit-notes Accept: application/json Content-Type: application/json Authorization: Bearer {{apiKey}} { "affected_document_id": "{{documentId}}", "series": "FC01", "reason_code": "01" } ### Nota de débito por intereses POST {{baseUrl}}/v1/debit-notes Accept: application/json Content-Type: application/json Authorization: Bearer {{apiKey}} { "affected_document_id": "{{documentId}}", "series": "FD01", "reason_code": "01", "items": [ { "description": "Intereses por mora", "quantity": 1, "unit_price": 11.80 } ] } ### Anular un comprobante (202 · 409 DocumentNotAccepted / VoidAlreadyRequested / AlreadyVoided · 422 VoidWindowExpired) POST {{baseUrl}}/v1/documents/{{documentId}}/void Accept: application/json Content-Type: application/json Authorization: Bearer {{apiKey}} { "reason": "Error en el precio" } ### Factura con descuentos, orden de compra y guía POST {{baseUrl}}/v1/invoices Accept: application/json Content-Type: application/json Authorization: Bearer {{apiKey}} { "series": "F001", "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." }, "items": [ { "description": "Laptop", "quantity": 1, "unit_price": 118, "discount": { "amount": 18 } }, { "description": "Mouse", "quantity": 2, "unit_price": 50, "discount": { "percent": 10 } } ], "discount": { "amount": 5 }, "purchase_order": "OC-2026-001", "despatch_references": [{ "type": "09", "number": "T001-123" }] } ### Factura con detracción al crédito (cuotas = neto pendiente de pago) POST {{baseUrl}}/v1/invoices Accept: application/json Content-Type: application/json Authorization: Bearer {{apiKey}} { "series": "F001", "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." }, "items": [{ "description": "Mantenimiento de equipos", "quantity": 1, "unit_price": 1180 }], "detraction": { "code": "020", "percent": 12, "bank_account": "00-000-123456" }, "payment": { "type": "credito", "installments": [{ "amount": 1038.40, "due_date": "2099-01-15" }] } } ### Nota de crédito 13: nuevo cronograma de una factura al crédito (va en cero) POST {{baseUrl}}/v1/credit-notes Accept: application/json Content-Type: application/json Authorization: Bearer {{apiKey}} { "affected_document_id": "{{documentId}}", "series": "FC01", "reason_code": "13", "payment": { "type": "credito", "installments": [{ "amount": 590, "due_date": "2099-02-15" }, { "amount": 590, "due_date": "2099-03-15" }] } } ### Boleta de restaurante con recargo al consumo y fecha de ayer POST {{baseUrl}}/v1/receipts Accept: application/json Content-Type: application/json Authorization: Bearer {{apiKey}} { "series": "B001", "issue_date": "2026-11-13", "customer": { "doc_type": "NONE" }, "items": [{ "description": "Menú ejecutivo", "quantity": 2, "unit_price": 25 }], "service_charge": { "percent": 10 } } ### Reenviar un comprobante failed (tras corregir la clave SOL) POST {{baseUrl}}/v1/documents/{{documentId}}/retry Accept: application/json Authorization: Bearer {{apiKey}} ### Listar comprobantes (filtros opcionales) GET {{baseUrl}}/v1/documents?document_type=03&page=1&page_size=20 Accept: application/json Authorization: Bearer {{apiKey}} ### Enviar el comprobante por correo (202 · 409 DocumentNotAccepted · 503 EmailNotConfigured) POST {{baseUrl}}/v1/documents/{{documentId}}/email Accept: application/json Content-Type: application/json Authorization: Bearer {{apiKey}} { "to": ["cliente@ejemplo.pe"] } ### PDF del comprobante (application/pdf · format=a4|ticket|ticket58) GET {{baseUrl}}/v1/documents/{{documentId}}/pdf?format=ticket Authorization: Bearer {{apiKey}} ### Consultar un RUC (404 RucNotFound · 422 InvalidRuc · 503 RucLookupUnavailable) GET {{baseUrl}}/v1/lookup/ruc/20131312955 Accept: application/json Authorization: Bearer {{apiKey}} ### Consultar hasta 1000 RUC a la vez POST {{baseUrl}}/v1/lookup/ruc Accept: application/json Content-Type: application/json Authorization: Bearer {{apiKey}} { "rucs": ["20131312955", "20100070970", "123"] } ### Consultar un DNI (personas con RUC 10 en el padrón de SUNAT; si no tiene RUC 10, 404 DniNotFound) GET {{baseUrl}}/v1/lookup/dni/45678912 Accept: application/json Authorization: Bearer {{apiKey}} ### Registrar un webhook (201 con secret una sola vez · 422 InvalidWebhookUrl · 409 TooManyWebhooks) POST {{baseUrl}}/v1/webhooks Accept: application/json Content-Type: application/json Authorization: Bearer {{apiKey}} { "url": "https://erp.miempresa.pe/faktura/webhook", "events": ["document.accepted", "document.rejected"] } ### Listar webhooks GET {{baseUrl}}/v1/webhooks Accept: application/json Authorization: Bearer {{apiKey}} ### Eliminar un webhook (204 · 404) @webhookId = 00000000-0000-0000-0000-000000000000 DELETE {{baseUrl}}/v1/webhooks/{{webhookId}} Authorization: Bearer {{apiKey}}