Autenticación

Toda petición (salvo /healthz) lleva la clave en la cabecera Authorization como Bearer token. Una clave está permanentemente ligada a un entorno (chk_test_… para Pruebas, chk_live_… para Real) y a los datos de ese entorno únicamente.

import requests

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://chiklin.com/api/v1"

response = requests.get(
    f"{BASE_URL}/healthz",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
print(response.status_code, response.json())

Crear una factura

Emite una factura Ordinaria o Simplificada: calcula IVA/IRPF, numera correlativamente por serie y la registra en VeriFactu. Añade una cabecera Idempotency-Key (un UUID por intento lógico) para que un reintento de red no emita una segunda factura.

import requests, uuid

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://chiklin.com/api/v1"

payload = {
    "series_id": "b3f1a2e0-4c1a-4e7a-9c1a-3f6a8e2d9c11",
    "issue_date": "2026-07-27",
    "invoice_type": "STANDARD",
    "contact_id": "9d2f1a3b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
    "items": [
        {"description": "Desarrollo web - Sprint 3", "quantity": 1, "unit_price": 1500.00, "tax_rate": 21, "irpf_rate": 15}
    ],
}

response = requests.post(
    f"{BASE_URL}/invoices",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json=payload,
)
response.raise_for_status()
print(response.json())  # { "invoice_id": "...", "invoice_number": "2026/0001" }

Anular una factura

No borra ni marca un flag: emite una factura rectificativa (R4/R5 según AEAT) que invierte el signo de cada línea y la registra en VeriFactu. Solo si esa rectificativa queda correctamente registrada, la original pasa a voided.

import requests, uuid

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://chiklin.com/api/v1"
invoice_id = "3a1b2c3d-4e5f-6789-abcd-ef0123456789"

response = requests.post(
    f"{BASE_URL}/invoices/{invoice_id}/void",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"rectification_reason": "Error en el importe de la línea 2"},
)
response.raise_for_status()
print(response.json())  # { "original_invoice_id", "corrective_invoice_id", "corrective_invoice_number" }

Crear un cliente

Da de alta un contacto como cliente (is_customer=true). Valida el NIF/CIF según el país antes de guardarlo.

import requests

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://chiklin.com/api/v1"

payload = {
    "person_type_code": "J",
    "tax_identification_number": "B12345674",
    "corporate_name": "Acme Soluciones SL",
    "address": "Calle Mayor 1",
    "post_code": "28001",
    "town": "Madrid",
    "province": "Madrid",
    "email": "facturacion@acme.es",
}

response = requests.post(f"{BASE_URL}/clients", headers={"Authorization": f"Bearer {API_KEY}"}, json=payload)
response.raise_for_status()
print(response.json())

Crear un proveedor

Igual que /clients pero marca is_provider=true (is_customer queda a false). Un mismo NIF puede existir a la vez como cliente y como proveedor en dos contactos distintos.

import requests

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://chiklin.com/api/v1"

payload = {
    "person_type_code": "F",
    "tax_identification_number": "12345678Z",
    "first_name": "Laura",
    "first_surname": "Gomez",
    "address": "Av. Diagonal 200",
    "post_code": "08018",
    "town": "Barcelona",
    "province": "Barcelona",
}

response = requests.post(f"{BASE_URL}/suppliers", headers={"Authorization": f"Bearer {API_KEY}"}, json=payload)
response.raise_for_status()
print(response.json())

Crear una serie de facturación

El prefijo debe ser único dentro del entorno de la clave. Sujeto al límite de series de tu plan.

import requests

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://chiklin.com/api/v1"

payload = {"name": "Serie B", "prefix": "B-2026"}

response = requests.post(f"{BASE_URL}/series", headers={"Authorization": f"Bearer {API_KEY}"}, json=payload)
response.raise_for_status()
print(response.json())

Crear una plantilla recurrente

Requiere plan Pro o Developer. La plantilla queda congelada al entorno de la clave; si no envías next_run_date se calcula a partir de la frecuencia.

import requests

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://chiklin.com/api/v1"

payload = {
    "series_id": "b3f1a2e0-4c1a-4e7a-9c1a-3f6a8e2d9c11",
    "contact_id": "9d2f1a3b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
    "frequency": "monthly",
    "items": [
        {"description": "Mantenimiento mensual", "quantity": 1, "unit_price": 250.00, "tax_rate": 21, "irpf_rate": 15}
    ],
}

response = requests.post(f"{BASE_URL}/recurring-invoices", headers={"Authorization": f"Bearer {API_KEY}"}, json=payload)
response.raise_for_status()
print(response.json())

Registrar un gasto

Un ticket (document_type: RECEIPT) nunca es deducible de IVA aunque envíes is_iva_deductible: true — el servidor lo fuerza a false.

import requests

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://chiklin.com/api/v1"

payload = {
    "provider_id": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d",
    "expense_date": "2026-07-20",
    "document_type": "INVOICE",
    "total_gross_amount": 500.00,
    "tax_rate": 21,
    "irpf_rate": 15,
    "category": "Suministros",
}

response = requests.post(f"{BASE_URL}/expenses", headers={"Authorization": f"Bearer {API_KEY}"}, json=payload)
response.raise_for_status()
print(response.json())

Crear un producto/servicio

Alta simple en el catálogo. El producto nace activo y en el entorno de la clave usada.

import requests

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://chiklin.com/api/v1"

payload = {"name": "Hora de consultoria", "unit_price": 60.00, "tax_rate": 21}

response = requests.post(f"{BASE_URL}/products", headers={"Authorization": f"Bearer {API_KEY}"}, json=payload)
response.raise_for_status()
print(response.json())