Autenticación

Toda petición (salvo /healthz) lleva la clave en la cabecera Authorization como Bearer token; la API requiere el plan Developer. Una clave está permanentemente ligada a un entorno (chk_test_… para Pruebas, chk_live_… para Real) y a los datos de ese entorno únicamente. Para comprobar que tu clave funciona, pide cualquier recurso, por ejemplo tus series: 200 si es válida, 401 si no (/healthz no mira la clave). Usa siempre https://www.chiklin.com: el dominio sin www redirige y la mayoría de clientes HTTP descartan la cabecera Authorization al seguir la redirección.

import requests

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

response = requests.get(
    f"{BASE_URL}/series",
    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. issue_date es opcional (por defecto, hoy en hora de Madrid); con una clave chk_live_ solo se admite la fecha de hoy. Si la operación se hizo otro día, indícalo en operation_date, que no puede ser posterior a issue_date. El cliente va como contact_id (uno existente) o como contact (objeto con los mismos campos que POST /clients, que lo da de alta); una Simplificada puede ir sin cliente; una Ordinaria (invoice_type por defecto) sin cliente responde 400. Opcionales: payment_method (TRANSFER, CASH, CARD, CHECK, DIRECT_DEBIT o NONE), payment_term_days (calcula el vencimiento) y, por línea, irpf_rate y surcharge_rate (recargo de equivalencia). Responde 201 con invoice_id e invoice_number. Por ahora, con una clave chk_live_ se responde 400 a una factura con alguna línea al 0 % de IVA o a un cliente con identificador extranjero (NIF-IVA, pasaporte…): el registro de VeriFactu todavía no sabe describir esas operaciones.

import requests, uuid

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

payload = {
    "series_id": "b3f1a2e0-4c1a-4e7a-9c1a-3f6a8e2d9c11",
    "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": "..." } (formato según la plantilla de la serie)

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. La rectificativa se numera en la serie de rectificativas del entorno (se crea si no existe), nunca en la de la factura original. Solo si esa rectificativa queda correctamente registrada, la original pasa a voided. rectification_reason (obligatorio, hasta 150 caracteres) se imprime en el PDF de la rectificativa.

import requests, uuid

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://www.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. Un NIF/CIF solo puede estar en un contacto por entorno: si ya existe (como cliente, proveedor o ambos) responde 409 con contact_id, el del contacto que ya lo tiene.

import requests

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://www.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 NIF/CIF solo puede estar en un contacto por entorno: si ya existe, aunque sea como cliente, responde 409 con contact_id. Un mismo contacto puede ser cliente y proveedor a la vez, pero ese segundo papel se le añade desde la app (Clientes o Proveedores).

import requests

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://www.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. Con "is_rectificativa": true crea una serie solo para rectificativas: la ley obliga a numerarlas en su propia serie, y en ella no se puede emitir ninguna otra factura. Sujeto al límite de series de tu plan, que cuenta aparte las de rectificativas.

import requests

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://www.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

La plantilla queda congelada al entorno de la clave y necesita una serie normal (no de rectificativas). frequency: weekly, monthly, quarterly o yearly. Si no envías next_run_date se calcula a partir de la frecuencia. Opcionales: end_date, max_occurrences, payment_method y payment_term_days.

import requests

API_KEY = "chk_test_xxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://www.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

total_gross_amount es la base imponible (sin IVA); el IVA, la retención y el total se calculan con tax_rate e irpf_rate. provider_id es opcional (un proveedor del mismo entorno). Otros campos opcionales: description, invoice_number (el número de la factura del proveedor), category e is_iva_deductible (por defecto true). 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://www.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://www.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())