API des factures fournisseurs

L’API des factures fournisseurs permet à un fournisseur d’envoyer ses factures à une société dans TrakIT depuis son propre système, au lieu de les saisir dans le portail externe. Elle fait ce que fait la page des factures du portail : créer une facture fournisseur, joindre la facture numérisée, la soumettre, corriger et soumettre à nouveau une facture rejetée, et lister les factures avec leur statut et leurs paiements. Les mêmes règles que dans le portail s’appliquent.

Point de terminaison	Ce qu’il fait
POST /api/public/createbill	Crée une facture fournisseur en brouillon.
POST /api/public/uploadbillfile	Joint un fichier à une facture fournisseur.
POST /api/public/submitbill	Soumet une facture fournisseur en brouillon à la société.
POST /api/public/updatebill	Modifie une facture fournisseur en brouillon ou rejetée.
GET /api/public/getbills	Liste les factures du fournisseur, avec leur statut et leurs paiements.

Fonctionnement d’une clé fournisseur

Chaque clé d’API est liée à trois éléments :

• un fournisseur : l’entité dont proviennent les factures ;
• une société : la société dans TrakIT à laquelle les factures sont adressées ;
• un utilisateur externe de ce fournisseur : la personne au nom de laquelle la clé agit.

Chaque facture et chaque fichier envoyés avec la clé sont enregistrés comme ajoutés par cet utilisateur externe. Les factures apparaissent dans le portail de cet utilisateur, et l’équipe financière de la société les voit comme des factures envoyées par le fournisseur, de la même façon que les factures envoyées via le portail. Le fournisseur et la société viennent toujours de la clé : une requête ne peut pas désigner un autre fournisseur ni une autre société.

Une clé ne fonctionne que tant que toutes ces conditions sont remplies :

• la clé est active et a l’autorisation du point de terminaison (voir le tableau ci-dessous) ;
• l’utilisateur externe est actif et toujours lié au fournisseur ;
• le fournisseur facture toujours cette société ;
• le rôle du portail de l’utilisateur externe permet l’action, dans ses sections Vendor Bills et Documents.

Autorisation de la clé	Point de terminaison	Action requise dans le rôle du portail
bill.create	createbill	Vendor Bills : Create
bill.update	updatebill	Vendor Bills : Update
bill.upload	uploadbillfile	Vendor Bills : Read, et Documents : Upload
bill.submit	submitbill	Vendor Bills : Submit Bill
bill.list	getbills	Vendor Bills : Read

Pour obtenir une clé, adressez-vous au support TrakIT. Le support configure la clé avec ses autorisations, la société et l’utilisateur externe du fournisseur. Un fournisseur qui facture deux sociétés a besoin d’une clé pour chacune.

Déroulement type

1. Créez la facture fournisseur avec createbill. Conservez le BillID renvoyé.
2. Joignez la facture numérisée avec uploadbillfile. Recommencez pour chaque fichier.
3. Soumettez la facture fournisseur avec submitbill. Elle passe à l’état Submitted et attend que la société l’accepte.
4. Suivez la facture fournisseur avec getbills : son statut, sa date d’échéance et ses paiements.
5. Si la société rejette la facture fournisseur, lisez ses Remarks pour en connaître la raison, corrigez-la avec updatebill, joignez au besoin un fichier corrigé, puis soumettez-la à nouveau.

Authentification

Envoyez la clé dans l’en-tête APIKey de chaque requête, en HTTPS :

APIKey: your-api-key

Ne mettez jamais la clé dans l’URL. Pour le fonctionnement des clés dans l’ensemble de l’API publique, voir Clés d’API.

Réponses

Chaque point de terminaison répond avec le statut HTTP 200 et la même enveloppe JSON :

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

