Skip to content

Build a Mapping Template

Applies to: e-Invoice · e-Way Bill · Which modules do I have?

Purpose

Walk through building a mapping template end to end, in the screens where the work actually happens. A mapping template is what lets your ERP post its own field names and its own value codes to Complifly and have them arrive as a valid NIC document — so nobody re-keys anything, and nobody has to change the ERP's data model to match NIC's.

This page is the procedure. Mapping Templates API is the same capability as a REST reference, for building templates programmatically.

Audience

Integration developers and implementation consultants building an ERP connection. You need someone alongside you who knows which table and field the ERP holds each value in — that person is usually not the same person who administers Complifly.

Prerequisites

  • An account that can open Administration in Complifly. Templates are scoped to your company: you see and edit only your own.
  • A machine credential for the ERP, created first — see Machine-to-Machine Auth. Nothing you build here can be called without one.
  • One real sample document exported from the ERP, in JSON or CSV, carrying the values it genuinely produces. Not a cleaned-up example — see step 2.
  • The ERP module licensed and enabled for the registrations you will send for.

Steps

1. Download the Complifly template and read what it asks for

Open Upload Invoice in the sidebar (/upload, shown as Template Center in the quick-access panel).

  1. Expand Tax Invoice – IRN Generation Template.
  2. Download the workbook closest to the transactions you are integrating. Eleven scenarios ship, and they differ in which fields are mandatory, not in formatting:
Workbook Use it for
B2B - Business to Business Regular Scenario The ordinary domestic sale — start here
B2B_SHP / B2B_DIS / B2B_CMB Ship-to, ship-from, and both together
B2B_REF_CON Purchase-order, contract and reference details
B2B_WPD With payment details
EXPWP / EXPWOP Export with / without payment of tax
SEZWP / SEZWOP SEZ supply with / without payment of tax
DEXP Deemed export

For e-Way Bills raised without an IRN — delivery challans, stock transfers, job work, bills of entry — the template lives on a different screen. Open Upload EWB (No IRN) (/ewb-doc/upload), complete the three declarations in Step 1, and the matching template appears for download in Step 2. The declarations gate the download deliberately: the template you get is specific to the processing route you declared.

The Template Builder button is a column previewer, not a template source

The Template Builder dialog on the upload screen lets you pick and reorder columns and show the resulting JSON schema. Its Save Draft and Preview buttons are not wired to anything in the current release. Use the downloaded workbooks above as your field list, and Template Builder only to explore what the columns are.

2. Extract those fields in your ERP — under your own names

Configure the ERP to emit every field the template marks mandatory for your scenario, plus the optional ones your business actually uses.

Do not rename anything to match NIC. That is what the mapping template is for, and doing it in the ERP puts the translation in the place hardest to change later. CustomerGSTRegNo, bill_to_gstin and KUNNR_GSTIN are all perfectly good ERP-side names.

Two rules decide whether the rest of this goes smoothly:

  • Export a raw sample, not a tidied one. The most common cause of an integration that passes testing and fails in production is a sample that was cleaned by hand first — trailing spaces removed, a date reformatted, a null replaced with an empty string. Map against what the ERP really emits.
  • Include at least one multi-line document in what you look at, so line-item paths are visible.

The extractor accepts either shape:

Sample format What you get in the editor
JSON Every leaf path, with its sample value beside it — customer.gstin, items[0].hsn. Arrays are read from their first element only, and nesting is followed to five levels. Anything deeper is not offered for mapping
CSV The header row, as flat column names. No sample values are shown, because only the header is read

3. Create the template

  1. Go to Administration → ERP Mapping.
  2. Click New Template.
  3. Fill in:
Field Guidance
Template name Required. Name it for the system and the environment — SAP S/4 Production, not Mapping 1. You will be reading this in a URL at 2 a.m.
ERP type Optional label, shown under the name in the template list
Description Optional. The right place to record which document types this template covers
  1. Click Create. Complifly opens the mapping editor for the new template immediately, and the header shows a Template #N badge. That number is the template ID you will put in the ingest URL in step 8.

Build one template per document shape, not one per ERP. A sales invoice and a credit note that carry different fields belong in different templates; the same invoice from two plants does not.

4. Load your ERP's fields into the editor

