API de facturas de proveedor

La API de facturas de proveedor permite que un proveedor envíe sus facturas a una empresa en TrakIT desde su propio sistema, en lugar de introducirlas en el portal externo. Hace lo mismo que la página de facturas del portal: crear una factura de proveedor, adjuntar la factura escaneada, enviarla, corregir y volver a enviar una factura rechazada, y listar las facturas con su estado y sus pagos. Se aplican las mismas reglas que en el portal.

Punto de conexión	Qué hace
POST /api/public/createbill	Crea una factura de proveedor en borrador.
POST /api/public/uploadbillfile	Adjunta un archivo a una factura de proveedor.
POST /api/public/submitbill	Envía a la empresa una factura de proveedor en borrador.
POST /api/public/updatebill	Modifica una factura de proveedor en borrador o rechazada.
GET /api/public/getbills	Lista las facturas del proveedor, con su estado y sus pagos.

Cómo funciona una clave de proveedor

Cada clave de API está vinculada a tres elementos:

• un proveedor: la entidad de la que proceden las facturas;
• una empresa: la empresa en TrakIT a la que van dirigidas las facturas;
• un usuario externo de ese proveedor: la persona en cuyo nombre actúa la clave.

Cada factura y cada archivo que se envían con la clave quedan registrados como añadidos por ese usuario externo. Las facturas aparecen en el portal de ese usuario, y el equipo financiero de la empresa las ve como facturas enviadas por el proveedor, igual que las facturas enviadas a través del portal. El proveedor y la empresa siempre proceden de la clave: una solicitud no puede indicar otro proveedor ni otra empresa.

Una clave solo funciona mientras se cumplan todas estas condiciones:

• la clave está activa y tiene el permiso del punto de conexión (véase la tabla siguiente);
• el usuario externo está activo y sigue vinculado al proveedor;
• el proveedor sigue facturando a esa empresa;
• el rol del portal del usuario externo permite la acción, en sus secciones Vendor Bills y Documents.

Permiso de la clave	Punto de conexión	Acción necesaria en el rol del portal
bill.create	createbill	Vendor Bills: Create
bill.update	updatebill	Vendor Bills: Update
bill.upload	uploadbillfile	Vendor Bills: Read, y Documents: Upload
bill.submit	submitbill	Vendor Bills: Submit Bill
bill.list	getbills	Vendor Bills: Read

Para obtener una clave, diríjase al soporte de TrakIT. El soporte configura la clave con sus permisos, la empresa y el usuario externo del proveedor. Un proveedor que factura a dos empresas necesita una clave para cada una.

Flujo habitual

1. Cree la factura de proveedor con createbill. Guarde el BillID que devuelve.
2. Adjunte la factura escaneada con uploadbillfile. Repita para cada archivo.
3. Envíe la factura de proveedor con submitbill. Pasa al estado Submitted y espera a que la empresa la acepte.
4. Siga la factura de proveedor con getbills: su estado, su fecha de vencimiento y sus pagos.
5. Si la empresa rechaza la factura de proveedor, lea sus Remarks para conocer el motivo, corríjala con updatebill, adjunte un archivo corregido si hace falta y vuelva a enviarla.

Autenticación

Envíe la clave en el encabezado APIKey de cada solicitud, por HTTPS:

APIKey: your-api-key

No ponga nunca la clave en la URL. Para saber cómo funcionan las claves en toda la API pública, consulte Claves de API.

Respuestas

Todos los puntos de conexión responden con el estado HTTP 200 y el mismo sobre JSON:

{
  "Code": 1,
  "Info": "",
  "RetInfo": { },
  "RowsAffected": 0,
  "Scalar": null,
  "Identity": 0
}

Campo	Significado
Code	1 si la solicitud ha tenido éxito, 0 si se ha rechazado, -1 si ha habido un error.
Info	El motivo del rechazo, o el error. Vacío si tiene éxito.
RetInfo	El resultado: una factura de proveedor, una lista de facturas o un archivo.
RowsAffected	En getbills, el número de facturas de la página.
Identity	El identificador de lo que se ha creado o modificado: la factura de proveedor, o el archivo en uploadbillfile.

Compruebe siempre Code. Una solicitud rechazada no modifica nada.

Estos rechazos pueden proceder de cualquier punto de conexión:

Info	Significado
API Key Missing	Falta el encabezado APIKey.
Key is disabled, not recognized or permission denied	La clave es incorrecta, está desactivada o no tiene el permiso del punto de conexión.
This API key is not set up for vendor billing	La clave no tiene proveedor, empresa o usuario externo.
The vendor user must be an active external user linked to the vendor	El usuario externo de la clave está bloqueado o ya no está vinculado al proveedor.
The vendor does not bill that company	El proveedor ya no factura a la empresa de la clave.
The vendor user of this API key is locked or not permitted to do this	El rol del portal del usuario externo no permite la acción.
Bill not found	Ninguna factura de proveedor con ese identificador pertenece al proveedor y a la empresa de la clave.

Objeto factura de proveedor

createbill, updatebill, submitbill y getbills devuelven las facturas de proveedor con esta forma. Las fechas tienen el formato yyyy-MM-dd.

{
  "BillID": 109827,
  "BillNumber": "INV-2026-0042",
  "BillDate": "2026-10-20",
  "DueDate": null,
  "CurrCode": "USD",
  "Amount": 1000.00,
  "TaxAmount": 150.00,
  "Total": 1150.00,
  "AdjTotal": 0.00,
  "PaidAmount": 0.00,
  "Outstanding": 1150.00,
  "Status": "Draft",
  "Remarks": "",
  "FileCount": 1,
  "Company": "Example Logistics SL"
}

Campo	Significado
BillID	El identificador de la factura de proveedor en TrakIT. Utilícelo en los demás puntos de conexión.
BillNumber	El número de factura del proveedor, en mayúsculas y sin espacios.
BillDate	La fecha de la factura.
DueDate	La fecha de vencimiento, cuando la empresa la fija. Si no, null.
CurrCode	La moneda de la factura.
Amount	El importe sin impuestos.
TaxAmount	El impuesto.
Total	El importe facturado, impuestos incluidos.
AdjTotal	Los ajustes que la empresa ha hecho en la factura.
PaidAmount	El importe pagado hasta ahora.
Outstanding	El importe pendiente: Total + AdjTotal - PaidAmount.
Status	En qué punto está la factura: véase Estados.
Remarks	Las observaciones de la empresa al proveedor, como el motivo de un rechazo.
FileCount	El número de archivos de la factura, incluidos los que haya añadido la empresa.
Company	La empresa a la que va dirigida la factura.

Estados

Estado	Significado
Draft	Creada, todavía no enviada. Se puede modificar y enviar.
Submitted	Enviada a la empresa, a la espera de que la acepte.
Received	Aceptada por la empresa, o introducida por la propia empresa, y en tramitación.
Approved	Validada por la empresa. Después vienen los pagos.
Disputed	La empresa la ha marcado como en disputa. Véase Remarks.
Rejected	La empresa ha devuelto la factura. Consulte Remarks, corríjala con updatebill y vuelva a enviarla.

Cuando se aplica más de un estado, se muestra el primero en este orden: Rejected, Approved, Disputed, Draft, Submitted, Received.

Reintentos

Un número de factura solo se puede usar una vez por proveedor. Si una solicitud createbill agota el tiempo de espera y no sabe si se ha completado, busque la factura con getbills?BillNumber=... antes de volver a enviarla. De lo contrario, un nuevo envío devuelve Bill Number specified already exists for this entity and office.