Introducción

Descripción general

Nuestra API proporciona una interfaz RESTful para interactuar con nuestros servicios. Todos los endpoints devuelven respuestas JSON y soportan métodos HTTP estándar.

URL Base

Todas las solicitudes a la API deben realizarse a:

Características Principales

• Diseño RESTful - Estructura de URLs limpia y predecible
• Respuestas JSON - Todas las respuestas están en formato JSON
• Autenticación - Soporte seguro para API key
• Límites de Uso - Políticas de uso justo con límites claros
• Idempotencia - Reintenta solicitudes POST sin duplicar registros
• Modo de prueba - Timbra CFDI y complementos de pago de prueba sin validez fiscal

Primeros pasos

1. Crea una API key - En la aplicación, abre Equipo y ve a Desarrolladores → API keys
2. Haz tu primera solicitud - Verifica tu API key con Consultar API key
3. Explora las APIs - Consulta nuestra referencia completa de la API

Autenticación

Envía tu API key en el header Authorization de cada solicitud. Las API keys empiezan con cdx_ y pertenecen a la organización, no a una persona. La API key completa solo se muestra una vez, al crearla.

Authorization: Bearer TU_API_KEY

Permisos

Al crear una API key eliges Acceso total o Permisos seleccionados. Con permisos seleccionados, cada recurso tiene uno de estos niveles, y cada nivel incluye a los anteriores:

Una API key nunca puede tener más permisos que el rol de quien la crea. Cada endpoint indica el permiso que requiere; si la API key no lo tiene, la API responde 403 con el código INSUFFICIENT_PERMISSIONS.

Cuando una acción hecha con una API key aparece en la actividad de la organización, se muestra con el nombre de la API key.

Límites de Uso

Cada API key puede hacer 600 solicitudes por minuto. La ventana empieza con la primera solicitud y termina 60 segundos después. Cada respuesta incluye estos headers:

Al superar el límite, la API responde 429 con el código RATE_LIMITED y el header retry-after con los segundos que debes esperar.

Idempotencia

Las solicitudes POST aceptan el header opcional Idempotency-Key (máximo 255 caracteres). Si repites una solicitud exitosa con la misma llave, la API devuelve la respuesta original sin volver a ejecutarla, con el header idempotent-replayed: true. Las llaves se guardan 24 horas.

Idempotency-Key: 5f7c1d2e-alta-cliente

Si la solicitud responde con un error, la llave se libera y puedes reintentarla con la misma llave.

Errores

Los errores usan status HTTP estándar y siempre tienen la misma forma. code es un identificador estable en inglés para que tu sistema tome decisiones; message es una descripción en español. Cada respuesta incluye el header x-request-id con el mismo valor que request_id.

{
  "code": "VALIDATION_ERROR",
  "message": "...",
  "errors": [
    {
      "field": "name",
      "code": "...",
      "message": "..."
    }
  ],
  "request_id": "..."
}

Paginación

Los endpoints que listan registros devuelven 20 resultados por página. Usa el query param page (empieza en 1) para navegar; next y previous son las URLs completas de la página siguiente y la anterior.

{
  "count": 42,
  "page": 1,
  "page_size": 20,
  "total_pages": 3,
  "next": ".../api/v1/customers?page=2",
  "previous": null,
  "results": []
}

Formato de datos

• Los nombres de los campos van en snake_case.
• Los IDs son cadenas de texto; las órdenes de cobro también tienen invoice_number.
• Los montos se envían y devuelven como cadenas de texto: "1160.00".
• Las fechas usan YYYY-MM-DD y las marcas de tiempo ISO 8601.
• POST responde 201, PATCH responde 200 con el registro completo y DELETE responde 204 sin cuerpo.
• Las acciones sobre un registro usan POST /recurso/{id}/accion y responden 200 con el registro actualizado.

Modo de prueba

Los endpoints que timbran aceptan "test": true para emitir CFDI y complementos de pago de prueba, sin validez fiscal. Úsalo para probar tu integración sin generar documentos reales ante el SAT.

• Los documentos de prueba se guardan aparte y nunca cambian el estatus SAT de la orden de cobro.
• La orden de cobro, el pago o el movimiento de saldo creados en la misma solicitud sí son reales.
• Los documentos de prueba aparecen en los listados de la API con "test": true y no se muestran en la aplicación.