Skip to content

Mapping Templates API

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

Purpose

Define the translation between your ERP's native payload and the document envelope Complifly submits, so the ERP never has to produce the envelope itself.

Audience

Integration developers and implementation consultants.

Prerequisites

  • API Authentication — these endpoints use a user token, not a machine credential
  • A real sample payload from the ERP, unmodified
  • Knowledge of the ERP's date format and coded values

Building a template by hand?

This page is the REST interface. If you are building the mapping in the product instead, Build a Mapping Template is the screen-by-screen procedure for the same capability.

Reference

Base path: /api/admin/mapping-templates

The endpoints

Method Path Purpose
GET / List templates
GET /{id} One template with its rules
POST / Create a template
PUT /{id}/rules Replace the rule set
PATCH /{id} Update template attributes
DELETE /{id} Delete a template
POST /extract-fields Discover the field paths in a sample payload

The model

A template represents one ERP integration — typically one per ERP and company combination. It holds rules, each translating one source field to one target field.

Field Purpose
templateName Unique within the company
erpType A label: SAP, D365, Tally, Oracle, Custom
description Free text; use it to say which system and which company
sample_payload A stored sample, for reference while editing
is_active An inactive template cannot be used at ingest

The four transform types

direct — copy the value unchanged. Supports dot notation into nested structures.

{ "erpFieldPath": "seller.address.pincode",
  "nicFieldPath": "SellerDtls.Pin",
  "transformType": "direct" }

date — convert from the ERP's format to the envelope's DD/MM/YYYY. Declare the source format:

{ "erpFieldPath": "DOCDATE",
  "nicFieldPath": "DocDtls.Dt",
  "transformType": "date",
  "erpDateFormat": "M/D/YYYY h:mm:ss AM" }

Get this exactly right. A wrong format token does not usually fail — it silently produces the wrong date, which passes validation and produces a legally wrong document. Test with an unambiguous date such as the fifth of March, where a transposition is visible.

static — supply a fixed value regardless of the payload. Useful for a constant the ERP does not carry.

lookup — translate a coded value through a map, with a default:

{ "erpFieldPath": "DOCTYPE",
  "nicFieldPath": "DocDtls.Typ",
  "transformType": "lookup",
  "lookupMap": { "0": "INV", "1": "CRN", "2": "DBN" },
  "lookupDefault": "INV" }

Choose lookupDefault deliberately. A default that quietly turns an unrecognised code into a tax invoice will route documents to the wrong pipeline and register things that should not be registered. Where any unrecognised value is a genuine error, prefer a default that fails validation over one that guesses.

Array handling

Line items map with index notation, for example ItemList[0].SlNo. Multi-line documents are expanded from the source array.

Always test with a multi-line document. A single-line sample hides every array-handling problem, and those problems appear on the first real invoice.

Rule order

Rules are applied in a defined order. Where one rule's output feeds another, order matters; where they are independent, it does not. Keep the order meaningful for a human reading the template later.

Building a template

Step Action
1 Obtain a raw, unmodified sample from the ERP, including its quirks
2 Use extract-fields to discover the addressable paths
3 Create the template
4 Add rules, starting with the required fields
5 Test with the sample and inspect the mapped payload
6 Test with edge cases: export, reverse charge, zero-rated, discounts, multi-line
7 Activate

Step 1 is the one most often compromised. A hand-cleaned sample produces a template that works in testing and fails on real documents.

Validation

Check Method Pass condition
Every required field is mapped Ingest a real document Accepted, with no missing-field errors
Dates convert correctly Use a date such as 05/03 Stored as the intended date, not transposed
Coded values translate Send one document of each type Each routes correctly
The lookup default is safe Send an unrecognised code Produces the intended outcome, not a silent misclassification
Multi-line documents work Send a document with several lines Every line present, in order, with correct values
Nested paths resolve Check a deeply nested field Correct value
Edge cases work Send export, reverse charge and discounted documents All accepted, with correct values
Amounts are numeric Inspect the mapped payload No formatted strings
Inactive templates are refused Deactivate and attempt ingest Refused
The mapped payload is inspected Review it directly Every field carries the intended value

Inspecting the mapped payload is the highest-value check on this page. Acceptance proves the document was valid; only the payload proves it was correct.

Troubleshooting

Symptom Cause Action
A field arrives empty Path wrong, or the ERP omits it for this document type Compare the rule's path against the raw payload
Dates a month out Format token does not match the ERP's real format Correct and re-test with an unambiguous date
All documents become tax invoices Lookup default too permissive Choose a default that fails rather than guesses
Documents route to the wrong pipeline The mapped type value is not what you expect Routing reads the mapped value, not the ERP's original
Only the first line appears Array notation wrong, or the source array path is wrong Test with a multi-line document
Works in testing, fails on real documents The sample was hand-cleaned Use raw ERP output
A template change broke everything Changed without re-testing Test every template change against real documents before activating
Ingest refused with a template error Template inactive, deleted, or the wrong identifier in the URL Confirm the identifier and its active state
Amounts rejected Mapped as formatted strings Map to numeric values
Two ERPs interfere One template shared between them One template per ERP and company combination