Kosmos Tek
← Blog

Para programadores: la API de KOSMOS desde cualquier lenguaje (7 ejemplos probados)

La API v1 de KOSMOS Impuestos es REST con JSON sobre HTTPS. Eso significa que cualquier lenguaje que pueda hacer una petición HTTPS puede integrarse: desde Python o C# hasta ABAP, X++, AL, ABL de OpenEdge o Power Query de Excel.

Aquí tienes el mismo ejemplo en siete lenguajes. Los siete se ejecutaron contra un portal simulado antes de publicarlos.

1. Lo que necesitas

  • Una llave kha_… con alcance sync, creada en el portal en Seguridad > Llaves de la API. Guárdala en una variable de entorno, nunca en el código.
  • El módulo API-SYNC contratado por el despacho o la empresa. Sin él, el portal responde 402.
  • La guía pública: portal.kosmostek.net/api/v1/docs. El formato exacto de cada tipo de lote está en GET /api/v1/sync/schema.

2. El lote

Un lote de pólizas del mes: catálogo con "kind": "accounts" y pólizas con "kind": "entries". Cada póliza tiene número, fecha, tipo (I, E o D), descripción de al menos 5 caracteres y al menos dos partidas cuadradas.

lote.json

{"rfc": "XAXX010101000", "kind": "entries", "year": 2026, "month": 3,
 "items": [{"number": 1, "date": "2026-03-15", "type": "I",
            "description": "Venta de contado a cliente nacional",
            "lines": [{"account": "102.01", "debit": 1160},
                      {"account": "401.01", "credit": 1000},
                      {"account": "208.01", "credit": 160}]}]}

3. Primero valida: POST /api/v1/sync/validate

Revisa el lote completo y no guarda nada. Úsalo siempre antes de enviar.

Python (requests)

import json, os, requests

lote = json.load(open("lote.json", encoding="utf-8"))
r = requests.post("https://portal.kosmostek.net/api/v1/sync/validate",
                  headers={"Authorization": "Bearer " + os.environ["KOSMOS_API_KEY"]},
                  json=lote, timeout=60)
print(r.status_code, r.json())

JavaScript (Node 18 o posterior)

import { readFile } from "node:fs/promises";

const lote = JSON.parse(await readFile("lote.json", "utf8"));
const r = await fetch("https://portal.kosmostek.net/api/v1/sync/validate", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.KOSMOS_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify(lote),
});
console.log(r.status, await r.json());

C# (.NET 8)

using System.Net.Http.Headers;
using System.Text;

var lote = await File.ReadAllTextAsync("lote.json");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KOSMOS_API_KEY"));
var res = await http.PostAsync("https://portal.kosmostek.net/api/v1/sync/validate",
    new StringContent(lote, Encoding.UTF8, "application/json"));
Console.WriteLine($"{(int)res.StatusCode} {await res.Content.ReadAsStringAsync()}");

Java 11 o posterior

import java.net.URI;
import java.net.http.*;
import java.nio.file.*;

public class Ejemplo {
  public static void main(String[] args) throws Exception {
    String lote = Files.readString(Path.of("lote.json"));
    HttpRequest req = HttpRequest.newBuilder(URI.create("https://portal.kosmostek.net/api/v1/sync/validate"))
        .header("Authorization", "Bearer " + System.getenv("KOSMOS_API_KEY"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(lote))
        .build();
    HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(res.statusCode() + " " + res.body());
  }
}

Go

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	lote, _ := os.ReadFile("lote.json")
	req, _ := http.NewRequest("POST", "https://portal.kosmostek.net/api/v1/sync/validate", bytes.NewReader(lote))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KOSMOS_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(body))
}

PHP (cURL)

<?php
$lote = file_get_contents("lote.json");
$ch = curl_init("https://portal.kosmostek.net/api/v1/sync/validate");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("KOSMOS_API_KEY"), "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => $lote,
]);
$respuesta = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE) . " " . $respuesta . "\n";

Ruby

require "net/http"
require "json"

uri = URI("https://portal.kosmostek.net/api/v1/sync/validate")
req = Net::HTTP::Post.new(uri, "Authorization" => "Bearer #{ENV['KOSMOS_API_KEY']}", "Content-Type" => "application/json")
req.body = File.read("lote.json")
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
puts "#{res.code} #{res.body}"

4. Después envía: POST /api/v1/sync/batches

Es la misma petición, a la ruta /sync/batches, con el encabezado Idempotency-Key (hasta 120 caracteres). Usa una llave estable por lote, por ejemplo un SHA-256 de su contenido. Si repites el envío por una caída de red, el portal no duplica nada.

5. Las respuestas que debes manejar

CódigoSignificaQué hacer
201Lote aceptadoGuardar el resultado y avanzar
200 replayedEl mismo lote ya había entradoTratarlo como éxito
409La misma Idempotency-Key con otro contenidoRevisar tu llave de idempotencia: no es un éxito
422Lote inválido: no se guardó nada (todo o nada)Corregir con la lista de errores por renglón
401 / 403Llave inválida, sin alcance o IP no permitidaDetenerse y revisar la llave
402Módulo API-SYNC no contratadoDetenerse y avisar
429Demasiadas llamadasEsperar lo que diga Retry-After y reintentar
5xxFalla temporal del servidorReintentar con espera creciente

6. Límites

  • 120 llamadas por minuto por llave.
  • Hasta 64 MB por lote, 20,000 pólizas y 250,000 partidas.
  • Con mode=replace, el envío de un mes reemplaza lo que la API mandó antes para ese mes. Lo subido a mano por el portal no se toca.
¿Tu sistema es Business Central, Odoo, SAP Business One u OpenEdge? No tienes que programar: ya tenemos conectores en pruebas. Para los demás, esta API es el camino. Escríbenos si quieres que revisemos tu integración.