API pública de ANTARES
Respuesta corta. API REST sobre HTTPS, autenticada con una clave que se crea en Ajustes → Integraciones. Requiere plan Business. La v1 lee y da de alta clientes y catálogo, y lee documentos; no emite facturas ni borra nada.
Qué necesitas antes de empezar
- Plan Business. La API no responde en ningún otro plan.
- Ser el administrador de la cuenta: es quien crea las claves.
- Un sistema capaz de mandar una cabecera
Authorization.
Cómo crear una clave, paso a paso
Autenticación
Authorization: Bearer r3z_live_xxxxxxxxxxxxxxxxxxxx
Las claves empiezan por r3z_live_. Se acepta también la clave a secas, sin Bearer, para
que un curl de prueba no falle por eso.
Los permisos de una clave
| Permiso | Qué habilita |
|---|---|
clientes:read | Leer clientes |
clientes:write | Crear y editar clientes |
listado:read | Leer el catálogo |
listado:write | Crear y editar productos |
documentos:read | Leer documentos |
No existe ningún permiso de borrado, y documentos:write tampoco se ofrece: emitir una
factura asigna número correlativo y la deja inmutable, y eso merece su propio diseño antes
que un endpoint.
Los recursos
| Método | Ruta | Permiso |
|---|---|---|
GET | /api/v1/negocio | ninguno |
GET | /api/v1/clientes | clientes:read |
GET | /api/v1/clientes/{id} | clientes:read |
POST | /api/v1/clientes | clientes:write |
PATCH | /api/v1/clientes/{id} | clientes:write |
GET | /api/v1/productos | listado:read |
GET | /api/v1/productos/{id} | listado:read |
POST | /api/v1/productos | listado:write |
PATCH | /api/v1/productos/{id} | listado:write |
GET | /api/v1/documentos | documentos:read |
GET | /api/v1/documentos/{id} | documentos:read |
/api/v1/negocio no exige permiso a propósito: es el que se llama para comprobar que la
clave funciona, y pedir un permiso para eso sería un círculo.
Paginación
Los listados aceptan limite (1–100, por defecto 50), desde y buscar:
GET /api/v1/clientes?limite=100&desde=200&buscar=acme
y responden con el total, para que puedas recorrerlo entero sin adivinar cuándo parar:
{
"datos": [ … ],
"paginacion": { "total": 1240, "limite": 100, "desde": 200, "hay_mas": true }
}
Errores
El código es el contrato; el mensaje es para que lo lea una persona y puede cambiar.
| HTTP | error | Cuándo |
|---|---|---|
| 400 | datos_invalidos | Falta un campo obligatorio o el cuerpo no es JSON |
| 401 | no_autenticado | No hay cabecera Authorization |
| 401 | clave_invalida | La clave no existe, está revocada o ha caducado |
| 403 | plan_insuficiente | El negocio no está en Business |
| 403 | scope_insuficiente | A la clave le falta ese permiso |
| 404 | no_encontrado | No hay ningún recurso con ese id |
| 409 | limite_plan | Se ha alcanzado un cupo del plan |
| 429 | rate_limited | Más de 600 peticiones en una hora |
Qué tener en cuenta
- 600 peticiones por hora y por clave. El cupo es de la clave, no de la IP: dos servidores con la misma clave comparten cuota y dos negocios detrás del mismo NAT no se la quitan entre ellos.
- Los cupos del plan se aplican igual. Dar de alta un cliente por API cuenta para el límite exactamente como hacerlo por la interfaz.
PATCHes parcial. Una clave ausente no toca el campo; unnullexplícito lo vacía.- Bajar de Business corta la API, pero no borra las claves: al volver a subir siguen funcionando sin rehacer nada.
Lo que no es evidente
- Un id de otro negocio y un id inexistente devuelven el mismo 404. No es descuido: distinguirlos confirmaría que ese identificador existe en algún sitio, que es la mitad de un ataque de enumeración.
precio_costey las notas internas no salen nunca por la API. Los campos expuestos son una lista blanca, no unselectde toda la tabla, precisamente para que el día que compartas una clave de solo lectura con un partner no se le vaya tu margen con ella.- Una clave revocada no se borra y no ocupa cupo. Se conserva para que quede el rastro de que existió, con qué permisos y cuándo se usó por última vez — que es justo lo que hay que mirar el día que haya que investigar algo. Y como no ocupa hueco, rotar es gratis.
- El permiso se comprueba por operación, no por clave. Una clave con
clientes:readpuede listar y no puede crear, aunque el endpoint sea el mismo camino. - No hay webhooks de vuelta desde la API. Si lo que quieres es enterarte de lo que pasa en ANTARES, eso son los webhooks salientes, que van en la otra dirección y existen desde Standard.
Preguntas frecuentes sobre la API
¿Puedo emitir facturas por API?
No en la v1. Asignar número correlativo y dejar el documento inmutable es difícil de deshacer si la integración se equivoca.
¿Puedo borrar por API?
No. No existe ningún permiso de borrado.
He perdido la clave, ¿me la podéis dar?
No. Solo se guarda su huella. Crea otra y revoca la anterior.
¿Qué pasa si bajo de plan?
La API deja de responder al momento, pero las claves se conservan.
¿Hay librerías oficiales?
No. Es REST con JSON: vale cualquier cliente HTTP.
Qué leer después
Fuente: documentación oficial de ANTARES (R3ZON). Actualizado el 2026-08-27. https://docs.r3zon.com/antares/referencia/api-publica