Check an Excel file before importing it
Reads an Excel workbook (.xlsx) in the Archivio — a file attached to the chat is one — and reports what importing it into Anagrafiche WOULD do, writing nothing: the tab and header row found, how each column was read (read_as, null = not read), how many anagrafiche would be created, updated or left alone, and every row with a problem (Excel row, column, why). ANY list works: map the file’s own headers with columns and give every row a role with roles. Existing anagrafiche are matched by codice fiscale, else partita IVA, else name, and updated, never duplicated. Employee lists work too (Nome/Cognome, matricola, Responsabile, dates; the Custodo login is bound by e-mail). Repeat with a better mapping until the report is clean, then call anagrafiche_import_spreadsheet with EXACTLY the same arguments. It reads the file itself — no documents_get_content first. At most 2000 rows and 8 MB.
Examples
- Update the contacts with the customer list I attached GET /api/v1/rest/anagrafiche/imports/66666666-7777-4888-8999-aaaaaaaaaaaa/analysis?columns=%7B%22Cliente%22%3A%22name%22%2C%22Nazionalit%C3%A0%22%3A%22ignore%22%2C%22Classificazioni%22%3A%22tags%22%7D&roles=cliente
- Add only the new suppliers from this list and leave the ones I have alone GET /api/v1/rest/anagrafiche/imports/66666666-7777-4888-8999-aaaaaaaaaaaa/analysis?roles=fornitore&existing=skip
- Load our employees from this HR list, with their managers GET /api/v1/rest/anagrafiche/imports/66666666-7777-4888-8999-aaaaaaaaaaaa/analysis?columns=%7B%22Matr%22%3A%22employee_code%22%2C%22Resp.+diretto%22%3A%22manager%22%2C%22Assunto+il%22%3A%22hired_on%22%2C%22Reparto%22%3A%22custom.reparto%22%7D&roles=dipendente
Request
- Base URL: https://api.custodo.ai
- URL: https://api.custodo.ai/api/v1/rest/anagrafiche/imports/{document_id}/analysis
- Auth: HTTP bearer
Path parameters
The Archivio document holding the .xlsx workbook. A file attached to a Custode message is already in the Archivio: use the id the message lists. From another client, file it first with documents_upload.
Query parameters
The file’s own column headers, EXACTLY as the analysis lists them, mapped to the register’s fields — e.g. {"Cliente": "name", "Cod. Fiscale": "tax_code", "Nazionalità": "ignore"}. Only needed for headers the analysis did not recognise (read_as null) or read wrongly; "ignore" leaves a column unread. Every row needs name (the denominazione) — or, for a person, first_name/last_name. company is the company a PERSON belongs to, by its name. For an employee: employee_code (matricola), manager (their Responsabile’s name — another employee, in the register or in the file), hired_on, left_on. The organisation’s own fields are "custom.<key>", as the analysis lists them under custom_fields.
Roles EVERY row takes, on top of any «Ruoli» column: a list of customers → ["cliente"], of suppliers → ["fornitore"]. Keys from anagrafiche_list_roles.
A row whose anagrafica is ALREADY in the register — same codice fiscale, else same partita IVA, else same name — "update"s it (default: only cells that carry a value change anything; roles and labels are added, never removed; notes are never overwritten; the kind never changes) or is left alone with "skip". Either way nothing is duplicated.
false (default): one row with a problem blocks the whole import. true: the rows that pass are written and the others are left out and listed. Set it only after the person has seen which rows would be left out and agreed.
The tab to read, by name, when the workbook has several (the analysis lists them). A workbook of one tab needs nothing.
Headers
The organisation to act in. An API key is bound to exactly one, so this is optional for a key and must match the one it was minted for.
Response
Done. data is the tool’s own answer.
Changes
No recorded changes to this operation across all 1 revision of this API.