API

La API v1 permite registrar documentos en Amable Conti desde otros sistemas. Cada solicitud utiliza las mismas validaciones contables, fiscales y de permisos que la interfaz web.

El flujo habitual de una integración es:

1. Crear una clave de API y seleccionar las empresas y acciones permitidas.
2. Consultar los catálogos para obtener los IDs requeridos.
3. Enviar el documento al endpoint correspondiente.
4. Procesar la respuesta o corregir los errores informados.

Primeros pasos

URL base

Todas las rutas de esta guía parten de una empresa autorizada:

https://www.amableconti.com/api/v1/empresas/{empresaId}

Las solicitudes que incluyen un cuerpo deben usar Content-Type: application/json.

Autenticación

1. Abre Configuración > Claves de API (/configuracion/api-keys).
2. Crea una clave y selecciona al menos una empresa, las acciones permitidas y un vencimiento: 30 días, 90 días, 1 año o sin vencimiento.
3. Guarda la clave cuando se muestre. La clave completa solo aparece una vez.
4. Usa el ID de una empresa autorizada en la URL y envía la clave en la cabecera x-api-key de cada solicitud.

curl 'https://www.amableconti.com/api/v1/empresas/123/cuentas' \
  -H 'x-api-key: ac_live_REEMPLAZAR'

Cada clave admite un subconjunto de las empresas y permisos de su propietario. Solo puedes delegar permisos que ya posees. Una solicitud se autoriza si la empresa indicada pertenece a la clave y tanto la clave como su propietario conservan el permiso requerido.

La selección de cada empresa conserva el ejercicio que estaba activo al configurar la clave. Para cambiar empresas, ejercicios vinculados o permisos, edita la clave desde Configuración > Claves de API. Revocar desactiva inmediatamente las nuevas operaciones.

Guarda la clave ac_live_… en un gestor de secretos o una variable de entorno del servidor. No la incluyas en repositorios, registros, capturas ni código que se ejecute en el navegador. Si se expone, revócala y crea otra.

Cada clave admite hasta 120 solicitudes por minuto.

Ante un 429, espera antes de reintentar y aplica una pausa incremental. No repitas una creación sin determinar primero si la solicitud anterior alcanzó a completarse, porque la API no ofrece una clave de idempotencia general.

Referencia rápida

Crear documentos

La ruta determina el tipoDocumento; no debes enviarlo en el cuerpo.

Consultar catálogos

Todos los catálogos responden con la forma { "data": [...] }. Por ejemplo, GET /api/v1/empresas/123/cuentas puede devolver:

{
  "data": [
    {
      "id": 120,
      "codigo": "1-1-2-01",
      "nombre": "Clientes",
      "naturaleza": "activo",
      "type": "Regular",
      "monedaId": null,
      "auxiliar": false,
      "centroCosto": false
    }
  ]
}

Convenciones de datos

Fechas

Envía las fechas como cadenas ISO 8601 con zona horaria:

2026-08-20T10:00:00-04:00

Montos

Envía los montos como números o cadenas con un máximo de dos decimales. La API reconoce automáticamente el punto o la coma decimal y los separadores de miles: 1000.01, "1000.01", "1.000,01" y "1,000.01" representan el mismo monto.

IDs y datos calculados

• Los IDs de auxiliares, cuentas, métodos de pago y demás referencias deben existir en la empresa asociada a la clave.
• No envíes ivaId ni impuestoMonedaId. Amable Conti infiere la alícuota vigente a partir de fechaDocumento, base y el total del impuesto.
• No envíes monedas ni registroMoneda. En los comprobantes, Amable Conti calcula los importes de todas las monedas operativas usando fecha y la configuración de la empresa.

Auxiliares

El tipo de auxiliar debe corresponder con el documento:

Permisos

Para crear un documento Aprobado, el propietario de la clave necesita permiso de creación en documentos aprobados. Para crear un Borrador, necesita el permiso equivalente de borradores.

Campos compartidos

Las ventas, compras, reportes Z y notas comparten los siguientes campos:

Asiento detallado

Ventas, compras y reportes Z admiten contabilización inmediata detallada. Envía contabilizacion: "InmediataDetallada" y una o más líneas en metodosPago. Cada metodoPagoId se obtiene de GET /api/v1/empresas/{empresaId}/metodos-pago y debe corresponder al origen del documento, venta o compra.

En ventas y reportes Z, la suma de metodosPago[].monto debe ser igual al total del documento, incluido el IGTF y descontadas las retenciones incluidas. En compras, debe ser igual a la suma de las bases de las líneas de IVA. Amable Conti genera las líneas fiscales y la contrapartida en cuentaAcreedoraId. Por ejemplo, una venta con total 116.00 puede incluir este fragmento:

{
  "contabilizar": true,
  "contabilizacion": "InmediataDetallada",
  "cuentaAcreedoraId": 450,
  "metodosPago": [
    {
      "metodoPagoId": 12,
      "monto": "70.00",
      "referencia": "TRANSFERENCIA-1042"
    },
    {
      "metodoPagoId": 15,
      "monto": "46.00",
      "centroCostoId": 8
    }
  ]
}

No envíes cuentaDeudoraId para sustituir las líneas detalladas. Esa cuenta pertenece al flujo Inmediata; en InmediataDetallada, las cuentas deudoras provienen de los métodos de registro.

IVA

Cada elemento de iva incluye la base imponible, el IVA y el total correspondiente:

{
  "base": "100.00",
  "totalIva": "16.00",
  "total": "116.00"
}

IGTF

El objeto impuestoMoneda es opcional y permite registrar IGTF:

