MEF Geographic Address Notification (Mef Lso Cantata Geographic Address Notification)
MEF Geographic Address Notification from MEF — 1 path(s) described in OpenAPI.
OpenAPI Specification
openapi: 3.0.1
info:
description: |
**This file forms part of Mplify 121.1**
This API implements Business Requirements described in Mplify 150
This draft represents Mplify work in progress and is subject to change
It allows the Buyer to retrieve address information from the Seller, including
exact formats, for addresses known to the Seller.
List of supported Use Cases:
- Send Notifications
Copyright 2025 Mplify Alliance and its contributors.
This file includes content based on the TM Forum Geographic Address API
(TMF673 v4.0.1) available at
https://github.com/tmforum-apis/TMF673_GeographicAddress, which is licensed
by the TM Forum under the Apache License version 2.0. Such content has been
modified by the Mplify Alliance and its contributors.
title: Geographic Address Notification
version: 2.0.0
servers:
- url: 'https://{serverBase}/mefApi/cantata/geographicAddressNotification/v2/'
variables:
serverBase:
default: mplify.net
description: The base of Buyer's URL.
tags:
- description: |
The Seller's endpoint to send particular event types notifications to.
name: Notification listeners
paths:
/listener/geographicAddressValidationStateChangeEvent:
post:
deprecated: false
description: >-
This endpoint is used to receive notifications on Geographic Address Validation state
change
operationId: listenToGeographicAddressValidationStateChangeEvent
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request when the responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/GeographicAddressValidationEvent'
required: true
responses:
'204':
description:
'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
'400':
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
description: Bad Request
'401':
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
description: Unauthorized
'403':
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
description: Forbidden
'500':
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
description: Internal Server Error
summary: Geographic Address Validation State Change Notification endpoint
tags:
- Notification listeners
components:
schemas:
Error:
description: >
Standard Class used to describe API response error
Not intended to be use directly. The `code` in the HTTP header is used
as a discriminator for the type of error returned in runtime.
properties:
reason:
description: >-
Text that explains the reason for error. This can be shown to a
client user.
maxLength: 255
type: string
message:
description: >-
Text that provide mode details and corrective actions related to the
error. This can be shown to a client user.
type: string
referenceError:
description: url pointing to documentation describing the error
format: uri
type: string
required:
- reason
type: object
Error400:
allOf:
- $ref: '#/components/schemas/Error'
- properties:
code:
description: >-
One of the following error codes:
- missingQueryParameter: The URI is missing a required
query-string parameter
- missingQueryValue: The URI is missing a required query-string
parameter value
- invalidQuery: The query section of the URI is invalid.
- invalidBody: The request has an invalid body
$ref: '#/components/schemas/Error400Code'
required:
- code
type: object
description:
'Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)'
Error400Code:
description: >-
One of the following error codes:
- missingQueryParameter: The URI is missing a required query-string
parameter
- missingQueryValue: The URI is missing a required query-string
parameter value
- invalidQuery: The query section of the URI is invalid.
- invalidBody: The request has an invalid body
enum:
- missingQueryParameter
- missingQueryValue
- invalidQuery
- invalidBody
type: string
Error401:
allOf:
- $ref: '#/components/schemas/Error'
- properties:
code:
description: >-
One of the following error codes:
- missingCredentials: No credentials provided.
- invalidCredentials: Provided credentials are invalid or
expired
$ref: '#/components/schemas/Error401Code'
required:
- code
type: object
description:
'Unauthorized. (https://tools.ietf.org/html/rfc7235#section-3.1)'
Error401Code:
description: |-
One of the following error codes:
- missingCredentials: No credentials provided.
- invalidCredentials: Provided credentials are invalid or expired
enum:
- missingCredentials
- invalidCredentials
type: string
Error403:
allOf:
- $ref: '#/components/schemas/Error'
- properties:
code:
description: |-
This code indicates that the server understood
the request but refuses to authorize it because
of one of the following error codes:
- accessDenied: Access denied
- forbiddenRequester: Forbidden requester
- tooManyUsers: Too many users
$ref: '#/components/schemas/Error403Code'
required:
- code
type: object
description:
'Forbidden. (https://tools.ietf.org/html/rfc7231#section-6.5.3)'
Error403Code:
description: |-
This code indicates that the server understood
the request but refuses to authorize it because
of one of the following error codes:
- accessDenied: Access denied
- forbiddenRequester: Forbidden requester
- tooManyUsers: Too many users
enum:
- accessDenied
- forbiddenRequester
- tooManyUsers
type: string
Error500:
allOf:
- $ref: '#/components/schemas/Error'
- properties:
code:
description: >-
One of the following error codes:
- internalError: Internal server error - the server encountered
an unexpected condition that prevented it from fulfilling the
request.
enum:
- internalError
type: string
required:
- code
type: object
description: >-
Internal Server Error.
(https://tools.ietf.org/html/rfc7231#section-6.6.1)
Event:
description: >-
Event class is used to describe information structure used for
notification.
type: object
properties:
eventId:
description: Id of the event
type: string
eventTime:
description: Date-time when the event occurred
type: string
format: date-time
eventType:
description: The type of the notification.
type: string
event:
description: The event linked to the involved resource object
type: object
required:
- event
- eventId
- eventTime
- eventType
GeographicAddressValidationEvent:
allOf:
- $ref: '#/components/schemas/Event'
- properties:
eventType:
description: |
Indicates the type of the event.
enum:
- geographicAddressValidationStateChangeEvent
type: string
event:
description: >
A reference to the Geographic Address Validation that is source of the
notification.
$ref: '#/components/schemas/GeographicAddressValidationEventPayload'
required:
- event
- eventType
type: object
GeographicAddressValidationEventPayload:
description: >-
The identifier of the Geographic Address Validation being subject of
this event.
properties:
id:
description: ID of the Geographic Address Validation
type: string
href:
description: Hyperlink to access the Geographic Address Validation
type: string
state:
description: A state reached at change date
$ref: '#/components/schemas/GeographicAddressValidationStateType'
required:
- id
- state
type: object
GeographicAddressValidationStateType:
description: |
A list of possible `state` values for GeographicAddressValidation.
| Name | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| acknowledged | A GeographicAddressValidation request has been received by the Seller and has passed basic validation. A `GeographicAddressValidation.id` is assigned in the `acknowledged` state and moves to `inProgress` when it passes business validation. If it does not pass business validation, it moves to the `rejected` state. |
| inProgress | The GeographicAddressValidation request is currently being worked on by the Seller. |
| ready | The GeographicAddressValidation processing is completed by the Seller and it is ready to be retrieved or the Immediate Response has been returned. |
| rejected | The GeographicAddressValidation processing has failed at least one of the validation checks the Seller performs after it reached the `acknowledged` state. |
type: string
enum:
- acknowledged
- inProgress
- ready
- rejected