AGT Mock API — Endpoint Documentation

Professional reference for AGT integration endpoints, authentication model, payload structure, expected responses, and implementation notes.

1. Overview

This API simulates AGT electronic invoicing workflows. It supports invoice submission, submission status lookup, series requests, series listing, and callback testing.

The API is divided into two main groups:

Admin API — used by the administration console with JWT authentication.
AGT API — used by POS/invoicing integrations with Basic Authentication per company credential.

2. Base URL

              http://127.0.0.1:8080
            

3. Authentication

3.1 Admin endpoints

All /api/admin/* routes require JWT Bearer authentication.

                Authorization: Bearer <jwt-token>
              

3.2 AGT endpoints

All /sigt/fe/v1/* routes require company Basic Authentication, except where your backend explicitly allows otherwise.

                Authorization: Basic <base64(username:password)>
              

The frontend generates these credentials in the Credentials section and stores them by company.

4. Common AGT Request Envelope

Most AGT requests in this project use a shared top-level structure. Even endpoints like obterEstado and solicitarSerie may require this envelope depending on backend validation.

              { "schemaVersion": "1.2", "submissionUUID":
              "641fca42-95c4-4e5f-9646-7e6c3dd13b65", "taxRegistrationNumber":
              "5000000010", "submissionTimeStamp": "2026-04-20T22:30:23.839Z",
              "softwareInfo": { "softwareInfoDetail": { "productId":
              "ENGINE-INVOICE", "productVersion": "2.0.0",
              "softwareValidationNumber": "C_134", "signatureVersion": 1 },
              "jwsSoftwareSignature": "header.payload.signature" } }
            

Field	Type	Description
schemaVersion	string	Version of the AGT request schema. Example: `1.2`.
submissionUUID	string (UUID)	Unique request identifier generated client-side for traceability.
taxRegistrationNumber	string	Company NIF associated with the authenticated credential.
submissionTimeStamp	ISO datetime	Timestamp of request creation.
softwareInfo	object	Software identification and JWS signature metadata.
softwareInfoDetail.productId	string	Software product identifier.
softwareInfoDetail.productVersion	string	Software version used to generate the request.
softwareInfoDetail.softwareValidationNumber	string	Validation number assigned to the invoicing software.
softwareInfoDetail.signatureVersion	integer	Signature format version.
jwsSoftwareSignature	string	JWS string in `header.payload.signature` format.

5. Endpoint: registarFactura

POST /sigt/fe/v1/registarFactura

Submits one or more fiscal documents for processing and validation.

Request payload

              { "schemaVersion": "1.2", "submissionUUID":
              "641fca42-95c4-4e5f-9646-7e6c3dd13b65", "taxRegistrationNumber":
              "5000000010", "submissionTimeStamp": "2026-04-20T22:30:23.839Z",
              "softwareInfo": { "softwareInfoDetail": { "productId":
              "ENGINE-INVOICE", "productVersion": "2.0.0",
              "softwareValidationNumber": "C_134", "signatureVersion": 1 },
              "jwsSoftwareSignature": "header.payload.signature" },
              "numberOfEntries": 1, "documents": [ { "documentNo":
              "FT6325S2C/10001", "documentStatus": "N", "jwsDocumentSignature":
              "header.payload.signature", "documentDate": "2026-04-20",
              "documentType": "FT", "eacCode": "46900", "systemEntryDate":
              "2026-04-20T22:30:23.839Z", "customerTaxID": "999999999",
              "customerCountry": "AO", "companyName": "Consumidor Final",
              "lines": [ { "lineNumber": 1, "operationType": "TB",
              "productCode": "PROD-001", "productDescription": "Produto via
              Frontend", "quantity": 1, "unitOfMeasure": "UN", "unitPriceBase":
              500, "unitPrice": 500, "debitAmount": 0, "creditAmount": 500,
              "taxes": [ { "taxType": "IVA", "taxCountryRegion": "AO",
              "taxCode": "NOR", "taxPercentage": 14, "taxContribution": 70 } ],
              "settlementAmount": 0 } ], "documentTotals": { "netTotal": 500,
              "taxPayable": 70, "grossTotal": 570 }, "withholdingTaxList": [] }
              ] }
            

Success response example

              { "requestID": "REQ00000000001", "errorList": [] }
            

Validation error example

              { "errorList": [ { "idError": "E08", "descriptionError":
              "jwsSoftwareSignature must be a valid JWS (3 Base64URL parts
              separated by dots).", "documentNo": null } ] }
            

Notes

numberOfEntries should match the number of documents sent.
The NIF in the payload should match the company credential used in Basic Auth.
jwsSoftwareSignature and jwsDocumentSignature must have valid JWS structure.
Totals should be coherent with lines and tax values.

6. Endpoint: obterEstado

POST /sigt/fe/v1/obterEstado

Retrieves the processing status of a previously submitted request.

Request payload

              { "schemaVersion": "1.2", "submissionUUID":
              "1b49c6d8-22bc-48a8-b0fc-e6ddbd90f928", "taxRegistrationNumber":
              "5000000010", "submissionTimeStamp": "2026-04-21T01:10:00.000Z",
              "softwareInfo": { "softwareInfoDetail": { "productId":
              "ENGINE-INVOICE", "productVersion": "2.0.0",
              "softwareValidationNumber": "C_134", "signatureVersion": 1 },
              "jwsSoftwareSignature": "header.payload.signature" }, "requestID":
              "REQ00000000001" }
            

Success response example

              { "requestID": "REQ00000000001", "resultCode": 0, "resultMessage":
              "Processed successfully", "documentStatusList": [ { "documentNo":
              "FT6325S2C/10001", "documentStatus": "V", "errorList": [] } ] }
            

Error example

              { "errorCode": "E96", "errorDescription": "Malformed request.
              Missing: schemaVersion, submissionUUID, taxRegistrationNumber,
              submissionTimeStamp, softwareInfo" }
            

Notes

Do not send only requestID if your backend validates the full AGT envelope.
Use the returned requestID from registarFactura.

7. Endpoint: solicitarSerie

POST /sigt/fe/v1/solicitarSerie

Requests a document series for a given document type and fiscal year.

Request payload

              { "schemaVersion": "1.2", "submissionUUID":
              "f06195dd-c254-43c9-b3c8-b97f52d3ee73", "taxRegistrationNumber":
              "5000000010", "submissionTimeStamp": "2026-04-21T01:15:00.000Z",
              "softwareInfo": { "softwareInfoDetail": { "productId":
              "ENGINE-INVOICE", "productVersion": "2.0.0",
              "softwareValidationNumber": "C_134", "signatureVersion": 1 },
              "jwsSoftwareSignature": "header.payload.signature" },
              "documentType": "FT", "year": 2026 }
            

Success response example

              { "series": "FT6325S2C", "documentType": "FT", "year": 2026,
              "status": "active" }
            

Error example

              { "errorList": [ { "idError": "E01", "descriptionError": "Missing
              required field: schemaVersion" } ] }
            

8. Endpoint: listarSeries

GET /sigt/fe/v1/listarSeries

Returns available document series for the authenticated company.

Request

This endpoint is defined as GET in your backend route list and usually relies on authentication context.

Success response example

              [ { "series": "FT6325S2C", "documentType": "FT", "year": 2026,
              "status": "active" }, { "series": "FR6325S2C", "documentType":
              "FR", "year": 2026, "status": "active" } ]
            

Notes

Because this is a GET route, avoid relying on JSON body payloads.
If the backend later requires a body here, the route design should be reconsidered.

9. Endpoint: callback

POST /sigt/fe/v1/callback

Simulates callback delivery so the client system can test status updates.

Request payload

              { "requestID": "REQ00000000001", "resultCode": 0,
              "taxRegistrationNumber": "5000000010", "documentStatusList": [ {
              "documentNo": "FT6325S2C/10001", "documentStatus": "V",
              "errorList": [] } ] }
            

Success response example

              { "success": true, "message": "Callback processed successfully." }
            

Important note

If the frontend is opened from a different origin, this endpoint may fail due to CORS until the backend allows that origin in config/cors.php.

10. Recommended Integration Flow

Authenticate admin in the frontend.
Create or load a company.
Generate company Basic Auth credentials.
Submit an invoice using registarFactura.
Read the returned requestID.
Check status with obterEstado.
Request or list series when needed.
Test callback delivery separately.

11. Common Problems

Missing credential — no saved Basic Auth for the selected company.
Token not provided — JWT missing on admin routes.
E08 invalid JWS — JWS fields are not in valid three-part structure.
E96 malformed request — backend expects the common AGT envelope.
CORS blocked — callback origin not allowed by backend CORS config.