Ir al contenido

Desarrolladores

Proveedores

Facturas recibidas extraídas por el flujo de documentos.

GET /suppliers

Listar facturas recibidas

Facturas de compra extraídas por el flujo de lectura de documentos. Los filtros de fecha se aplican a `createdAt` (fecha de entrada), no a la fecha de la factura.

Permiso exigido: purchases:documents.read (Compras › Facturas de proveedor y gastos › Leer)

Paginación: Parámetros page y limit. La respuesta incluye total, page, limit, hasMore.

Parámetros

NombreEnTipoDescripción
statequerystringEstado en el flujo de entrada de documentos, p. ej. BOOKED o NEEDS_REVIEW.
needsReviewqueryboolean
dateFromquerystring (date)
dateToquerystring (date)
pagequeryinteger
Por defecto: 1
limitqueryinteger
Por defecto: 50 · máximo: 500

Respuestas

200 Lista de facturas recibidas · application/json

NombreTipoDescripción
itemsobject[]
items[].idstring
items[].companyIdstring
items[].filenamestring
items[].confidencenumber
puede ser null
items[].statestring
items[].needsReviewboolean
items[].createdAtstring (date-time)
items[].updatedAtstring (date-time)
totalintegerTotal de elementos que cumplen el filtro.
pageintegerPágina devuelta (empieza en 1).
limitintegerTamaño de página aplicado.
hasMorebooleanHay más páginas después de esta.

401 Falta el token Bearer o no es válido. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

403 El token no tiene el permiso exigido o el recurso queda fuera de su alcance. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

429 Se ha alcanzado un límite de uso. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

Ejemplos

curl
curl -X GET "https://app.bm.consulting/api/v1/suppliers?limit=50" \
  -H "Authorization: Bearer $BMC_TOKEN"