Champ	Signification
Code	1 quand la requête a réussi, 0 quand elle a été refusée, -1 en cas d’erreur.
Info	La raison du refus, ou l’erreur. Vide en cas de succès.
RetInfo	Le résultat : une facture fournisseur, une liste de factures, ou un fichier.
RowsAffected	Pour getbills, le nombre de factures sur la page.
Identity	L’identifiant de ce qui a été créé ou modifié : la facture fournisseur, ou le fichier pour uploadbillfile.

Vérifiez toujours Code. Une requête refusée ne modifie rien.

Ces refus peuvent venir de n’importe quel point de terminaison :

Info	Signification
API Key Missing	L’en-tête APIKey est absent.
Key is disabled, not recognized or permission denied	La clé est incorrecte, désactivée, ou n’a pas l’autorisation du point de terminaison.
This API key is not set up for vendor billing	La clé n’a pas de fournisseur, de société ou d’utilisateur externe.
The vendor user must be an active external user linked to the vendor	L’utilisateur externe de la clé est verrouillé ou n’est plus lié au fournisseur.
The vendor does not bill that company	Le fournisseur ne facture plus la société de la clé.
The vendor user of this API key is locked or not permitted to do this	Le rôle du portail de l’utilisateur externe ne permet pas l’action.
Bill not found	Aucune facture fournisseur avec cet identifiant n’appartient au fournisseur et à la société de la clé.

Objet facture fournisseur

createbill, updatebill, submitbill et getbills renvoient les factures fournisseurs sous cette forme. Les dates sont au format yyyy-MM-dd.

{
  "BillID": 109827,
  "BillNumber": "INV-2026-0042",
  "BillDate": "2026-10-20",
  "DueDate": null,
  "CurrCode": "XOF",
  "Amount": 655000.00,
  "TaxAmount": 117900.00,
  "Total": 772900.00,
  "AdjTotal": 0.00,
  "PaidAmount": 0.00,
  "Outstanding": 772900.00,
  "Status": "Draft",
  "Remarks": "",
  "FileCount": 1,
  "Company": "Example Logistics SA"
}

Champ	Signification
BillID	L’identifiant de la facture fournisseur dans TrakIT. Utilisez-le dans les autres points de terminaison.
BillNumber	Le numéro de facture du fournisseur, en majuscules et sans espaces.
BillDate	La date de la facture.
DueDate	La date d’échéance, une fois fixée par la société. Sinon null.
CurrCode	La devise de la facture.
Amount	Le montant hors taxes.
TaxAmount	La taxe.
Total	Le montant facturé, taxes comprises.
AdjTotal	Les ajustements apportés par la société à la facture.
PaidAmount	Le montant payé jusqu’ici.
Outstanding	Le montant restant dû : Total + AdjTotal - PaidAmount.
Status	L’état de la facture : voir Statuts.
Remarks	Les remarques de la société au fournisseur, comme la raison d’un rejet.
FileCount	Le nombre de fichiers de la facture, y compris ceux ajoutés par la société.
Company	La société à laquelle la facture est adressée.

Statuts

Statut	Signification
Draft	Créée, pas encore soumise. Elle peut être modifiée et soumise.
Submitted	Envoyée à la société, en attente de son acceptation.
Received	Acceptée par la société, ou saisie par la société elle-même, et en cours de traitement.
Approved	Validée par la société. Les paiements suivent.
Disputed	La société conteste la facture. Voir Remarks.
Rejected	La société a renvoyé la facture. Voir Remarks, puis corrigez-la avec updatebill et soumettez-la à nouveau.

Quand plusieurs statuts s’appliquent, le premier dans cet ordre est affiché : Rejected, Approved, Disputed, Draft, Submitted, Received.

Nouvelles tentatives

Un numéro de facture ne peut être utilisé qu’une fois par fournisseur. Si une requête createbill expire et que vous ne savez pas si elle a abouti, recherchez la facture avec getbills?BillNumber=... avant de l’envoyer à nouveau. Sinon, un nouvel envoi renvoie Bill Number specified already exists for this entity and office.