Introducción

¡Bienvenido a la API de facturación de Tandia! Nuestra API te brinda acceso a una variedad de recursos y funciones para el envío de documentos electrónicos tales como:

• Facturas
• Boletas
• Notas de crédito
• Notas de débito
• Guías de remisión remitente
• Guías de remisión transportista

La API trabaja actualmente con comprobantes electrónicos peruanos y usa códigos tributarios compatibles con SUNAT. En esta documentación usamos el término documento como entidad general, y comprobante para referirnos al tipo tributario específico que se emite.

URL Base

Para interactuar con nuestra API en Producción, debes utilizar la URL base:

https://invoice.tandia.io/api

Para interactuar con nuestra API en el ambiente de pruebas, debes utilizar la URL base:

https://invoice.test.tandia.io/api

Asegúrate de utilizar esta URL como punto de partida para todas tus solicitudes a la API.

Autenticación

Para garantizar la seguridad de tus datos y recursos, nuestra API requiere autenticación. Debes incluir un token de API válido en el encabezado de autorización (Bearer) en tus solicitudes. Consulta la sección de autenticación en la documentación para obtener más detalles sobre cómo obtener y utilizar tu token de API.

Conceptos principales

• Cuenta: representa al integrador o usuario dueño del token de API.
• Compañía: empresa emisora registrada en Tandia. Se identifica por tax_id (RUC).
• Cliente: persona o empresa receptora del comprobante. Se define con document_type, document_number y registration_name.
• Documento: registro electrónico creado por la API. Su identificador interno usa el prefijo doc_.
• Comprobante: variante tributaria del documento: invoice, receipt, credit-note, debit-note, despatch o carrier-despatch.
• Serie: prefijo tributario del comprobante, por ejemplo FF01, BB01, FC01 o T001.
• Número: número completo del comprobante, por ejemplo FF01-00000001. Si usas endpoints básicos puedes enviar serie para que la API use el correlativo registrado.
• Correlativo: número secuencial asociado a una serie y tipo de comprobante.
• CDR: constancia de recepción emitida por SUNAT cuando corresponde.

Tipos de comprobante

Valor	Comprobante	Uso común
invoice	Factura	Ventas a empresas o clientes con RUC.
receipt	Boleta	Ventas a consumidores finales.
credit-note	Nota de crédito	Anulación, devolución, descuento o disminución de valor de un comprobante previo.
debit-note	Nota de débito	Incremento de valor u otros cargos sobre un comprobante previo.
despatch	Guía de remisión remitente	Traslado de bienes emitido por el remitente.
carrier-despatch	Guía de remisión transportista	Traslado de bienes emitido por el transportista.

Estados de un documento

Estado	Significado
created	La API recibió y guardó el documento.
pending	El documento está pendiente de procesamiento o envío al proveedor tributario.
succeeded	El documento fue procesado satisfactoriamente.
error	El proveedor tributario rechazó el documento o se detectó un error no reprocesable.
failed	Ocurrió un fallo técnico reprocesable, por ejemplo indisponibilidad temporal del proveedor.

Los webhooks notifican principalmente resultados finales como succeeded o error. Un documento en failed puede ser reintentado por el sistema.

Montos e impuestos

En los endpoints detallados debes enviar los importes calculados. Los campos más usados son:

Campo	Descripción
sale_value	Valor de venta sin impuestos de las operaciones del comprobante.
tax_total	Total de impuestos del comprobante, por ejemplo IGV o ICBPER.
subtotal	Suma base del comprobante antes de ajustes finales. En operaciones gravadas suele ser sale_value + tax_total.
total	Importe final del comprobante. Puede cambiar si hay anticipos, descuentos, retenciones, percepciones o redondeo.
taxed_amount	Base gravada afectada a IGV.
exonerated_amount	Base exonerada.
unaffected_amount	Base inafecta.
free_amount	Valor referencial de operaciones gratuitas.
tax_amounts	Resumen de impuestos por código a nivel de comprobante.
items[].taxes	Impuestos aplicados a cada ítem.

Los códigos tributarios más frecuentes en la documentación son IGV, EXO, INA, GRA e ICBPER.