TypeScript (fetch)
const res = await fetch("https://app.bm.consulting/api/v1/suppliers?limit=50", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BMC_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
Python (requests)
import os
import requests

res = requests.get(
    "https://app.bm.consulting/api/v1/suppliers?limit=50",
    headers={"Authorization": f"Bearer {os.environ['BMC_TOKEN']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()

GET /suppliers/items/{id}

Consultar una factura recibida

Detalle extraído completo, con los campos de cada línea. Responde 404 si el elemento queda fuera del alcance del token.

Permiso exigido: purchases:documents.read (Compras › Facturas de proveedor y gastos › Leer)

Paginación: Sin paginación: devuelve el conjunto completo.

Parámetros

NombreEnTipoDescripción
idobligatoriorutastring

Respuestas

200 Factura recibida · application/json

NombreTipoDescripción
idstring
companyIdstring
filenamestring
confidencenumber
puede ser null
issuerNifstring
puede ser null
issuerNamestring
puede ser null
invoiceNumberstring
puede ser null
invoiceDatestring (date)
dueDatestring (date)
puede ser null
baseAmountnumber
puede ser null
vatAmountnumber
puede ser null
totalnumber
puede ser null
currencystring
statestring
linesobject[]
lines[].descriptionstring
puede ser null
lines[].quantitynumber
puede ser null
lines[].unitPricenumber
puede ser null
lines[].lineTotalnumber
puede ser null
lines[].vatRatenumber
puede ser null
lines[].taxCodestring
puede ser null
Código de régimen del SII
lines[].accountCodestring
puede ser null
Código de cuenta del PGC
fileUrlstring (uri)Se canjea por una descarga firmada con GET /suppliers/items/{id}/file.

401 Falta el token Bearer o no es válido. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

403 El token no tiene el permiso exigido o el recurso queda fuera de su alcance. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

404 El recurso no existe o queda fuera del alcance del token. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

429 Se ha alcanzado un límite de uso. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

Ejemplos

curl
curl -X GET "https://app.bm.consulting/api/v1/suppliers/items/<id>" \
  -H "Authorization: Bearer $BMC_TOKEN"
TypeScript (fetch)
const res = await fetch("https://app.bm.consulting/api/v1/suppliers/items/<id>", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BMC_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
Python (requests)
import os
import requests

res = requests.get(
    "https://app.bm.consulting/api/v1/suppliers/items/<id>",
    headers={"Authorization": f"Bearer {os.environ['BMC_TOKEN']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()

GET /suppliers/items/{id}/file

Descargar el fichero de una factura recibida

Redirige a una URL firmada de corta duración con el fichero original.

Permiso exigido: purchases:documents.read (Compras › Facturas de proveedor y gastos › Leer)

Paginación: Sin paginación: devuelve el conjunto completo.

Parámetros

NombreEnTipoDescripción
idobligatoriorutastring

Respuestas

302 Redirección a una URL de descarga firmada

401 Falta el token Bearer o no es válido. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

403 El token no tiene el permiso exigido o el recurso queda fuera de su alcance. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

404 El recurso no existe o queda fuera del alcance del token. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

429 Se ha alcanzado un límite de uso. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

Ejemplos

curl
curl -X GET "https://app.bm.consulting/api/v1/suppliers/items/<id>/file" \
  -H "Authorization: Bearer $BMC_TOKEN"
TypeScript (fetch)
const res = await fetch("https://app.bm.consulting/api/v1/suppliers/items/<id>/file", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BMC_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
Python (requests)
import os
import requests

res = requests.get(
    "https://app.bm.consulting/api/v1/suppliers/items/<id>/file",
    headers={"Authorization": f"Bearer {os.environ['BMC_TOKEN']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()

POST /ingest/batches

Subir un documento de compra

Subida multipart de una factura de compra (PDF o imagen). Si el fichero es idéntico a uno ya subido (SHA-256), responde 200. `companyId` sale del token. Lectura a máquina: con su propio token ligado a su cuenta, un documento enviado sin `consent` entra en la cola de OCR y extracción, salvo que su cuenta haya pedido que solo lo traten personas; con `consent=AI_AUTO` se lee también entonces (manda su elección para ese documento); con `consent=HUMAN_ONLY` no se lee nunca. Los tokens internos de BMC (el equipo de BMC, sus agentes y la pasarela MCP) necesitan `consent=AI_AUTO` u `origen=email` explícitos, y nunca pueden saltarse que su cuenta haya pedido que solo lo traten personas. Un documento que no se lee se guarda y lo completa una persona (`status: NEEDS_REVIEW`). La respuesta nunca oculta que no se ha leído: `lectura: "en_cola"` cuando está en cola para leerse, o `lectura: "no"` con un `motivo` de una lista cerrada: `sin_consentimiento` (token interno, sin consentimiento ni origen), `origen_sin_eleccion` (token interno, un canal distinto del correo y sin consentimiento), `cuenta_solo_personas` (la cuenta pidió que solo lo traten personas), `human_only` (consent=HUMAN_ONLY), `propietario_sin_resolver` (no se puede saber de qué cuenta es: no se lee nunca), `origen_no_verificado` (token interno, `origen=email` sin referencia a un correo de la misma cuenta). `origen=email` solo cuenta con `threadAttachmentId` o `messageId` de un correo de la misma cuenta. `consentimiento` lleva la decisión: consent, origen, llamante (cliente | interno) y origenVerificado.

Permiso exigido: documents:ingest.create (Documentos › Lectura automática de documentos › Crear)

Paginación: Sin paginación: devuelve el conjunto completo.

Cuerpo de la petición multipart/form-data

NombreTipoDescripción
fileobligatoriostring (binary)El contenido del documento.
filenamestring
consentstringSi el documento se puede leer a máquina. Con su token ligado a su cuenta: sin indicar, se lee, salvo que su cuenta haya pedido que solo lo traten personas; AI_AUTO, se lee también entonces; HUMAN_ONLY, no se lee nunca. Con tokens internos: sin indicar, no se lee, salvo con origen=email.
Valores: AI_AUTO, HUMAN_ONLY
origenstringCanal por el que llegó el documento. Solo decide con tokens internos: un correo se lee salvo que la cuenta haya pedido que solo lo traten personas, y solo con la referencia del correo (threadAttachmentId o messageId); cualquier otro canal, solo con consentimiento AI_AUTO.
Valores: email, subir, data_room, desconocido
threadAttachmentIdstringCon origen=email: el adjunto del correo de origen. Tiene que existir y ser de la misma cuenta.
messageIdstringCon origen=email: el mensaje de correo de origen, si no se envía threadAttachmentId. Tiene que existir y ser de la misma cuenta.

Respuestas

200 Duplicado: ya se había recibido un fichero idéntico

201 Fichero aceptado (devuelve batchId e itemId, `lectura`, `motivo` y `consentimiento`): `status: QUEUED` y `lectura: "en_cola"` cuando se lee a máquina; `status: NEEDS_REVIEW` y `lectura: "no"` con su `motivo` cuando lo completa una persona

400 Falta el fichero, su tipo no se admite o es demasiado grande · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

401 Falta el token Bearer o no es válido. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

403 El token no tiene el permiso exigido o el recurso queda fuera de su alcance. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

429 Se ha alcanzado un límite de uso. · application/json

NombreTipoDescripción
errorstringMensaje de error legible
required_permissionstringSolo en el 403: el permiso que falta (área:recurso.acción)

Ejemplos

curl
curl -X POST "https://app.bm.consulting/api/v1/ingest/batches" \
  -H "Authorization: Bearer $BMC_TOKEN" \
  -F "file=@documento.pdf"
TypeScript (fetch)
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("documento.pdf")]), "documento.pdf");

const res = await fetch("https://app.bm.consulting/api/v1/ingest/batches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BMC_TOKEN}`,
  },
  body: form,
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
Python (requests)
import os
import requests

res = requests.post(
    "https://app.bm.consulting/api/v1/ingest/batches",
    headers={"Authorization": f"Bearer {os.environ['BMC_TOKEN']}"},
    files={"file": open("documento.pdf", "rb")},
    timeout=30,
)
res.raise_for_status()
data = res.json()
Reservar primera reunión gratuita