In the mapping editor, use the Step 1 — Load ERP fields strip:

  • Upload JSON / CSV — select the sample file you exported in step 2, or
  • Paste JSON — paste from the clipboard instead.

Complifly parses the sample and reports N ERP fields extracted. They appear in the left panel, each with its sample value, and that panel is your field inventory for the rest of the job.

If the count is far lower than you expect, the sample is the problem rather than the parser — an array with no elements contributes nothing, and a structure nested more than five deep is not walked.

5. Drag ERP fields onto NIC fields

The editor is two panels: ERP fields on the left, NIC fields on the right, grouped into NIC's sections — Transaction, Document, Seller, Buyer, Ship To, Dispatch From, Value, Payment, Reference, Export, E-Way Bill, Additional Doc and Line Item.

  1. Expand the NIC section you are filling.
  2. Drag a field from the left panel and drop it on the NIC field on the right. The target reads drop here until it holds a rule.
  3. The pair binds, the NIC row highlights, and a link icon appears beside the ERP field to mark it as used.
  4. To remove a rule, hover the NIC row and click the ✕.

A NIC field holds one rule. Dropping a second ERP field on the same NIC field replaces the first — it does not add to it.

Use the search box above both panels as you go. It filters left and right at once, matching ERP paths, sample values, NIC paths and the ERP field a NIC row is already mapped to. It is the fastest way to answer "have I mapped SubTyp yet?" without scrolling.

Line items map through the ItemList[0] section. Map them once, against index 0. At ingest time every line in the document is expanded from that one set of rules — you never map line 2.

6. Set the transform type on each rule

Every rule carries a type, in the type: dropdown that appears on the NIC row once a rule exists. Three are available in the editor.

direct — direct mapping. Copy the value across unchanged. The default for everything except known date fields, and the right answer whenever the ERP already holds the value in the form NIC expects.

date — date format mapping. Convert a date from the ERP's format into NIC's. Choosing date reveals a second dropdown: the format the ERP produces, not the one NIC wants.

DD/MM/YYYY · YYYY-MM-DD · YYYYMMDD · DD-MM-YYYY · MM/DD/YYYY · MM-DD-YYYY · YYYY/MM/DD · DD.MM.YYYY · YYYY-MM-DDTHH:mm:ss · YYYY-MM-DDTHH:mm:ssZ · M/D/YYYY h:mm:ss AM

Drop an ERP field onto a NIC field Complifly already knows to be a date — DocDtls.Dt, RefDtls.PORefDt, ExpDtls.ShipBDt, EwbDtls.TransDocDt, the batch dates — and the type is set to date for you, with DD/MM/YYYY pre-selected. Pre-selected is not verified. If your ERP emits 2026-05-26 and you leave the default, every date is wrong, and for the first twelve days of any month it is wrong silently: 05/06/2026 is a real date read either way. Pick a test date where day and month cannot be confused, such as the 26th.

lookup — value mapping. Translate the ERP's codes into NIC's. This is the type that decides whether documents are classified correctly, and it is where a mapping quietly goes wrong. Choosing lookup opens a small editor with two parts:

  • The map — one row per ERP value and the NIC value it becomes: SALE → INV, CREDIT → CRN, DEBIT → DBN, or 0 → INV, 1 → CRN, 2 → DBN.
  • The default — what happens to a value that is not in the map. Leave it empty and the raw ERP value passes straight through, unchanged.

Set the default deliberately. A pass-through default means a new document kind added in the ERP next year arrives at NIC as itself, is rejected, and the failure is at least visible. A default of INV means it arrives as a tax invoice, is accepted, and is wrong on a return nobody re-reads. Prefer the option that fails.

A fourth type, static, exists in the API only

Rules with transformType: "static" — a constant written into every document regardless of the ERP payload — are honoured by the ingest engine and can be created through the API, but the editor's type dropdown offers only direct, date and lookup. A static rule created via the API survives editing the template in the UI; you simply cannot create one there.

7. Test the transform, then save

  1. Click Test in the header.
  2. Paste a sample ERP invoice JSON into the panel.
  3. Click Run Transform. The mapped NIC payload appears below.
  4. Read it field by field. "It produced output" is not the check; "BuyerDtls.Pos holds 27" is.
  5. Click Save Mapping. Complifly confirms N rules saved.

