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 alcancesync, 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ódigo | Significa | Qué hacer |
|---|---|---|
| 201 | Lote aceptado | Guardar el resultado y avanzar |
200 replayed | El mismo lote ya había entrado | Tratarlo como éxito |
| 409 | La misma Idempotency-Key con otro contenido | Revisar tu llave de idempotencia: no es un éxito |
| 422 | Lote inválido: no se guardó nada (todo o nada) | Corregir con la lista de errores por renglón |
| 401 / 403 | Llave inválida, sin alcance o IP no permitida | Detenerse y revisar la llave |
| 402 | Módulo API-SYNC no contratado | Detenerse y avisar |
| 429 | Demasiadas llamadas | Esperar lo que diga Retry-After y reintentar |
| 5xx | Falla temporal del servidor | Reintentar 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.
