Skip to content

API Documentation

Applies to: All subscriptions

Purpose

Give an integration developer everything needed to build, test and ship an integration end to end — including correct handling of every documented failure — without access to Complifly's source and without a call to Complifly.

Audience

Integration developers, customer-side and partner-side.

Prerequisites

Steps

The API surfaces

Complifly exposes several distinct surfaces with different audiences and different authentication.

Surface Base path Audience Authentication
Ingest /api/v1/ingest ERP systems sending documents Machine credential
Integration (write-back) /api/v1/integration ERP systems receiving outcomes Machine credential
Mapping templates /api/admin/mapping-templates Integration developers configuring translation User token
Administration /api/admin Administrative tooling User token
Application /api/* The Complifly web application User token

Integrations should use the first two. The application surface exists to serve the product's own front end; it is not a supported integration contract and its shape follows the needs of the user interface.

Read the pages in this order

Page Covers
Conventions Request and response shapes, status codes, identifiers, idempotency
API Authentication Obtaining and presenting credentials on each surface
Ingest API Sending documents in, single and batch, raw and mapped
Write-back API Receiving compliance outcomes
Mapping Templates API Defining and testing ERP-to-platform translation
Administration API Users, credentials, feature and provider configuration
Endpoint Index The full inventory, by area
Rate Limits and Errors Limits, error envelope, retry policy

Five design properties to build against

Validation happens before the government call. A document that fails validation is rejected or quarantined without any provider call being made. Your integration will see a validation rejection far more often than a government rejection, and the two need different handling: validation failures name a field, government rejections carry a number.

A rejection is deterministic. Retrying it is waste. Retry transport failures and server errors; never retry a validation rejection or a duplicate. Each pointless retry consumes rate-limit headroom, and in the government's case, money.

Duplicates are permanent. The registration portal consumes a document number per supplier, type and year, permanently. A duplicate response is not a transient condition and will never succeed on retry.

Write-back is pull-or-push, asynchronous, and at-least-once. Compliance completes whether or not your ERP is reachable. Events land in an outbox and are delivered later, possibly more than once. Your consumer must be idempotent on the event identifier.

GSTIN scope is the authorisation boundary. A credential may act only for the registrations in its scope. A forbidden response on ingest is almost always a scope mismatch, not a broken credential — worth distinguishing in your own error handling.

Validation

An integration is ready for production when it demonstrably handles all of these, tested in the sandbox:

Scenario Required behaviour
Successful ingest Records the returned identifier
Validation rejection Surfaces the failing fields to a human; does not retry
Duplicate Recognises it as terminal; does not retry
Forbidden Reports a scope problem, distinct from an authentication problem
Unauthorised Refreshes the credential and retries once
Rate limited Backs off and retries
Server error Retries with backoff, up to a bounded limit
Network timeout Retries, and reconciles by document status rather than assuming failure
Duplicate event delivery Processes once; the second delivery is a no-op
Out-of-order events Handled, or ordering is enforced by sequence

The timeout row is the one most often missed. A timeout does not mean the document was not accepted — it means you do not know. Reconcile by status before resending, or a retry becomes a duplicate.

Troubleshooting

Symptom Cause Action
HTTP 401 Credential invalid, expired, or clock drift See API Authentication
HTTP 403 on ingest Supplier registration outside the credential's scope Widen the scope deliberately, or send from the correct credential
HTTP 409 Duplicate document number Terminal. Do not retry
HTTP 422 Validation failure The response names the fields
HTTP 429 Rate limited Back off. See Rate Limits and Errors
No events on the write-back feed Write-back disabled, no subscription, or nothing has happened yet Check the flag and subscription first
Events delivered twice Delivery is at-least-once by design Make the consumer idempotent