Introducción
La API de Santos Brezo ofrece, en formato JSON y solo para lectura, los datos de la aplicación de gestión que necesitan las integraciones externas: contactos, artículos y proyectos en preproducción o producción. Ninguna ruta permite crear, modificar ni eliminar datos.
Está dirigida a los equipos que integran sus sistemas con Santos Brezo. Todas las rutas cuelgan del
prefijo versionado /api/v1, responden solo a GET y exigen una credencial propia de cada
integración.
Cada recurso se ofrece de dos formas:
- Entrega incremental (
GET /api/v1/contactos,/articulos,/proyectos): devuelve lo que ha cambiado desde la última entrega a su integración. Es la forma habitual de mantener una copia sincronizada. - Consulta por identificador (
GET /api/v1/contactos/{id}, …): devuelve un elemento concreto, con su estado actual, sin afectar a la entrega incremental.
Esta documentación no ejecuta peticiones: los ejemplos usan datos ficticios y una credencial de ejemplo que debe sustituir por la suya.
Inicio rápido
1. Obtenga su credencial
La credencial la facilita el administrador de la API de Santos Brezo; no hay registro ni emisión de credenciales desde esta web. Cada integración recibe la suya, con los permisos que necesita y una fecha de caducidad. Guárdela como un secreto: solo se muestra una vez.
2. Compruebe el permiso del recurso
| Recurso | Permiso (ability) |
|---|---|
| Contactos | contactos:read |
| Artículos | articulos:read |
| Proyectos | proyectos:read |
3. Prepare las cabeceras
Todas las peticiones llevan la credencial como bearer token y piden JSON:
Authorization: Bearer 1|TOKEN-DE-EJEMPLO
Accept: application/json
4. Haga su primera petición
La URL base es https://api.santosbrezo.com. Sustituya la credencial de ejemplo por la suya:
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/contactos
5. Interprete la respuesta
Una respuesta correcta (200) trae los elementos en data y la información de la entrega en
meta:
{
"data": [
{ "id": 10234, "tipo": "empresa", "nombre": "Cocinas Ejemplo S.L.", "activo": true, "…": "…" }
],
"meta": {
"desde": "2026-09-25T10:15:00+02:00",
"hasta": "2026-10-02T10:15:00+02:00",
"entregados": 1,
"hay_mas": false
}
}
Si meta.hay_mas es true, vuelva a llamar para recibir el resto. Consulte
Funcionamiento general antes de programar la sincronización.
6. Si algo falla
- 401: falta la credencial o no es válida, ha caducado o se ha revocado. Compruebe la cabecera
Authorizationy, si sigue fallando, pida una credencial nueva al administrador. - 403: la credencial es válida pero no tiene el permiso del recurso. Pida al administrador que se lo añada.
El resto de códigos se explican en Errores.
Autenticación
Todas las rutas exigen una credencial de cliente API enviada como bearer token en la cabecera
Authorization:
Authorization: Bearer 1|TOKEN-DE-EJEMPLO
Credenciales
- Las emite el administrador de la API: no existe registro, inicio de sesión ni emisión de credenciales desde la API ni desde esta web.
- Cada integración (aplicación, organización, persona o entorno) tiene su propio cliente y sus propias credenciales. No las comparta.
- Cada credencial tiene una fecha de caducidad y puede revocarse en cualquier momento. Una credencial caducada o revocada deja de funcionar de inmediato.
Permisos (abilities)
Cada credencial declara los permisos que concede. Cada ruta exige uno concreto:
| Rutas | Permiso |
|---|---|
GET /api/v1/contactos, GET /api/v1/contactos/{id} |
contactos:read |
GET /api/v1/articulos, GET /api/v1/articulos/{id} |
articulos:read |
GET /api/v1/proyectos, GET /api/v1/proyectos/{id} |
proyectos:read |
GET /api/v1/status |
cualquier credencial válida |
Tener el permiso de un recurso no da acceso a los demás.
Respuestas de acceso
| Código | Cuándo | Qué hacer |
|---|---|---|
401 |
Sin credencial, o credencial inválida, caducada o revocada | Revise la cabecera; si persiste, pida una credencial nueva |
403 |
Credencial válida sin el permiso de la ruta | Pida al administrador que añada el permiso |
La credencial y el permiso se comprueban antes que cualquier otra cosa: sin acceso, nunca sabrá si un identificador existe.
Funcionamiento general
La API ofrece cada recurso de dos formas complementarias: la entrega incremental, para mantener una copia sincronizada, y la consulta por identificador, para obtener un elemento concreto.
Entrega incremental
GET /api/v1/contactos, GET /api/v1/articulos y GET /api/v1/proyectos devuelven lo que se ha
creado o modificado desde la última entrega a su integración. No admiten parámetros: la API
calcula la ventana de cada llamada.
Una posición por integración y por recurso
La API guarda, para cada integración (cliente API) y para cada recurso, hasta dónde le ha entregado. Contactos, artículos y proyectos avanzan por separado: llamar a contactos no cambia lo que recibirá de proyectos. Dos integraciones distintas tampoco se afectan entre sí.
Primera llamada: las últimas 168 horas
La primera llamada de una integración a un recurso entrega lo cambiado en las últimas 168 horas (siete días). No hay carga inicial completa: lo que no cambió en ese periodo no se entrega hasta que vuelva a cambiar. Para obtener un elemento anterior, use la consulta por identificador.
GET /api/v1/contactos (primera vez, 2 de octubre a las 10:15)
→ meta.desde = 2026-09-25T10:15:00+02:00, meta.hasta = 2026-10-02T10:15:00+02:00
Llamadas siguientes y solape de 5 minutos
Cada llamada continúa desde la última entrega completa menos 5 minutos de solape, para no perder cambios registrados en el mismo instante. Por eso un elemento puede llegar repetido.
Máximo por respuesta y hay_mas
Cada respuesta trae como máximo 100 contactos o artículos, o 25 proyectos (cada uno
completo), ordenados del cambio más antiguo al más reciente. Si quedan más, meta.hay_mas es
true: vuelva a llamar enseguida y la API continuará justo después del último elemento entregado.
GET /api/v1/proyectos → meta.entregados = 25, meta.hay_mas = true
GET /api/v1/proyectos → meta.entregados = 7, meta.hay_mas = false (fin de la secuencia)
Campo de meta |
Significado |
|---|---|
desde |
Inicio de la ventana aplicada en esta respuesta |
hasta |
Fin de la ventana aplicada en esta respuesta |
entregados |
Número de elementos de data |
hay_mas |
true si quedan cambios por entregar |
Sin cambios
Si no hay cambios, la respuesta es igualmente 200, con data: [], entregados: 0 y
hay_mas: false. No es un error.
Cuándo avanza la posición: respuestas perdidas
La posición avanza cuando el servidor genera la respuesta 200, no cuando su integración la
recibe. Si la respuesta se pierde por el camino (corte de red, tiempo de espera agotado), esos
elementos no se vuelven a entregar. Para recuperarlos, consulte por identificador los
elementos que le falten o espere a que vuelvan a cambiar. Un error 500 no avanza la posición.
No haga llamadas en paralelo con la misma integración al mismo recurso.
Entregas repetidas: aplíquelas de forma idempotente
Un mismo elemento puede llegar más de una vez (solape, llamadas concurrentes, cambios durante una
secuencia con hay_mas, cambio de hora). Aplique cada entrega de forma idempotente por id:
- Contactos y artículos: conserve la versión con
fecha_modificacionmás reciente. - Proyectos: conserve siempre la última recibida, no la de
fecha_modificacionmás reciente (esa fecha puede retroceder si se borra el dato relacionado más reciente). Al recibir un proyecto, sustituya por completo sus colecciones anidadas, no las fusione.
Qué cuenta como cambio
- Contactos: los cambios en el propio contacto. Los cambios solo en sus correos, teléfonos,
direcciones o cuentas no cuentan. Los contactos inactivos se entregan con
activo: false. - Artículos: los cambios en el propio artículo. Renombrar una marca o una familia no cuenta: el
nombre nuevo llega cuando el artículo vuelva a cambiar. Trate
activo: falsecomo baja. - Proyectos: los cambios en el proyecto (incluido su estado), en sus contactos, líneas, recibos, pagos, pedidos, recepciones e incidencias, y en su cliente, titular o dirección de montaje. Los cambios de catálogo (artículos, marcas, proveedores, almacenes, tipos de IVA…) no cuentan.
El detalle está en la descripción de cada colección: contactos, artículos y proyectos.
Lo que no se notifica
- Los elementos eliminados en la aplicación de gestión no dejan rastro y no se notifican.
- Los proyectos solo existen para la API mientras están en PREPRODUCCIÓN o PRODUCCIÓN.
Cuando un proyecto sale de esas fases deja de entregarse sin ninguna señal de salida, y su
consulta por identificador responde
404.
Sin filtros ni histórico completo
Las colecciones no admiten filtros, ordenaciones, paginación por páginas ni ningún otro parámetro:
cualquier parámetro de consulta responde 422. Tampoco permiten recuperar, con llamadas
sucesivas, lo anterior a la primera ventana de 168 horas.
Consulta por identificador
GET /api/v1/contactos/{id}, GET /api/v1/articulos/{id} y GET /api/v1/proyectos/{id}
devuelven un elemento concreto con su estado actual, sin importar cuándo cambió por última
vez, con exactamente la misma representación que en su colección.
- No aplican ninguna ventana ni modifican su posición de entrega: la siguiente llamada a la colección es la misma que sin la consulta.
- Sirven para recuperar elementos antiguos o respuestas perdidas.
- Proyectos: solo se obtienen los que están en PREPRODUCCIÓN o PRODUCCIÓN en el momento de la
llamada; cualquier otro responde
404, igual que uno inexistente. - Un identificador inexistente o con formato no válido (texto,
0, negativo, con ceros a la izquierda) responde404; nunca un elemento vacío.
GET /api/v1/contactos/10234 → 200 con el contacto, aunque no cambie desde 2024
GET /api/v1/proyectos/30512 → 404 si el proyecto ya está en posventa
Reglas comunes
- Métodos: solo
GET. Cualquier otro, incluidoHEAD, responde405. - Límite de consumo: 60 llamadas por minuto e integración, compartido por todas las rutas. Al
superarlo,
429: espere antes de reintentar. X-Request-Id: toda respuesta lleva esta cabecera. Facilítela si necesita ayuda con una petición concreta.- Fechas: ISO 8601 con segundos y desfase, en la zona horaria
Europe/Madrid(2026-10-02T10:15:00+02:00). En la hora repetida del cambio de hora de octubre se usa+02:00. Las fechas sin hora (fecha de un pago) se expresan comoAAAA-MM-DD. - Importes: cadena con dos decimales y punto (
"1114.00"), tal como constan; la API no calcula impuestos ni totales. - Valores ausentes: los campos sin valor son
nully las listas vacías[]; nunca se omiten.
GET /api/v1/contactos
Contactos creados o modificados desde la última entrega a este cliente
Permiso necesario:
contactos:read
Entrega incremental por cliente API. La API calcula la ventana; no admite ningún parámetro.
- Primera llamada (o sin referencia recuperable): contactos cambiados en las últimas 168 h.
- Llamadas siguientes: desde la última entrega completa menos 5 minutos de solape, o
justo después del último contacto entregado si la respuesta anterior tenía
hay_mas. - Máximo 100 contactos por respuesta, del cambio más antiguo al más reciente. Si
meta.hay_masestrue, vuelva a llamar para recibir el resto. - Un contacto puede entregarse más de una vez (solape, llamadas concurrentes, cambio de
hora). Aplique las entregas de forma idempotente por
id, conservando la defecha_modificacionmás reciente. - La referencia avanza cuando el servidor genera la respuesta 200. Si no llega a recibirla (corte de red, timeout), esos contactos no se vuelven a entregar.
- Los cambios solo en correos, teléfonos, direcciones o cuentas no cuentan como cambio del contacto. Los contactos eliminados no se notifican.
- Fechas en ISO 8601,
Europe/Madrid, con desfase. En la hora repetida de octubre se usa+02:00.
Requiere la ability contactos:read. Límite: 60 llamadas por minuto y cliente.
Parámetros
No admite parámetros. Cualquier parámetro de consulta responde 422.
Cabeceras de la petición
| Cabecera | Valor |
|---|---|
Authorization | Bearer {credencial} |
Accept | application/json |
Respuestas
| Código | Causa | Cabeceras |
|---|---|---|
200 |
Cambios de la ventana (posiblemente ninguno) | X-Request-Id |
401 |
Credencial ausente, inválida, caducada o revocada | X-Request-Id |
403 |
La credencial no tiene la ability requerida por el endpoint | X-Request-Id |
422 |
La petición incluye parámetros de consulta (no se admite ninguno) | X-Request-Id |
429 |
Límite de consumo del cliente superado | X-Request-Id |
500 |
Error interno; la referencia de entrega no avanza | X-Request-Id |
data es una lista de Contacto.
Campos de la respuesta
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
data |
array de Contacto | No | Sí | Elementos cambiados en la ventana, del cambio más antiguo al más reciente (máximo 100); lista vacía si no hay cambios. | |
meta |
object | No | Sí | Ventana aplicada y continuidad de la entrega. | |
meta.desde |
string (date-time) | No | Sí | Inicio de la ventana aplicada en esta respuesta. | |
meta.hasta |
string (date-time) | No | Sí | Fin de la ventana aplicada en esta respuesta. | |
meta.entregados |
integer | No | Sí | Número de elementos de data. |
|
meta.hay_mas |
boolean | No | Sí | true si quedan cambios de la ventana por entregar: vuelva a llamar para recibirlos. |
Ejemplos
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/contactos
{
"data": [
{
"id": 10234,
"tipo": "empresa",
"nombre": "Cocinas Ejemplo S.L.",
"apellidos": null,
"nif": "B00000000",
"roles": [
"cliente"
],
"activo": true,
"fecha_creacion": "2025-03-14T09:30:00+01:00",
"fecha_modificacion": "2026-09-30T17:05:12+02:00",
"emails": [
{
"email": "compras@example.com",
"etiqueta": "Compras",
"principal": true
}
],
"telefonos": [
{
"telefono": "910000000",
"etiqueta": "Oficina",
"principal": true
},
{
"telefono": "600000000",
"etiqueta": null,
"principal": false
}
],
"direcciones": [
{
"tipo_via": "Calle",
"via": "Mayor",
"numero": "1",
"escalera": null,
"piso": "2",
"letra": "B",
"codigo_postal": "28000",
"municipio": "Madrid",
"provincia": "Madrid",
"etiqueta": "Sede",
"principal": true
}
],
"cuentas_bancarias": [
{
"titular": "Cocinas Ejemplo S.L.",
"iban": "ES9121000418450200051332",
"swift": "CAIXESBBXXX",
"etiqueta": null,
"principal": true
}
]
},
{
"id": 10388,
"tipo": "persona",
"nombre": "Ana",
"apellidos": "Pérez Ejemplo",
"nif": "00000000T",
"roles": [
"cliente",
"profesional"
],
"activo": false,
"fecha_creacion": "2024-11-02T12:00:00+01:00",
"fecha_modificacion": "2026-10-01T08:41:00+02:00",
"emails": [],
"telefonos": [
{
"telefono": "600000001",
"etiqueta": "Móvil",
"principal": true
}
],
"direcciones": [],
"cuentas_bancarias": []
}
],
"meta": {
"desde": "2026-09-25T10:15:00+02:00",
"hasta": "2026-10-02T10:15:00+02:00",
"entregados": 2,
"hay_mas": false
}
}
{
"message": "Unauthenticated."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
{
"message": "This action is unauthorized."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
{
"message": "Este parámetro no está permitido.",
"errors": {
"desde": [
"Este parámetro no está permitido."
]
}
}
{
"message": "Too Many Attempts."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
GET /api/v1/contactos/{id}
Detalle de un contacto por su identificador
Permiso necesario:
contactos:read
Devuelve el contacto con su estado actual, sin importar cuándo se creó o modificó ni si
está activo. Misma representación que cada elemento de GET /api/v1/contactos.
- No aplica ninguna ventana temporal ni altera la referencia de entrega del cliente: la
siguiente llamada a
GET /api/v1/contactoses la misma que sin esta consulta. - No admite parámetros de consulta.
- Orden de las comprobaciones: 401, 403, 422 y por último 404 (
HEADresponde 405 tras el 401). Un identificador con formato no válido y uno inexistente responden igual. - Fechas en ISO 8601,
Europe/Madrid, con desfase. En la hora repetida de octubre se usa+02:00.
Requiere la ability contactos:read. Límite: 60 llamadas por minuto y cliente,
compartido con el resto de la API.
Parámetros
| Parámetro | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
id |
integer | No | Sí | Identificador numérico del contacto (el campo id de GET /api/v1/contactos). Entero positivo sin signo, ceros a la izquierda ni espacios; cualquier otro valor responde 404. |
Cabeceras de la petición
| Cabecera | Valor |
|---|---|
Authorization | Bearer {credencial} |
Accept | application/json |
Respuestas
| Código | Causa | Cabeceras |
|---|---|---|
200 |
Contacto encontrado | X-Request-Id |
401 |
Credencial ausente, inválida, caducada o revocada | X-Request-Id |
403 |
La credencial no tiene la ability requerida por el endpoint | X-Request-Id |
404 |
El recurso no existe o el identificador no tiene un formato válido | X-Request-Id |
422 |
La petición incluye parámetros de consulta (no se admite ninguno) | X-Request-Id |
429 |
Límite de consumo del cliente superado | X-Request-Id |
500 |
Error interno, sin detalles de la aplicación ni de la base de datos | X-Request-Id |
data es un Contacto,
con la misma representación que cada elemento de
/api/v1/contactos.
Campos de la respuesta
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
data |
Contacto | No | Sí | El recurso solicitado, con la misma representación que cada elemento de la colección. |
Ejemplos
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/contactos/10234
{
"data": {
"id": 10234,
"tipo": "empresa",
"nombre": "Cocinas Ejemplo S.L.",
"apellidos": null,
"nif": "B00000000",
"roles": [
"cliente"
],
"activo": true,
"fecha_creacion": "2025-03-14T09:30:00+01:00",
"fecha_modificacion": "2026-09-30T17:05:12+02:00",
"emails": [
{
"email": "compras@example.com",
"etiqueta": "Compras",
"principal": true
}
],
"telefonos": [
{
"telefono": "910000000",
"etiqueta": "Oficina",
"principal": true
},
{
"telefono": "600000000",
"etiqueta": null,
"principal": false
}
],
"direcciones": [
{
"tipo_via": "Calle",
"via": "Mayor",
"numero": "1",
"escalera": null,
"piso": "2",
"letra": "B",
"codigo_postal": "28000",
"municipio": "Madrid",
"provincia": "Madrid",
"etiqueta": "Sede",
"principal": true
}
],
"cuentas_bancarias": [
{
"titular": "Cocinas Ejemplo S.L.",
"iban": "ES9121000418450200051332",
"swift": "CAIXESBBXXX",
"etiqueta": null,
"principal": true
}
]
}
}
{
"message": "Unauthenticated."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
{
"message": "This action is unauthorized."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
{
"message": "Contacto no encontrado."
}
{
"message": "Este parámetro no está permitido.",
"errors": {
"desde": [
"Este parámetro no está permitido."
]
}
}
{
"message": "Too Many Attempts."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
GET /api/v1/articulos
Artículos creados o modificados desde la última entrega a este cliente
Permiso necesario:
articulos:read
Entrega incremental por cliente API. La API calcula la ventana; no admite ningún parámetro. La referencia de artículos de cada cliente es independiente de la de contactos.
- Primera llamada (o sin referencia recuperable): artículos cambiados en las últimas 168 h.
- Llamadas siguientes: desde la última entrega completa menos 5 minutos de solape, o
justo después del último artículo entregado si la respuesta anterior tenía
hay_mas. - Máximo 100 artículos por respuesta, del cambio más antiguo al más reciente. Si
meta.hay_masestrue, vuelva a llamar para recibir el resto. - Un artículo puede entregarse más de una vez (solape, llamadas concurrentes, cambios
durante una secuencia con
hay_mas, cambio de hora). Aplique las entregas de forma idempotente porid, conservando la defecha_modificacionmás reciente. - La referencia avanza cuando el servidor genera la respuesta 200. Si no llega a recibirla (corte de red, timeout), esos artículos no se vuelven a entregar.
- Se entregan todos los artículos, activos o no. Trate
activo: falsecomo baja. Los artículos eliminados físicamente no dejan rastro y no se notifican. - Renombrar una marca o una familia no cuenta como cambio del artículo: el nombre nuevo llega cuando el artículo vuelva a cambiar.
- Fechas en ISO 8601,
Europe/Madrid, con desfase. En la hora repetida de octubre se usa+02:00.
Requiere la ability articulos:read. Límite: 60 llamadas por minuto y cliente,
compartido con el resto de la API.
Parámetros
No admite parámetros. Cualquier parámetro de consulta responde 422.
Cabeceras de la petición
| Cabecera | Valor |
|---|---|
Authorization | Bearer {credencial} |
Accept | application/json |
Respuestas
| Código | Causa | Cabeceras |
|---|---|---|
200 |
Cambios de la ventana (posiblemente ninguno) | X-Request-Id |
401 |
Credencial ausente, inválida, caducada o revocada | X-Request-Id |
403 |
La credencial no tiene la ability requerida por el endpoint | X-Request-Id |
422 |
La petición incluye parámetros de consulta (no se admite ninguno) | X-Request-Id |
429 |
Límite de consumo del cliente superado | X-Request-Id |
500 |
Error interno; la referencia de entrega no avanza | X-Request-Id |
data es una lista de Articulo.
Campos de la respuesta
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
data |
array de Articulo | No | Sí | Elementos cambiados en la ventana, del cambio más antiguo al más reciente (máximo 100); lista vacía si no hay cambios. | |
meta |
object | No | Sí | Ventana aplicada y continuidad de la entrega. | |
meta.desde |
string (date-time) | No | Sí | Inicio de la ventana aplicada en esta respuesta. | |
meta.hasta |
string (date-time) | No | Sí | Fin de la ventana aplicada en esta respuesta. | |
meta.entregados |
integer | No | Sí | Número de elementos de data. |
|
meta.hay_mas |
boolean | No | Sí | true si quedan cambios de la ventana por entregar: vuelva a llamar para recibirlos. |
Ejemplos
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/articulos
{
"data": [
{
"id": 48213,
"referencia": "HX-100-INOX",
"ean": "0000000000017",
"descripcion": "Horno multifunción inox de ejemplo",
"precio": "649.00",
"activo": true,
"fecha_modificacion": "2026-09-29T11:20:00+02:00",
"marca": {
"id": 12,
"nombre": "Marca Ejemplo"
},
"familia": {
"id": 3,
"nombre": "Hornos"
}
},
{
"id": 48390,
"referencia": "PROMO-OTOÑO",
"ean": null,
"descripcion": "Descuento promocional de ejemplo",
"precio": "-50.00",
"activo": false,
"fecha_modificacion": "2026-10-01T16:00:00+02:00",
"marca": {
"id": 1,
"nombre": "Genérica"
},
"familia": {
"id": 9,
"nombre": "Promociones"
}
}
],
"meta": {
"desde": "2026-09-25T10:15:00+02:00",
"hasta": "2026-10-02T10:15:00+02:00",
"entregados": 2,
"hay_mas": false
}
}
{
"message": "Unauthenticated."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
{
"message": "This action is unauthorized."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
{
"message": "Este parámetro no está permitido.",
"errors": {
"desde": [
"Este parámetro no está permitido."
]
}
}
{
"message": "Too Many Attempts."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
GET /api/v1/articulos/{id}
Detalle de un artículo por su identificador
Permiso necesario:
articulos:read
Devuelve el artículo con su estado actual, sin importar cuándo se creó o modificó, si está
activo o si es ad hoc. Misma representación que cada elemento de GET /api/v1/articulos.
- No aplica ninguna ventana temporal ni altera la referencia de entrega del cliente: la
siguiente llamada a
GET /api/v1/articuloses la misma que sin esta consulta. - No admite parámetros de consulta.
- Orden de las comprobaciones: 401, 403, 422 y por último 404 (
HEADresponde 405 tras el 401). Un identificador con formato no válido y uno inexistente responden igual. precioes el PVP unitario con IVA incluido tal como consta en la aplicación de gestión: cadena con dos decimales y punto ("1234.50"), puede ser"0.00"o negativo, ynullsi no hay precio. La API no calcula impuestos, descuentos ni tarifas.- Fechas en ISO 8601,
Europe/Madrid, con desfase. En la hora repetida de octubre se usa+02:00.
Requiere la ability articulos:read. Límite: 60 llamadas por minuto y cliente,
compartido con el resto de la API.
Parámetros
| Parámetro | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
id |
integer | No | Sí | Identificador numérico del artículo (el campo id de GET /api/v1/articulos). Entero positivo sin signo, ceros a la izquierda ni espacios; cualquier otro valor responde 404. |
Cabeceras de la petición
| Cabecera | Valor |
|---|---|
Authorization | Bearer {credencial} |
Accept | application/json |
Respuestas
| Código | Causa | Cabeceras |
|---|---|---|
200 |
Artículo encontrado | X-Request-Id |
401 |
Credencial ausente, inválida, caducada o revocada | X-Request-Id |
403 |
La credencial no tiene la ability requerida por el endpoint | X-Request-Id |
404 |
El artículo no existe o el identificador no tiene un formato válido | X-Request-Id |
422 |
La petición incluye parámetros de consulta (no se admite ninguno) | X-Request-Id |
429 |
Límite de consumo del cliente superado | X-Request-Id |
500 |
Error interno, sin detalles de la aplicación ni de la base de datos | X-Request-Id |
data es un Articulo,
con la misma representación que cada elemento de
/api/v1/articulos.
Campos de la respuesta
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
data |
Articulo | No | Sí | El recurso solicitado, con la misma representación que cada elemento de la colección. |
Ejemplos
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/articulos/48213
{
"data": {
"id": 48213,
"referencia": "HX-100-INOX",
"ean": "0000000000017",
"descripcion": "Horno multifunción inox de ejemplo",
"precio": "649.00",
"activo": true,
"fecha_modificacion": "2026-09-29T11:20:00+02:00",
"marca": {
"id": 12,
"nombre": "Marca Ejemplo"
},
"familia": {
"id": 3,
"nombre": "Hornos"
}
}
}
{
"message": "Unauthenticated."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
{
"message": "This action is unauthorized."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
{
"message": "Artículo no encontrado."
}
{
"message": "Este parámetro no está permitido.",
"errors": {
"desde": [
"Este parámetro no está permitido."
]
}
}
{
"message": "Too Many Attempts."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
GET /api/v1/proyectos
Proyectos en preproducción o producción cambiados desde la última entrega a este cliente
Permiso necesario:
proyectos:read
Entrega incremental por cliente API. La API calcula la ventana; no admite ningún parámetro. La referencia de proyectos de cada cliente es independiente de las de contactos y artículos.
Selección
- Solo se entregan los proyectos cuyo estado, en el momento de la llamada, pertenece a la fase PREPRODUCCIÓN o PRODUCCIÓN. El resto no existe para esta API: cuando un proyecto sale de esas fases deja de entregarse y no se envía ninguna señal de salida.
- Estado y fase no forman parte de la respuesta.
Qué cuenta como cambio (fecha_modificacion es ese instante)
- Cambios en el propio proyecto (incluida su entrada en las fases o un cambio de estado).
- Altas o cambios en sus contactos, líneas de artículos, recibos, pagos, imputaciones de pagos a recibos, pedidos, líneas de pedido, recepciones e incidencias.
- Cambios en su cliente, su titular del contrato o su dirección de montaje.
- Cambios en la configuración de su estado actual (p. ej. que el estado pase a otra fase).
- NO cuentan: cambios en el catálogo de artículos o marcas, proveedores, almacenes, tipos de pedido o de incidencia, tipos de IVA, datos geográficos ni en los datos de comercial, montador o transportista. El dato nuevo llega cuando el proyecto vuelva a cambiar.
- Los borrados físicos de datos relacionados no se detectan: al recibir un proyecto, sustituya por completo sus colecciones anidadas, no las fusione.
Ventana y continuidad
- Primera llamada (o sin referencia recuperable): proyectos cambiados en las últimas 168 h. No hay carga inicial completa: los proyectos en fase sin cambios en ese periodo no se entregan hasta que vuelvan a cambiar.
- Llamadas siguientes: desde la última entrega completa menos 5 minutos de solape, o justo
después del último proyecto entregado si la respuesta anterior tenía
hay_mas. - Máximo 25 proyectos por respuesta, cada uno completo, del cambio más antiguo al más
reciente. Si
meta.hay_masestrue, vuelva a llamar para recibir el resto. - Un proyecto puede entregarse más de una vez (solape, llamadas concurrentes, cambios
durante una secuencia con
hay_mas, cambio de hora). Aplique las entregas de forma idempotente porid, conservando siempre la última recibida (no la defecha_modificacionmás reciente: esa fecha puede retroceder si se borra el dato relacionado más reciente). No haga llamadas en paralelo con el mismo cliente. - La referencia avanza cuando el servidor genera la respuesta 200. Si no llega a recibirla (corte de red, timeout), esos proyectos no se vuelven a entregar.
Formato
- Importes, tasas de IVA, porcentajes y cantidades decimales: cadena con dos decimales y
punto (
"1114.00"), tal como constan; la API no calcula ni recalcula importes ni impuestos. Cantidades de pedido, horas y minutos: enteros. - Fechas con hora en ISO 8601,
Europe/Madrid, con desfase (en la hora repetida de octubre,+02:00); fechas sin hora (fecha de un pago) comoAAAA-MM-DD. - Textos normalizados: tabuladores y saltos de línea se sustituyen por un espacio, los
espacios repetidos se reducen a uno y se recortan los extremos; un texto vacío es
null. - Los objetos relacionados ausentes o inexistentes son
null; las colecciones son siempre listas, ordenadas porid, e incluyen los elementos inactivos (activo: false). - Los pagos no imputados a ningún recibo no se entregan.
documentoses siempre una lista vacía: la API no sirve ni enlaza ficheros.
Requiere la ability proyectos:read. Límite: 60 llamadas por minuto y cliente,
compartido con el resto de la API.
Parámetros
No admite parámetros. Cualquier parámetro de consulta responde 422.
Cabeceras de la petición
| Cabecera | Valor |
|---|---|
Authorization | Bearer {credencial} |
Accept | application/json |
Respuestas
| Código | Causa | Cabeceras |
|---|---|---|
200 |
Cambios de la ventana (posiblemente ninguno) | X-Request-Id |
401 |
Credencial ausente, inválida, caducada o revocada | X-Request-Id |
403 |
La credencial no tiene la ability requerida por el endpoint | X-Request-Id |
422 |
La petición incluye parámetros de consulta (no se admite ninguno) | X-Request-Id |
429 |
Límite de consumo del cliente superado | X-Request-Id |
500 |
Error interno; la referencia de entrega no avanza | X-Request-Id |
data es una lista de Proyecto.
Campos de la respuesta
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
data |
array de Proyecto | No | Sí | Elementos cambiados en la ventana, del cambio más antiguo al más reciente (máximo 25); lista vacía si no hay cambios. | |
meta |
object | No | Sí | Ventana aplicada y continuidad de la entrega. | |
meta.desde |
string (date-time) | No | Sí | Inicio de la ventana aplicada en esta respuesta. | |
meta.hasta |
string (date-time) | No | Sí | Fin de la ventana aplicada en esta respuesta. | |
meta.entregados |
integer | No | Sí | Número de elementos de data. |
|
meta.hay_mas |
boolean | No | Sí | true si quedan cambios de la ventana por entregar: vuelva a llamar para recibirlos. |
Ejemplos
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/proyectos
{
"data": [
{
"id": 30512,
"referencia": "P-26-0412",
"nombre": "Cocina vivienda calle Mayor",
"fecha_modificacion": "2026-10-01T18:02:44+02:00",
"cliente": {
"id": 10388,
"nif": "00000000T",
"nombre": "Ana",
"apellidos": "Pérez Ejemplo"
},
"titular_contrato": {
"id": 10388,
"nif": "00000000T",
"nombre": "Ana",
"apellidos": "Pérez Ejemplo"
},
"contactos": [
{
"id": 7001,
"nombre": "Luis Ejemplo",
"etiqueta": "Portero",
"telefono": "600000002",
"email": null,
"logistica": true,
"activo": true
}
],
"direccion_montaje": {
"id": 5120,
"tipo_via": {
"id": 1,
"nombre": "Calle"
},
"direccion": "Mayor",
"numero": "1",
"escalera": null,
"piso": "2",
"letra": "B",
"codigo_postal": "28000",
"municipio": {
"id": 28079,
"nombre": "Madrid"
},
"provincia": {
"id": 28,
"nombre": "Madrid"
}
},
"comercial": {
"id": 15,
"nombre": "Marta",
"apellidos": "Comercial Ejemplo"
},
"montador": {
"id": 42,
"nombre": "Jorge",
"apellidos": "Montador Ejemplo"
},
"transportista": null,
"tipo_iva": {
"id": 1,
"nombre": "General",
"iva_mobiliario": "21.00",
"iva_electrodomesticos": "21.00"
},
"mobiliario_neto": "5000.00",
"mobiliario_tasa_iva": "21.00",
"mobiliario_cuota_iva": "1050.00",
"mobiliario_total": "6050.00",
"electrodomesticos_neto": "1000.00",
"electrodomesticos_tasa_iva": "21.00",
"electrodomesticos_cuota_iva": "210.00",
"electrodomesticos_total": "1210.00",
"total_proyecto_neto": "6000.00",
"total_proyecto_iva": "1260.00",
"total_proyecto": "7260.00",
"articulos": [
{
"id": 90001,
"articulo": {
"id": 48213,
"nombre": "Horno multifunción inox de ejemplo",
"referencia": "HX-100-INOX",
"marca": {
"id": 12,
"nombre": "Marca Ejemplo"
}
},
"cantidad": "1.00",
"precio": "649.00",
"importe": "649.00",
"porcentaje_descuento": "10.00",
"importe_total": "584.10",
"activo": true
}
],
"recibos": [
{
"id": 81001,
"concepto": "Señal",
"importe": "2178.00",
"activo": true,
"pagos": [
{
"id": 82001,
"fecha": "2026-09-18",
"importe": "2178.00",
"importe_parcial": "2178.00",
"activo": true
}
]
}
],
"pedidos": [
{
"id": 60001,
"tipo": {
"id": 2,
"nombre": "Electrodomésticos",
"observaciones": null
},
"proveedor": {
"id": 20500,
"nif": "B11111111",
"nombre": "Distribuciones Ejemplo S.A.",
"apellidos": null
},
"almacen": {
"id": 3,
"nombre": "Almacén central",
"direccion": "Polígono Ejemplo, nave 4",
"cp": "28000",
"poblacion": "Madrid",
"email": "almacen@example.com",
"telefonos": "910000001"
},
"articulos": [
{
"id": 61001,
"articulo_id": 48213,
"nombre": "Horno multifunción inox de ejemplo",
"cantidad_pedida": 1,
"cantidad_recibida": 1
}
],
"recepciones": [
{
"id": 62001,
"fecha": "2026-09-28T09:10:00+02:00",
"albaran": "ALB-0001",
"importe_neto": "480.00",
"importe_total": "580.80"
}
]
}
],
"incidencias": [
{
"id": 70001,
"incidencia": "Puerta de mueble alto con arañazo",
"tipo": {
"id": 4,
"nombre": "Material dañado"
},
"solucion": "Sustituir la puerta",
"pedir_material": true,
"cargo_cliente": false,
"horas": 1,
"minutos": 30,
"activo": true
}
],
"documentos": []
}
],
"meta": {
"desde": "2026-09-25T10:15:00+02:00",
"hasta": "2026-10-02T10:15:00+02:00",
"entregados": 1,
"hay_mas": false
}
}
{
"message": "Unauthenticated."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
{
"message": "This action is unauthorized."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
{
"message": "Este parámetro no está permitido.",
"errors": {
"desde": [
"Este parámetro no está permitido."
]
}
}
{
"message": "Too Many Attempts."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
GET /api/v1/proyectos/{id}
Detalle de un proyecto en preproducción o producción por su identificador
Permiso necesario:
proyectos:read
Devuelve el proyecto completo, con todas sus relaciones y su estado actual, sin importar
cuándo cambió por última vez. Misma representación que cada elemento de
GET /api/v1/proyectos (formatos de importes, fechas y textos, null y listas vacías,
orden de colecciones, pagos no imputados omitidos y documentos siempre vacío: ver esa
operación).
- Solo se obtienen los proyectos cuyo estado, en el momento de la llamada, pertenece a la fase PREPRODUCCIÓN o PRODUCCIÓN, el mismo alcance que la entrega incremental. Cualquier otro responde 404, igual que uno inexistente: el 404 no distingue entre proyecto inexistente y proyecto fuera de esas fases.
fecha_modificaciones el último cambio del proyecto o de sus datos propios, calculado igual que enGET /api/v1/proyectos; las fechas de datos relacionados posteriores al instante de la petición no cuentan.- No aplica ninguna ventana temporal ni altera la referencia de entrega del cliente: la
siguiente llamada a
GET /api/v1/proyectoses la misma que sin esta consulta. - No admite parámetros de consulta.
- Orden de las comprobaciones: 401, 403, 422 y por último 404 (
HEADresponde 405 tras el 401). Un identificador con formato no válido y uno inexistente responden igual.
Requiere la ability proyectos:read. Límite: 60 llamadas por minuto y cliente,
compartido con el resto de la API.
Parámetros
| Parámetro | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
id |
integer | No | Sí | Identificador numérico del proyecto (el campo id de GET /api/v1/proyectos). Entero positivo sin signo, ceros a la izquierda ni espacios; cualquier otro valor responde 404. |
Cabeceras de la petición
| Cabecera | Valor |
|---|---|
Authorization | Bearer {credencial} |
Accept | application/json |
Respuestas
| Código | Causa | Cabeceras |
|---|---|---|
200 |
Proyecto encontrado en preproducción o producción | X-Request-Id |
401 |
Credencial ausente, inválida, caducada o revocada | X-Request-Id |
403 |
La credencial no tiene la ability requerida por el endpoint | X-Request-Id |
404 |
El proyecto no existe, no está en preproducción ni producción, o el identificador no tiene un formato válido | X-Request-Id |
422 |
La petición incluye parámetros de consulta (no se admite ninguno) | X-Request-Id |
429 |
Límite de consumo del cliente superado | X-Request-Id |
500 |
Error interno, sin detalles de la aplicación ni de la base de datos | X-Request-Id |
data es un Proyecto,
con la misma representación que cada elemento de
/api/v1/proyectos.
Campos de la respuesta
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
data |
Proyecto | No | Sí | El recurso solicitado, con la misma representación que cada elemento de la colección. |
Ejemplos
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/proyectos/30512
{
"data": {
"id": 30512,
"referencia": "P-26-0412",
"nombre": "Cocina vivienda calle Mayor",
"fecha_modificacion": "2026-10-01T18:02:44+02:00",
"cliente": {
"id": 10388,
"nif": "00000000T",
"nombre": "Ana",
"apellidos": "Pérez Ejemplo"
},
"titular_contrato": {
"id": 10388,
"nif": "00000000T",
"nombre": "Ana",
"apellidos": "Pérez Ejemplo"
},
"contactos": [
{
"id": 7001,
"nombre": "Luis Ejemplo",
"etiqueta": "Portero",
"telefono": "600000002",
"email": null,
"logistica": true,
"activo": true
}
],
"direccion_montaje": {
"id": 5120,
"tipo_via": {
"id": 1,
"nombre": "Calle"
},
"direccion": "Mayor",
"numero": "1",
"escalera": null,
"piso": "2",
"letra": "B",
"codigo_postal": "28000",
"municipio": {
"id": 28079,
"nombre": "Madrid"
},
"provincia": {
"id": 28,
"nombre": "Madrid"
}
},
"comercial": {
"id": 15,
"nombre": "Marta",
"apellidos": "Comercial Ejemplo"
},
"montador": {
"id": 42,
"nombre": "Jorge",
"apellidos": "Montador Ejemplo"
},
"transportista": null,
"tipo_iva": {
"id": 1,
"nombre": "General",
"iva_mobiliario": "21.00",
"iva_electrodomesticos": "21.00"
},
"mobiliario_neto": "5000.00",
"mobiliario_tasa_iva": "21.00",
"mobiliario_cuota_iva": "1050.00",
"mobiliario_total": "6050.00",
"electrodomesticos_neto": "1000.00",
"electrodomesticos_tasa_iva": "21.00",
"electrodomesticos_cuota_iva": "210.00",
"electrodomesticos_total": "1210.00",
"total_proyecto_neto": "6000.00",
"total_proyecto_iva": "1260.00",
"total_proyecto": "7260.00",
"articulos": [
{
"id": 90001,
"articulo": {
"id": 48213,
"nombre": "Horno multifunción inox de ejemplo",
"referencia": "HX-100-INOX",
"marca": {
"id": 12,
"nombre": "Marca Ejemplo"
}
},
"cantidad": "1.00",
"precio": "649.00",
"importe": "649.00",
"porcentaje_descuento": "10.00",
"importe_total": "584.10",
"activo": true
}
],
"recibos": [
{
"id": 81001,
"concepto": "Señal",
"importe": "2178.00",
"activo": true,
"pagos": [
{
"id": 82001,
"fecha": "2026-09-18",
"importe": "2178.00",
"importe_parcial": "2178.00",
"activo": true
}
]
}
],
"pedidos": [
{
"id": 60001,
"tipo": {
"id": 2,
"nombre": "Electrodomésticos",
"observaciones": null
},
"proveedor": {
"id": 20500,
"nif": "B11111111",
"nombre": "Distribuciones Ejemplo S.A.",
"apellidos": null
},
"almacen": {
"id": 3,
"nombre": "Almacén central",
"direccion": "Polígono Ejemplo, nave 4",
"cp": "28000",
"poblacion": "Madrid",
"email": "almacen@example.com",
"telefonos": "910000001"
},
"articulos": [
{
"id": 61001,
"articulo_id": 48213,
"nombre": "Horno multifunción inox de ejemplo",
"cantidad_pedida": 1,
"cantidad_recibida": 1
}
],
"recepciones": [
{
"id": 62001,
"fecha": "2026-09-28T09:10:00+02:00",
"albaran": "ALB-0001",
"importe_neto": "480.00",
"importe_total": "580.80"
}
]
}
],
"incidencias": [
{
"id": 70001,
"incidencia": "Puerta de mueble alto con arañazo",
"tipo": {
"id": 4,
"nombre": "Material dañado"
},
"solucion": "Sustituir la puerta",
"pedir_material": true,
"cargo_cliente": false,
"horas": 1,
"minutos": 30,
"activo": true
}
],
"documentos": []
}
}
{
"message": "Unauthenticated."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
{
"message": "This action is unauthorized."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
{
"message": "Proyecto no encontrado."
}
{
"message": "Este parámetro no está permitido.",
"errors": {
"desde": [
"Este parámetro no está permitido."
]
}
}
{
"message": "Too Many Attempts."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
GET /api/v1/status
Estado del servicio y de la conexión con la BD legacy
Permiso necesario: cualquier credencial válida
Parámetros
No admite parámetros. Cualquier parámetro de consulta responde 422.
Cabeceras de la petición
| Cabecera | Valor |
|---|---|
Authorization | Bearer {credencial} |
Accept | application/json |
Respuestas
| Código | Causa | Cabeceras |
|---|---|---|
200 |
Servicio operativo | X-Request-Id |
401 |
Token ausente o inválido | X-Request-Id |
Campos de la respuesta
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
data |
object | No | Sí | Estado del servicio. | |
data.status |
string | No | Sí | ok degraded |
ok si la API conecta con la base de datos de gestión; degraded si no. |
data.legacy |
boolean | No | Sí | true si la conexión con la base de datos de gestión funciona. |
Ejemplos
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/status
{
"data": {
"status": "ok",
"legacy": true
}
}
{
"message": "Unauthenticated."
}
Mensaje orientativo: el texto depende del idioma configurado en la API.
Esquema Contacto
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
id |
integer | No | Sí | Identificador numérico del contacto en la aplicación de gestión; es el {id} de GET /api/v1/contactos/{id}. |
|
tipo |
string | Sí | Sí | persona empresa null |
persona, empresa o null si no consta. |
nombre |
string | Sí | Sí | Nombre (de la persona) o razón social (de la empresa). null si no consta. |
|
apellidos |
string | Sí | Sí | Apellidos; solo relevante para personas. null si no consta. |
|
nif |
string | Sí | Sí | NIF o CIF. null si no consta. |
|
roles |
array de string | No | Sí | Roles del contacto, sin repetir; lista vacía si no tiene ninguno. | |
activo |
boolean | No | Sí | false si el contacto está desactivado; se entrega igualmente con todos sus datos para que deje de tratarse como vigente. |
|
fecha_creacion |
string (date-time) | Sí | Sí | Fecha de alta del contacto. null si no consta. |
|
fecha_modificacion |
string (date-time) | Sí | Sí | Fecha de última modificación del contacto. null si no consta. |
|
emails |
array de object | No | Sí | Correos electrónicos activos; lista vacía si no tiene. | |
emails[].email |
string | Sí | Sí | Dirección de correo. null si no consta. |
|
emails[].etiqueta |
string | Sí | Sí | Etiqueta del correo (p. ej. trabajo). null si no consta. |
|
emails[].principal |
boolean | No | Sí | true si es el correo principal. |
|
telefonos |
array de object | No | Sí | Teléfonos activos; lista vacía si no tiene. | |
telefonos[].telefono |
string | Sí | Sí | Número de teléfono tal como consta. null si no consta. |
|
telefonos[].etiqueta |
string | Sí | Sí | Etiqueta del teléfono. null si no consta. |
|
telefonos[].principal |
boolean | No | Sí | true si es el teléfono principal. |
|
direcciones |
array de object | No | Sí | Direcciones activas; lista vacía si no tiene. | |
direcciones[].tipo_via |
string | Sí | Sí | Nombre del tipo de vía (p. ej. Calle). null si falta o no puede resolverse. |
|
direcciones[].via |
string | Sí | Sí | Nombre de la vía. null si no consta. |
|
direcciones[].numero |
string | Sí | Sí | Número de la vía. null si no consta. |
|
direcciones[].escalera |
string | Sí | Sí | Escalera. null si no consta. |
|
direcciones[].piso |
string | Sí | Sí | Piso. null si no consta. |
|
direcciones[].letra |
string | Sí | Sí | Letra o puerta. null si no consta. |
|
direcciones[].codigo_postal |
string | Sí | Sí | Código postal. null si no consta. |
|
direcciones[].municipio |
string | Sí | Sí | Nombre del municipio. null si falta o no puede resolverse. |
|
direcciones[].provincia |
string | Sí | Sí | Nombre de la provincia. null si falta o no puede resolverse. |
|
direcciones[].etiqueta |
string | Sí | Sí | Etiqueta de la dirección. null si no consta. |
|
direcciones[].principal |
boolean | No | Sí | true si es la dirección principal. |
|
cuentas_bancarias |
array de object | No | Sí | Cuentas bancarias autorizadas (activas); lista vacía si no tiene. | |
cuentas_bancarias[].titular |
string | Sí | Sí | Titular de la cuenta. null si no consta. |
|
cuentas_bancarias[].iban |
string | Sí | Sí | IBAN completo. null si no consta. |
|
cuentas_bancarias[].swift |
string | Sí | Sí | Código SWIFT/BIC. null si no consta. |
|
cuentas_bancarias[].etiqueta |
string | Sí | Sí | Etiqueta de la cuenta. null si no consta. |
|
cuentas_bancarias[].principal |
boolean | No | Sí | true si es la cuenta principal. |
Esquema Articulo
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
id |
integer | No | Sí | Identificador numérico del artículo en la aplicación de gestión; es el {id} de GET /api/v1/articulos/{id}. |
|
referencia |
string | Sí | Sí | Referencia del artículo. null si no consta. |
|
ean |
string | Sí | Sí | Código de barras tal como consta, sin validar (conserva ceros iniciales). | |
descripcion |
string | Sí | Sí | Nombre descriptivo del artículo. null si no consta. |
|
precio |
string | Sí | Sí | PVP unitario en euros, IVA incluido, tal como consta en la aplicación de gestión, con dos decimales y punto decimal. Sin desglose de impuestos ni tipo de IVA (lo fija cada operación). Puede ser 0.00 o negativo (promociones y descuentos). null si no consta. |
|
activo |
boolean | No | Sí | false si el artículo está dado de baja; trátelo como baja. |
|
fecha_modificacion |
string (date-time) | Sí | Sí | Fecha de última modificación del artículo. null si no consta. |
|
marca |
Clasificacion | No | Sí | Marca del artículo; siempre presente. | |
familia |
Clasificacion | No | Sí | Familia del artículo; siempre presente. |
Esquema Clasificacion
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
id |
integer | No | Sí | Identificador numérico de la marca o familia. | |
nombre |
string | Sí | Sí | Nombre de la marca o familia. null si no consta. |
Esquema Proyecto
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
id |
integer | No | Sí | Identificador numérico del proyecto en la aplicación de gestión; es el {id} de GET /api/v1/proyectos/{id}. |
|
referencia |
string | Sí | Sí | Referencia del proyecto. null si no consta. |
|
nombre |
string | Sí | Sí | Nombre del proyecto. null si no consta. |
|
fecha_modificacion |
string (date-time) | No | Sí | Último cambio del proyecto o de sus datos propios (ver la descripción de GET /api/v1/proyectos); en la entrega incremental decide la ventana en que se entrega. | |
cliente |
ProyectoTitular | Sí | Sí | Cliente del proyecto. null si no consta o no existe. |
|
titular_contrato |
ProyectoTitular | Sí | Sí | Titular del contrato. null si no consta o no existe. |
|
contactos |
array de object | No | Sí | Contactos propios del proyecto, ordenados por id, incluidos los inactivos; lista vacía si no tiene. |
|
contactos[].id |
integer | No | Sí | Identificador del contacto del proyecto. | |
contactos[].nombre |
string | Sí | Sí | Nombre del contacto. null si no consta. |
|
contactos[].etiqueta |
string | Sí | Sí | Etiqueta del contacto. null si no consta. |
|
contactos[].telefono |
string | Sí | Sí | Teléfono del contacto. null si no consta. |
|
contactos[].email |
string | Sí | Sí | Correo del contacto. null si no consta. |
|
contactos[].logistica |
boolean | Sí | Sí | Contacto para montaje y logística. | |
contactos[].activo |
boolean | No | Sí | false si el contacto está inactivo. |
|
direccion_montaje |
DireccionMontaje | Sí | Sí | Dirección de montaje. null si no consta o no existe. |
|
comercial |
PersonaAsignada | Sí | Sí | Comercial asignado. null si no hay. |
|
montador |
PersonaAsignada | Sí | Sí | Montador asignado. null si no hay. |
|
transportista |
PersonaAsignada | Sí | Sí | Transportista asignado. null si no hay. |
|
tipo_iva |
object | Sí | Sí | Tipo de IVA aplicado al proyecto. null si no consta o no existe. |
|
tipo_iva.id |
integer | No | Sí | Identificador del tipo de IVA. | |
tipo_iva.nombre |
string | Sí | Sí | Nombre del tipo de IVA. null si no consta. |
|
tipo_iva.iva_mobiliario |
string | Sí | Sí | Tasa de IVA para mobiliario, tal como consta. | |
tipo_iva.iva_electrodomesticos |
string | Sí | Sí | Tasa de IVA para electrodomésticos, tal como consta. | |
mobiliario_neto |
string | Sí | Sí | Importe neto del mobiliario, tal como consta (la API no lo calcula). | |
mobiliario_tasa_iva |
string | Sí | Sí | Tasa de IVA del mobiliario, tal como consta. | |
mobiliario_cuota_iva |
string | Sí | Sí | Cuota de IVA del mobiliario, tal como consta. | |
mobiliario_total |
string | Sí | Sí | Total del mobiliario con IVA, tal como consta. | |
electrodomesticos_neto |
string | Sí | Sí | Importe neto de los electrodomésticos, tal como consta. | |
electrodomesticos_tasa_iva |
string | Sí | Sí | Tasa de IVA de los electrodomésticos, tal como consta. | |
electrodomesticos_cuota_iva |
string | Sí | Sí | Cuota de IVA de los electrodomésticos, tal como consta. | |
electrodomesticos_total |
string | Sí | Sí | Total de los electrodomésticos con IVA, tal como consta. | |
total_proyecto_neto |
string | Sí | Sí | Importe neto total del proyecto, tal como consta. | |
total_proyecto_iva |
string | Sí | Sí | IVA total del proyecto, tal como consta. | |
total_proyecto |
string | Sí | Sí | Total del proyecto con IVA, tal como consta. | |
articulos |
array de object | No | Sí | Líneas de artículos del proyecto. | |
articulos[].id |
integer | No | Sí | Identificador de la línea del proyecto. | |
articulos[].articulo |
object | Sí | Sí | null si el artículo no existe en el catálogo. |
|
articulos[].articulo.id |
integer | No | Sí | Identificador del artículo en el catálogo. | |
articulos[].articulo.nombre |
string | Sí | Sí | Nombre del artículo. null si no consta. |
|
articulos[].articulo.referencia |
string | Sí | Sí | Referencia del artículo. null si no consta. |
|
articulos[].articulo.marca |
CatalogoOpcional | Sí | Sí | Marca del artículo. null si no consta o no existe. |
|
articulos[].cantidad |
string | Sí | Sí | Cantidad de la línea, tal como consta. | |
articulos[].precio |
string | Sí | Sí | Precio unitario de la línea, tal como consta. | |
articulos[].importe |
string | Sí | Sí | Importe de la línea antes de descuento, tal como consta. | |
articulos[].porcentaje_descuento |
string | Sí | Sí | Porcentaje de descuento de la línea, tal como consta. | |
articulos[].importe_total |
string | Sí | Sí | Importe total de la línea, tal como consta. | |
articulos[].activo |
boolean | No | Sí | false si la línea está inactiva. |
|
recibos |
array de object | No | Sí | Recibos del proyecto, ordenados por id, incluidos los inactivos; lista vacía si no tiene. |
|
recibos[].id |
integer | No | Sí | Identificador del recibo. | |
recibos[].concepto |
string | Sí | Sí | Concepto del recibo. null si no consta. |
|
recibos[].importe |
string | Sí | Sí | Importe del recibo, tal como consta. | |
recibos[].activo |
boolean | Sí | Sí | false si el recibo está inactivo. null si no consta. |
|
recibos[].pagos |
array de object | No | Sí | Pagos imputados a este recibo. Un pago imputado a varios recibos aparece bajo cada uno con su importe parcial. Los pagos sin imputar no se entregan. | |
recibos[].pagos[].id |
integer | No | Sí | Identificador del pago. | |
recibos[].pagos[].fecha |
string (date) | Sí | Sí | Fecha del pago, sin hora (AAAA-MM-DD). null si no consta. |
|
recibos[].pagos[].importe |
string | Sí | Sí | Importe total del pago, tal como consta. | |
recibos[].pagos[].importe_parcial |
string | Sí | Sí | Parte del pago imputada a este recibo, tal como consta. | |
recibos[].pagos[].activo |
boolean | Sí | Sí | false si el pago está inactivo. null si no consta. |
|
pedidos |
array de object | No | Sí | Pedidos del proyecto, ordenados por id; lista vacía si no tiene. |
|
pedidos[].id |
integer | No | Sí | Identificador del pedido. | |
pedidos[].tipo |
object | Sí | Sí | Tipo de pedido. null si no consta o no existe. |
|
pedidos[].tipo.id |
integer | No | Sí | Identificador del tipo de pedido. | |
pedidos[].tipo.nombre |
string | Sí | Sí | Nombre del tipo de pedido. null si no consta. |
|
pedidos[].tipo.observaciones |
string | Sí | Sí | Observaciones del tipo de pedido. null si no consta. |
|
pedidos[].proveedor |
ProyectoTitular | Sí | Sí | Proveedor del pedido. null si no consta o no existe. |
|
pedidos[].almacen |
object | Sí | Sí | Almacén de destino del pedido. null si no consta o no existe. |
|
pedidos[].almacen.id |
integer | No | Sí | Identificador del almacén. | |
pedidos[].almacen.nombre |
string | Sí | Sí | Nombre del almacén. null si no consta. |
|
pedidos[].almacen.direccion |
string | Sí | Sí | Dirección del almacén. null si no consta. |
|
pedidos[].almacen.cp |
string | Sí | Sí | Código postal del almacén. null si no consta. |
|
pedidos[].almacen.poblacion |
string | Sí | Sí | Población del almacén. null si no consta. |
|
pedidos[].almacen.email |
string | Sí | Sí | Correo del almacén. null si no consta. |
|
pedidos[].almacen.telefonos |
string | Sí | Sí | Teléfonos del almacén, en un único texto tal como constan. null si no consta. |
|
pedidos[].articulos |
array de object | No | Sí | Líneas del pedido, ordenadas por id; lista vacía si no tiene. |
|
pedidos[].articulos[].id |
integer | No | Sí | Identificador de la línea de pedido. | |
pedidos[].articulos[].articulo_id |
integer | No | Sí | Identificador del artículo pedido en el catálogo. | |
pedidos[].articulos[].nombre |
string | Sí | Sí | Nombre del artículo en la línea de pedido. null si no consta. |
|
pedidos[].articulos[].cantidad_pedida |
integer | No | Sí | Unidades pedidas (entero). | |
pedidos[].articulos[].cantidad_recibida |
integer | No | Sí | Unidades recibidas (entero). | |
pedidos[].recepciones |
array de object | No | Sí | Recepciones del pedido, ordenadas por id; lista vacía si no tiene. |
|
pedidos[].recepciones[].id |
integer | No | Sí | Identificador de la recepción. | |
pedidos[].recepciones[].fecha |
string (date-time) | Sí | Sí | Fecha y hora de la recepción. null si no consta. |
|
pedidos[].recepciones[].albaran |
string | Sí | Sí | Número de albarán. null si no consta. |
|
pedidos[].recepciones[].importe_neto |
string | Sí | Sí | Importe neto de la recepción, tal como consta. | |
pedidos[].recepciones[].importe_total |
string | Sí | Sí | Importe total de la recepción, tal como consta. | |
incidencias |
array de object | No | Sí | Incidencias del proyecto, ordenadas por id, incluidas las inactivas; lista vacía si no tiene. |
|
incidencias[].id |
integer | No | Sí | Identificador de la incidencia. | |
incidencias[].incidencia |
string | Sí | Sí | Descripción de la incidencia. null si no consta. |
|
incidencias[].tipo |
CatalogoOpcional | Sí | Sí | Tipo de incidencia. null si no consta o no existe. |
|
incidencias[].solucion |
string | Sí | Sí | Solución aplicada. null si no consta. |
|
incidencias[].pedir_material |
boolean | No | Sí | true si la incidencia requiere pedir material. |
|
incidencias[].cargo_cliente |
boolean | No | Sí | true si la incidencia se carga al cliente. |
|
incidencias[].horas |
integer | Sí | Sí | Horas registradas en la incidencia (entero), tal como constan. null si no consta. |
|
incidencias[].minutos |
integer | Sí | Sí | Minutos registrados en la incidencia (entero), tal como constan. null si no consta. |
|
incidencias[].activo |
boolean | No | Sí | false si la incidencia está inactiva. |
|
documentos |
array de object | No | Sí | Siempre vacía; la API no sirve, copia ni enlaza ficheros. |
Esquema ProyectoTitular
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
id |
integer | No | Sí | Identificador del contacto en la aplicación de gestión. | |
nif |
string | Sí | Sí | NIF o CIF. null si no consta. |
|
nombre |
string | Sí | Sí | Nombre o razón social, sin concatenar con los apellidos. null si no consta. |
|
apellidos |
string | Sí | Sí | Apellidos. null si no consta. |
Esquema PersonaAsignada
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
id |
integer | No | Sí | Identificador de la persona asignada. | |
nombre |
string | Sí | Sí | Nombre. null si no consta. |
|
apellidos |
string | Sí | Sí | Apellidos. null si no consta. |
Esquema CatalogoOpcional
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
id |
integer | No | Sí | Identificador del elemento del catálogo. | |
nombre |
string | Sí | Sí | Nombre del elemento del catálogo. null si no consta. |
Esquema DireccionMontaje
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
id |
integer | No | Sí | Identificador de la dirección. | |
tipo_via |
CatalogoOpcional | Sí | Sí | Tipo de vía. null si no consta o no existe. |
|
direccion |
string | Sí | Sí | Nombre de la vía. null si no consta. |
|
numero |
string | Sí | Sí | Número de la vía. null si no consta. |
|
escalera |
string | Sí | Sí | Escalera. null si no consta. |
|
piso |
string | Sí | Sí | Piso. null si no consta. |
|
letra |
string | Sí | Sí | Letra o puerta. null si no consta. |
|
codigo_postal |
string | Sí | Sí | Código postal. null si no consta. |
|
municipio |
CatalogoOpcional | Sí | Sí | Municipio. null si no consta o no existe. |
|
provincia |
CatalogoOpcional | Sí | Sí | Provincia. null si no consta o no existe. |
Esquema Error
| Campo | Tipo | Nulo | Obligatorio | Valores | Descripción |
|---|---|---|---|---|---|
message |
string | No | Sí | Mensaje legible del error, sin detalles internos. |
Errores
Todas las respuestas de error usan la misma estructura JSON:
{
"message": "Descripción legible del error."
}
El 422 añade errors, con los mensajes de cada parámetro rechazado. Ningún error revela
consultas, nombres internos, rutas del servidor ni detalles técnicos.
Toda respuesta, también las de error, lleva la cabecera X-Request-Id. Si necesita ayuda con
una petición concreta, facilite ese valor: permite localizarla sin exponer datos.
Códigos
| Código | Causa | Qué hacer |
|---|---|---|
401 |
Sin credencial, o credencial inválida, caducada o revocada | Revise la cabecera Authorization; si persiste, pida una credencial nueva |
403 |
Credencial válida sin el permiso de la ruta | Pida al administrador que añada el permiso |
404 |
Recurso inexistente o identificador no válido | Compruebe el identificador; no reintente |
405 |
Método distinto de GET (incluido HEAD) |
Use GET |
422 |
La petición lleva parámetros de consulta | Quite todos los parámetros de la URL |
429 |
Más de 60 llamadas por minuto de su integración | Espere y reintente más tarde |
500 |
Error interno | Reintente más tarde; si persiste, avise facilitando el X-Request-Id |
En GET y HEAD las comprobaciones se hacen en este orden: credencial (401), método (405,
solo HEAD), permiso (403), parámetros (422) y, por último, existencia del recurso (404).
Sin credencial ni permiso nunca sabrá si un identificador existe. Los demás métodos (POST,
PUT, DELETE…) responden 405 directamente, sin revelar nada.
401 y 403
Los mensajes de 401, 403, 429 y 500 dependen del idioma configurado en la API: los textos
de los ejemplos son orientativos. Identifique el error por el código, no por el mensaje.
{
"message": "Unauthenticated."
}
404
Las rutas por identificador responden 404 cuando el elemento no existe y también cuando el
identificador no es un entero positivo escrito sin signo, ceros a la izquierda ni espacios (abc,
0, -5, 007). En proyectos, también cuando el proyecto no está en PREPRODUCCIÓN ni
PRODUCCIÓN. Nunca se devuelve un elemento vacío. Los mensajes son fijos:
| Ruta | Mensaje |
|---|---|
GET /api/v1/contactos/{id} |
Contacto no encontrado. |
GET /api/v1/articulos/{id} |
Artículo no encontrado. |
GET /api/v1/proyectos/{id} |
Proyecto no encontrado. |
405
Solo se admite GET. El resto de métodos responde 405 con el mensaje Método no permitido. y la
cabecera Allow: GET. En HEAD la credencial se comprueba antes: sin credencial válida responde
401, y con ella, 405 sin cuerpo.
422
Ninguna ruta admite parámetros de consulta, ni siquiera los que algunos clientes añaden para
evitar cachés. Cualquiera responde 422:
{
"message": "Este parámetro no está permitido.",
"errors": {
"desde": [
"Este parámetro no está permitido."
]
}
}
429 y 500
El límite es de 60 llamadas por minuto por integración, compartido por todas las rutas. Tras un
429, espere antes de reintentar. Un 500 no hace avanzar la entrega incremental: puede repetir
la llamada más tarde sin perder cambios.