bizAPIs V3

Previous Approach (v2)

In v2, each service had its own dedicated endpoint:

POST /v2/documents/at-divida
POST /v2/documents/nifName
POST /v2/documents/cpp

New Approach (v3)

In v3, all service calls go through a single endpoint, with the service name passed as a body parameter:

POST /v3/documents/processRequest

Endpoints

List Available Services

Returns all services enabled for the authenticated user's account.

Endpoint: GET /v3/documents/list-services

Response:

[
  {
    "serviceName": "at-aggregator",
    "serviceIdentifier": "AT-AGGREGATOR",
    "sourcePortalURL": "https://www.acesso.gov.pt/v2/loginForm?partID=PFAP&path=/geral/dashboard",
    "sourcePortal": "Autoridade Tributária",
    "region": {
      "countryPortal": "PT",
      "jurisdictionCode": "PT"
    },
    "servicePayload": {
      "user": "<nif para autenticação no portal>",
      "password": "<password para autenticação no portal>",
      "properties": {
        "demoMode": "false"
      }
    }
  }
]

Response Fields:

Field	Type	Description
`serviceName`	string	Internal name of the service
`serviceIdentifier`	string	Unique identifier for the service
`sourcePortalURL`	string	URL of the source portal
`sourcePortal`	string	Human-readable name of the source portal
`region`	object	Region configuration for the service
`region.countryPortal`	string	Country portal code
`region.jurisdictionCode`	string	Jurisdiction code
`servicePayload`	object	Template payload showing required fields

Process Request

Invokes the specified service with the provided parameters.

Endpoint: POST /v3/documents/processRequest

Request Body:

Field	Type	Required	Description
`serviceName`	string	Yes	The name of the service to invoke
`region`	object	Yes	Region configuration for the request
`region.countryPortal`	string	Yes	Country portal code (e.g., "PT")
`region.jurisdictionCode`	string	Yes	Jurisdiction code (e.g., "PT")
`payload`	object	Yes	Container for service-specific parameters
`payload.serviceRequestBody`	object	Yes	Service-specific request parameters

Example Request:

{
  "serviceName": "at-divida",
  "region": {
    "countryPortal": "PT",
    "jurisdictionCode": "PT"
  },
  "payload": {
    "serviceRequestBody": {
      "exampleBodyParameter1": "",
      "exampleBodyParameter2": 11
    }
  }
}

Migration Steps

Update your endpoint URL to use /v3/documents/processRequest
Move the service name from the URL path to the serviceName field in the request body
Add the region object with appropriate countryPortal and jurisdictionCode values
Wrap your existing request parameters inside payload.serviceRequestBody