Para desarrolladores y apps
contix como backend de facturación: tu app pone la pantalla, contix emite la factura
Si tu aplicación o tu asistente de IA necesita que sus usuarios emitan facturas en España, no tienes que construir la numeración, la huella encadenada ni el PDF. Tu app crea una cuenta de contix para cada usuario y llama a la API; contix numera, encadena, genera el PDF y, si la cuenta lo activa, registra la factura en la AEAT. Tu usuario sigue en tu app.
Cómo encaja
- Una cuenta de contix por usuario de tu app. Cada una con su NIF, su numeración y su cadena de huellas. Las facturas de un usuario nunca se mezclan con las de otro.
- Dos tipos de clave. La clave de socio es tuya, vive en tu servidor y solo sirve para crear cuentas y rotar sus claves. Cada cuenta tiene además su propia API-Key (
cx_live_…) para facturar. - contix no aparece ante tu usuario. La cuenta nace con el onboarding hecho, sin correo de bienvenida y sin marca de contix en el PDF.
- Mismo motor que el panel. Una factura creada por API es igual que una creada en el navegador; el resto de la API está en la referencia.
1. La clave de socio
Se envía en la cabecera X-Partner-Key y solo en las llamadas a /api/v1/partner/…. Nunca va en el navegador de tu usuario. Cada socio tiene la suya; con ella solo ves y gestionas las cuentas que has creado tú. Se pide por correo (ver Cómo empezar).
PARTNER_KEY=la-clave-que-te-damos
curl -s -o /dev/null -w "%{http_code}\n" -X POST https://api.contix.es/api/v1/partner/cuentas \
-H "X-Partner-Key: $CLAVE_ERRONEA" -H "Content-Type: application/json" -d '{}'
# → 401 (con tu clave y un cuerpo vacío: 422, la clave es válida)2. Crear la cuenta de un usuario
external_ref es un UUID tuyo para ese usuario: sirve de idempotencia. tipo es autonomo o empresa (con empresa hay que enviar company_name). El NIF se valida con su dígito de control. disclaimer_accepted: true confirma que tu usuario aceptó, en tu app, las condiciones que acordemos contigo; el nombre del documento va en disclaimer_ref.
curl -X POST https://api.contix.es/api/v1/partner/cuentas \
-H "X-Partner-Key: $PARTNER_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "ana@ejemplo.com",
"external_ref": "7c1f6c0e-5a52-4d0e-9a53-0d8c2a6f4b11",
"tipo": "autonomo",
"nif": "12345678Z",
"first_name": "Ana",
"last_name": "Prueba",
"address_line1": "Calle Mayor 1",
"postal_code": "28013",
"city": "Madrid",
"province": "Madrid",
"disclaimer_accepted": true,
"disclaimer_ref": "condiciones-2026-11"
}'
# → 201 {"tenant_id": 84, "api_key": "cx_live_…"}La api_key aparece solo en esta respuesta y contix no puede volver a mostrarla: guárdala cifrada en tu lado. Opcionales: invoice_prefix (serie, por defecto F), start_number (para continuar una numeración que ya llevabas), phone.
3. Cliente, factura y finalizar
A partir de aquí todo va con la API-Key de esa cuenta (Authorization: Bearer cx_live_…). Primero el cliente de tu usuario:
curl -X POST https://api.contix.es/api/v1/customers \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"contact_name": "Empresa Ejemplo SL", "company_name": "Empresa Ejemplo SL",
"country": "ES", "nif": "B84645654", "email": "facturas@ejemplo.es"}'
# → 200 {"id": 811, "nif": "B84645654", "nif_aviso": null, …}Si el NIF y el nombre no coinciden con el censo de la AEAT, nif_aviso trae el aviso y el nombre del censo; el cliente se guarda igualmente. Después la factura como borrador:
curl -X POST https://api.contix.es/api/v1/invoices \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{
"customer_id": 811,
"external_id": "pedido-10492",
"invoice_type": "standard",
"tax_rate": 21,
"retention_rate": 0,
"items": [{
"description": "Desarrollo web, noviembre",
"quantity": 1, "unit_price": "900",
"calificacion_operacion": "S1", "impuesto": "01"
}]
}'
# → 201 {"id": 7502, "status": "draft", "invoice_number": null,
# "subtotal": 900.0, "tax_amount": 189.0, "total": 1089.0, …}Los tipos, retenciones y calificaciones los pones tú según tu usuario y su gestoría; contix no los propone. Un borrador se puede editar o borrar y no consume número. Para emitirla:
curl -X POST https://api.contix.es/api/v1/invoices/7502/finalize \
-H "Authorization: Bearer $KEY"
# → 200 {"message": "Invoice finalized successfully",
# "invoice_number": "F-2026-0001",
# "current_hash": "558768…e4005", "previous_hash": null,
# "hash_timestamp": "2026-11-19T20:01:17", "aeat": null}Aquí se asigna el número correlativo y se encadena la huella con la factura anterior de esa cuenta. Finalizar es irreversible: la factura queda inmutable y solo se corrige con una rectificativa. external_id es opcional pero recomendable: una factura por cada pedido tuyo.
4. PDF y consulta
curl -o factura.pdf https://api.contix.es/api/v1/invoices/7502/pdf \
-H "Authorization: Bearer $KEY"
# → 200 application/pdf
curl https://api.contix.es/api/v1/invoices/7502 -H "Authorization: Bearer $KEY"
# estado, número, huella, estado del envío a la AEAT (aeat_submission_status), …También puedes pedir que contix envíe la factura por correo al cliente (POST /api/v1/invoices/{id}/send-email), o descargar el PDF y enviarla tú desde tu app: las dos vías usan los mismos datos. Los cobros se registran con POST /api/v1/invoices/{id}/record-payment, y las rectificativas y anulaciones están en la referencia.
Errores y casos límite
Las respuestas de error de /partner traen siempre un code estable:
401: clave de socio incorrecta o ausente. Si no hay ninguna clave configurada para tu entorno, la ruta responde404, como si no existiera.409 existe: ya hay una cuenta con eseexternal_ref; trae sutenant_id. Para recuperar el acceso, rota la clave (abajo).409 email_existe: ese correo ya pertenece a otra cuenta de contix. No se crea ni se enlaza nada; escríbenos y lo resolvemos con el usuario.409 nif_existe: ese NIF ya tiene cuenta. Igual que el anterior.422 nif_invalido: el NIF no supera la validación (letra o dígito de control). Traecampoymensaje.422 falta_campoy422 disclaimer: faltacompany_nameen una empresa, odisclaimer_acceptedno estrue.
En la API de facturación:
409al crear una factura con unexternal_idrepetido: traeinvoice_ideinvoice_numberde la que ya existe. Tu reintento no duplica nada: usa ese id.finalizesobre una factura ya finalizada yPUTsobre una finalizada devuelven error con el motivo; la corrección es una rectificativa.422 nif_no_identificadoal finalizar: el NIF y el nombre del cliente no figuran en el censo de la AEAT. No se gasta número; corrige el cliente y vuelve a finalizar.422 verifactu_requeridoal finalizar: desde la fecha en que Veri*factu es obligatorio para el tipo de cuenta (1 de enero de 2027 sociedades, 1 de julio de 2027 las demás, según el BOE vigente), una cuenta sin envío real a la AEAT no emite. No se gasta número; activa el envío y vuelve a finalizar.401con una API-Key revocada o rotada.
Perdí la clave de una cuenta
curl -X POST https://api.contix.es/api/v1/partner/cuentas/84/clave \
-H "X-Partner-Key: $PARTNER_KEY"
# → 200 {"tenant_id": 84, "api_key": "cx_live_…"} (las claves anteriores quedan revocadas)Solo funciona con cuentas que creaste tú; con las demás responde 404.
Veri*factu y la AEAT: qué pasa hoy
Una cuenta recién creada por la API numera, encadena la huella y genera el PDF, pero no envía nada a la AEAT (aeat: null en la respuesta de finalizar). El envío se activa por cuenta, con el certificado de ese usuario:
curl https://api.contix.es/api/v1/verifactu/settings -H "Authorization: Bearer $KEY"
# → {"submission_mode": "none", "environment": "test", "has_certificate": false,
# "production_allowed": false, …}
# subir el certificado .p12 del usuario (multipart) y activar el modo:
curl -X POST https://api.contix.es/api/v1/verifactu/settings/certificate \
-H "Authorization: Bearer $KEY" -F "file=@certificado.p12" -F "password=…"
curl -X PUT https://api.contix.es/api/v1/verifactu/settings/mode \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"submission_mode": "verifactu", "environment": "test"}'Sin certificado, el cambio de modo responde 400. Hoy el modo verifactu funciona contra el entorno de pruebas de la AEAT; el envío en real se habilita cuenta por cuenta (production_allowed) y se acuerda con nosotros antes de la primera factura real de un usuario. Desde la fecha de obligatoriedad, una cuenta sin envío real no emite (422 verifactu_requerido, sin gastar número).
contix es una herramienta para emitir facturas, no asesoría fiscal: qué datos y qué tipos se aplican a cada factura lo decide tu usuario con su gestoría.
Por MCP desde un asistente de IA
La API-Key de cada cuenta sirve también para el servidor MCP (https://api.contix.es/api/v1/mcp, cabecera Authorization: Bearer): create_customer, create_invoice, finalize_invoice, record_payment y el resto. Si tu producto es un asistente, crea la cuenta por /partner/cuentas y deja que el asistente use esas herramientas con la clave de su usuario.
Límites
- 120 peticiones por minuto por API-Key.
- Una cuenta por NIF y por correo. No hay borrado de cuentas por API.
- La clave de socio solo crea cuentas y rota claves: no lee facturas ni datos de las cuentas.
- Exportación completa de datos, borrado de cuenta y suscripción: solo desde el panel de la cuenta.
Cómo empezar
Escríbenos con una línea sobre tu app y el nombre del socio (de 2 a 13 caracteres, minúsculas, cifras y guiones). Te enviamos la clave de socio y acordamos las condiciones. Las cuentas que crees con ella no envían nada a la AEAT hasta que su usuario suba un certificado y active el modo, así que puedes probar todo el recorrido con datos ficticios.
Pedir la clave de socio