Documentacion API de Tikel

Documentacion de endpoints para integracion del sistema. Incluye headers requeridos, ejemplos y campos de body para metodos POST.

Contenido

📖Introduccion#

Esta documentacion centraliza los endpoints disponibles para catalogos, clientes, productos y facturacion.

URL Base: https://{empresa}-sandbox.tikel.app/api/v1
Ejemplo: https://tikel-sandbox.tikel.app/api/v1
Formato: Todas las peticiones y respuestas usan JSON

Importante: El prefijo de la URL cambia segun la empresa (por ejemplo, tikel), pero el sufijo -sandbox.tikel.app es fijo.

🔐Headers Requeridos#

Cada endpoint debe enviarse con estos headers:

Parámetro	Tipo	Requerido	Opciones	Depende de	Descripción
`Accept`	header	✅ Requerido	-	-	Debe enviarse como application/json
`Content-Type`	header	✅ Requerido	-	-	Debe enviarse como application/json
`Authorization`	header	✅ Requerido	-	-	Bearer your-token

Headers

Accept: application/json
Content-Type: application/json
Authorization: Bearer your-token

Importante: El token debe enviarse como Bearer token valido.

🌐Endpoints Generales#

AUTENTIFICACION PRIMERO: Consume primero POST /token y guarda el token. Ese token debe enviarse en Authorization: Bearer ...para el resto de endpoints protegidos.

POSThttps://tikel-sandbox.tikel.app/api/v1/token

AUTENTIFICACION: Genera token para consumir los demas endpoints

Request POST /token

{
  "email": "usuario@empresa.com",
  "password": "tu-password"
}

POST /token - Body

Parámetro	Tipo	Requerido	Opciones	Depende de	Descripción
`email`	string	✅ Requerido	-	-	Correo del usuario
`password`	string	✅ Requerido	-	-	Contrasena del usuario

Clave: Guarda el token recibido y reutilizalo en los headers Authorization para no perder la sesion.

GEThttps://tikel-sandbox.tikel.app/api/v1/users

Obtiene el listado de usuarios

Request GET /users

curl -X GET "https://tikel-sandbox.tikel.app/api/v1/users" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token"

GEThttps://tikel-sandbox.tikel.app/api/v1/countries

Obtiene catalogo de paises

Request GET /countries

curl -X GET "https://tikel-sandbox.tikel.app/api/v1/countries" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token"

GEThttps://tikel-sandbox.tikel.app/api/v1/cities

Obtiene catalogo de ciudades

Request GET /cities

curl -X GET "https://tikel-sandbox.tikel.app/api/v1/cities" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token"

GEThttps://tikel-sandbox.tikel.app/api/v1/departments

Obtiene catalogo de departamentos

Request GET /departments

curl -X GET "https://tikel-sandbox.tikel.app/api/v1/departments" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token"

GEThttps://tikel-sandbox.tikel.app/api/v1/activities

Obtiene catalogo de actividades economicas

Request GET /activities

curl -X GET "https://tikel-sandbox.tikel.app/api/v1/activities" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token"

GEThttps://tikel-sandbox.tikel.app/api/v1/incoterms

Obtiene catalogo de incoterms

Request GET /incoterms

curl -X GET "https://tikel-sandbox.tikel.app/api/v1/incoterms" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token"

POSThttps://tikel-sandbox.tikel.app/api/v1/webhook

WEBHOOK: Endpoint que debe escuchar el cliente para eventos de facturacion de /billing-invoice

Request POST /webhook

curl -X POST "https://tikel-sandbox.tikel.app/api/v1/webhook" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Webhook del cliente: Este endpoint debe quedar escuchando en tu cliente para recibir eventos cuando se ejecuta POST /billing-invoice.

Nota: Este endpoint no lleva body.

👥Endpoints Customers#

GEThttps://tikel-sandbox.tikel.app/api/v1/clients

Lista clientes

Request GET /clients

curl -X GET "https://tikel-sandbox.tikel.app/api/v1/clients" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token"

GEThttps://tikel-sandbox.tikel.app/api/v1/clients/{id}

