Datos de empresa
- RUC con dígito verificador.
- Razón social exacta.
- Nombre comercial si aplica.
- Tipo de contribuyente y régimen fiscal.
- Dirección fiscal y actividad económica que debe salir en el imprimible.
Manual de preparación
Antes de integrar como autoimpresor
Usá este manual cuando el cliente ya tiene autoimpresión autorizada o está por operar documentos imprimibles fiscales desde su ERP, POS, ecommerce o sistema interno.
Checklist mínimo antes de tocar la API
Si falta uno de estos datos, la integración puede avanzar en sandbox, pero no debería salir a producción.
Sucursal y punto
- Código de sucursal autorizado.
- Dirección, departamento, distrito y ciudad.
- Código de punto de expedición.
- Descripción operativa del punto: caja, ecommerce, depósito o servicio.
- Responsable interno de ese punto.
Autorización autoimpresor
- Número de autorización.
- Software declarado ante la autoridad correspondiente.
- Proveedor o backend que reserva número y confirma emisión.
- Endpoint productivo y, si existe, endpoint de prueba.
- Credencial o llave del backend autoimpresor.
Timbrado y rango
- Tipo documental autorizado: factura, nota de crédito, nota de débito, remisión, recibo o autofactura.
- Timbrado por tipo documental.
- Fecha desde y fecha hasta.
- Rango inicial y final autorizado.
- Próximo número real sin usar.
Impresión
- Campos fiscales obligatorios que deben aparecer.
- Logo o texto de marca si corresponde.
- Leyenda inferior o nota comercial.
- Formato esperado: PDF/imprimible.
- Persona que aprueba el primer PDF generado.
Integración técnica
- Clave API con alcance de documentos.
- external_id único en el sistema origen.
- Idempotency-Key estable por documento.
- Webhook HTTPS si el sistema origen recibirá cambios de estado.
- Manejo de errores de validación, configuración, backend y numeración.
Secuencia de configuración
La consola debe quedar lista antes de que el sistema origen cree documentos reales.
- 1
Crear empresa
Cargar RUC, razón social, tipo de contribuyente, régimen y datos comerciales.
- 2
Crear sucursal y punto
Cargar los códigos autorizados y confirmar que coinciden con la documentación fiscal.
- 3
Configurar autoimpresor
Cargar autorización, software declarado, endpoint, credencial, sucursal, punto y rangos por tipo documental.
- 4
Crear clave API
Entregar la clave una sola vez al equipo técnico y guardarla fuera de tickets o chats.
- 5
Probar payload
Validar un documento con /v1/documents/validate antes de crear documentos reales.
- 6
Emitir primer documento controlado
Crear una factura o documento de prueba acordado con el cliente, confirmar número reservado, PDF/imprimible, estado y webhook.
Criterios para salir a producción
No alcanza con que la API responda 200. El cliente debe poder reconciliar y auditar el documento.
Debe estar listo
- Canal autoimpresor en estado listo.
- Rango cargado con próximo número correcto.
- Primer documento validado o emitido.
- Reintento con la misma Idempotency-Key sin duplicar documento.
- PDF/imprimible aprobado por el responsable fiscal.
No hacer
- No mandar timbrado o próximo número desde el payload.
- No reutilizar rangos de otro punto de expedición.
- No mezclar documentos de prueba con datos productivos.
- No regenerar PDFs sin revisar impacto operativo.
- No pegar credenciales en capturas, tickets o correo.