Autentica con tus credenciales y obtén un par access + refresh token.

Parámetros (JSON)

Campo	Tipo		Descripción
client_id	string	requerido	UUID del cliente API
client_secret	string	requerido	Secreto generado al crear las credenciales

Ejemplo

curl -X POST https://pos.tekio.com.co/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "client_secret": "abc123...secreto"
  }'

Respuesta 200

{
  "access_token": "4f8a2b...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "9e1c7f...",
  "refresh_token_expires_in": 2592000
}

Obtén un nuevo par de tokens. El refresh token anterior queda invalidado.

Parámetros (JSON)

Campo	Tipo		Descripción
refresh_token	string	requerido	Refresh token activo y no expirado

Ejemplo

curl -X POST https://pos.tekio.com.co/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "9e1c7f..."}'

Respuesta 200

{
  "access_token": "nuevo_token...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "nuevo_refresh...",
  "refresh_token_expires_in": 2592000
}

Registra una venta y emite la factura electrónica a la DIAN en un solo paso.

Headers requeridos

Authorization: Bearer <access_token>
Content-Type: application/json

El cliente y los productos se crean automáticamente si no existen en el sistema.

Parámetros (JSON)

Campo	Tipo		Descripción
customer	object	requerido	Datos del cliente — ver esquema abajo
items	array	requerido	Líneas de detalle — ver esquema de ítems
payment_form	string	opcional	1 contado (por defecto) · 2 crédito — ver catálogo
payment_method_code	string	opcional	10 efectivo · 20 tarjeta · 42 transferencia. Por defecto 10 — ver catálogo
payment_due_date	string	opcional	Fecha vencimiento YYYY-MM-DD (solo si payment_form=2)
observation	string	opcional	Observaciones de la factura
cost_center_id	integer	opcional	ID del centro de costo

Esquema de customer

Campo		Descripción
identification	requerido	NIT o cédula (sin DV)
dv	opcional	Dígito de verificación
company	opcional	Razón social
names	opcional	Nombre completo (personas naturales)
email	opcional	Correo electrónico
phone	opcional	Teléfono
address	opcional	Dirección
identification_document_id	opcional	13 cédula · 31 NIT · 41 pasaporte — ver catálogo
legal_organization_id	opcional	1 persona jurídica · 2 persona natural — ver catálogo
tribute_id	opcional	Responsabilidad fiscal DIAN (ej: 21=No responsable IVA) — ver catálogo
municipality_id	opcional	Código municipio DANE (ej: 11001=Bogotá) — ver catálogo

Ejemplo completo

curl -X POST https://pos.tekio.com.co/v1/invoices \
  -H "Authorization: Bearer 4f8a2b..." \
  -H "Content-Type: application/json" \
  -d '{
    "payment_form": "1",
    "payment_method_code": "10",
    "observation": "Pedido web #1024",
    "customer": {
      "identification": "901354671",
      "dv": "1",
      "company": "NEXO CONTABLE SAS",
      "email": "contacto@nexo.com",
      "phone": "3175751320",
      "address": "CALLE 60 B SUR 44 100",
      "identification_document_id": "31",
      "legal_organization_id": "1",
      "tribute_id": "21",
      "municipality_id": "05631"
    },
    "items": [
      {
        "code_reference": "1041",
        "name": "SERVICIO EN LA NUBE",
        "quantity": 1,
        "price": 500000,
        "tax_rate": "19.00",
        "discount_rate": 0,
        "unit_measure_id": 70,
        "withholding_taxes": [
          {"code": "06", "withholding_tax_rate": "15.00"}
        ]
      },
      {
        "code_reference": "1043",
        "name": "CAMISETA DE DOTACION",
        "quantity": 3,
        "price": 20000,
        "tax_rate": "0.00",
        "discount_rate": 0
      }
    ]
  }'

Respuesta 201 — Factura emitida

{
  "sale_id": 301,
  "customer_id": 42,
  "total": 619000.00,
  "numero_completo": "SETP990000001",
  "cufe": "abc123...",
  "items_created": 1,
  "dian": {
    "success": true,
    "cufe": "abc123...",
    "numero_completo": "SETP990000001",
    "message": "Documento procesado correctamente",
    "status_code": "00"
  }
}

items_created: número de productos que fueron creados automáticamente en el catálogo.

Respuesta 207 — Venta guardada, error DIAN

{
  "sale_id": 302,
  "customer_id": 42,
  "total": 619000.00,
  "items_created": 0,
  "dian": { "success": false, "message": "Error al conectar con la DIAN" }
}

Emite una nota crédito electrónica para una factura ya emitida a la DIAN.

Headers requeridos

Authorization: Bearer <access_token>
Content-Type: application/json

Parámetros (JSON)