Obtiene detalle de un cliente

Parámetro	Tipo	Requerido	Opciones	Depende de	Descripción
`id`	integer	✅ Requerido	-	-	ID del recurso (parametro de ruta)

POSThttps://tikel-sandbox.tikel.app/api/v1/clients

Crea un cliente

Parámetro	Tipo	Requerido	Opciones	Depende de	Descripción
`nombre`	string	✅ Requerido	-	-	Nombre completo o razon social del cliente
`correo`	string	✅ Requerido	-	-	Correo electronico del cliente
`telefono`	string	❌ Opcional	-	-	Telefono de contacto (opcional)
`fecha_nacimiento`	string	❌ Opcional	-	-	Fecha de nacimiento en formato YYYY-MM-DD (opcional)
`direccion`	object	❌ Opcional	-	-	Objeto { country_id, department_id, city_id, complemento }
`direccion.city_id`	number	⚠️ Condicional	-	Si se envia direccion como objeto	ID de ciudad (opcional, si no se envia en direccion objeto)
`direccion.department_id`	number	⚠️ Condicional	-	Si se envia direccion como objeto	ID de departamento (opcional, si no se envia en direccion objeto)
`direccion.country_id`	number	⚠️ Condicional	-	Si se envia direccion como objeto	ID de pais (opcional, si no se envia en direccion objeto)
`direccion.complemento`	string	⚠️ Condicional	-	Si se envia direccion como objeto	Complemento de la direccion (opcional, si no se envia en direccion objeto)
`dui`	string	⚠️ Condicional	-	payment_method = 2 o 3	Longitud exacta: 10 (con guion). Debe ser unico si se envia
`nit`	string	⚠️ Condicional	-	payment_method = 2 o 3	Longitud exacta: 14 (sin guion). Debe ser unico si se envia
`nrc`	string	⚠️ Condicional	-	payment_method = 2	Longitud exacta: 7 (sin guion). Debe ser unico si se envia
`payment_method`	integer	✅ Requerido	2: CCF 3: Sujeto Excluido 4: Exportacion	-	Metodo de pago
`actividad_economica_id`	number	⚠️ Condicional	-	payment_method = 2 o 3	ID de actividad economica
`actividad`	string	⚠️ Condicional	-	payment_method = 4	Nombre de la actividad economica
`customer_kind`	integer	⚠️ Condicional	1: Grande 2: Mediana 3: Pequeña	payment_method = 2	Tamaño de la empresa
`documento`	string	⚠️ Condicional	-	payment_method = 4	Documento principal del cliente
`tipo_persona`	integer	⚠️ Condicional	1: Natural 2: Juridica	payment_method = 4	Tipo de persona
`id_codincoterms`	number	⚠️ Condicional	-	payment_method = 4	ID del incoterm

PUThttps://tikel-sandbox.tikel.app/api/v1/clients/{id}

Actualiza un cliente (id obligatorio en path)

