API Santos Brezo

v1.0.0 · /api/v1 · Actualizada el

Estado en vivo no disponible sin JavaScript · comprobar /up

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 Authorization y, 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_modificacion más reciente.
  • Proyectos: conserve siempre la última recibida, no la de fecha_modificacion má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: false como 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) responde 404; 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, incluido HEAD, responde 405.
  • 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 como AAAA-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 null y 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_mas es true, 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 de fecha_modificacion má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

CabeceraValor
AuthorizationBearer {credencial}
Acceptapplication/json

Respuestas

CódigoCausaCabeceras
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

CampoTipoNuloObligatorioValoresDescripció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

Petición
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/contactos
Respuesta 200
{
    "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
    }
}
Respuesta 401
{
    "message": "Unauthenticated."
}

Mensaje orientativo: el texto depende del idioma configurado en la API.

Respuesta 403
{
    "message": "This action is unauthorized."
}

Mensaje orientativo: el texto depende del idioma configurado en la API.

Respuesta 422
{
    "message": "Este parámetro no está permitido.",
    "errors": {
        "desde": [
            "Este parámetro no está permitido."
        ]
    }
}
Respuesta 429
{
    "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/contactos es la misma que sin esta consulta.
  • No admite parámetros de consulta.
  • Orden de las comprobaciones: 401, 403, 422 y por último 404 (HEAD responde 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ámetroTipoNuloObligatorioValoresDescripció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

CabeceraValor
AuthorizationBearer {credencial}
Acceptapplication/json

Respuestas

CódigoCausaCabeceras
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

CampoTipoNuloObligatorioValoresDescripción
data Contacto No Sí El recurso solicitado, con la misma representación que cada elemento de la colección.

Ejemplos

Petición
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/contactos/10234
Respuesta 200
{
    "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
            }
        ]
    }
}
Respuesta 401
{
    "message": "Unauthenticated."
}

Mensaje orientativo: el texto depende del idioma configurado en la API.

Respuesta 403
{
    "message": "This action is unauthorized."
}

Mensaje orientativo: el texto depende del idioma configurado en la API.

Respuesta 404
{
    "message": "Contacto no encontrado."
}
Respuesta 422
{
    "message": "Este parámetro no está permitido.",
    "errors": {
        "desde": [
            "Este parámetro no está permitido."
        ]
    }
}
Respuesta 429
{
    "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_mas es true, 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 por id, conservando la de fecha_modificacion má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: false como 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

CabeceraValor
AuthorizationBearer {credencial}
Acceptapplication/json

Respuestas

CódigoCausaCabeceras
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

CampoTipoNuloObligatorioValoresDescripció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

Petición
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/articulos
Respuesta 200
{
    "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
    }
}
Respuesta 401
{
    "message": "Unauthenticated."
}

Mensaje orientativo: el texto depende del idioma configurado en la API.

Respuesta 403
{
    "message": "This action is unauthorized."
}

Mensaje orientativo: el texto depende del idioma configurado en la API.

Respuesta 422
{
    "message": "Este parámetro no está permitido.",
    "errors": {
        "desde": [
            "Este parámetro no está permitido."
        ]
    }
}
Respuesta 429
{
    "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/articulos es la misma que sin esta consulta.
  • No admite parámetros de consulta.
  • Orden de las comprobaciones: 401, 403, 422 y por último 404 (HEAD responde 405 tras el 401). Un identificador con formato no válido y uno inexistente responden igual.
  • precio es 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, y null si 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ámetroTipoNuloObligatorioValoresDescripció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

CabeceraValor
AuthorizationBearer {credencial}
Acceptapplication/json

Respuestas

CódigoCausaCabeceras
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

CampoTipoNuloObligatorioValoresDescripción
data Articulo No Sí El recurso solicitado, con la misma representación que cada elemento de la colección.

Ejemplos

Petición
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/articulos/48213
Respuesta 200
{
    "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"
        }
    }
}
Respuesta 401
{
    "message": "Unauthenticated."
}