{
  "base": "116.00",
  "totalImpuesto": "3.48",
  "total": "119.48"
}

Comprobantes

Crear un comprobante manual

POST /api/v1/empresas/{empresaId}/comprobantes

Este endpoint solo crea comprobantes de origen Manual en el período vinculado a la clave. No admite origen ni registroId. El número es opcional; si se omite, Amable Conti genera uno.

Cada elemento de registros admite:

Un comprobante Aprobado debe balancear Debe y Haber. Las cuentas de orden se balancean por separado.

En este ejemplo se usa el formato decimal con coma:

{
  "numero": "42",
  "fecha": "2026-08-20T10:00:00-04:00",
  "descripcion": "Venta sector privado",
  "estatus": "Aprobado",
  "registros": [
    {
      "cuentaId": 120,
      "descripcion": "Clientes",
      "debe": "10.000,00"
    },
    {
      "cuentaId": 450,
      "descripcion": "Ventas sector privado",
      "haber": "10.000,00"
    }
  ]
}

Ventas

Crear una venta

POST /api/v1/empresas/{empresaId}/ventas

Además de los campos compartidos, una venta admite:

Ejemplo de borrador sin contabilización:

{
  "auxiliarId": 125,
  "fechaDocumento": "2026-08-20T10:00:00-04:00",
  "fechaValidez": "2026-08-20T10:00:00-04:00",
  "estatus": "Borrador",
  "tipoTransaccion": "Registro",
  "numeroControl": "00-000123",
  "numeroDocumento": "4580",
  "contabilizar": false,
  "iva": [
    {
      "base": "100.00",
      "totalIva": "16.00",
      "total": "116.00"
    }
  ]
}

Compras

Crear una compra

POST /api/v1/empresas/{empresaId}/compras

Además de los campos compartidos, una compra admite:

{
  "auxiliarId": 210,
  "fechaDocumento": "2026-08-20T10:00:00-04:00",
  "fechaValidez": "2026-08-20T10:00:00-04:00",
  "estatus": "Borrador",
  "tipoTransaccion": "Registro",
  "numeroDocumentoCompra": "FAC-9001",
  "numeroControl": "00-000900",
  "serieString": "A",
  "creditoFiscal": "Deducible",
  "tipoCompra": "Interna",
  "contabilizar": false,
  "contabilizacion": "Inmediata",
  "iva": [
    {
      "base": "100.00",
      "totalIva": "16.00",
      "total": "116.00"
    }
  ]
}

Reportes Z

Crear un reporte Z

POST /api/v1/empresas/{empresaId}/reportes-z

Además de los campos compartidos, un reporte Z admite:

{
  "auxiliarId": 340,
  "fechaDocumento": "2026-08-20T23:00:00-04:00",
  "fechaValidez": "2026-08-20T23:00:00-04:00",
  "estatus": "Borrador",
  "tipoTransaccion": "Registro",
  "numeroReporteZ": "000154",
  "numeroPrimeraFactura": "1000",
  "numeroUltimaFactura": "1025",
  "cantidadDeFacturas": "26",
  "contabilizar": false,
  "iva": [
    {
      "base": "2,500.00",
      "totalIva": "400.00",
      "total": "2,900.00"
    }
  ]
}

Notas de crédito y débito

Crear una nota

• POST /api/v1/empresas/{empresaId}/notas-credito
• POST /api/v1/empresas/{empresaId}/notas-debito

Ambas rutas requieren los campos compartidos y los siguientes campos:

Una nota no puede tener una fecha anterior a la del documento afectado. Una nota de crédito tampoco puede exceder el saldo disponible del documento original.

Nota con origen en venta

Envía los campos de una venta y usa numeroDocumento como número de la nota:

{
  "origen": "venta",
  "documentoAfectadoId": 8001,
  "auxiliarId": 125,
  "fechaDocumento": "2026-08-21T10:00:00-04:00",
  "fechaValidez": "2026-08-21T10:00:00-04:00",
  "estatus": "Borrador",
  "tipoTransaccion": "Registro",
  "numeroControl": "00-000124",
  "numeroDocumento": "81",
  "contabilizar": false,
  "iva": [
    {
      "base": "10.00",
      "totalIva": "1.60",
      "total": "11.60"
    }
  ]
}

Nota con origen en compra

Envía los campos de una compra y usa numeroDocumentoCompra como número de la nota:

{
  "origen": "compra",
  "documentoAfectadoId": 8100,
  "auxiliarId": 210,
  "fechaDocumento": "2026-08-21T10:00:00-04:00",
  "fechaValidez": "2026-08-21T10:00:00-04:00",
  "estatus": "Borrador",
  "tipoTransaccion": "Registro",
  "numeroDocumentoCompra": "NC-44",
  "numeroControl": "00-000901",
  "creditoFiscal": "Deducible",
  "tipoCompra": "Interna",
  "contabilizar": false,
  "contabilizacion": "Inmediata",
  "iva": [
    {
      "base": "10.00",
      "totalIva": "1.60",
      "total": "11.60"
    }
  ]
}

Respuestas

Creación exitosa

Una creación exitosa responde con 201 Created.

Para ventas, compras, reportes Z y notas, la respuesta tiene esta forma:

{
  "id": 9120,
  "origen": "venta",
  "tipoDocumento": "Factura"
}

Para un comprobante manual:

{
  "id": 9121,
  "origen": "Manual",
  "tipoDocumento": "Comprobante"
}

Errores

Ejemplo de un error de validación:

{
  "code": "VALIDATION_ERROR",
  "error": "El cuerpo de la solicitud no es válido.",
  "details": {
    "fechaDocumento": {
      "_errors": ["Invalid input"]
    }
  }
}