Campo	Tipo		Descripción
sale_id	integer	requerido	ID de la venta con factura DIAN emitida
correction_concept_id	integer	opcional	1 Devolución · 2 Anulación (por defecto) · 3 Rebaja · 4 Ajuste
description	string	opcional	Motivo. Si se omite usa el texto por defecto del concepto

Ejemplo

curl -X POST https://pos.tekio.com.co/v1/credit-notes \
  -H "Authorization: Bearer 4f8a2b..." \
  -H "Content-Type: application/json" \
  -d '{
    "sale_id": 301,
    "correction_concept_id": 2,
    "description": "Error en el precio unitario"
  }'

Respuesta 201

{
  "success": true,
  "cufe": "xyz987...",
  "numero_completo": "NC990000001",
  "message": "Nota crédito emitida correctamente"
}

Respuesta

{
  "data": [
    { "id": "1", "name": "Contado" },
    { "id": "2", "name": "Crédito" }
  ]
}

Respuesta

{
  "data": [
    { "code": "10",  "name": "Efectivo" },
    { "code": "20",  "name": "Cheque" },
    { "code": "42",  "name": "Consignación / Transferencia bancaria" },
    { "code": "47",  "name": "Transferencia débito bancario" },
    { "code": "48",  "name": "Tarjeta de crédito" },
    { "code": "49",  "name": "Tarjeta débito" },
    { "code": "1",   "name": "Instrumento no definido" },
    { "code": "ZZZ", "name": "Otro" }
  ]
}

Respuesta

{
  "data": [
    { "id": "11", "name": "Registro civil" },
    { "id": "12", "name": "Tarjeta de identidad" },
    { "id": "13", "name": "Cédula de ciudadanía" },
    { "id": "21", "name": "Tarjeta de extranjería" },
    { "id": "22", "name": "Cédula de extranjería" },
    { "id": "31", "name": "NIT" },
    { "id": "41", "name": "Pasaporte" },
    { "id": "42", "name": "Documento de identificación extranjero" },
    { "id": "50", "name": "NIT de otro país" },
    { "id": "91", "name": "NUIP" }
  ]
}

Respuesta

{
  "data": [
    { "id": "1", "name": "Persona jurídica y asimiladas" },
    { "id": "2", "name": "Persona natural y asimiladas" }
  ]
}

Respuesta

{
  "data": [
    { "id": "01", "name": "IVA — Impuesto sobre las ventas" },
    { "id": "04", "name": "INC — Impuesto nacional al consumo" },
    { "id": "07", "name": "Retención en la fuente a título de renta" },
    { "id": "09", "name": "Retención en la fuente en IVA" },
    { "id": "11", "name": "Retención en la fuente en ICA" },
    { "id": "12", "name": "ICA — Impuesto de industria y comercio" },
    { "id": "21", "name": "No responsable de IVA (régimen simplificado)" },
    { "id": "22", "name": "Régimen simple de tributación — SIMPLE" },
    { "id": "23", "name": "Gran contribuyente" },
    { "id": "24", "name": "Autorretenedor" },
    { "id": "ZZ", "name": "No aplica" }
  ]
}

Respuesta

{
  "data": [
    { "rate": "0.00",  "name": "Excluido / Exento de IVA",   "tribute_id": "1" },
    { "rate": "5.00",  "name": "IVA 5%",                     "tribute_id": "1" },
    { "rate": "19.00", "name": "IVA 19% (tarifa general)",   "tribute_id": "1" },
    { "rate": "8.00",  "name": "INC 8% (bebidas azucaradas)","tribute_id": "4" }
  ]
}

Respuesta

{
  "data": [
    {
      "code": "01",
      "name": "ReteFuente — Retención en la fuente a título de renta",
      "base": "valor_neto_linea",
      "common_rates": ["1.50","2.50","3.50","4.00","6.00","11.00"]
    },
    {
      "code": "04",
      "name": "ReteICA — Retención de industria y comercio",
      "base": "valor_neto_linea",
      "common_rates": ["0.414","0.483","0.552","0.966","1.104"]
    },
    {
      "code": "06",
      "name": "ReteIVA — Retención del impuesto sobre las ventas",
      "base": "valor_iva_linea",
      "common_rates": ["15.00"]
    }
  ]
}

base indica sobre qué valor se calcula la retención: el valor neto de la línea o el valor de IVA de la línea.

Query params

Parámetro		Descripción
search	opcional	Filtra por nombre de municipio (ej: ?search=bogota)
department	opcional	Filtra por código de departamento DANE (ej: ?department=11)
limit	opcional	Máximo resultados. Por defecto 50, máximo 200

Ejemplo

GET https://pos.tekio.com.co/v1/catalogs/municipalities?search=bogota

Respuesta

{
  "total": 1,
  "data": [
    { "id": "11001", "name": "Bogota D.C.", "department": "Bogota D.C." }
  ],
  "note": "Usa ?search=nombre para filtrar. ?department=codigo para filtrar por departamento."
}