The test panel does not apply date conversion

The preview runs in your browser. It applies direct and lookup rules faithfully, but previews a date rule as a straight copy — the format you selected is not exercised. A date that looks untouched in the preview is expected, and tells you nothing about whether the format is right.

Dates are proved only by sending a document: post one to the sandbox and read DocDtls.Dt back from the ingested record. Use an unambiguous date, past the 12th of the month, so a day-month swap cannot hide.

Nothing is persisted until you click Save Mapping. Leaving the editor with unsaved drag-and-drop work discards it without a prompt.

8. Send documents through the template

Put the template ID from step 3 into the ingest URL:

POST /api/v1/ingest/invoice/mapped/12
X-API-Key: cfly_...
Content-Type: application/json

Batches go to the same path with /batch appended.

Complifly auto-detects the payload shape — you do not declare it, and all three work against the same template:

Shape you post Detected as Use when
{ "header": {…}, "items": [ {…}, {…} ] } Nested The explicit form. Prefer it for multi-line documents
{ …, "ItemList": [ {…}, {…} ] } Item list The ERP already nests its lines under ItemList
{ "DOCNO": …, "HSN": …, … } Flat A single-line document with no array at all

Header rules apply to the header object; rules targeting ItemList[0].* apply to every element of the array, expanding to ItemList[0], ItemList[1] and so on.

Then handle the response exactly as The Integration Pattern sets out — in particular, never retry a 422, a 409 or a 403.

Validation

A template is ready when all of these hold. Check them in order; each can pass while the next fails.

# Check Pass condition
1 Every mandatory field for your scenario is mapped The NIC panel shows a rule on each one. The section badges count them for you
2 The rule count is what you expect The header badge and the N rules saved toast agree with the mapped-pairs list at the foot of the editor
3 Dates are correct on an ingested document Post one to the sandbox dated past the 12th, then read the stored value back. Not from the test panel — it does not convert dates
4 Every lookup covers every code the ERP can emit Ask the ERP owner for the full code list, not the codes that happen to be in your sample
5 An unmapped lookup value fails rather than defaulting Post a document carrying a deliberately unknown code and confirm it is rejected, not silently classified
6 A multi-line document expands Post one with three lines; confirm itemsIngested is 3, not 1
7 The template ID in the ERP's URL is this template POST …/mapped/{id} returns 201 with templateId echoed back, matching the Template #N badge
8 A rejection is legible Force a 422 and confirm the errors[] array names the field, so whoever fixes it knows where to look

Troubleshooting

Symptom Cause Action
Left panel empty after uploading a sample The file parsed but yielded no leaves — usually an empty array, or the payload sitting deeper than five levels inside an ERP wrapper Export a sample containing at least one populated line, flattened enough to be walked
Far fewer fields extracted than the ERP emits Arrays are read from element [0] only; nesting stops at five levels Not a defect. Map from [0] — every line is expanded at ingest
CSV sample shows no sample values Only the header row is read for CSV Expected. Use JSON if you need to see values while mapping
Dropping a field replaced an existing mapping A NIC field holds exactly one rule Intended. Map the other ERP field to a different NIC field, or reconsider which one belongs there
Dates land one day or one month out The date format describes NIC's format instead of the ERP's, or DD/MM/YYYY was left at its default Set the format the ERP produces, then re-test with a date past the 12th
Dates look unconverted in the Test panel The preview does not apply date conversion Expected. Verify by posting a document
Credit notes arrive as tax invoices Lookup default is permissive, so an unmapped code passed through or fell to INV Add the missing codes, and set the default so an unknown value fails
404 Mapping template N not found or inactive Wrong ID, template deactivated, or the credential belongs to a different company Confirm the Template #N badge, that the template is active, and that the credential is your company's
Only the first line reaches Complifly The payload is flat, or the lines sit under a key that is neither items nor ItemList Post one of the three detected shapes above
422 naming a field you are certain you mapped The rule targets a different NIC path than the validator requires, or the source value resolved empty — empty values are not written Run the Test panel and read the mapped payload at that exact path
Rules vanished after editing The editor was left without Save Mapping Redo and save. There is no autosave and no warning on exit
Changes had no effect on documents already sent A template applies at ingest; it does not re-transform stored documents Correct the template, then resend the affected documents