Mensaje orientativo: el texto depende del idioma configurado en la API.

Respuesta 403
{
    "message": "This action is unauthorized."
}

Mensaje orientativo: el texto depende del idioma configurado en la API.

Respuesta 404
{
    "message": "Artículo no encontrado."
}
Respuesta 422
{
    "message": "Este parámetro no está permitido.",
    "errors": {
        "desde": [
            "Este parámetro no está permitido."
        ]
    }
}
Respuesta 429
{
    "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_mas es true, 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 por id, conservando siempre la última recibida (no la de fecha_modificacion má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) como AAAA-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 por id, e incluyen los elementos inactivos (activo: false).
  • Los pagos no imputados a ningún recibo no se entregan.
  • documentos es 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

CabeceraValor
AuthorizationBearer {credencial}
Acceptapplication/json

Respuestas

CódigoCausaCabeceras
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

CampoTipoNuloObligatorioValoresDescripció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

Petición
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/proyectos
Respuesta 200
{
    "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
    }
}
Respuesta 401
{
    "message": "Unauthenticated."
}

Mensaje orientativo: el texto depende del idioma configurado en la API.

Respuesta 403
{
    "message": "This action is unauthorized."
}

Mensaje orientativo: el texto depende del idioma configurado en la API.

Respuesta 422
{
    "message": "Este parámetro no está permitido.",
    "errors": {
        "desde": [
            "Este parámetro no está permitido."
        ]
    }
}
Respuesta 429
{
    "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_modificacion es el último cambio del proyecto o de sus datos propios, calculado igual que en GET /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/proyectos es la misma que sin esta consulta.
  • No admite parámetros de consulta.
  • Orden de las comprobaciones: 401, 403, 422 y por último 404 (HEAD responde 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ámetroTipoNuloObligatorioValoresDescripció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

CabeceraValor
AuthorizationBearer {credencial}
Acceptapplication/json

Respuestas

CódigoCausaCabeceras
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

CampoTipoNuloObligatorioValoresDescripción
data Proyecto No Sí El recurso solicitado, con la misma representación que cada elemento de la colección.

Ejemplos

Petición
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/proyectos/30512
Respuesta 200
{
    "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": []
    }
}
Respuesta 401
{
    "message": "Unauthenticated."
}

Mensaje orientativo: el texto depende del idioma configurado en la API.

Respuesta 403
{
    "message": "This action is unauthorized."
}

Mensaje orientativo: el texto depende del idioma configurado en la API.

Respuesta 404
{
    "message": "Proyecto no encontrado."
}
Respuesta 422
{
    "message": "Este parámetro no está permitido.",
    "errors": {
        "desde": [
            "Este parámetro no está permitido."
        ]
    }
}
Respuesta 429
{
    "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

CabeceraValor
AuthorizationBearer {credencial}
Acceptapplication/json

Respuestas

CódigoCausaCabeceras
200 Servicio operativo X-Request-Id
401 Token ausente o inválido X-Request-Id

Campos de la respuesta

CampoTipoNuloObligatorioValoresDescripció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

Petición
curl -H "Accept: application/json" -H "Authorization: Bearer 1|TOKEN-DE-EJEMPLO" https://api.santosbrezo.com/api/v1/status
Respuesta 200
{
    "data": {
        "status": "ok",
        "legacy": true
    }
}
Respuesta 401
{
    "message": "Unauthenticated."
}

Mensaje orientativo: el texto depende del idioma configurado en la API.

Esquema Contacto

CampoTipoNuloObligatorioValoresDescripció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

CampoTipoNuloObligatorioValoresDescripció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

CampoTipoNuloObligatorioValoresDescripció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

CampoTipoNuloObligatorioValoresDescripció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

CampoTipoNuloObligatorioValoresDescripció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

CampoTipoNuloObligatorioValoresDescripció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

CampoTipoNuloObligatorioValoresDescripció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

CampoTipoNuloObligatorioValoresDescripció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

CampoTipoNuloObligatorioValoresDescripció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.