Parámetro	Tipo	Requerido	Opciones	Depende de	Descripción
`id`	integer	✅ Requerido	-	-	ID del cliente a actualizar (parametro de ruta)
`nombre`	string	⚠️ Condicional	-	Requerido si no existe valor previo en el cliente	Si no se envia, toma el valor actual del cliente
`correo`	string	⚠️ Condicional	-	Requerido si no existe valor previo en el cliente	Si no se envia, toma el valor actual del cliente
`telefono`	string	❌ Opcional	-	-	Telefono de contacto (opcional)
`fecha_nacimiento`	string	❌ Opcional	-	-	Fecha de nacimiento en formato YYYY-MM-DD (opcional)
`direccion`	object	❌ Opcional	-	-	Objeto { country_id, department_id, city_id, complemento }
`direccion.city_id`	number	⚠️ Condicional	-	Si se envia direccion como objeto	ID de ciudad (opcional, si no se envia en direccion objeto)
`direccion.department_id`	number	⚠️ Condicional	-	Si se envia direccion como objeto	ID de departamento (opcional, si no se envia en direccion objeto)
`direccion.country_id`	number	⚠️ Condicional	-	Si se envia direccion como objeto	ID de pais (opcional, si no se envia en direccion objeto)
`direccion.complemento`	string	⚠️ Condicional	-	Si se envia direccion como objeto	Complemento de la direccion (opcional, si no se envia en direccion objeto)
`dui`	string	⚠️ Condicional	-	payment_method = 2 o 3	Longitud exacta: 10 (con guion). Debe ser unico si se envia. Unicidad validada excluyendo el mismo id del cliente
`nit`	string	⚠️ Condicional	-	payment_method = 2 o 3	Longitud exacta: 14 (sin guion). Debe ser unico si se envia. Unicidad validada excluyendo el mismo id del cliente
`nrc`	string	⚠️ Condicional	-	payment_method = 2	Longitud exacta: 7 (sin guion). Debe ser unico si se envia. Unicidad validada excluyendo el mismo id del cliente
`payment_method`	integer	⚠️ Condicional	2: CCF 3: Sujeto Excluido 4: Exportacion	Requerido si no existe valor previo en el cliente	Si no se envia, toma el valor actual del cliente
`actividad_economica_id`	number	⚠️ Condicional	-	payment_method = 2 o 3	ID de actividad economica
`actividad`	string	⚠️ Condicional	-	payment_method = 4	Nombre de la actividad economica
`customer_kind`	integer	⚠️ Condicional	1: Grande 2: Mediana 3: Pequeña	payment_method = 2	Tamaño de la empresa
`documento`	string	⚠️ Condicional	-	payment_method = 4	Documento principal del cliente
`tipo_persona`	integer	⚠️ Condicional	1: Natural 2: Juridica	payment_method = 4	Tipo de persona
`id_codincoterms`	number	⚠️ Condicional	-	payment_method = 4	ID del incoterm

DELETEhttps://tikel-sandbox.tikel.app/api/v1/clients/{id}

Elimina un cliente (solo recibe id en path, sin body)

Parámetro	Tipo	Requerido	Opciones	Depende de	Descripción
`id`	integer	✅ Requerido	-	-	ID del cliente a eliminar (parametro de ruta)

📦Endpoints Products#

GEThttps://tikel-sandbox.tikel.app/api/v1/products

Lista productos

Request GET /products

curl -X GET "https://tikel-sandbox.tikel.app/api/v1/products" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token"

GEThttps://tikel-sandbox.tikel.app/api/v1/products/{id}

Obtiene detalle de producto

Parámetro	Tipo	Requerido	Opciones	Depende de	Descripción
`id`	integer	✅ Requerido	-	-	ID del recurso (parametro de ruta)

POSThttps://tikel-sandbox.tikel.app/api/v1/products

Crea un producto

Parámetro	Tipo	Requerido	Opciones	Depende de	Descripción
`name`	string	✅ Requerido	-	-	Nombre del producto

🧾Endpoints Invoices#

GEThttps://tikel-sandbox.tikel.app/api/v1/detail-invoice/{id}

Obtiene detalle de factura

Parámetro	Tipo	Requerido	Opciones	Depende de	Descripción
`id`	integer	✅ Requerido	-	-	ID del recurso (parametro de ruta)

POSThttps://tikel-sandbox.tikel.app/api/v1/invoices

Crea una factura

Parámetro	Tipo	Requerido	Opciones	Depende de	Descripción
`payment_method`	integer	✅ Requerido	2: CCF 3: Sujeto Excluido 4: Exportacion	-	Metodo de pago
`id_cliente`	integer	✅ Requerido	-	-	ID del cliente a facturar
`id_user`	integer	✅ Requerido	-	-	ID del usuario que crea la factura
`details`	array	✅ Requerido	-	-	Listado de lineas de factura (no puede estar vacio)
`details[].product_id`	integer	✅ Requerido	-	-	ID del producto en la linea
`details[].descripcion`	string	✅ Requerido	-	-	Descripcion del item en la linea
`details[].amount`	integer	✅ Requerido	-	-	Cantidad del item
`details[].price`	decimal	✅ Requerido	-	-	Precio unitario del item
`renta`	integer	⚠️ Condicional	1: aplicar retencion 0: no aplicar retencion Default: 0	payment_method = 2	Aplicar retencion de renta 10%
`retencion`	decimal	❌ Opcional	-	-	Monto de retencion a descontar
`comment`	string	❌ Opcional	-	-	Comentario u observacion de la factura

