Documentación de la API

Referencia completa de la API REST de TukiFact para integrar facturación electrónica en tu sistema.

Autenticación

Todas las solicitudes a la API requieren autenticación mediante una API Key. Incluí tu clave en el header Authorization de cada request.

Header de autenticación

Authorization: Bearer TF_live_xxxxxxxxxxxxxxxxxxxx

⚠ Importante: Nunca expongas tu API Key en código del lado del cliente (browser). Usá siempre variables de entorno del servidor.

URLs Base

Producción

API en vivo

https://api.tukifact.net.pe

Usa API Keys con prefijo TF_live_

Sandbox

Entorno de pruebas

https://sandbox.tukifact.net.pe

Usa API Keys con prefijo TF_test_

Límites por Plan

Los headers X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset se incluyen en cada respuesta.

Plan	Requests/hora	Documentos/mes
Free	100 req/hora	1,000 documentos
Emprendedor	500 req/hora	10,000 documentos
Negocio	2,000 req/hora	50,000 documentos
Profesional	5,000 req/hora	200,000 documentos
Empresa	20,000 req/hora	Ilimitado

Formato de Respuesta

Todas las respuestas son en JSON. Las listas incluyen paginación estándar.

Respuesta exitosa

{
  "data": { ... },
  "meta": {
    "requestId": "req_xxxx"
  }
}

Lista paginada

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 150,
    "totalPages": 8
  }
}

Códigos de Error

Código	Nombre	Descripción
400	Bad Request	Datos inválidos en el cuerpo de la solicitud
401	Unauthorized	API Key ausente, inválida o expirada
403	Forbidden	Sin permisos para este recurso o acción
404	Not Found	El recurso solicitado no existe
409	Conflict	El documento ya fue emitido o hay un conflicto de estado
422	Unprocessable Entity	Error de validación SUNAT en el XML generado
429	Too Many Requests	Límite de requests por hora excedido
500	Internal Server Error	Error interno — contactar soporte
503	Service Unavailable	SUNAT no disponible temporalmente, reintentar

Endpoints

Documentos

POST/v1/documentsCrear y emitir un comprobante electrónico

GET/v1/documentsListar comprobantes con filtros y paginación

GET/v1/documents/:idObtener un comprobante por ID

GET/v1/documents/:id/pdfDescargar el PDF del comprobante

GET/v1/documents/:id/xmlDescargar el XML firmado

GET/v1/documents/:id/statusConsultar estado en SUNAT

POST/v1/documents/:id/voidAnular un comprobante emitido

Clientes

GET/v1/customersListar clientes del negocio

POST/v1/customersCrear un nuevo cliente

GET/v1/customers/:idObtener cliente por ID

PUT/v1/customers/:idActualizar datos de un cliente

DELETE/v1/customers/:idEliminar un cliente

Series

GET/v1/seriesListar series disponibles

POST/v1/seriesCrear una nueva serie

GET/v1/series/:id/next-numberObtener el siguiente número correlativo

Webhooks

GET/v1/webhooksListar webhooks configurados

POST/v1/webhooksRegistrar un nuevo webhook endpoint

PUT/v1/webhooks/:idActualizar un webhook

DELETE/v1/webhooks/:idEliminar un webhook

POST/v1/webhooks/:id/testEnviar un evento de prueba

Notificaciones

GET/v1/notificationsListar notificaciones del sistema

POST/v1/notifications/:id/readMarcar notificación como leída