PUThttps://tikel-sandbox.tikel.app/api/v1/invoices/{id}

Actualiza una factura

Parámetro	Tipo	Requerido	Opciones	Depende de	Descripción
`id`	integer	✅ Requerido	-	-	ID de la factura a actualizar (parametro de ruta)
`details`	array	✅ Requerido	-	-	Listado de lineas de factura (no puede estar vacio)
`details[].id`	integer	⚠️ Condicional	Puede ser 0 si se action = 2 para crear nuevo detalle	action = 0 o 1	ID del detalle de factura
`details[].product_id`	integer	✅ Requerido	-	-	ID del producto en la linea
`details[].descripcion`	string	✅ Requerido	-	-	Descripcion del item en la linea
`details[].amount`	integer	✅ Requerido	-	-	Cantidad del item
`details[].price`	decimal	✅ Requerido	-	-	Precio unitario del item
`details[].action`	integer	✅ Requerido	0: actualizar 1: eliminar 2: crear	-	Accion a ejecutar para cada detalle
`renta`	integer	❌ Opcional	1: aplicar retencion 0: no aplicar retencion	-	Si no se envia, mantiene el valor actual
`retencion`	decimal	❌ Opcional	-	-	Si no se envia, mantiene el valor actual
`comment`	string	❌ Opcional	-	-	Comentario u observacion de la factura

POSThttps://tikel-sandbox.tikel.app/api/v1/billing-invoice

Dispara proceso de facturacion (webhook)

Parámetro	Tipo	Requerido	Opciones	Depende de	Descripción
`factura_id`	integer	✅ Requerido	-	-	ID de la factura a facturar
`user`	integer	✅ Requerido	-	-	ID del usuario que ejecuta el proceso de facturacion

POSThttps://tikel-sandbox.tikel.app/api/v1/invoices-credit-note

Crea nota de credito

Parámetro	Tipo	Requerido	Opciones	Depende de	Descripción
`id_factura`	integer	✅ Requerido	-	-	ID de factura original
`id_cliente`	integer	✅ Requerido	-	-	ID del cliente asociado a la factura
`id_user`	integer	✅ Requerido	-	-	ID del usuario que crea la nota de credito
`tipo`	integer	✅ Requerido	2: Devolucion por Valor 3: Devolucion por Producto	-	Tipo de nota de credito
`descripcion`	string	❌ Opcional	-	-	Descripcion general de la nota de credito
`renta`	integer	❌ Opcional	1: aplicar retencion 0: no aplicar retencion	-	Aplicar retencion de renta
`details`	array	✅ Requerido	-	-	Items de la nota de credito (no puede estar vacio)
`details[].product_id`	integer	✅ Requerido	-	-	Producto a acreditar (debe existir en la factura original)
`details[].descripcion`	string	✅ Requerido	-	-	Descripcion del item
`details[].amount`	integer	✅ Requerido	-	-	Cantidad a acreditar (no puede ser mayor a la de factura original)
`details[].price`	decimal	✅ Requerido	-	-	Precio unitario del item

⚠️Manejo de Errores#

Codigo	Error	Descripcion
400	Bad Request	Parametros invalidos o faltantes
401	Unauthorized	Token invalido o faltante
404	Not Found	Recurso no encontrado
500	Internal Server Error	Error interno del servidor

Ejemplo de respuesta de error

{
    "type": 0,
    "message": "Faltan campos obligatorios(Comprobante de Credito Fiscal): nit (STRING), dui (STRING), nrc (STRING), customer_kind (INTEGER), actividad_economica_id (INTEGER)",
    "data": []
}

Si necesitas ampliar esta documentacion, agrega nuevos endpoints en esta misma estructura.

Ejemplo cURL

curl -X POST "https://tikel-sandbox.tikel.app/api/v1/token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"usuario@empresa.com","password":"tu-password"}'